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: 1>)

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: 1>)
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

copy(repository=None, tag=None, source_transport=None, target_transport=<SkopeoTransport.DOCKER: 2>, source_path=None, target_path=None, logs=True)

Copy this image

:param repository to be copied to :param tag :param source_transport Transport :param target_transport Transport :param source_path needed to specify for dir, docker-archive or oci transport :param target_path needed to specify for dir, docker-archive or oci transport :param logs enable/disable logs :return: the new 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
load_from(image)

Load from another DockerImage to this one

Parameters:image
Returns:
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

save_to(image)

Save this image to another DockerImage

Parameters:image – DockerImage
Returns:
skopeo_pull()

Pull image from Docker to local Docker daemon using skopeo

Returns:pulled image
skopeo_push(repository=None, tag=None)

Push image from Docker daemon to Docker using skopeo

Parameters:
  • repository – repository to be pushed to
  • tag – tag
Returns:

pushed image

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

using_transport(transport=None, path=None, logs=True)

change used transport

Parameters:transport – from where will be this image copied

:param path in filesystem :param logs enable/disable :return: self

class conu.DockerImagePullPolicy

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: 1>)

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