Bases
Abstract Base
- class craft_providers.Base[source]
Bases:
abc.ABC
Interface for providers to configure instantiated environments.
Defines how to setup/configure an environment that has been instantiated by a provider and prepare it for some operation, e.g. execute build. It must account for:
the OS type and version.
(2) the provided image that was launched, e.g. bootstrapping a minimal image versus a more fully featured one.
(3) any dependencies that are required for the operation to complete, e.g. installed applications, networking configuration, etc. This includes any environment configuration that the application will assume is available.
- Variables
compatibility_tag – Tag/Version for variant of build configuration and setup. Any change to this version would indicate that prior [versioned] instances are incompatible and must be cleaned. As such, any new value should be unique to old values (e.g. incrementing). It is suggested to extend this tag, not overwrite it, e.g.: compatibility_tag = f”{appname}-{Base.compatibility_tag}.{apprevision}” to ensure base compatibility levels are maintained.
- abstract get_command_environment()[source]
Get command environment to use when executing commands.
- Return type
Dict
[str
,Optional
[str
]]- Returns
Dictionary of environment, allowing None as a value to indicate that a value should be unset.
- abstract setup(*, executor, retry_wait=0.25, timeout=None)[source]
Prepare base instance for use by the application.
Wait for environment to become ready and configure it. At completion of setup, the executor environment should have networking up and have all of the installed dependencies required for subsequent use by the application.
Setup should not be called more than once in a given instance to refresh/update the environment, use warmup for that.
If timeout is specified, abort operation if time has been exceeded.
- Parameters
executor (
Executor
) – Executor for target container.retry_wait (
float
) – Duration to sleep() between status checks (if required).timeout (
Optional
[float
]) – Timeout in seconds.
- Raises
BaseCompatibilityError – if instance is incompatible.
BaseConfigurationError – on other unexpected error.
- Return type
None
- abstract wait_until_ready(*, executor, retry_wait=0.25, timeout=None)[source]
Wait until base instance is ready.
Ensure minimum-required boot services are running. This would be used when starting an environment’s container/VM after already [recently] running setup(), e.g. rebooting the instance. Allows the environment to be used without the cost incurred by re-executing the steps unnecessarily.
If timeout is specified, abort operation if time has been exceeded.
- Parameters
executor (
Executor
) – Executor for target container.retry_wait (
float
) – Duration to sleep() between status checks (if required).timeout (
Optional
[float
]) – Timeout in seconds.
- Raises
BaseCompatibilityError – if instance is incompatible.
BaseConfigurationError – on other unexpected error.
- Return type
None
- abstract warmup(*, executor, retry_wait=0.25, timeout=None)[source]
Prepare a previously created and setup instance for use by the application.
Ensure the instance is still valid and wait for environment to become ready.
If timeout is specified, abort operation if time has been exceeded.
- Parameters
executor (
Executor
) – Executor for target container.retry_wait (
float
) – Duration to sleep() between status checks (if required).timeout (
Optional
[float
]) – Timeout in seconds.
- Raises
BaseCompatibilityError – if instance is incompatible.
BaseConfigurationError – on other unexpected error.
- Return type
None
Buildd Base
- class craft_providers.bases.BuilddBase(*, alias, compatibility_tag=None, environment=None, hostname='craft-buildd-instance', snaps=None, packages=None)[source]
Bases:
craft_providers.base.Base
Support for Ubuntu minimal buildd images.
- Variables
compatibility_tag – Tag/Version for variant of build configuration and setup. Any change to this version would indicate that prior [versioned] instances are incompatible and must be cleaned. As such, any new value should be unique to old values (e.g. incrementing). It is suggested to extend this tag, not overwrite it, e.g.: compatibility_tag = f”{appname}-{BuildBase.compatibility_tag}.{apprevision}” to ensure base compatibility levels are maintained.
instance_config_path – Path to persistent environment configuration used for compatibility checks (or other data). Set to /etc/craft-instance.conf, but may be overridden for application-specific reasons.
instance_config_class – Class defining instance configuration. May be overridden with an application-specific subclass of InstanceConfiguration to enable application-specific extensions.
- Parameters
alias (
BuilddBaseAlias
) – Base alias / version.environment (
Optional
[Dict
[str
,Optional
[str
]]]) – Environment to set in /etc/environment.hostname (
str
) – Hostname to configure.snaps (
Optional
[List
[Snap
]]) – Optional list of snaps to install on the base image.packages (
Optional
[List
[str
]]) – Optional list of system packages to install on the base image.compatibility_tag (
Optional
[str
]) –
- get_command_environment()[source]
Get command environment to use when executing commands.
- Return type
Dict
[str
,Optional
[str
]]- Returns
Dictionary of environment, allowing None as a value to indicate that a value should be unset.
- instance_config_class
alias of
craft_providers.bases.instance_config.InstanceConfiguration
- setup(*, executor, retry_wait=0.25, timeout=None)[source]
Prepare base instance for use by the application.
Wait for environment to become ready and configure it. At completion of setup, the executor environment should have networking up and have all of the installed dependencies required for subsequent use by the application.
Setup may be called more than once in a given instance to refresh/update the environment.
If timeout is specified, abort operation if time has been exceeded.
- Guarantees provided by this setup:
configured /etc/environment
configured hostname
networking available (IP & DNS resolution)
apt cache up-to-date
snapd configured and ready
system services are started and ready
- Parameters
executor (
Executor
) – Executor for target container.retry_wait (
float
) – Duration to sleep() between status checks (if required).timeout (
Optional
[float
]) – Timeout in seconds.
- Raises
BaseCompatibilityError – if instance is incompatible.
BaseConfigurationError – on other unexpected error.
- Return type
None
- wait_until_ready(*, executor, retry_wait=0.25, timeout=None)[source]
Wait until base instance is ready.
Ensure minimum-required boot services are running. This would be used when starting an environment’s container/VM after already [recently] running setup(), e.g. rebooting the instance. Allows the environment to be used without the cost incurred by re-executing the steps unnecessarily.
If timeout is specified, abort operation if time has been exceeded.
Guarantees provided by this wait:
networking available (IP & DNS resolution)
system services are started and ready
- Parameters
executor (
Executor
) – Executor for target container.retry_wait (
float
) – Duration to sleep() between status checks (if required).timeout (
Optional
[float
]) – Timeout in seconds.
- Raises
ProviderError – on timeout or unexpected error.
- Return type
None
- warmup(*, executor, retry_wait=0.25, timeout=None)[source]
Prepare a previously created and setup instance for use by the application.
Ensure the instance is still valid and wait for environment to become ready.
- Guarantees provided by this wait:
OS and instance config are compatible
networking available (IP & DNS resolution)
system services are started and ready
If timeout is specified, abort operation if time has been exceeded.
- Parameters
executor (
Executor
) – Executor for target container.retry_wait (
float
) – Duration to sleep() between status checks (if required).timeout (
Optional
[float
]) – Timeout in seconds.
- Raises
BaseCompatibilityError – if instance is incompatible.
BaseConfigurationError – on other unexpected error.
- Return type
None