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