Docker Image¶
Aside from methods in API definition - conu.apidefs.image.Image
, DockerImage implements following methods:
-
class
conu.
DockerImage
(repository, tag=u'latest', identifier=None, pull_policy=<DockerImagePullPolicy.IF_NOT_PRESENT: 1>, short_metadata=None)¶ Utility functions for docker images.
These methods are specific to this backend:
These generic methods are not implemented in this backend:
conu.apidefs.image.Image.create_container()
conu.apidefs.image.Image.directory_is_present()
conu.apidefs.image.Image.file_is_present()
conu.apidefs.image.Image.get_selinux_context()
conu.apidefs.image.Image.load_from_file()
conu.apidefs.image.Image.mount_image()
conu.apidefs.image.Image.run_via_api()
-
__init__
(repository, tag=u'latest', identifier=None, pull_policy=<DockerImagePullPolicy.IF_NOT_PRESENT: 1>, short_metadata=None)¶ 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
- short_metadata – dict, metadata obtained from docker.APIClient.images()
-
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_metadata
(refresh=True)¶ return cached metadata by default
Parameters: refresh – bool, update the metadata with up to date content Returns: dict
-
static
get_volume_options
()¶ 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)¶ return cached metadata by default (a convenience method)
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
-
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
-
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_via_binary
(run_command_instance=None, command=None, volumes=None, additional_opts=None, *args, **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
¶ 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)¶ These generic methods are not implemented in this backend:
-
__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=u'latest')¶ These methods are specific to this backend:
S2IDockerImage.has_pkgs_signed_with()
S2IDockerImage.extend()
S2IDockerImage.inspect()
S2IDockerImage.run_via_binary_in_foreground()
S2IDockerImage.is_present()
S2IDockerImage.tag_image()
S2IDockerImage.build()
S2IDockerImage.usage()
These generic methods are not implemented in this backend:
conu.apidefs.image.Image.create_container()
conu.apidefs.image.Image.directory_is_present()
conu.apidefs.image.Image.file_is_present()
conu.apidefs.image.Image.get_selinux_context()
conu.apidefs.image.Image.load_from_file()
conu.apidefs.image.Image.mount_image()
conu.apidefs.image.Image.run_via_api()
-
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