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
- 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)¶
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