Configuration API Reference

API functions

apolo_sdk.find_project_root(path: Path | None = None) → Path

Look for project root directory.

Folder is considered a project root when it contains .apolo.toml. Search begins at path or Path.cwd() (current working directory) when path is None and checks all parent folders sequentially. Will raise an ConfigError if search reaches root directory.

Config

class apolo_sdk.Config

Configuration subsystem, available as Client.config.

Use it for analyzing fetching information about the system configuration, e.g. a list of available clusters or switching the active cluster.

path

Path to a folder with config file, pathlib.Path.

username

User name used for working with Apolo Platform, read-only str.

presets

A typing.Mapping of preset name (str) to Preset dataclass for the current cluster.

clusters

A typing.Mapping of cluster name (str) to Cluster dataclass for available clusters.

cluster_name

The current cluster name, read-only str.

To switch on another cluster use switch_cluster().

org_name

The current org name, read-only str.

To switch on another org use switch_org().

async fetch() → None[source]

Fetch available clusters configuration from the Apolo Platform.

Note

The call updates local configuration files.

async switch_cluster(name: str) → None[source]

Switch the current cluster to name.

Note

The call updates local configuration files.

async switch_org(name: str) → None[source]

Switch the current org to name.

Note

The call updates local configuration files.

Miscellaneous helpers

api_url

The Apolo Platform URL, yarl.URL.

registry_url

Docker Registry URL for the cluster, yarl.URL.

Cluster.registry_url for the current cluster.

storage_url

Storage URL for the cluster, yarl.URL.

Cluster.storage_url for the current cluster.

monitoring_url

Monitoring URL for the cluster, yarl.URL.

Cluster.monitoring_url for the current cluster.

async get_user_config() → Mapping[str, Any][source]

Return user-provided config dictionary. Config is loaded from config files. There are two configuration files: global and local, both are optional and can be absent.

The global file is named user.toml and the API search for it in the path provided to Factory or get() ($HOME/.apolo/user.toml by default).

The local config file is named .apolo.toml, and the API search for this file starting from the current folder up to the root directory.

Found local and global configurations are merged. If a parameter is present are both global and local versions the local parameter take a precedence.

Configuration files have a TOML format (a stricter version of well-known INI format). See https://en.wikipedia.org/wiki/TOML and https://github.com/toml-lang/toml#toml for the format specification details.

The API will raise an ConfigError if configuration files contains unknown sections or parameters. Note that currently API doesn’t use any parameter from user config.

Known sections: alias, job, storage.

Section alias can have any subsections with any keys.

Section job can have following keys: ps-format - string, life-span - string.

Section storage can have following keys: cp-exclude - list of strings, cp-exclude-from-files - list of strings.

There is a plugin system that allows to register additional config parameters. To define a plugin, add a apolo_api entrypoint (check https://packaging.python.org/specifications/entry-points/ for more info about entry points). Entry point should be callable with single argument of type PluginManager.

Added in version 20.01.15.

async token() → str[source]

Bearer token to log into the Apolo Platform.

The token expires after some period, the call automatically refreshes the token if needed.

Cluster

class apolo_sdk.Cluster

Read-only dataclass for describing a cluster configuration.

Clusters are loaded on login to the Apolo platform and updated on Config.fetch() call.

Config.switch_cluster() changes the active cluster.

name

Cluster name, str.

registry_url

Docker Registry URL for the cluster, yarl.URL.

storage_url

Storage URL for the cluster, yarl.URL.

users_url

Users URL for the cluster, yarl.URL.

monitoring_url

Monitoring URL for the cluster, yarl.URL.

presets

A typing.Mapping of available job resource presets, keys are preset names (str), values are Preset objects.

apps

A AppsConfig object, representing platform applications configuration in the cluster.

Preset

class apolo_sdk.Preset

Read-only dataclass for describing a job configuration provided by Apolo Platform.

Presets list is loaded on login to the Apolo platform and depends on used cluster.

cpu

Requested number of CPUs, float. Please note, Docker supports fractions here, e.g. 0.5 CPU means a half or CPU on the target node.

memory_mb

Requested memory amount in MegaBytes, int.

is_preemptible

A flag that specifies is the job is preemptible or not, see Preemption for details.

gpu

The number of requested GPUs, int. Use None for jobs that doesn’t require GPU.

gpu_model

The name of requested GPU model, str (or None for job without GPUs).

tpu_type

Requested TPU type, see also https://en.wikipedia.org/wiki/Tensor_processing_unit

tpu_software_version

Requested TPU software version.

AppsConfig

class apolo_sdk.AppsConfig

Read-only dataclass for describing applications configuration within the cluster provided by Apolo Platform.

Applications configurations are loaded on login to the Apolo platform and depends on the used cluster.

hostname_templates

Represent application ingress hostname templates, list[str]. Empty list by default. The hostname templates are defined and controlled by the cluster administrators and should be used when creating ingress resources for applications.