From 36a75bc08cd2d690944474495fe06af44c3424e8 Mon Sep 17 00:00:00 2001 From: Christopher Bartz Date: Wed, 10 Jul 2024 13:55:09 +0200 Subject: [PATCH] fix src-docs for packaging --- generate-src-docs.sh | 2 +- src-docs/{charm.py.md => charm.md} | 26 +- src-docs/charm_state.py.md | 899 ------------------ src-docs/errors.md | 405 ++++++++ src-docs/errors.py.md | 339 ------- .../{event_timer.py.md => event_timer.md} | 94 +- src-docs/{firewall.py.md => firewall.md} | 108 ++- .../{github_client.py.md => github_client.md} | 18 +- .../{github_type.py.md => github_type.md} | 118 ++- src-docs/{logrotate.py.md => logrotate.md} | 34 +- src-docs/{lxd.py.md => lxd.md} | 546 ++++++----- src-docs/{lxd_type.py.md => lxd_type.md} | 117 ++- src-docs/{events.md => metrics.events.md} | 2 +- src-docs/{github.md => metrics.github.md} | 2 +- src-docs/metrics.md | 29 + src-docs/metrics.runner.md | 174 ++++ ...{runner_logs.md => metrics.runner_logs.md} | 2 +- src-docs/{storage.md => metrics.storage.md} | 2 +- src-docs/{type.md => metrics.type.md} | 2 +- src-docs/openstack_cloud.md | 57 ++ ...d => openstack_cloud.openstack_manager.md} | 2 +- src-docs/{job.md => reactive.job.md} | 2 +- src-docs/reactive.md | 14 + src-docs/reactive.runner.md | 28 + src-docs/reactive.runner_manager.md | 84 ++ ...py.md => repo_policy_compliance_client.md} | 8 +- src-docs/runner.md | 231 +---- src-docs/runner.py.md | 180 ---- src-docs/runner_manager.md | 79 +- src-docs/runner_manager.py.md | 244 ----- ...ager_type.py.md => runner_manager_type.md} | 150 ++- src-docs/runner_type.md | 192 ++++ src-docs/runner_type.py.md | 102 -- src-docs/{shared_fs.py.md => shared_fs.md} | 2 +- src-docs/{utilities.py.md => utilities.md} | 4 +- 35 files changed, 1730 insertions(+), 2568 deletions(-) rename src-docs/{charm.py.md => charm.md} (90%) delete mode 100644 src-docs/charm_state.py.md create mode 100644 src-docs/errors.md delete mode 100644 src-docs/errors.py.md rename src-docs/{event_timer.py.md => event_timer.md} (75%) rename src-docs/{firewall.py.md => firewall.md} (76%) rename src-docs/{github_client.py.md => github_client.md} (89%) rename src-docs/{github_type.py.md => github_type.md} (70%) rename src-docs/{logrotate.py.md => logrotate.md} (84%) rename src-docs/{lxd.py.md => lxd.md} (85%) rename src-docs/{lxd_type.py.md => lxd_type.md} (65%) rename src-docs/{events.md => metrics.events.md} (99%) rename src-docs/{github.md => metrics.github.md} (96%) create mode 100644 src-docs/metrics.md create mode 100644 src-docs/metrics.runner.md rename src-docs/{runner_logs.md => metrics.runner_logs.md} (94%) rename src-docs/{storage.md => metrics.storage.md} (99%) rename src-docs/{type.md => metrics.type.md} (94%) create mode 100644 src-docs/openstack_cloud.md rename src-docs/{openstack_manager.md => openstack_cloud.openstack_manager.md} (98%) rename src-docs/{job.md => reactive.job.md} (99%) create mode 100644 src-docs/reactive.md create mode 100644 src-docs/reactive.runner.md create mode 100644 src-docs/reactive.runner_manager.md rename src-docs/{repo_policy_compliance_client.py.md => repo_policy_compliance_client.md} (83%) delete mode 100644 src-docs/runner.py.md delete mode 100644 src-docs/runner_manager.py.md rename src-docs/{runner_manager_type.py.md => runner_manager_type.md} (58%) create mode 100644 src-docs/runner_type.md delete mode 100644 src-docs/runner_type.py.md rename src-docs/{shared_fs.py.md => shared_fs.md} (98%) rename src-docs/{utilities.py.md => utilities.md} (98%) diff --git a/generate-src-docs.sh b/generate-src-docs.sh index d13066a1a..7f9bbe506 100644 --- a/generate-src-docs.sh +++ b/generate-src-docs.sh @@ -3,4 +3,4 @@ # Copyright 2024 Canonical Ltd. # See LICENSE file for licensing details. -lazydocs --no-watermark --output-path src-docs src/* +lazydocs --no-watermark --output-path src-docs src diff --git a/src-docs/charm.py.md b/src-docs/charm.md similarity index 90% rename from src-docs/charm.py.md rename to src-docs/charm.md index ef6b849be..c32b64fd0 100644 --- a/src-docs/charm.py.md +++ b/src-docs/charm.md @@ -2,7 +2,7 @@ -# module `charm.py` +# module `charm` Charm for creating and managing GitHub self-hosted runner instances. **Global Variables** @@ -72,6 +72,19 @@ Catch common errors in actions. --- + + +## class `ReconcileRunnersEvent` +Event representing a periodic check to ensure runners are ok. + + + + + +--- + + + ## class `GithubRunnerCharm` Charm for managing GitHub self-hosted runners. @@ -89,7 +102,7 @@ Charm for managing GitHub self-hosted runners. -### function `__init__` +### method `__init__` ```python __init__(*args: Any, **kwargs: Any) → None @@ -150,12 +163,3 @@ Unit that this execution is responsible for. ---- - -## class `ReconcileRunnersEvent` -Event representing a periodic check to ensure runners are ok. - - - - - diff --git a/src-docs/charm_state.py.md b/src-docs/charm_state.py.md deleted file mode 100644 index 41c5b1c92..000000000 --- a/src-docs/charm_state.py.md +++ /dev/null @@ -1,899 +0,0 @@ - - - - -# module `charm_state.py` -State of the Charm. - -**Global Variables** ---------------- -- **ARCHITECTURES_ARM64** -- **ARCHITECTURES_X86** -- **BASE_IMAGE_CONFIG_NAME** -- **DENYLIST_CONFIG_NAME** -- **DOCKERHUB_MIRROR_CONFIG_NAME** -- **GROUP_CONFIG_NAME** -- **LABELS_CONFIG_NAME** -- **OPENSTACK_CLOUDS_YAML_CONFIG_NAME** -- **OPENSTACK_NETWORK_CONFIG_NAME** -- **OPENSTACK_FLAVOR_CONFIG_NAME** -- **PATH_CONFIG_NAME** -- **RECONCILE_INTERVAL_CONFIG_NAME** -- **REPO_POLICY_COMPLIANCE_TOKEN_CONFIG_NAME** -- **REPO_POLICY_COMPLIANCE_URL_CONFIG_NAME** -- **RUNNER_STORAGE_CONFIG_NAME** -- **TEST_MODE_CONFIG_NAME** -- **TOKEN_CONFIG_NAME** -- **USE_APROXY_CONFIG_NAME** -- **VIRTUAL_MACHINES_CONFIG_NAME** -- **VM_CPU_CONFIG_NAME** -- **VM_MEMORY_CONFIG_NAME** -- **VM_DISK_CONFIG_NAME** -- **COS_AGENT_INTEGRATION_NAME** -- **DEBUG_SSH_INTEGRATION_NAME** -- **IMAGE_INTEGRATION_NAME** -- **MONGO_DB_INTEGRATION_NAME** -- **LTS_IMAGE_VERSION_TAG_MAP** - ---- - - - -## function `parse_github_path` - -```python -parse_github_path(path_str: str, runner_group: str) → GithubOrg | GithubRepo -``` - -Parse GitHub path. - - - -**Args:** - - - `path_str`: GitHub path in string format. - - `runner_group`: Runner group name for GitHub organization. If the path is a repository this argument is ignored. - - - -**Raises:** - - - `CharmConfigInvalidError`: if an invalid path string was given. - - - -**Returns:** - GithubPath object representing the GitHub repository, or the GitHub organization with runner group information. - - ---- - -## class `AnyHttpsUrl` -Represents an HTTPS URL. - - - -**Attributes:** - - - `allowed_schemes`: Allowed schemes for the URL. - - - - - ---- - -## class `Arch` -Supported system architectures. - - - -**Attributes:** - - - `ARM64`: Represents an ARM64 system architecture. - - `X64`: Represents an X64/AMD64 system architecture. - - - - - ---- - -## class `BaseImage` -The ubuntu OS base image to build and deploy runners on. - - - -**Attributes:** - - - `JAMMY`: The jammy ubuntu LTS image. - - `NOBLE`: The noble ubuntu LTS image. - - - - - ---- - -## class `CharmConfig` -General charm configuration. - -Some charm configurations are grouped into other configuration models. - - - -**Attributes:** - - - `denylist`: List of IPv4 to block the runners from accessing. - - `dockerhub_mirror`: Private docker registry as dockerhub mirror for the runners to use. - - `labels`: Additional runner labels to append to default (i.e. os, flavor, architecture). - - `openstack_clouds_yaml`: The openstack clouds.yaml configuration. - - `path`: GitHub repository path in the format '/', or the GitHub organization name. - - `reconcile_interval`: Time between each reconciliation of runners in minutes. - - `repo_policy_compliance`: Configuration for the repo policy compliance service. - - `token`: GitHub personal access token for GitHub API. - - - - ---- - - - -### classmethod `check_reconcile_interval` - -```python -check_reconcile_interval(reconcile_interval: int) → int -``` - -Validate the general charm configuration. - - - -**Args:** - - - `reconcile_interval`: The value of reconcile_interval passed to class instantiation. - - - -**Raises:** - - - `ValueError`: if an invalid reconcile_interval value of less than 2 has been passed. - - - -**Returns:** - The validated reconcile_interval value. - ---- - - - -### classmethod `from_charm` - -```python -from_charm(charm: CharmBase) → CharmConfig -``` - -Initialize the config from charm. - - - -**Args:** - - - `charm`: The charm instance. - - - -**Raises:** - - - `CharmConfigInvalidError`: If any invalid configuration has been set on the charm. - - - -**Returns:** - Current config of the charm. - - ---- - -## class `CharmConfigInvalidError` -Raised when charm config is invalid. - - - -**Attributes:** - - - `msg`: Explanation of the error. - - - -### function `__init__` - -```python -__init__(msg: str) -``` - -Initialize a new instance of the CharmConfigInvalidError exception. - - - -**Args:** - - - `msg`: Explanation of the error. - - - - - ---- - -## class `CharmState` -The charm state. - - - -**Attributes:** - - - `arch`: The underlying compute architecture, i.e. x86_64, amd64, arm64/aarch64. - - `charm_config`: Configuration of the juju charm. - - `is_metrics_logging_available`: Whether the charm is able to issue metrics. - - `proxy_config`: Proxy-related configuration. - - `instance_type`: The type of instances, e.g., local lxd, openstack. - - `reactive_config`: The charm configuration related to reactive spawning mode. - - `runner_config`: The charm configuration related to runner VM configuration. - - `ssh_debug_connections`: SSH debug connections configuration information. - - - - ---- - - - -### classmethod `from_charm` - -```python -from_charm(charm: CharmBase, database: DatabaseRequires) → CharmState -``` - -Initialize the state from charm. - - - -**Args:** - - - `charm`: The charm instance. - - `database`: The database instance. - - - -**Raises:** - - - `CharmConfigInvalidError`: If an invalid configuration was set. - - - -**Returns:** - Current state of the charm. - - ---- - -## class `GithubConfig` -Charm configuration related to GitHub. - - - -**Attributes:** - - - `token`: The Github API access token (PAT). - - `path`: The Github org/repo path. - - - - ---- - - - -### classmethod `from_charm` - -```python -from_charm(charm: CharmBase) → GithubConfig -``` - -Get github related charm configuration values from charm. - - - -**Args:** - - - `charm`: The charm instance. - - - -**Raises:** - - - `CharmConfigInvalidError`: If an invalid configuration value was set. - - - -**Returns:** - The parsed GitHub configuration values. - - ---- - -## class `GithubOrg` -Represent GitHub organization. - - - -**Attributes:** - - - `org`: Name of the GitHub organization. - - `group`: Runner group to spawn the runners in. - - - - ---- - - - -### function `path` - -```python -path() → str -``` - -Return a string representing the path. - - - -**Returns:** - Path to the GitHub entity. - - ---- - -## class `GithubRepo` -Represent GitHub repository. - - - -**Attributes:** - - - `owner`: Owner of the GitHub repository. - - `repo`: Name of the GitHub repository. - - - - ---- - - - -### function `path` - -```python -path() → str -``` - -Return a string representing the path. - - - -**Returns:** - Path to the GitHub entity. - - ---- - -## class `ImmutableConfigChangedError` -Represents an error when changing immutable charm state. - - - -### function `__init__` - -```python -__init__(msg: str) -``` - -Initialize a new instance of the ImmutableConfigChangedError exception. - - - -**Args:** - - - `msg`: Explanation of the error. - - - - - ---- - -## class `InstanceType` -Type of instance for runner. - - - -**Attributes:** - - - `LOCAL_LXD`: LXD instance on the local juju machine. - - `OPENSTACK`: OpenStack instance on a cloud. - - - - - ---- - -## class `LocalLxdRunnerConfig` -Runner configurations for local LXD instances. - - - -**Attributes:** - - - `base_image`: The ubuntu base image to run the runner virtual machines on. - - `virtual_machines`: Number of virtual machine-based runner to spawn. - - `virtual_machine_resources`: Hardware resource used by one virtual machine for a runner. - - `runner_storage`: Storage to be used as disk for the runner. - - - - ---- - - - -### classmethod `check_virtual_machine_resources` - -```python -check_virtual_machine_resources( - vm_resources: VirtualMachineResources -) → VirtualMachineResources -``` - -Validate the virtual_machine_resources field values. - - - -**Args:** - - - `vm_resources`: the virtual_machine_resources value to validate. - - - -**Raises:** - - - `ValueError`: if an invalid number of cpu was given or invalid memory/disk size was given. - - - -**Returns:** - The validated virtual_machine_resources value. - ---- - - - -### classmethod `check_virtual_machines` - -```python -check_virtual_machines(virtual_machines: int) → int -``` - -Validate the virtual machines configuration value. - - - -**Args:** - - - `virtual_machines`: The virtual machines value to validate. - - - -**Raises:** - - - `ValueError`: if a negative integer was passed. - - - -**Returns:** - Validated virtual_machines value. - ---- - - - -### classmethod `from_charm` - -```python -from_charm(charm: CharmBase) → LocalLxdRunnerConfig -``` - -Initialize the config from charm. - - - -**Args:** - - - `charm`: The charm instance. - - - -**Raises:** - - - `CharmConfigInvalidError`: if an invalid runner charm config has been set on the charm. - - - -**Returns:** - Local LXD runner config of the charm. - - ---- - -## class `OpenstackImage` -OpenstackImage from image builder relation data. - - - -**Attributes:** - - - `id`: The OpenStack image ID. - - `tags`: Image tags, e.g. jammy - - - - ---- - - - -### classmethod `from_charm` - -```python -from_charm(charm: CharmBase) → OpenstackImage | None -``` - -Initialize the OpenstackImage info from relation data. - -None represents relation not established. None values for id/tags represent image not yet ready but the relation exists. - - - -**Args:** - - - `charm`: The charm instance. - - - -**Returns:** - OpenstackImage metadata from charm relation data. - - ---- - -## class `OpenstackRunnerConfig` -Runner configuration for OpenStack Instances. - - - -**Attributes:** - - - `virtual_machines`: Number of virtual machine-based runner to spawn. - - `openstack_flavor`: flavor on openstack to use for virtual machines. - - `openstack_network`: Network on openstack to use for virtual machines. - - `openstack_image`: Openstack image to use for virtual machines. - - - - ---- - - - -### classmethod `from_charm` - -```python -from_charm(charm: CharmBase) → OpenstackRunnerConfig -``` - -Initialize the config from charm. - - - -**Args:** - - - `charm`: The charm instance. - - - -**Raises:** - - - `CharmConfigInvalidError`: Error with charm configuration virtual-machines not of int type. - - - -**Returns:** - Openstack runner config of the charm. - - ---- - -## class `ProxyConfig` -Proxy configuration. - - - -**Attributes:** - - - `aproxy_address`: The address of aproxy snap instance if use_aproxy is enabled. - - `http`: HTTP proxy address. - - `https`: HTTPS proxy address. - - `no_proxy`: Comma-separated list of hosts that should not be proxied. - - `use_aproxy`: Whether aproxy should be used for the runners. - - ---- - -#### property aproxy_address - -Return the aproxy address. - - - ---- - - - -### classmethod `check_use_aproxy` - -```python -check_use_aproxy(use_aproxy: bool, values: dict) → bool -``` - -Validate the proxy configuration. - - - -**Args:** - - - `use_aproxy`: Value of use_aproxy variable. - - `values`: Values in the pydantic model. - - - -**Raises:** - - - `ValueError`: if use_aproxy was set but no http/https was passed. - - - -**Returns:** - Validated use_aproxy value. - ---- - - - -### classmethod `from_charm` - -```python -from_charm(charm: CharmBase) → ProxyConfig -``` - -Initialize the proxy config from charm. - - - -**Args:** - - - `charm`: The charm instance. - - - -**Returns:** - Current proxy config of the charm. - - ---- - -## class `ReactiveConfig` -Represents the configuration for reactive scheduling. - - - -**Attributes:** - - - `mq_uri`: The URI of the MQ to use to spawn runners reactively. - - - - ---- - - - -### classmethod `from_database` - -```python -from_database(database: DatabaseRequires) → ReactiveConfig | None -``` - -Initialize the ReactiveConfig from charm config and integration data. - - - -**Args:** - - - `database`: The database to fetch integration data from. - - - -**Returns:** - The connection information for the reactive MQ or None if not available. - - - -**Raises:** - - - `MissingIntegrationDataError`: If the respective reactive MQ integration data is missing. - - ---- - -## class `RepoPolicyComplianceConfig` -Configuration for the repo policy compliance service. - - - -**Attributes:** - - - `token`: Token for the repo policy compliance service. - - `url`: URL of the repo policy compliance service. - - - - ---- - - - -### classmethod `from_charm` - -```python -from_charm(charm: CharmBase) → RepoPolicyComplianceConfig -``` - -Initialize the config from charm. - - - -**Args:** - - - `charm`: The charm instance. - - - -**Raises:** - - - `CharmConfigInvalidError`: If an invalid configuration was set. - - - -**Returns:** - Current repo-policy-compliance config. - - ---- - -## class `RunnerStorage` -Supported storage as runner disk. - - - -**Attributes:** - - - `JUJU_STORAGE`: Represents runner storage from Juju storage. - - `MEMORY`: Represents tempfs storage (ramdisk). - - - - - ---- - -## class `SSHDebugConnection` -SSH connection information for debug workflow. - - - -**Attributes:** - - - `host`: The SSH relay server host IP address inside the VPN. - - `port`: The SSH relay server port. - - `rsa_fingerprint`: The host SSH server public RSA key fingerprint. - - `ed25519_fingerprint`: The host SSH server public ed25519 key fingerprint. - - - - ---- - - - -### classmethod `from_charm` - -```python -from_charm(charm: CharmBase) → list['SSHDebugConnection'] -``` - -Initialize the SSHDebugInfo from charm relation data. - - - -**Args:** - - - `charm`: The charm instance. - - - -**Returns:** - List of connection information for ssh debug access. - - ---- - -## class `UnsupportedArchitectureError` -Raised when given machine charm architecture is unsupported. - - - -**Attributes:** - - - `arch`: The current machine architecture. - - - -### function `__init__` - -```python -__init__(arch: str) → None -``` - -Initialize a new instance of the CharmConfigInvalidError exception. - - - -**Args:** - - - `arch`: The current machine architecture. - - - - - ---- - -## class `VirtualMachineResources` -Virtual machine resource configuration. - - - -**Attributes:** - - - `cpu`: Number of vCPU for the virtual machine. - - `memory`: Amount of memory for the virtual machine. - - `disk`: Amount of disk for the virtual machine. - - - - - diff --git a/src-docs/errors.md b/src-docs/errors.md new file mode 100644 index 000000000..33e782716 --- /dev/null +++ b/src-docs/errors.md @@ -0,0 +1,405 @@ + + + + +# module `errors` +Errors used by the charm. + + + +--- + + + +## class `RunnerError` +Generic runner error as base exception. + + + + + +--- + + + +## class `RunnerExecutionError` +Error for executing commands on runner. + + + + + +--- + + + +## class `RunnerFileLoadError` +Error for loading file on runner. + + + + + +--- + + + +## class `RunnerCreateError` +Error for runner creation failure. + + + + + +--- + + + +## class `RunnerRemoveError` +Error for runner removal failure. + + + + + +--- + + + +## class `RunnerStartError` +Error for runner start failure. + + + + + +--- + + + +## class `RunnerBinaryError` +Error of getting runner binary. + + + + + +--- + + + +## class `RunnerAproxyError` +Error for setting up aproxy. + + + + + +--- + + + +## class `MissingRunnerBinaryError` +Error for missing runner binary. + + + + + +--- + + + +## class `ConfigurationError` +Error for juju configuration. + + + + + +--- + + + +## class `MissingIntegrationDataError` +Error for missing integration data. + + + + + +--- + + + +## class `LxdError` +Error for executing LXD actions. + + + + + +--- + + + +## class `SubprocessError` +Error for Subprocess calls. + + + +**Attributes:** + + - `cmd`: Command in list form. + - `return_code`: Return code of the subprocess. + - `stdout`: Content of stdout of the subprocess. + - `stderr`: Content of stderr of the subprocess. + + + +### method `__init__` + +```python +__init__( + cmd: 'list[str]', + return_code: 'int', + stdout: 'Union[bytes, str]', + stderr: 'Union[bytes, str]' +) +``` + +Construct the subprocess error. + + + +**Args:** + + - `cmd`: Command in list form. + - `return_code`: Return code of the subprocess. + - `stdout`: Content of stdout of the subprocess. + - `stderr`: Content of stderr of the subprocess. + + + + + +--- + + + +## class `IssueMetricEventError` +Represents an error when issuing a metric event. + + + + + +--- + + + +## class `LogrotateSetupError` +Represents an error raised when logrotate cannot be setup. + + + + + +--- + + + +## class `MetricsStorageError` +Base class for all metrics storage errors. + + + + + +--- + + + +## class `SharedFilesystemError` +Base class for all shared filesystem errors. + + + + + +--- + + + +## class `CreateMetricsStorageError` +Represents an error when the metrics storage could not be created. + + + + + +--- + + + +## class `DeleteMetricsStorageError` +Represents an error when the metrics storage could not be deleted. + + + + + +--- + + + +## class `GetMetricsStorageError` +Represents an error when the metrics storage could not be retrieved. + + + + + +--- + + + +## class `QuarantineMetricsStorageError` +Represents an error when the metrics storage could not be quarantined. + + + + + +--- + + + +## class `SharedFilesystemMountError` +Represents an error related to the mounting of the shared filesystem. + + + + + +--- + + + +## class `RunnerMetricsError` +Base class for all runner metrics errors. + + + + + +--- + + + +## class `CorruptMetricDataError` +Represents an error with the data being corrupt. + + + + + +--- + + + +## class `GithubMetricsError` +Base class for all github metrics errors. + + + + + +--- + + + +## class `GithubClientError` +Base class for all github client errors. + + + + + +--- + + + +## class `GithubApiError` +Represents an error when the GitHub API returns an error. + + + + + +--- + + + +## class `TokenError` +Represents an error when the token is invalid or has not enough permissions. + + + + + +--- + + + +## class `JobNotFoundError` +Represents an error when the job could not be found on GitHub. + + + + + +--- + + + +## class `RunnerLogsError` +Base class for all runner logs errors. + + + + + +--- + + + +## class `OpenStackError` +Base class for OpenStack errors. + + + + + +--- + + + +## class `OpenStackInvalidConfigError` +Represents an invalid OpenStack configuration. + + + + + +--- + + + +## class `OpenStackUnauthorizedError` +Represents an unauthorized connection to OpenStack. + + + + + diff --git a/src-docs/errors.py.md b/src-docs/errors.py.md deleted file mode 100644 index 5355069b7..000000000 --- a/src-docs/errors.py.md +++ /dev/null @@ -1,339 +0,0 @@ - - - - -# module `errors.py` -Errors used by the charm. - - - ---- - -## class `ConfigurationError` -Error for juju configuration. - - - - - ---- - -## class `CorruptMetricDataError` -Represents an error with the data being corrupt. - - - - - ---- - -## class `CreateMetricsStorageError` -Represents an error when the metrics storage could not be created. - - - - - ---- - -## class `DeleteMetricsStorageError` -Represents an error when the metrics storage could not be deleted. - - - - - ---- - -## class `GetMetricsStorageError` -Represents an error when the metrics storage could not be retrieved. - - - - - ---- - -## class `GithubApiError` -Represents an error when the GitHub API returns an error. - - - - - ---- - -## class `GithubClientError` -Base class for all github client errors. - - - - - ---- - -## class `GithubMetricsError` -Base class for all github metrics errors. - - - - - ---- - -## class `IssueMetricEventError` -Represents an error when issuing a metric event. - - - - - ---- - -## class `JobNotFoundError` -Represents an error when the job could not be found on GitHub. - - - - - ---- - -## class `LogrotateSetupError` -Represents an error raised when logrotate cannot be setup. - - - - - ---- - -## class `LxdError` -Error for executing LXD actions. - - - - - ---- - -## class `MetricsStorageError` -Base class for all metrics storage errors. - - - - - ---- - -## class `MissingIntegrationDataError` -Error for missing integration data. - - - - - ---- - -## class `MissingRunnerBinaryError` -Error for missing runner binary. - - - - - ---- - -## class `OpenStackError` -Base class for OpenStack errors. - - - - - ---- - -## class `OpenStackInvalidConfigError` -Represents an invalid OpenStack configuration. - - - - - ---- - -## class `OpenStackUnauthorizedError` -Represents an unauthorized connection to OpenStack. - - - - - ---- - -## class `QuarantineMetricsStorageError` -Represents an error when the metrics storage could not be quarantined. - - - - - ---- - -## class `RunnerAproxyError` -Error for setting up aproxy. - - - - - ---- - -## class `RunnerBinaryError` -Error of getting runner binary. - - - - - ---- - -## class `RunnerCreateError` -Error for runner creation failure. - - - - - ---- - -## class `RunnerError` -Generic runner error as base exception. - - - - - ---- - -## class `RunnerExecutionError` -Error for executing commands on runner. - - - - - ---- - -## class `RunnerFileLoadError` -Error for loading file on runner. - - - - - ---- - -## class `RunnerLogsError` -Base class for all runner logs errors. - - - - - ---- - -## class `RunnerMetricsError` -Base class for all runner metrics errors. - - - - - ---- - -## class `RunnerRemoveError` -Error for runner removal failure. - - - - - ---- - -## class `RunnerStartError` -Error for runner start failure. - - - - - ---- - -## class `SharedFilesystemError` -Base class for all shared filesystem errors. - - - - - ---- - -## class `SharedFilesystemMountError` -Represents an error related to the mounting of the shared filesystem. - - - - - ---- - -## class `SubprocessError` -Error for Subprocess calls. - - - -**Attributes:** - - - `cmd`: Command in list form. - - `return_code`: Return code of the subprocess. - - `stdout`: Content of stdout of the subprocess. - - `stderr`: Content of stderr of the subprocess. - - - -### function `__init__` - -```python -__init__( - cmd: 'list[str]', - return_code: 'int', - stdout: 'Union[bytes, str]', - stderr: 'Union[bytes, str]' -) -``` - -Construct the subprocess error. - - - -**Args:** - - - `cmd`: Command in list form. - - `return_code`: Return code of the subprocess. - - `stdout`: Content of stdout of the subprocess. - - `stderr`: Content of stderr of the subprocess. - - - - - ---- - -## class `TokenError` -Represents an error when the token is invalid or has not enough permissions. - - - - - diff --git a/src-docs/event_timer.py.md b/src-docs/event_timer.md similarity index 75% rename from src-docs/event_timer.py.md rename to src-docs/event_timer.md index b29f90455..57055e575 100644 --- a/src-docs/event_timer.py.md +++ b/src-docs/event_timer.md @@ -2,7 +2,7 @@ -# module `event_timer.py` +# module `event_timer` EventTimer for scheduling dispatch of juju event on regular intervals. **Global Variables** @@ -12,6 +12,52 @@ EventTimer for scheduling dispatch of juju event on regular intervals. --- + + +## class `TimerError` +Generic timer error as base exception. + + + + + +--- + + + +## class `TimerEnableError` +Raised when unable to enable a event timer. + + + + + +--- + + + +## class `TimerDisableError` +Raised when unable to disable a event timer. + + + + + +--- + + + +## class `TimerStatusError` +Raised when unable to check status of a event timer. + + + + + +--- + + + ## class `EventConfig` Configuration used by service and timer templates. @@ -31,6 +77,8 @@ Configuration used by service and timer templates. --- + + ## class `EventTimer` Manages the timer to emit juju events at regular intervals. @@ -42,7 +90,7 @@ Manages the timer to emit juju events at regular intervals. -### function `__init__` +### method `__init__` ```python __init__(unit_name: str) @@ -63,7 +111,7 @@ Construct the timer manager. -### function `disable_event_timer` +### method `disable_event_timer` ```python disable_event_timer(event_name: str) → None @@ -87,7 +135,7 @@ Disable the systemd timer for the given event. -### function `ensure_event_timer` +### method `ensure_event_timer` ```python ensure_event_timer( @@ -121,7 +169,7 @@ The timeout is the number of seconds before an event is timed out. If not set or -### function `is_active` +### method `is_active` ```python is_active(event_name: str) → bool @@ -147,39 +195,3 @@ Check if the systemd timer is active for the given event. - `TimerStatusError`: Timer status cannot be determined. ---- - -## class `TimerDisableError` -Raised when unable to disable a event timer. - - - - - ---- - -## class `TimerEnableError` -Raised when unable to enable a event timer. - - - - - ---- - -## class `TimerError` -Generic timer error as base exception. - - - - - ---- - -## class `TimerStatusError` -Raised when unable to check status of a event timer. - - - - - diff --git a/src-docs/firewall.py.md b/src-docs/firewall.md similarity index 76% rename from src-docs/firewall.py.md rename to src-docs/firewall.md index 486c03290..3b59a41d5 100644 --- a/src-docs/firewall.py.md +++ b/src-docs/firewall.md @@ -2,117 +2,133 @@ -# module `firewall.py` +# module `firewall` The runner firewall manager. --- -## class `Firewall` -Represent a firewall and provides methods to refresh its configuration. + - +## class `FirewallEntry` +Represent an entry in the firewall. + + + +**Attributes:** + + - `ip_range`: The IP address range using CIDR notation. + + -### function `__init__` +### method `__init__` ```python -__init__(network: str) +__init__(ip_range: str) → None ``` -Initialize a new Firewall instance. -**Args:** - - - `network`: The LXD network name. --- - + -### function `get_host_ip` +### classmethod `decode` ```python -get_host_ip() → str +decode(entry: str) → FirewallEntry ``` -Get the host IP address for the corresponding LXD network. +Decode a firewall entry from a string. + + + +**Args:** + + - `entry`: The firewall entry string, e.g. '192.168.0.1:80' or '192.168.0.0/24:80-90:udp'. **Returns:** - The host IP address. + + - `FirewallEntry`: A FirewallEntry instance representing the decoded entry. ---- - -### function `refresh_firewall` +**Raises:** + + - `ValueError`: If the entry string is not in the expected format. -```python -refresh_firewall( - denylist: Iterable[FirewallEntry], - allowlist: Optional[Iterable[FirewallEntry]] = None -) → None -``` -Refresh the firewall configuration. +--- + +## class `Firewall` +Represent a firewall and provides methods to refresh its configuration. -**Args:** - - - `denylist`: The list of FirewallEntry rules to allow. - - `allowlist`: The list of FirewallEntry rules to allow. + +### method `__init__` ---- +```python +__init__(network: str) +``` -## class `FirewallEntry` -Represent an entry in the firewall. +Initialize a new Firewall instance. -**Attributes:** +**Args:** - - `ip_range`: The IP address range using CIDR notation. + - `network`: The LXD network name. --- - + -### classmethod `decode` +### method `get_host_ip` ```python -decode(entry: str) → FirewallEntry +get_host_ip() → str ``` -Decode a firewall entry from a string. +Get the host IP address for the corresponding LXD network. -**Args:** - - - `entry`: The firewall entry string, e.g. '192.168.0.1:80' or '192.168.0.0/24:80-90:udp'. +**Returns:** + The host IP address. +--- + -**Returns:** - - - `FirewallEntry`: A FirewallEntry instance representing the decoded entry. +### method `refresh_firewall` +```python +refresh_firewall( + denylist: Iterable[FirewallEntry], + allowlist: Optional[Iterable[FirewallEntry]] = None +) → None +``` +Refresh the firewall configuration. -**Raises:** + + +**Args:** - - `ValueError`: If the entry string is not in the expected format. + - `denylist`: The list of FirewallEntry rules to allow. + - `allowlist`: The list of FirewallEntry rules to allow. diff --git a/src-docs/github_client.py.md b/src-docs/github_client.md similarity index 89% rename from src-docs/github_client.py.md rename to src-docs/github_client.md index 9ea4b2374..6cd298c52 100644 --- a/src-docs/github_client.py.md +++ b/src-docs/github_client.md @@ -2,7 +2,7 @@ -# module `github_client.py` +# module `github_client` GitHub API client. Migrate to PyGithub in the future. PyGithub is still lacking some API such as remove token for runner. @@ -36,12 +36,14 @@ Catch HTTP errors and raise custom exceptions. --- + + ## class `GithubClient` GitHub API client. -### function `__init__` +### method `__init__` ```python __init__(token: str) @@ -62,7 +64,7 @@ Instantiate the GiHub API client. -### function `delete_runner` +### method `delete_runner` ```python delete_runner(path: GithubOrg | GithubRepo, runner_id: int) → None @@ -81,7 +83,7 @@ Delete the self-hosted runner from GitHub. -### function `get_job_info` +### method `get_job_info` ```python get_job_info( @@ -117,7 +119,7 @@ Get information about a job for a specific workflow run. -### function `get_runner_application` +### method `get_runner_application` ```python get_runner_application( @@ -152,7 +154,7 @@ Get runner application available for download for given arch. -### function `get_runner_github_info` +### method `get_runner_github_info` ```python get_runner_github_info(path: GithubOrg | GithubRepo) → list[SelfHostedRunner] @@ -175,7 +177,7 @@ Get runner information on GitHub under a repo or org. -### function `get_runner_registration_token` +### method `get_runner_registration_token` ```python get_runner_registration_token(path: GithubOrg | GithubRepo) → str @@ -198,7 +200,7 @@ Get token from GitHub used for registering runners. -### function `get_runner_remove_token` +### method `get_runner_remove_token` ```python get_runner_remove_token(path: GithubOrg | GithubRepo) → str diff --git a/src-docs/github_type.py.md b/src-docs/github_type.md similarity index 70% rename from src-docs/github_type.py.md rename to src-docs/github_type.md index 8e4d650eb..4c196b632 100644 --- a/src-docs/github_type.py.md +++ b/src-docs/github_type.md @@ -2,13 +2,15 @@ -# module `github_type.py` +# module `github_type` Return type for the GitHub web API. --- + + ## class `GitHubRunnerStatus` Status of runner on GitHub. @@ -25,22 +27,21 @@ Status of runner on GitHub. --- -## class `JobConclusion` -Conclusion of a job on GitHub. + -See :https://docs.github.com/en/rest/actions/workflow-runs?apiVersion=2022-11-28#list-workflow-runs-for-a-repository +## class `RunnerApplication` +Information on the runner application. **Attributes:** - - `ACTION_REQUIRED`: Represents additional action required on the job. - - `CANCELLED`: Represents a cancelled job status. - - `FAILURE`: Represents a failed job status. - - `NEUTRAL`: Represents a job status that can optionally succeed or fail. - - `SKIPPED`: Represents a skipped job status. - - `SUCCESS`: Represents a successful job status. - - `TIMED_OUT`: Represents a job that has timed out. + - `os`: Operating system to run the runner application on. + - `architecture`: Computer Architecture to run the runner application on. + - `download_url`: URL to download the runner application. + - `filename`: Filename of the runner application. + - `temp_download_token`: A short lived bearer token used to download the runner, if needed. + - `sha256_checksum`: SHA256 Checksum of the runner application. @@ -48,17 +49,18 @@ See :https://docs.github.com/en/rest/actions/workflow-runs?apiVersion=2022-11-28 --- -## class `JobStats` -Stats for a job on GitHub. + + +## class `SelfHostedRunnerLabel` +A single label of self-hosted runners. **Attributes:** - - `job_id`: The ID of the job. - - `created_at`: The time the job was created. - - `started_at`: The time the job was started. - - `conclusion`: The end result of a job. + - `id`: Unique identifier of the label. + - `name`: Name of the label. + - `type`: Type of label. Read-only labels are applied automatically when the runner is configured. @@ -66,15 +68,21 @@ Stats for a job on GitHub. --- -## class `RegistrationToken` -Token used for registering GitHub runners. + + +## class `SelfHostedRunner` +Information on a single self-hosted runner. **Attributes:** - - `token`: Token for registering GitHub runners. - - `expires_at`: Time the token expires at. + - `busy`: Whether the runner is executing a job. + - `id`: Unique identifier of the runner. + - `labels`: Labels of the runner. + - `os`: Operation system of the runner. + - `name`: Name of the runner. + - `status`: The Github runner status. @@ -82,15 +90,17 @@ Token used for registering GitHub runners. --- -## class `RemoveToken` -Token used for removing GitHub runners. + + +## class `SelfHostedRunnerList` +Information on a collection of self-hosted runners. **Attributes:** - - `token`: Token for removing GitHub runners. - - `expires_at`: Time the token expires at. + - `total_count`: Total number of runners. + - `runners`: List of runners. @@ -98,19 +108,17 @@ Token used for removing GitHub runners. --- -## class `RunnerApplication` -Information on the runner application. + + +## class `RegistrationToken` +Token used for registering GitHub runners. **Attributes:** - - `os`: Operating system to run the runner application on. - - `architecture`: Computer Architecture to run the runner application on. - - `download_url`: URL to download the runner application. - - `filename`: Filename of the runner application. - - `temp_download_token`: A short lived bearer token used to download the runner, if needed. - - `sha256_checksum`: SHA256 Checksum of the runner application. + - `token`: Token for registering GitHub runners. + - `expires_at`: Time the token expires at. @@ -118,19 +126,17 @@ Information on the runner application. --- -## class `SelfHostedRunner` -Information on a single self-hosted runner. + + +## class `RemoveToken` +Token used for removing GitHub runners. **Attributes:** - - `busy`: Whether the runner is executing a job. - - `id`: Unique identifier of the runner. - - `labels`: Labels of the runner. - - `os`: Operation system of the runner. - - `name`: Name of the runner. - - `status`: The Github runner status. + - `token`: Token for removing GitHub runners. + - `expires_at`: Time the token expires at. @@ -138,16 +144,24 @@ Information on a single self-hosted runner. --- -## class `SelfHostedRunnerLabel` -A single label of self-hosted runners. + + +## class `JobConclusion` +Conclusion of a job on GitHub. + +See :https://docs.github.com/en/rest/actions/workflow-runs?apiVersion=2022-11-28#list-workflow-runs-for-a-repository **Attributes:** - - `id`: Unique identifier of the label. - - `name`: Name of the label. - - `type`: Type of label. Read-only labels are applied automatically when the runner is configured. + - `ACTION_REQUIRED`: Represents additional action required on the job. + - `CANCELLED`: Represents a cancelled job status. + - `FAILURE`: Represents a failed job status. + - `NEUTRAL`: Represents a job status that can optionally succeed or fail. + - `SKIPPED`: Represents a skipped job status. + - `SUCCESS`: Represents a successful job status. + - `TIMED_OUT`: Represents a job that has timed out. @@ -155,15 +169,19 @@ A single label of self-hosted runners. --- -## class `SelfHostedRunnerList` -Information on a collection of self-hosted runners. + + +## class `JobStats` +Stats for a job on GitHub. **Attributes:** - - `total_count`: Total number of runners. - - `runners`: List of runners. + - `job_id`: The ID of the job. + - `created_at`: The time the job was created. + - `started_at`: The time the job was started. + - `conclusion`: The end result of a job. diff --git a/src-docs/logrotate.py.md b/src-docs/logrotate.md similarity index 84% rename from src-docs/logrotate.py.md rename to src-docs/logrotate.md index 414dfe06a..31a250929 100644 --- a/src-docs/logrotate.py.md +++ b/src-docs/logrotate.md @@ -2,7 +2,7 @@ -# module `logrotate.py` +# module `logrotate` Logrotate setup and configuration. **Global Variables** @@ -50,19 +50,19 @@ Write a particular logrotate config to disk. --- -## class `LogrotateConfig` -Configuration for logrotate. + + +## class `LogrotateFrequency` +The frequency of log rotation. **Attributes:** - - `name`: The name of the logrotate configuration. - - `log_path_glob_pattern`: The glob pattern for the log path. - - `rotate`: The number of log files to keep. - - `create`: Whether to create the log file if it does not exist. - - `notifempty`: Whether to not rotate the log file if it is empty. - - `frequency`: The frequency of log rotation. + - `DAILY`: Rotate the log daily. + - `WEEKLY`: Rotate the log weekly. + - `MONTHLY`: Rotate the log monthly. + - `YEARLY`: Rotate the log yearly. @@ -70,17 +70,21 @@ Configuration for logrotate. --- -## class `LogrotateFrequency` -The frequency of log rotation. + + +## class `LogrotateConfig` +Configuration for logrotate. **Attributes:** - - `DAILY`: Rotate the log daily. - - `WEEKLY`: Rotate the log weekly. - - `MONTHLY`: Rotate the log monthly. - - `YEARLY`: Rotate the log yearly. + - `name`: The name of the logrotate configuration. + - `log_path_glob_pattern`: The glob pattern for the log path. + - `rotate`: The number of log files to keep. + - `create`: Whether to create the log file if it does not exist. + - `notifempty`: Whether to not rotate the log file if it is empty. + - `frequency`: The frequency of log rotation. diff --git a/src-docs/lxd.py.md b/src-docs/lxd.md similarity index 85% rename from src-docs/lxd.py.md rename to src-docs/lxd.md index 3e9bd771d..231905c85 100644 --- a/src-docs/lxd.py.md +++ b/src-docs/lxd.md @@ -2,7 +2,7 @@ -# module `lxd.py` +# module `lxd` Low-level LXD client interface. The LxdClient class offers a low-level interface to isolate the underlying implementation of LXD. @@ -14,98 +14,174 @@ The LxdClient class offers a low-level interface to isolate the underlying imple --- -## class `LxdClient` -LXD client. + + +## class `LxdInstanceFileManager` +File manager of an LXD instance. - -### function `__init__` + +**Attributes:** + + - `instance` (LxdInstance): LXD instance where the files are located in. + + + +### method `__init__` ```python -__init__() → None +__init__(instance: 'LxdInstance') ``` -Instantiate the LXD client. +Instantiate the file manager. + + +**Args:** + + - `instance`: LXD instance where the files are located in. --- -## class `LxdImageManager` -LXD image manager. + + +### method `mk_dir` + +```python +mk_dir(dir_name: 'str') → None +``` + +Create a directory in the LXD instance. - -### function `__init__` + +**Args:** + + - `dir_name`: Name of the directory to create. + +--- + + + +### method `pull_file` ```python -__init__(pylxd_client: 'Client') +pull_file(source: 'str', destination: 'str', is_dir: 'bool' = False) → None ``` -Instantiate the LXD image manager. +Pull a file from the LXD instance to the local machine. **Args:** - - `pylxd_client`: Instance of pylxd.Client. + - `source`: Path of the file to pull in the LXD instance. + - `destination`: Path in local machine. + - `is_dir`: Whether the source is a directory. +**Raises:** + + - `LxdError`: Unable to load the file from the LXD instance. --- - + -### function `create` +### method `push_file` ```python -create(name: 'str', path: 'Path') → None +push_file( + source: 'str', + destination: 'str', + mode: 'Optional[str]' = None +) → None ``` -Import a LXD image. +Push a file to the LXD instance. **Args:** - - `name`: Alias for the image. - - `path`: Path of the LXD image file. + - `source`: Path of the file to push to the LXD instance. + - `destination`: Path in the LXD instance to load the file. + - `mode`: File permissions. **Raises:** - - `LxdError`: Unable to import the file as LXD image. + - `LxdError`: Unable to load the file into the LXD instance. --- - + -### function `exists` +### method `read_file` ```python -exists(alias: 'str') → bool +read_file(filepath: 'str') → str ``` -Check if an image with the given name exists. +Read the content of a file in the LXD instance. **Args:** - - `alias`: Alias name of the image to check. + - `filepath`: Path of the file in the LXD instance. + + + +**Raises:** + + - `LxdError`: Unable to load the file from the LXD instance. **Returns:** - Whether the image exists. + The content of the file. + +--- + + + +### method `write_file` + +```python +write_file( + filepath: 'str', + content: 'Union[str, bytes]', + mode: 'Optional[str]' = None +) → None +``` + +Write a file with the given content into the LXD instance. + + + +**Args:** + + - `filepath`: Path in the LXD instance to load the file. + - `content`: Content of the file. + - `mode`: File permission setting. + + + +**Raises:** + + - `LxdError`: Unable to load the file to the LXD instance. --- + + ## class `LxdInstance` An LXD instance. @@ -119,7 +195,7 @@ An LXD instance. -### function `__init__` +### method `__init__` ```python __init__(pylxd_instance: 'Instance') @@ -151,7 +227,7 @@ Status of the LXD instance. -### function `delete` +### method `delete` ```python delete(wait: 'bool' = False) → None @@ -175,7 +251,7 @@ Delete the LXD instance. -### function `execute` +### method `execute` ```python execute( @@ -212,7 +288,7 @@ The command is executed with `subprocess.run`, additional arguments can be passe -### function `start` +### method `start` ```python start(timeout: 'int' = 30, force: 'bool' = True, wait: 'bool' = False) → None @@ -238,7 +314,7 @@ Start the LXD instance. -### function `stop` +### method `stop` ```python stop(timeout: 'int' = 30, force: 'bool' = True, wait: 'bool' = False) → None @@ -263,254 +339,260 @@ Stop the LXD instance. --- -## class `LxdInstanceFileManager` -File manager of an LXD instance. - - + -**Attributes:** - - - `instance` (LxdInstance): LXD instance where the files are located in. +## class `LxdInstanceManager` +LXD instance manager. - + -### function `__init__` +### method `__init__` ```python -__init__(instance: 'LxdInstance') +__init__(pylxd_client: 'Client') ``` -Instantiate the file manager. +Instantiate the LXD instance manager. **Args:** - - `instance`: LXD instance where the files are located in. + - `pylxd_client`: Instance of pylxd.Client. --- - + -### function `mk_dir` +### method `all` ```python -mk_dir(dir_name: 'str') → None +all() → list[LxdInstance] ``` -Create a directory in the LXD instance. +Get list of LXD instances. -**Args:** +**Raises:** - - `dir_name`: Name of the directory to create. + - `LxdError`: Unable to get all LXD instances. + + + +**Returns:** + List of LXD instances. --- - + -### function `pull_file` +### method `create` ```python -pull_file(source: 'str', destination: 'str', is_dir: 'bool' = False) → None +create(config: 'LxdInstanceConfig', wait: 'bool') → LxdInstance ``` -Pull a file from the LXD instance to the local machine. +Create an LXD instance. **Args:** - - `source`: Path of the file to pull in the LXD instance. - - `destination`: Path in local machine. - - `is_dir`: Whether the source is a directory. + - `config`: Configuration for the LXD instance. + - `wait`: Whether to wait until the LXD instance is created before returning. **Raises:** - - `LxdError`: Unable to load the file from the LXD instance. + - `LxdError`: Unable to get all LXD instances. + + + +**Returns:** + The created LXD instance. + --- - + -### function `push_file` +## class `LxdProfileManager` +LXD profile manager. + + + +### method `__init__` ```python -push_file( - source: 'str', - destination: 'str', - mode: 'Optional[str]' = None -) → None +__init__(pylxd_client: 'Client') ``` -Push a file to the LXD instance. +Instantiate the LXD profile manager. **Args:** - - `source`: Path of the file to push to the LXD instance. - - `destination`: Path in the LXD instance to load the file. - - `mode`: File permissions. + - `pylxd_client`: Instance of pylxd.Client. -**Raises:** - - - `LxdError`: Unable to load the file into the LXD instance. --- - + -### function `read_file` +### method `create` ```python -read_file(filepath: 'str') → str +create( + name: 'str', + config: 'LxdResourceProfileConfig', + devices: 'LxdResourceProfileDevices' +) → None ``` -Read the content of a file in the LXD instance. +Create an LXD profile. **Args:** - - `filepath`: Path of the file in the LXD instance. + - `name`: Name of the LXD profile to create. + - `config`: Configuration of the LXD profile. + - `devices`: Devices configuration of the LXD profile. **Raises:** - - `LxdError`: Unable to load the file from the LXD instance. - - - -**Returns:** - The content of the file. + - `LxdError`: Unable to create the LXD profile. --- - + -### function `write_file` +### method `exists` ```python -write_file( - filepath: 'str', - content: 'Union[str, bytes]', - mode: 'Optional[str]' = None -) → None +exists(name: 'str') → bool ``` -Write a file with the given content into the LXD instance. +Check whether an LXD profile of a given name exists. **Args:** - - `filepath`: Path in the LXD instance to load the file. - - `content`: Content of the file. - - `mode`: File permission setting. + - `name`: Name for LXD profile to check. **Raises:** - - `LxdError`: Unable to load the file to the LXD instance. + - `LxdError`: Unable to check the LXD profile existence. ---- -## class `LxdInstanceManager` -LXD instance manager. +**Returns:** + Whether the LXD profile of the given name exists. - +--- -### function `__init__` + + +### method `get` ```python -__init__(pylxd_client: 'Client') +get(name: 'str') → LxdProfile ``` -Instantiate the LXD instance manager. +Get an LXD profile. **Args:** - - `pylxd_client`: Instance of pylxd.Client. + - `name`: Name of the LXD profile. +**Raises:** + + - `LxdError`: Unable to get the LXD profile with the name. + + + +**Returns:** + LXDProfile with given name. + --- - + + +## class `LxdProfile` +LXD profile. + + -### function `all` +### method `__init__` ```python -all() → list[LxdInstance] +__init__(pylxd_profile: 'Profile') ``` -Get list of LXD instances. +Instantiate the LXD profile. -**Raises:** +**Args:** - - `LxdError`: Unable to get all LXD instances. + - `pylxd_profile`: Instance of the pylxd.models.Profile. -**Returns:** - List of LXD instances. --- - + -### function `create` +### method `delete` ```python -create(config: 'LxdInstanceConfig', wait: 'bool') → LxdInstance +delete() → None ``` -Create an LXD instance. - - - -**Args:** - - - `config`: Configuration for the LXD instance. - - `wait`: Whether to wait until the LXD instance is created before returning. - +Delete the profile. +--- -**Raises:** - - - `LxdError`: Unable to get all LXD instances. + +### method `save` +```python +save() → None +``` -**Returns:** - The created LXD instance. +Save the current configuration of profile. --- + + ## class `LxdNetworkManager` LXD network manager. -### function `__init__` +### method `__init__` ```python __init__(pylxd_client: 'Client') @@ -531,7 +613,7 @@ Instantiate the LXD profile manager. -### function `get` +### method `get` ```python get(name: 'str') → LxdNetwork @@ -553,168 +635,127 @@ Get the LXD network information. --- -## class `LxdProfile` -LXD profile. + - +## class `LxdStoragePoolManager` +LXD storage pool manager. + + -### function `__init__` +### method `__init__` ```python -__init__(pylxd_profile: 'Profile') +__init__(pylxd_client: 'Client') ``` -Instantiate the LXD profile. +Instantiate the LXD storage pool manager. **Args:** - - `pylxd_profile`: Instance of the pylxd.models.Profile. - - - - ---- - - - -### function `delete` - -```python -delete() → None -``` - -Delete the profile. - ---- - - - -### function `save` + - `pylxd_client`: Instance of pylxd.Client. -```python -save() → None -``` -Save the current configuration of profile. --- -## class `LxdProfileManager` -LXD profile manager. - - + -### function `__init__` +### method `all` ```python -__init__(pylxd_client: 'Client') +all() → list[LxdStoragePool] ``` -Instantiate the LXD profile manager. - - - -**Args:** - - - `pylxd_client`: Instance of pylxd.Client. +Get all LXD storage pool. +**Returns:** + List of LXD storage pools. --- - + -### function `create` +### method `create` ```python -create( - name: 'str', - config: 'LxdResourceProfileConfig', - devices: 'LxdResourceProfileDevices' -) → None +create(config: 'LxdStoragePoolConfiguration') → LxdStoragePool ``` -Create an LXD profile. +Create an LXD storage pool. **Args:** - - `name`: Name of the LXD profile to create. - - `config`: Configuration of the LXD profile. - - `devices`: Devices configuration of the LXD profile. + - `config`: Configuration for the storage pool. -**Raises:** - - - `LxdError`: Unable to create the LXD profile. +**Returns:** + The LXD storage pool. --- - + -### function `exists` +### method `exists` ```python exists(name: 'str') → bool ``` -Check whether an LXD profile of a given name exists. +Check if an LXD storage pool exists. **Args:** - - `name`: Name for LXD profile to check. - - - -**Raises:** - - - `LxdError`: Unable to check the LXD profile existence. + - `name`: Name to check for. **Returns:** - Whether the LXD profile of the given name exists. + Whether the storage pool exists. --- - + -### function `get` +### method `get` ```python -get(name: 'str') → LxdProfile +get(name: 'str') → LxdStoragePool ``` -Get an LXD profile. +Get an LXD storage pool. **Args:** - - `name`: Name of the LXD profile. + - `name`: Name of the storage pool. **Raises:** - - `LxdError`: Unable to get the LXD profile with the name. + - `LxdError`: If the storage pool with given name was not found. **Returns:** - LXDProfile with given name. + The LXD storage pool. --- + + ## class `LxdStoragePool` An LXD storage pool. @@ -730,7 +771,7 @@ An LXD storage pool. -### function `__init__` +### method `__init__` ```python __init__(pylxd_storage_pool: 'StoragePool') @@ -751,7 +792,7 @@ Instantiate the LXD storage pool. -### function `delete` +### method `delete` ```python delete() → None @@ -763,7 +804,7 @@ Delete the storage pool. -### function `save` +### method `save` ```python save() → None @@ -774,18 +815,20 @@ Save the current configuration of storage pool. --- -## class `LxdStoragePoolManager` -LXD storage pool manager. + - +## class `LxdImageManager` +LXD image manager. -### function `__init__` + + +### method `__init__` ```python __init__(pylxd_client: 'Client') ``` -Instantiate the LXD storage pool manager. +Instantiate the LXD image manager. @@ -798,94 +841,71 @@ Instantiate the LXD storage pool manager. --- - - -### function `all` - -```python -all() → list[LxdStoragePool] -``` - -Get all LXD storage pool. - - - -**Returns:** - List of LXD storage pools. - ---- - - + -### function `create` +### method `create` ```python -create(config: 'LxdStoragePoolConfiguration') → LxdStoragePool +create(name: 'str', path: 'Path') → None ``` -Create an LXD storage pool. +Import a LXD image. **Args:** - - `config`: Configuration for the storage pool. + - `name`: Alias for the image. + - `path`: Path of the LXD image file. -**Returns:** - The LXD storage pool. +**Raises:** + + - `LxdError`: Unable to import the file as LXD image. --- - + -### function `exists` +### method `exists` ```python -exists(name: 'str') → bool +exists(alias: 'str') → bool ``` -Check if an LXD storage pool exists. +Check if an image with the given name exists. **Args:** - - `name`: Name to check for. + - `alias`: Alias name of the image to check. **Returns:** - Whether the storage pool exists. - ---- - - - -### function `get` + Whether the image exists. -```python -get(name: 'str') → LxdStoragePool -``` -Get an LXD storage pool. +--- + +## class `LxdClient` +LXD client. -**Args:** - - - `name`: Name of the storage pool. + +### method `__init__` +```python +__init__() → None +``` -**Raises:** - - - `LxdError`: If the storage pool with given name was not found. +Instantiate the LXD client. -**Returns:** - The LXD storage pool. diff --git a/src-docs/lxd_type.py.md b/src-docs/lxd_type.md similarity index 65% rename from src-docs/lxd_type.py.md rename to src-docs/lxd_type.md index 0b4ec54bb..b34f99406 100644 --- a/src-docs/lxd_type.py.md +++ b/src-docs/lxd_type.md @@ -2,7 +2,7 @@ -# module `lxd_type.py` +# module `lxd_type` Types used by Lxd class. The details of the configuration of different types of devices can be found here: https://linuxcontainers.org/lxd/docs/latest/reference/devices/ @@ -15,20 +15,32 @@ The unit of storage and network limits can be found here: https://linuxcontainer --- -## class `LxdInstanceConfig` -Configuration for the LXD instance. + -See https://documentation.ubuntu.com/lxd/en/latest/howto/instances_create/ +## class `LxdNetworkConfig` +Represent LXD network configuration. -**Attributes:** - - - `name`: Name of the instance. - - `type`: Instance type, i.e. "container" or "virtual-machine". - - `source`: Instance creation source configuration. - - `ephemeral`: Whether the container should be deleted after a single run. - - `profiles`: List of LXD profiles applied to the instance. + + +--- + + + +## class `LxdResourceProfileConfig` +Configuration LXD profile. + + + + + +--- + + + +## class `LxdResourceProfileDevicesDisk` +LXD device profile of disk. @@ -36,6 +48,8 @@ See https://documentation.ubuntu.com/lxd/en/latest/howto/instances_create/ --- + + ## class `LxdInstanceConfigSource` Configuration for source image in the LXD instance. @@ -54,19 +68,22 @@ Configuration for source image in the LXD instance. --- -## class `LxdNetwork` -LXD network information. + + +## class `LxdInstanceConfig` +Configuration for the LXD instance. + +See https://documentation.ubuntu.com/lxd/en/latest/howto/instances_create/ **Attributes:** - - `name`: The name of LXD network. - - `description`: LXD network descriptor. - - `type`: Network type, i.e. "bridge", "physical" - - `config`: The LXD network configuration values. - - `managed`: Whether the network is being managed by lxd. - - `used_by`: Number of instances using the network. + - `name`: Name of the instance. + - `type`: Instance type, i.e. "container" or "virtual-machine". + - `source`: Instance creation source configuration. + - `ephemeral`: Whether the container should be deleted after a single run. + - `profiles`: List of LXD profiles applied to the instance. @@ -74,26 +91,36 @@ LXD network information. --- -## class `LxdNetworkConfig` -Represent LXD network configuration. + + +## class `LxdStoragePoolConfig` +Configuration of the storage pool. +**Attributes:** + + - `source`: The storage pool configuration source image. + - `size`: The size of the storage pool, e.g. 30GiB ---- -## class `LxdResourceProfileConfig` -Configuration LXD profile. +--- + +## class `LxdStoragePoolConfiguration` +Configuration for LXD storage pool. ---- -## class `LxdResourceProfileDevicesDisk` -LXD device profile of disk. + +**Attributes:** + + - `name`: The storage pool name. + - `driver`: The storage driver being used, i.e. "dir", "btrfs", ... . See https://documentation.ubuntu.com/lxd/en/stable-5.0/reference/storage_drivers/ for more information. + - `config`: The storage pool configuration. @@ -101,32 +128,40 @@ LXD device profile of disk. --- -## class `LxdStoragePoolConfig` -Configuration of the storage pool. + + +## class `LxdNetwork` +LXD network information. **Attributes:** - - `source`: The storage pool configuration source image. - - `size`: The size of the storage pool, e.g. 30GiB - - + - `name`: The name of LXD network. + - `description`: LXD network descriptor. + - `type`: Network type, i.e. "bridge", "physical" + - `config`: The LXD network configuration values. + - `managed`: Whether the network is being managed by lxd. + - `used_by`: Number of instances using the network. + +### method `__init__` ---- +```python +__init__( + name: str, + description: str, + type: str, + config: LxdNetworkConfig, + managed: bool, + used_by: tuple[str] +) → None +``` -## class `LxdStoragePoolConfiguration` -Configuration for LXD storage pool. -**Attributes:** - - - `name`: The storage pool name. - - `driver`: The storage driver being used, i.e. "dir", "btrfs", ... . See https://documentation.ubuntu.com/lxd/en/stable-5.0/reference/storage_drivers/ for more information. - - `config`: The storage pool configuration. diff --git a/src-docs/events.md b/src-docs/metrics.events.md similarity index 99% rename from src-docs/events.md rename to src-docs/metrics.events.md index d93c52eec..3e44869d6 100644 --- a/src-docs/events.md +++ b/src-docs/metrics.events.md @@ -2,7 +2,7 @@ -# module `events` +# module `metrics.events` Models and functions for the metric events. **Global Variables** diff --git a/src-docs/github.md b/src-docs/metrics.github.md similarity index 96% rename from src-docs/github.md rename to src-docs/metrics.github.md index 7d6124e0a..30e6981eb 100644 --- a/src-docs/github.md +++ b/src-docs/metrics.github.md @@ -2,7 +2,7 @@ -# module `github` +# module `metrics.github` Functions to calculate metrics from data retrieved from GitHub. diff --git a/src-docs/metrics.md b/src-docs/metrics.md new file mode 100644 index 000000000..6348a9eed --- /dev/null +++ b/src-docs/metrics.md @@ -0,0 +1,29 @@ + + + + +# module `metrics` +Package for common metrics-related code. + +**Global Variables** +--------------- +- **events**: # Copyright 2024 Canonical Ltd. +# See LICENSE file for licensing details. + +- **runner_logs**: # Copyright 2024 Canonical Ltd. +# See LICENSE file for licensing details. + +- **storage**: # Copyright 2024 Canonical Ltd. +# See LICENSE file for licensing details. + +- **type**: # Copyright 2024 Canonical Ltd. +# See LICENSE file for licensing details. + +- **runner**: # Copyright 2024 Canonical Ltd. +# See LICENSE file for licensing details. + +- **github**: # Copyright 2024 Canonical Ltd. +# See LICENSE file for licensing details. + + + diff --git a/src-docs/metrics.runner.md b/src-docs/metrics.runner.md new file mode 100644 index 000000000..edf8f0a65 --- /dev/null +++ b/src-docs/metrics.runner.md @@ -0,0 +1,174 @@ + + + + +# module `metrics.runner` +Classes and function to extract the metrics from storage and issue runner metrics events. + +**Global Variables** +--------------- +- **FILE_SIZE_BYTES_LIMIT** +- **PRE_JOB_METRICS_FILE_NAME** +- **POST_JOB_METRICS_FILE_NAME** +- **RUNNER_INSTALLED_TS_FILE_NAME** + +--- + + + +## function `extract` + +```python +extract( + metrics_storage_manager: StorageManager, + ignore_runners: set[str] +) → Iterator[RunnerMetrics] +``` + +Extract metrics from runners. + +The metrics are extracted from the metrics storage of the runners. Orphan storages are cleaned up. + +If corrupt data is found, the metrics are not processed further and the storage is moved to a special quarantine directory, as this may indicate that a malicious runner is trying to manipulate the files on the storage. + +In order to avoid DoS attacks, the file size is also checked. + + + +**Args:** + + - `metrics_storage_manager`: The metrics storage manager. + - `ignore_runners`: The set of runners to ignore. + + + +**Yields:** + Extracted runner metrics of a particular runner. + + +--- + + + +## function `issue_events` + +```python +issue_events( + runner_metrics: RunnerMetrics, + flavor: str, + job_metrics: Optional[GithubJobMetrics] +) → set[Type[Event]] +``` + +Issue the metrics events for a runner. + + + +**Args:** + + - `runner_metrics`: The metrics for the runner. + - `flavor`: The flavor of the runner. + - `job_metrics`: The metrics about the job run by the runner. + + + +**Returns:** + A set of issued events. + + +--- + + + +## class `PreJobMetrics` +Metrics for the pre-job phase of a runner. + + + +**Attributes:** + + - `timestamp`: The UNIX time stamp of the time at which the event was originally issued. + - `workflow`: The workflow name. + - `workflow_run_id`: The workflow run id. + - `repository`: The repository path in the format '/'. + - `event`: The github event. + + + + + +--- + + + +## class `PostJobStatus` +The status of the post-job phase of a runner. + + + +**Attributes:** + + - `NORMAL`: Represents a normal post-job. + - `ABNORMAL`: Represents an error with post-job. + - `REPO_POLICY_CHECK_FAILURE`: Represents an error with repo-policy-compliance check. + + + + + +--- + + + +## class `CodeInformation` +Information about a status code. + + + +**Attributes:** + + - `code`: The status code. + + + + + +--- + + + +## class `PostJobMetrics` +Metrics for the post-job phase of a runner. + + + +**Attributes:** + + - `timestamp`: The UNIX time stamp of the time at which the event was originally issued. + - `status`: The status of the job. + - `status_info`: More information about the status. + + + + + +--- + + + +## class `RunnerMetrics` +Metrics for a runner. + + + +**Attributes:** + + - `installed_timestamp`: The UNIX time stamp of the time at which the runner was installed. + - `pre_job`: The metrics for the pre-job phase. + - `post_job`: The metrics for the post-job phase. + - `runner_name`: The name of the runner. + + + + + diff --git a/src-docs/runner_logs.md b/src-docs/metrics.runner_logs.md similarity index 94% rename from src-docs/runner_logs.md rename to src-docs/metrics.runner_logs.md index ff647d964..45d224bac 100644 --- a/src-docs/runner_logs.md +++ b/src-docs/metrics.runner_logs.md @@ -2,7 +2,7 @@ -# module `runner_logs` +# module `metrics.runner_logs` Functions to pull and remove the logs of the crashed runners. diff --git a/src-docs/storage.md b/src-docs/metrics.storage.md similarity index 99% rename from src-docs/storage.md rename to src-docs/metrics.storage.md index fdcb9932b..20250cd09 100644 --- a/src-docs/storage.md +++ b/src-docs/metrics.storage.md @@ -2,7 +2,7 @@ -# module `storage` +# module `metrics.storage` Classes and functions defining the metrics storage. It contains a protocol and reference implementation. diff --git a/src-docs/type.md b/src-docs/metrics.type.md similarity index 94% rename from src-docs/type.md rename to src-docs/metrics.type.md index eb3fce2f5..1e5e61e67 100644 --- a/src-docs/type.md +++ b/src-docs/metrics.type.md @@ -2,7 +2,7 @@ -# module `type` +# module `metrics.type` Data types used by modules handling metrics. diff --git a/src-docs/openstack_cloud.md b/src-docs/openstack_cloud.md new file mode 100644 index 000000000..8e26f7ba8 --- /dev/null +++ b/src-docs/openstack_cloud.md @@ -0,0 +1,57 @@ + + + + +# module `openstack_cloud` +Module for managing Openstack cloud. + +**Global Variables** +--------------- +- **openstack_manager**: # Copyright 2024 Canonical Ltd. +# See LICENSE file for licensing details. + + +--- + + + +## function `initialize` + +```python +initialize(cloud_config: dict) → None +``` + +Initialize Openstack integration. + +Validates config and writes it to disk. + + + +**Raises:** + + - `OpenStackInvalidConfigError`: If there was an given cloud config. + + + +**Args:** + + - `cloud_config`: The configuration in clouds.yaml format to apply. + + +--- + + + +## class `CloudConfig` +The parsed clouds.yaml configuration dictionary. + + + +**Attributes:** + + - `clouds`: A mapping of key "clouds" to cloud name mapped to cloud configuration. + + + + + diff --git a/src-docs/openstack_manager.md b/src-docs/openstack_cloud.openstack_manager.md similarity index 98% rename from src-docs/openstack_manager.md rename to src-docs/openstack_cloud.openstack_manager.md index 95936c56b..e6161a8eb 100644 --- a/src-docs/openstack_manager.md +++ b/src-docs/openstack_cloud.openstack_manager.md @@ -2,7 +2,7 @@ -# module `openstack_manager` +# module `openstack_cloud.openstack_manager` Module for handling interactions with OpenStack. **Global Variables** diff --git a/src-docs/job.md b/src-docs/reactive.job.md similarity index 99% rename from src-docs/job.md rename to src-docs/reactive.job.md index 3a6d87372..b47017579 100644 --- a/src-docs/job.md +++ b/src-docs/reactive.job.md @@ -2,7 +2,7 @@ -# module `job` +# module `reactive.job` Module responsible for job retrieval and handling. diff --git a/src-docs/reactive.md b/src-docs/reactive.md new file mode 100644 index 000000000..d3453c979 --- /dev/null +++ b/src-docs/reactive.md @@ -0,0 +1,14 @@ + + + + +# module `reactive` +Package for code implementing reactive scheduling. + +**Global Variables** +--------------- +- **runner_manager**: # Copyright 2024 Canonical Ltd. +# See LICENSE file for licensing details. + + + diff --git a/src-docs/reactive.runner.md b/src-docs/reactive.runner.md new file mode 100644 index 000000000..283e336ce --- /dev/null +++ b/src-docs/reactive.runner.md @@ -0,0 +1,28 @@ + + + + +# module `reactive.runner` +Module which contains code to spawn a runner reactively. + + +--- + + + +## function `reactive_runner` + +```python +reactive_runner(mq_uri: str, queue_name: str) → None +``` + +Spawn a runner reactively. + + + +**Args:** + + - `mq_uri`: The URI of the message queue. + - `queue_name`: The name of the queue. + + diff --git a/src-docs/reactive.runner_manager.md b/src-docs/reactive.runner_manager.md new file mode 100644 index 000000000..82308e9a9 --- /dev/null +++ b/src-docs/reactive.runner_manager.md @@ -0,0 +1,84 @@ + + + + +# module `reactive.runner_manager` +Module for managing reactive runners. + +**Global Variables** +--------------- +- **REACTIVE_RUNNER_SCRIPT_FILE** +- **REACTIVE_RUNNER_TIMEOUT_STR** +- **PYTHON_BIN** +- **PS_COMMAND_LINE_LIST** +- **TIMEOUT_COMMAND** +- **UBUNTU_USER** + +--- + + + +## function `reconcile` + +```python +reconcile(quantity: int, config: ReactiveRunnerConfig) → int +``` + +Spawn a runner reactively. + + + +**Args:** + + - `quantity`: The number of runners to spawn. + - `config`: The configuration for the reactive runner. + +Raises a ReactiveRunnerError if the runner fails to spawn. + + + +**Returns:** + The number of runners spawned. + + +--- + + + +## class `ReactiveRunnerError` +Raised when a reactive runner error occurs. + + + + + +--- + + + +## class `ReactiveRunnerConfig` +Configuration for spawning a reactive runner. + + + +**Attributes:** + + - `mq_uri`: The message queue URI. + - `queue_name`: The name of the queue. + + + +### method `__init__` + +```python +__init__(mq_uri: str, queue_name: str) → None +``` + + + + + + + + + diff --git a/src-docs/repo_policy_compliance_client.py.md b/src-docs/repo_policy_compliance_client.md similarity index 83% rename from src-docs/repo_policy_compliance_client.py.md rename to src-docs/repo_policy_compliance_client.md index 1be88e499..01823750c 100644 --- a/src-docs/repo_policy_compliance_client.py.md +++ b/src-docs/repo_policy_compliance_client.md @@ -2,13 +2,15 @@ -# module `repo_policy_compliance_client.py` +# module `repo_policy_compliance_client` Client for requesting repo policy compliance service. --- + + ## class `RepoPolicyComplianceClient` Client for repo policy compliance service. @@ -21,7 +23,7 @@ Client for repo policy compliance service. -### function `__init__` +### method `__init__` ```python __init__(url: str, charm_token: str) → None @@ -43,7 +45,7 @@ Construct the RepoPolicyComplianceClient. -### function `get_one_time_token` +### method `get_one_time_token` ```python get_one_time_token() → str diff --git a/src-docs/runner.md b/src-docs/runner.md index f23d2e4bd..d7bfb93c1 100644 --- a/src-docs/runner.md +++ b/src-docs/runner.md @@ -1,123 +1,72 @@ - + # module `runner` -Module which contains code to spawn a runner reactively. +Manage the lifecycle of runners. + +The `Runner` class stores the information on the runners and manages the lifecycle of the runners on LXD and GitHub. + +The `RunnerManager` class from `runner_manager.py` creates and manages a collection of `Runner` instances. **Global Variables** --------------- - **APROXY_ARM_REVISION** - **APROXY_AMD_REVISION** -- **FILE_SIZE_BYTES_LIMIT** -- **PRE_JOB_METRICS_FILE_NAME** -- **POST_JOB_METRICS_FILE_NAME** -- **RUNNER_INSTALLED_TS_FILE_NAME** - ---- - - - -## function `reactive_runner` - -```python -reactive_runner(mq_uri: str, queue_name: str) → None -``` - -Spawn a runner reactively. - - - -**Args:** - - - `mq_uri`: The URI of the message queue. - - `queue_name`: The name of the queue. --- - - -## function `extract` - -```python -extract( - metrics_storage_manager: StorageManager, - ignore_runners: set[str] -) → Iterator[RunnerMetrics] -``` - -Extract metrics from runners. - -The metrics are extracted from the metrics storage of the runners. Orphan storages are cleaned up. - -If corrupt data is found, the metrics are not processed further and the storage is moved to a special quarantine directory, as this may indicate that a malicious runner is trying to manipulate the files on the storage. + -In order to avoid DoS attacks, the file size is also checked. +## class `Snap` +This class represents a snap installation. -**Args:** +**Attributes:** - - `metrics_storage_manager`: The metrics storage manager. - - `ignore_runners`: The set of runners to ignore. + - `name`: The snap application name. + - `channel`: The channel to install the snap from. + - `revision`: The revision number of the snap installation. -**Yields:** - Extracted runner metrics of a particular runner. --- - + -## function `issue_events` - -```python -issue_events( - runner_metrics: RunnerMetrics, - flavor: str, - job_metrics: Optional[GithubJobMetrics] -) → set[Type[Event]] -``` - -Issue the metrics events for a runner. +## class `WgetExecutable` +The executable to be installed through wget. -**Args:** +**Attributes:** - - `runner_metrics`: The metrics for the runner. - - `flavor`: The flavor of the runner. - - `job_metrics`: The metrics about the job run by the runner. - + - `url`: The URL of the executable binary. + - `cmd`: Executable command name. E.g. yq_linux_amd64 -> yq + -**Returns:** - A set of issued events. +### method `__init__` +```python +__init__(url: str, cmd: str) → None +``` ---- - -## class `CodeInformation` -Information about a status code. -**Attributes:** - - - `code`: The status code. - - --- - + ## class `CreateRunnerConfig` The configuration values for creating a single runner instance. @@ -156,66 +105,7 @@ __init__( --- - - -## class `PostJobMetrics` -Metrics for the post-job phase of a runner. - - - -**Attributes:** - - - `timestamp`: The UNIX time stamp of the time at which the event was originally issued. - - `status`: The status of the job. - - `status_info`: More information about the status. - - - - - ---- - - - -## class `PostJobStatus` -The status of the post-job phase of a runner. - - - -**Attributes:** - - - `NORMAL`: Represents a normal post-job. - - `ABNORMAL`: Represents an error with post-job. - - `REPO_POLICY_CHECK_FAILURE`: Represents an error with repo-policy-compliance check. - - - - - ---- - - - -## class `PreJobMetrics` -Metrics for the pre-job phase of a runner. - - - -**Attributes:** - - - `timestamp`: The UNIX time stamp of the time at which the event was originally issued. - - `workflow`: The workflow name. - - `workflow_run_id`: The workflow run id. - - `repository`: The repository path in the format '/'. - - `event`: The github event. - - - - - ---- - - + ## class `Runner` Single instance of GitHub self-hosted runner. @@ -326,72 +216,3 @@ Remove this runner instance from LXD and GitHub. - `RunnerRemoveError`: Failure in removing runner. ---- - - - -## class `RunnerMetrics` -Metrics for a runner. - - - -**Attributes:** - - - `installed_timestamp`: The UNIX time stamp of the time at which the runner was installed. - - `pre_job`: The metrics for the pre-job phase. - - `post_job`: The metrics for the post-job phase. - - `runner_name`: The name of the runner. - - - - - ---- - - - -## class `Snap` -This class represents a snap installation. - - - -**Attributes:** - - - `name`: The snap application name. - - `channel`: The channel to install the snap from. - - `revision`: The revision number of the snap installation. - - - - - ---- - - - -## class `WgetExecutable` -The executable to be installed through wget. - - - -**Attributes:** - - - `url`: The URL of the executable binary. - - `cmd`: Executable command name. E.g. yq_linux_amd64 -> yq - - - -### method `__init__` - -```python -__init__(url: str, cmd: str) → None -``` - - - - - - - - - diff --git a/src-docs/runner.py.md b/src-docs/runner.py.md deleted file mode 100644 index 96e5102d2..000000000 --- a/src-docs/runner.py.md +++ /dev/null @@ -1,180 +0,0 @@ - - - - -# module `runner.py` -Manage the lifecycle of runners. - -The `Runner` class stores the information on the runners and manages the lifecycle of the runners on LXD and GitHub. - -The `RunnerManager` class from `runner_manager.py` creates and manages a collection of `Runner` instances. - -**Global Variables** ---------------- -- **APROXY_ARM_REVISION** -- **APROXY_AMD_REVISION** - - ---- - -## class `CreateRunnerConfig` -The configuration values for creating a single runner instance. - - - -**Attributes:** - - - `image`: Name of the image to launch the LXD instance with. - - `resources`: Resource setting for the LXD instance. - - `binary_path`: Path to the runner binary. - - `registration_token`: Token for registering the runner on GitHub. - - `arch`: Current machine architecture. - - - - - ---- - -## class `Runner` -Single instance of GitHub self-hosted runner. - - - -**Attributes:** - - - `runner_application`: The runner application directory path - - `env_file`: The runner environment source .env file path. - - `config_script`: The runner configuration script file path. - - `runner_script`: The runner start script file path. - - `pre_job_script`: The runner pre_job script file path. This is referenced in the env_file in the ACTIONS_RUNNER_HOOK_JOB_STARTED environment variable. - - - -### function `__init__` - -```python -__init__( - clients: RunnerManagerClients, - runner_config: RunnerConfig, - runner_status: RunnerStatus, - instance: Optional[LxdInstance] = None -) -``` - -Construct the runner instance. - - - -**Args:** - - - `clients`: Clients to access various services. - - `runner_config`: Configuration of the runner instance. - - `runner_status`: Status info of the given runner. - - `instance`: LXD instance of the runner if already created. - - - - ---- - - - -### function `create` - -```python -create(config: CreateRunnerConfig) → None -``` - -Create the runner instance on LXD and register it on GitHub. - - - -**Args:** - - - `config`: The instance config to create the LXD VMs and configure GitHub runner with. - - - -**Raises:** - - - `RunnerCreateError`: Unable to create an LXD instance for runner. - ---- - - - -### function `pull_logs` - -```python -pull_logs() → None -``` - -Pull the logs of the runner into a directory. - -Expects the runner to have an instance. - - - -**Raises:** - - - `RunnerLogsError`: If the runner logs could not be pulled. - ---- - - - -### function `remove` - -```python -remove(remove_token: Optional[str]) → None -``` - -Remove this runner instance from LXD and GitHub. - - - -**Args:** - - - `remove_token`: Token for removing the runner on GitHub. - - - -**Raises:** - - - `RunnerRemoveError`: Failure in removing runner. - - ---- - -## class `Snap` -This class represents a snap installation. - - - -**Attributes:** - - - `name`: The snap application name. - - `channel`: The channel to install the snap from. - - `revision`: The revision number of the snap installation. - - - - - ---- - -## class `WgetExecutable` -The executable to be installed through wget. - - - -**Attributes:** - - - `url`: The URL of the executable binary. - - `cmd`: Executable command name. E.g. yq_linux_amd64 -> yq - - - - - diff --git a/src-docs/runner_manager.md b/src-docs/runner_manager.md index f4a28eecc..38f501499 100644 --- a/src-docs/runner_manager.md +++ b/src-docs/runner_manager.md @@ -1,51 +1,19 @@ - + # module `runner_manager` -Module for managing reactive runners. +Runner Manager manages the runners on LXD and GitHub. **Global Variables** --------------- - **RUNNER_INSTALLED_TS_FILE_NAME** - **REMOVED_RUNNER_LOG_STR** -- **REACTIVE_RUNNER_SCRIPT_FILE** -- **REACTIVE_RUNNER_TIMEOUT_STR** -- **PYTHON_BIN** -- **PS_COMMAND_LINE_LIST** -- **TIMEOUT_COMMAND** -- **UBUNTU_USER** - ---- - - - -## function `reconcile` - -```python -reconcile(quantity: int, config: ReactiveRunnerConfig) → int -``` - -Spawn a runner reactively. - - - -**Args:** - - - `quantity`: The number of runners to spawn. - - `config`: The configuration for the reactive runner. - -Raises a ReactiveRunnerError if the runner fails to spawn. - - - -**Returns:** - The number of runners spawned. --- - + ## class `RunnerManager` Manage a group of runners according to configuration. @@ -276,44 +244,3 @@ Remove the existing runner binary to prevent it from being used. This is done to - `RunnerBinaryError`: If there was an error updating runner binary info. ---- - - - -## class `ReactiveRunnerError` -Raised when a reactive runner error occurs. - - - - - ---- - - - -## class `ReactiveRunnerConfig` -Configuration for spawning a reactive runner. - - - -**Attributes:** - - - `mq_uri`: The message queue URI. - - `queue_name`: The name of the queue. - - - -### method `__init__` - -```python -__init__(mq_uri: str, queue_name: str) → None -``` - - - - - - - - - diff --git a/src-docs/runner_manager.py.md b/src-docs/runner_manager.py.md deleted file mode 100644 index 77164e812..000000000 --- a/src-docs/runner_manager.py.md +++ /dev/null @@ -1,244 +0,0 @@ - - - - -# module `runner_manager.py` -Runner Manager manages the runners on LXD and GitHub. - -**Global Variables** ---------------- -- **RUNNER_INSTALLED_TS_FILE_NAME** -- **REMOVED_RUNNER_LOG_STR** - - ---- - -## class `RunnerManager` -Manage a group of runners according to configuration. - - - -**Attributes:** - - - `runner_bin_path`: The github runner app scripts path. - - `cron_path`: The path to runner build image cron job. - - - -### function `__init__` - -```python -__init__( - app_name: str, - unit: int, - runner_manager_config: RunnerManagerConfig -) → None -``` - -Construct RunnerManager object for creating and managing runners. - - - -**Args:** - - - `app_name`: An name for the set of runners. - - `unit`: Unit number of the set of runners. - - `runner_manager_config`: Configuration for the runner manager. - - - - ---- - - - -### function `build_runner_image` - -```python -build_runner_image() → None -``` - -Build the LXD image for hosting runner. - -Build container image in test mode, else virtual machine image. - - - -**Raises:** - - - `SubprocessError`: Unable to build the LXD image. - ---- - - - -### function `check_runner_bin` - -```python -check_runner_bin() → bool -``` - -Check if runner binary exists. - - - -**Returns:** - Whether runner bin exists. - ---- - - - -### function `flush` - -```python -flush(mode: FlushMode = ) → int -``` - -Remove existing runners. - - - -**Args:** - - - `mode`: Strategy for flushing runners. - - - -**Raises:** - - - `GithubClientError`: If there was an error getting remove-token to unregister runners from GitHub. - - - -**Returns:** - Number of runners removed. - ---- - - - -### function `get_github_info` - -```python -get_github_info() → Iterator[RunnerInfo] -``` - -Get information on the runners from GitHub. - - - -**Returns:** - List of information from GitHub on runners. - ---- - - - -### function `get_latest_runner_bin_url` - -```python -get_latest_runner_bin_url(os_name: str = 'linux') → RunnerApplication -``` - -Get the URL for the latest runner binary. - -The runner binary URL changes when a new version is available. - - - -**Args:** - - - `os_name`: Name of operating system. - - - -**Raises:** - - - `RunnerBinaryError`: If an error occurred while fetching runner application info. - - - -**Returns:** - Information on the runner application. - ---- - - - -### function `has_runner_image` - -```python -has_runner_image() → bool -``` - -Check if the runner image exists. - - - -**Returns:** - Whether the runner image exists. - ---- - - - -### function `reconcile` - -```python -reconcile(quantity: int, resources: VirtualMachineResources) → int -``` - -Bring runners in line with target. - - - -**Args:** - - - `quantity`: Number of intended runners. - - `resources`: Configuration of the virtual machine resources. - - - -**Returns:** - Difference between intended runners and actual runners. - ---- - - - -### function `schedule_build_runner_image` - -```python -schedule_build_runner_image() → None -``` - -Install cron job for building runner image. - ---- - - - -### function `update_runner_bin` - -```python -update_runner_bin(binary: RunnerApplication) → None -``` - -Download a runner file, replacing the current copy. - -Remove the existing runner binary to prevent it from being used. This is done to prevent security issues arising from outdated runner binaries containing security flaws. The newest version of runner binary should always be used. - - - -**Args:** - - - `binary`: Information on the runner binary to download. - - - -**Raises:** - - - `RunnerBinaryError`: If there was an error updating runner binary info. - - diff --git a/src-docs/runner_manager_type.py.md b/src-docs/runner_manager_type.md similarity index 58% rename from src-docs/runner_manager_type.py.md rename to src-docs/runner_manager_type.md index 20e91e885..c3509b433 100644 --- a/src-docs/runner_manager_type.py.md +++ b/src-docs/runner_manager_type.md @@ -2,13 +2,15 @@ -# module `runner_manager_type.py` +# module `runner_manager_type` Types used by RunnerManager class. --- + + ## class `FlushMode` Strategy for flushing runners. @@ -28,22 +30,36 @@ Strategy for flushing runners. --- -## class `OpenstackRunnerManagerConfig` -Configuration of runner manager. + + +## class `RunnerManagerClients` +Clients for accessing various services. **Attributes:** - - `charm_state`: The state of the charm. - - `path`: GitHub repository path in the format '/', or the GitHub organization name. - - `labels`: Additional labels for the runners. - - `token`: GitHub personal access token to register runner to the repository or organization. - - `flavor`: OpenStack flavor for defining the runner resources. - - `image`: Openstack image id to boot the runner with. - - `network`: OpenStack network for runner network access. - - `dockerhub_mirror`: URL of dockerhub mirror to use. - - `reactive_config`: The configuration to spawn runners reactively. + - `github`: Used to query GitHub API. + - `jinja`: Used for templating. + - `lxd`: Used to interact with LXD API. + - `repo`: Used to interact with repo-policy-compliance API. + + + +### method `__init__` + +```python +__init__( + github: GithubClient, + jinja: Environment, + lxd: LxdClient, + repo: RepoPolicyComplianceClient +) → None +``` + + + + @@ -51,66 +67,132 @@ Configuration of runner manager. --- -## class `RunnerInfo` -Information from GitHub of a runner. + -Used as a returned type to method querying runner information. +## class `RunnerManagerConfig` +Configuration of runner manager. **Attributes:** - - `name`: Name of the runner. - - `status`: Status of the runner. - - `busy`: Whether the runner has taken a job. + - `are_metrics_enabled`: Whether metrics for the runners should be collected. + - `charm_state`: The state of the charm. + - `image`: Name of the image for creating LXD instance. + - `lxd_storage_path`: Path to be used as LXD storage. + - `path`: GitHub repository path in the format '/', or the GitHub organization name. + - `service_token`: Token for accessing local service. + - `token`: GitHub personal access token to register runner to the repository or organization. + - `dockerhub_mirror`: URL of dockerhub mirror to use. + - `reactive_config`: The configuration to spawn runners reactively. + +### method `__init__` +```python +__init__( + charm_state: CharmState, + image: str, + lxd_storage_path: Path, + path: GithubOrg | GithubRepo, + service_token: str, + token: str, + dockerhub_mirror: str | None = None, + reactive_config: ReactiveConfig | None = None +) → None +``` ---- -## class `RunnerManagerClients` -Clients for accessing various services. -**Attributes:** - - - `github`: Used to query GitHub API. - - `jinja`: Used for templating. - - `lxd`: Used to interact with LXD API. - - `repo`: Used to interact with repo-policy-compliance API. +--- +#### property are_metrics_enabled + +Whether metrics for the runners should be collected. --- -## class `RunnerManagerConfig` + + +## class `OpenstackRunnerManagerConfig` Configuration of runner manager. **Attributes:** - - `are_metrics_enabled`: Whether metrics for the runners should be collected. - `charm_state`: The state of the charm. - - `image`: Name of the image for creating LXD instance. - - `lxd_storage_path`: Path to be used as LXD storage. - `path`: GitHub repository path in the format '/', or the GitHub organization name. - - `service_token`: Token for accessing local service. + - `labels`: Additional labels for the runners. - `token`: GitHub personal access token to register runner to the repository or organization. + - `flavor`: OpenStack flavor for defining the runner resources. + - `image`: Openstack image id to boot the runner with. + - `network`: OpenStack network for runner network access. - `dockerhub_mirror`: URL of dockerhub mirror to use. - `reactive_config`: The configuration to spawn runners reactively. + + +### method `__init__` + +```python +__init__( + charm_state: CharmState, + path: GithubOrg | GithubRepo, + labels: Iterable[str], + token: str, + flavor: str, + image: str, + network: str, + dockerhub_mirror: str | None, + reactive_config: ReactiveConfig | None = None +) → None +``` + + + + + + + + --- -#### property are_metrics_enabled + + +## class `RunnerInfo` +Information from GitHub of a runner. + +Used as a returned type to method querying runner information. + + + +**Attributes:** + + - `name`: Name of the runner. + - `status`: Status of the runner. + - `busy`: Whether the runner has taken a job. + + + +### method `__init__` + +```python +__init__(name: str, status: GitHubRunnerStatus, busy: bool) → None +``` + + + + -Whether metrics for the runners should be collected. diff --git a/src-docs/runner_type.md b/src-docs/runner_type.md new file mode 100644 index 000000000..481a17a62 --- /dev/null +++ b/src-docs/runner_type.md @@ -0,0 +1,192 @@ + + + + +# module `runner_type` +Types used by Runner class. + + + +--- + + + +## class `RunnerByHealth` +Set of runners instance by health state. + + + +**Attributes:** + + - `healthy`: Runners that are correctly running runner script. + - `unhealthy`: Runners that are not running runner script. + + + +### method `__init__` + +```python +__init__(healthy: tuple[str, ], unhealthy: tuple[str, ]) → None +``` + + + + + + + + + +--- + + + +## class `ProxySetting` +Represent HTTP-related proxy settings. + + + +**Attributes:** + + - `no_proxy`: The comma separated URLs to not go through proxy. + - `http`: HTTP proxy URL. + - `https`: HTTPS proxy URL. + - `aproxy_address`: Aproxy URL. + + + +### method `__init__` + +```python +__init__( + no_proxy: Optional[str], + http: Optional[str], + https: Optional[str], + aproxy_address: Optional[str] +) → None +``` + + + + + + + + + +--- + + + +## class `RunnerConfig` +Configuration for runner. + + + +**Attributes:** + + - `app_name`: Application name of the charm. + - `issue_metrics`: Whether to issue metrics. + - `labels`: Custom runner labels. + - `lxd_storage_path`: Path to be used as LXD storage. + - `name`: Name of the runner. + - `path`: GitHub repository path in the format '/', or the GitHub organization name. + - `proxies`: HTTP(S) proxy settings. + - `dockerhub_mirror`: URL of dockerhub mirror to use. + - `ssh_debug_connections`: The SSH debug server connections metadata. + + + +### method `__init__` + +```python +__init__( + app_name: str, + issue_metrics: bool, + labels: tuple[str], + lxd_storage_path: Path, + name: str, + path: GithubOrg | GithubRepo, + proxies: ProxySetting, + dockerhub_mirror: str | None = None, + ssh_debug_connections: list[SSHDebugConnection] | None = None +) → None +``` + + + + + + + + + +--- + + + +## class `RunnerStatus` +Status of runner. + + + +**Attributes:** + + - `runner_id`: ID of the runner. + - `exist`: Whether the runner instance exists on LXD. + - `online`: Whether GitHub marks this runner as online. + - `busy`: Whether GitHub marks this runner as busy. + + + +### method `__init__` + +```python +__init__( + runner_id: Optional[int] = None, + exist: bool = False, + online: bool = False, + busy: bool = False +) → None +``` + + + + + + + + + +--- + + + +## class `RunnerGithubInfo` +GitHub info of a runner. + + + +**Attributes:** + + - `runner_name`: Name of the runner. + - `runner_id`: ID of the runner assigned by GitHub. + - `online`: Whether GitHub marks this runner as online. + - `busy`: Whether GitHub marks this runner as busy. + + + +### method `__init__` + +```python +__init__(runner_name: str, runner_id: int, online: bool, busy: bool) → None +``` + + + + + + + + + diff --git a/src-docs/runner_type.py.md b/src-docs/runner_type.py.md deleted file mode 100644 index 12b1b9d85..000000000 --- a/src-docs/runner_type.py.md +++ /dev/null @@ -1,102 +0,0 @@ - - - - -# module `runner_type.py` -Types used by Runner class. - - - ---- - -## class `ProxySetting` -Represent HTTP-related proxy settings. - - - -**Attributes:** - - - `no_proxy`: The comma separated URLs to not go through proxy. - - `http`: HTTP proxy URL. - - `https`: HTTPS proxy URL. - - `aproxy_address`: Aproxy URL. - - - - - ---- - -## class `RunnerByHealth` -Set of runners instance by health state. - - - -**Attributes:** - - - `healthy`: Runners that are correctly running runner script. - - `unhealthy`: Runners that are not running runner script. - - - - - ---- - -## class `RunnerConfig` -Configuration for runner. - - - -**Attributes:** - - - `app_name`: Application name of the charm. - - `issue_metrics`: Whether to issue metrics. - - `labels`: Custom runner labels. - - `lxd_storage_path`: Path to be used as LXD storage. - - `name`: Name of the runner. - - `path`: GitHub repository path in the format '/', or the GitHub organization name. - - `proxies`: HTTP(S) proxy settings. - - `dockerhub_mirror`: URL of dockerhub mirror to use. - - `ssh_debug_connections`: The SSH debug server connections metadata. - - - - - ---- - -## class `RunnerGithubInfo` -GitHub info of a runner. - - - -**Attributes:** - - - `runner_name`: Name of the runner. - - `runner_id`: ID of the runner assigned by GitHub. - - `online`: Whether GitHub marks this runner as online. - - `busy`: Whether GitHub marks this runner as busy. - - - - - ---- - -## class `RunnerStatus` -Status of runner. - - - -**Attributes:** - - - `runner_id`: ID of the runner. - - `exist`: Whether the runner instance exists on LXD. - - `online`: Whether GitHub marks this runner as online. - - `busy`: Whether GitHub marks this runner as busy. - - - - - diff --git a/src-docs/shared_fs.py.md b/src-docs/shared_fs.md similarity index 98% rename from src-docs/shared_fs.py.md rename to src-docs/shared_fs.md index 724cf5714..004556f9f 100644 --- a/src-docs/shared_fs.py.md +++ b/src-docs/shared_fs.md @@ -2,7 +2,7 @@ -# module `shared_fs.py` +# module `shared_fs` Classes and functions to operate on the shared filesystem between the charm and the runners. **Global Variables** diff --git a/src-docs/utilities.py.md b/src-docs/utilities.md similarity index 98% rename from src-docs/utilities.py.md rename to src-docs/utilities.md index bebbc9347..860b66308 100644 --- a/src-docs/utilities.py.md +++ b/src-docs/utilities.md @@ -2,7 +2,7 @@ -# module `utilities.py` +# module `utilities` Utilities used by the charm. @@ -19,7 +19,7 @@ retry( delay: float = 0, max_delay: Optional[float] = None, backoff: float = 1, - local_logger: Logger = + local_logger: Logger = ) → Callable[[Callable[~ParamT, ~ReturnT]], Callable[~ParamT, ~ReturnT]] ```