Module ploigos_step_runner.utils.containers

Shared utils for dealing with containers.

Functions

def add_container_build_step_result_artifacts(step_result, contaimer_image_registry, container_image_repository, container_image_tag, container_image_digest, container_image_build_address, container_image_build_short_address)

Helper function to consistently add step results when building a container image.

NOTE: long term probably should move this into some mixin class that all container build StepImplementers also inherit from, but thats another pattern don't want to introduce right now.

Parameters

step_result : StepResult

Step result to add the container build artifacts to.

contaimer_image_registry : str

Container image registry the image was built into.

container_image_repository : str

Container image repository the image was built into.

container_image_tag : str

Container image tag the built image was tagged with.

container_image_digest : str

Container image digest of built image.

container_image_build_address : str

Container image full address (with registry) the image was built into and can be referenced by to push somewhere else.

container_image_build_short_address : str

Container image short address (without registry) the image was built into and can be referenced by to push somewhere else, assuming the registry is on the local container search path.

Results

step_result : StepResult The given StepResult which was modified in place. Returned for convenience / and clarity.

def container_registries_login(registries, containers_config_auth_file=None, containers_config_tls_verify=True, container_command_short_name=None)

Logs into one or more container registries.

Requires one of the following to be installed to do the authentication: * buidlah * podman * skopeo

Notes

registries example 1 (dict of dicts where child dict keys are registry uri):

{
    'registry.redhat.io': {
        'username': 'hello@world.xyz',
        'password': 'nope'
    },
    'registry.internal.example.xyz': {
        'username': 'hello@example.xyz',
        'password': 'nope'
    }
}

registries example 2 (dict of dicts where uri is key in child dicts):

{
    'redhat': {
        'uri': registry.redhat.io
        'username': 'hello@world.xyz',
        'password': 'nope'
    },
    'internal': {
        'uri': 'registry.internal.example.xyz'
        'username': 'hello@example.xyz',
        'password': 'nope'
    }
}

registries example 3 (list of dicts where uri is key in child dicts):

[
    {
        'uri': registry.redhat.io
        'username': 'hello@world.xyz',
        'password': 'nope'
    },
    {
        'uri': 'registry.internal.example.xyz'
        'username': 'hello@example.xyz',
        'password': 'nope'
    }
]

Parameters

registries : dict or list or None

Dict of dicts of registry configurations or a list of dicts of registry configurations. See Notes section for details. If none, does nothing.

containers_config_auth_file : str, optional

Path of the authentication file. If not specified default of the underlying authentication system will be used.

container_command_short_name : str, optional

Short name for the command to log in with. If not provided will pick the first command found in order (buildah, podman, skopeo).

See Also

container_registry_login()

Performs the login for a single container registry

sh.buildah

https://www.mankier.com/1/buildah-login

sh.podman

https://www.mankier.com/1/podman-login

sh.skopeo

https://www.mankier.com/1/skopeo-login

def container_registry_login(container_registry_uri, container_registry_username, container_registry_password, container_registry_tls_verify=True, containers_config_auth_file=None, container_command_short_name=None)

Performs the login for a single container registry.

Requires one of the following to be installed to do the authentication: * buidlah * podman * skopeo

Parameters

container_registry_uri : str or ConfigValue

URI to the container registry to log into.

container_registry_username : str or ConfigValue

Username to log into the container registry with.

container_registry_password : str or ConfigValue

Password to log into the container registry with.

container_registry_tls_verify : bool or str or ConfigValue

True to verify container registry certificates as part of authenticating. False to ignore certificate chain. NOTE: no matter what SSL is used to authenticate with container registry

containers_config_auth_file : str or ConfigValue, optional

Path of the authentication file. If not specified default of the underlying authentication system will be used.

container_command_short_name : str, optional

Short name for the command to log in with. If not provided will pick the first command found in order (buildah, podman, skopeo).

Raises

RuntimeError

When can not find tool to login to container registry with. When error loging into container registry.

See Also

container_registries_login()

authenticate with multiple container registries

sh.buildah

https://www.mankier.com/1/buildah-login

sh.podman

https://www.mankier.com/1/podman-login

sh.skopeo

https://www.mankier.com/1/skopeo-login

def create_container_from_image(image_address, repository_type='container-storage:')

Import a container image using buildah form a TAR file.

Parameters

image_address : str

Image tag to create a container from. ex: * localhost/my-app:latest * quay.io/my-org/my-app:latest * docker-archive:/local/path/to/my-app-container-image.tar

container_name : str

name for the working container.

repository_type : str

The type of repository to mount the given image tag from. See https://github.com/containers/skopeo for details on different repository types.

Returns

str

Name of the imported container.

Raises

RuntimeError

If error importing image.

def determine_container_image_address_info(contaimer_image_registry, container_image_tag, organization, application_name, service_name)

Determines the full and short build tags for a new container image.

Parameters

container_image_tag : str

A given image version. If none given, latest will be used.

organization : str

Organization the container image belongs to.

application_name : str

Application the container image belongs to.

service_name : str

Service the container image implements.

Returns

str, str, str, str, str

First result is the full build tag, including registry URI. Second result is the short build tag, as in no registry URI. Third result is the image registry uri. Forth result is the image repository name. Fifth result is the used image version.

def get_container_image_digest(container_image_address, containers_config_auth_file=None)

Get the container image digest for a given container image.

Will pull the given container image if needed.

Parameters

container_image_address : str

URI to the container image to get the container image digest for.

containers_config_auth_file : str

Path to container image registries authentication file.

Raises

RuntimeError

If error inspecting container image to get digest. If error finding digest on container image inspection results.

Returns

str

Container image digest for given container image.

def inspect_container_image(container_image_address, containers_config_auth_file=None)

Inspects a given container image for all its details. Useful for getting image labels and such.

Parameters

container_image_address : str

URI to the container image to inspect

containers_config_auth_file : str

Path to container image registries authentication file.

Raises

RuntimeError

If issue running buildah inspect

Returns

dict

Container image details from buildah inspect

def mount_container(buildah_unshare_command, container_id)

Use buildah to mount a container.

Parameters

buildah_unshare_command : sh.buildah.unshare.bake()

A baked sh.buildah.unshare command to use to run this command in the context off so that this can be done "rootless".

container_id : str

ID of the container to mount.

Returns

str

Absolute path to the mounted container.

Raises

RuntimeError

If error mounting the container.