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:

• DockerImage.build()

These generic methods are not implemented in this backend:

• conu.apidefs.image.Image.load_from_file()

__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
• path – in filesystem
• logs – enable/disable

Returns:

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:

• conu.apidefs.image.Image.load_from_file()

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