Docker Image

Aside from methods in API definition - conu.apidefs.image.Image, DockerImage implements following methods:

class conu.DockerImage(repository, tag='latest', identifier=None, pull_policy=DockerImagePullPolicy.IF_NOT_PRESENT)

Utility functions for docker images.

These methods are specific to this backend:

These generic methods are not implemented in this backend:

__init__(repository, tag='latest', identifier=None, pull_policy=DockerImagePullPolicy.IF_NOT_PRESENT)
Parameters:
  • repository – str, image name, examples: “fedora”, “registry.fedoraproject.org/fedora”, “tomastomecek/sen”, “docker.io/tomastomecek/sen”

  • tag – str, tag of the image, when not specified, “latest” is implied

  • identifier – str, unique identifier for this image

  • pull_policy – enum, strategy to apply for pulling the image

classmethod build(path, tag=None, dockerfile=None)

Build the image from the provided dockerfile in path

:param path : str, path to the directory containing the Dockerfile :param tag: str, A tag to add to the final image :param dockerfile: str, path within the build context to the Dockerfile :return: instance of DockerImage

get_full_name()

Provide full, complete image name

Returns:

str

get_id()

get unique identifier of this image

Returns:

str

get_layer_ids(rev=True)

Get IDs of image layers

Parameters:

rev – get layers reversed

Returns:

list of strings

get_metadata()

Provide metadata about this image.

Returns:

ImageMetadata, Image metadata instance

static get_volume_options(volumes)

Generates volume options to run methods.

Parameters:

volumes – tuple or list of tuples in form target x source,target x source,target,mode.

Returns:

list of the form [“-v”, “/source:/target”, “-v”, “/other/source:/destination:z”, …]

has_pkgs_signed_with(allowed_keys)

Check signature of packages installed in image. Raises exception when

  • rpm binary is not installed in image

  • parsing of rpm fails

  • there are packages in image that are not signed with one of allowed keys

Parameters:

allowed_keys – list of allowed keys

Returns:

bool

inspect(refresh=True)

provide metadata about the image; flip refresh=True if cached metadata are enough

Parameters:

refresh – bool, update the metadata with up to date content

Returns:

dict

is_present()

Is this docker image present locally on the system?

Returns:

bool, True if it is, False if it’s not

layers(rev=True)

Get list of DockerImage for every layer in image

Parameters:

rev – get layers rev

Returns:

list of DockerImages

mount(mount_point=None)

Provide access to filesystem of this docker image.

Parameters:

mount_point – str, directory where the filesystem will be mounted; if not provided, mkdtemp(dir=”/var/tmp”) is used

Returns:

instance of conu.apidefs.filesystem.Filesystem

pull()

Pull this image from registry. Raises an exception if the image is not found in the registry.

Returns:

None

push(repository=None, tag=None)

Push image to registry. Raise exception when push fail. :param repository: str, see constructor :param tag: str, see constructor :return: None

rmi(force=False, via_name=False)

remove this image

Parameters:
  • force – bool, force removal of the image

  • via_name – bool, refer to the image via name, if false, refer via ID

Returns:

None

run_in_pod(namespace='default')

run image inside Kubernetes Pod :param namespace: str, name of namespace where pod will be created :return: Pod instance

run_via_api(container_params=None)

create a container using this image and run it in background via Docker-py API. https://docker-py.readthedocs.io/en/stable/api.html Note: If you are using Healthchecks, be aware that support of some options were introduced just with version of Docker-py API 1.29 :param container_params: DockerContainerParameters :return: instance of DockerContainer

run_via_binary(run_command_instance=None, command=None, volumes=None, additional_opts=None, **kwargs)

create a container using this image and run it in background; this method is useful to test real user scenarios when users invoke containers using binary

Parameters:
  • run_command_instance – instance of DockerRunBuilder

  • command – list of str, command to run in the container, examples: - [“ls”, “/”] - [“bash”, “-c”, “ls / | grep bin”]

  • volumes

    tuple or list of tuples in the form:

    • (“/path/to/directory”, )

    • (“/host/path”, “/container/path”)

    • (“/host/path”, “/container/path”, “mode”)

    • (conu.Directory(‘/host/path’), “/container/path”) (source can be also

      Directory instance)

  • additional_opts – list of str, additional options for docker run

Returns:

instance of DockerContainer

run_via_binary_in_foreground(run_command_instance=None, command=None, volumes=None, additional_opts=None, popen_params=None, container_name=None)

Create a container using this image and run it in foreground; this method is useful to test real user scenarios when users invoke containers using binary and pass input into the container via STDIN. You are also responsible for:

  • redirecting STDIN when intending to use container.write_to_stdin afterwards by setting

    popen_params={“stdin”: subprocess.PIPE} during run_via_binary_in_foreground

  • checking whether the container exited successfully via:

    container.popen_instance.returncode

Please consult the documentation for subprocess python module for best practices on how you should work with instance of Popen

Parameters:
  • run_command_instance – instance of DockerRunBuilder

  • command – list of str, command to run in the container, examples: - [“ls”, “/”] - [“bash”, “-c”, “ls / | grep bin”]

  • volumes

    tuple or list of tuples in the form:

    • (“/path/to/directory”, )

    • (“/host/path”, “/container/path”)

    • (“/host/path”, “/container/path”, “mode”)

    • (conu.Directory(‘/host/path’), “/container/path”) (source can be also

      Directory instance)

  • additional_opts – list of str, additional options for docker run

  • popen_params – dict, keyword arguments passed to Popen constructor

  • container_name – str, pretty container identifier

Returns:

instance of DockerContainer

tag_image(repository=None, tag=None)

Apply additional tags to the image or even add a new name

Parameters:
  • repository – str, see constructor

  • tag – str, see constructor

Returns:

instance of DockerImage

class conu.DockerImagePullPolicy(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

This Enum defines the policy for pulling the docker images. The pull operation happens when creating an instance of a docker image. Supported values:

  • NEVER - do not pull the image

  • IF_NOT_PRESENT - pull it only if the image is not present

  • ALWAYS - always initiate the pull process - the image is being pulled even if it’s present locally. It means that it may be overwritten by a remote counterpart or there may be a exception being raised if no such image is present in the registry.

class conu.DockerImageViaArchiveFS(image, mount_point=None)
__init__(image, mount_point=None)

Provide image as an archive

Parameters:
  • image – instance of DockerImage

  • mount_point – str, directory where the filesystem will be made available

Aside from methods in API definition - conu.apidefs.image.S2Image, S2IDockerImage implements following methods:

class conu.S2IDockerImage(repository, tag='latest', identifier=None, pull_policy=DockerImagePullPolicy.IF_NOT_PRESENT)

These methods are specific to this backend:

  • S2IDockerImage.build()

These generic methods are not implemented in this backend:

extend(source, new_image_name, s2i_args=None)

extend this s2i-enabled image using provided source, raises ConuException if s2i build fails

Parameters:
  • source – str, source used to extend the image, can be path or url

  • new_image_name – str, name of the new, extended image

  • s2i_args – list of str, additional options and arguments provided to s2i build

Returns:

S2Image instance

usage()

Provide output of s2i usage

Returns:

str