Docker Container¶
Aside from methods in API definition - conu.apidefs.container.Container
, DockerContainer implements following methods:
- class conu.DockerContainer(image, container_id, name=None, popen_instance=None)¶
- __init__(image, container_id, name=None, popen_instance=None)¶
- Parameters
image – DockerImage instance (if None, it will be found from the container itself)
container_id – str, unique identifier of this container
name – str, pretty container name
popen_instance – instance of Popen (if container was created using method via_binary, this is the docker client process)
- copy_from(src, dest)¶
copy a file or a directory from container or image to host system.
- Parameters
src – str, path to a file or a directory within container or image
dest – str, path to a file or a directory on host system
- Returns
None
- copy_to(src, dest)¶
copy a file or a directory from host system to a container
- Parameters
src – str, path to a file or a directory on host system
dest – str, path to a file or a directory within container
- Returns
None
- delete(force=False, volumes=False, **kwargs)¶
remove this container; kwargs indicate that some container runtimes might accept more parameters
- Parameters
force – bool, if container engine supports this, force the functionality
volumes – bool, remove also associated volumes
- Returns
None
- execute(command, blocking=True, exec_create_kwargs=None, exec_start_kwargs=None)¶
Execute a command in this container – the container needs to be running.
If the command fails, a ConuException is thrown.
This is a blocking call by default and writes output of the command to logger using the INFO level – this behavior can be changed if you set the argument blocking to False.
If not blocking, you should consume the returned iterator in order to see logs or know when the command finished:
for line in container.execute(["ping", "-c", "4", "8.8.8.8"], blocking=False): print(line) print("command finished")
- Parameters
command – list of str, command to execute in the container
blocking – bool, if True blocks until the command finishes
exec_create_kwargs – dict, params to pass to exec_create()
exec_start_kwargs – dict, params to pass to exec_start()
- Returns
iterator if non-blocking or list of bytes if blocking
- exit_code()¶
get exit code of container. Return value is 0 for running and created containers
- Returns
int
- get_IPv4s()¶
Return all known IPv4 addresses of this container. It may be possible that the container has disabled networking: in that case, the list is empty
- Returns
list of str
- get_IPv6s()¶
Return all known IPv6 addresses of this container. It may be possible that the container has disabled networking: in that case, the list is empty
- Returns
list of str
- get_id()¶
get unique identifier of this container
- Returns
str
- get_image_name()¶
return name of the container image
- Returns
str
- get_metadata()¶
Convert dictionary returned after docker inspect command into instance of ContainerMetadata class :return: ContainerMetadata, container metadata instance
- get_port_mappings(port=None)¶
Get list of port mappings between container and host. The format of dicts is:
{“HostIp”: XX, “HostPort”: YY};
When port is None - return all port mappings. The container needs to be running, otherwise this returns an empty list.
- Parameters
port – int or None, container port
- Returns
list of dict or None; dict when port=None
- get_ports()¶
get ports specified in container metadata
- Returns
list of str
- get_status()¶
Get status of container
- Returns
one of: ‘created’, ‘restarting’, ‘running’, ‘paused’, ‘exited’, ‘dead’
- inspect(refresh=True)¶
return cached metadata by default
- Parameters
refresh – bool, returns up to date metadata if set to True
- Returns
dict
- is_port_open(port, timeout=2)¶
check if given port is open and receiving connections on container ip_address
- Parameters
port – int, container port
timeout – int, how many seconds to wait for connection; defaults to 2
- Returns
True if the connection has been established inside timeout, False otherwise
- is_running()¶
returns True if the container is running, this method should always ask the API and should not use a cached value
- Returns
bool
- kill(signal=None)¶
send a signal to this container (bear in mind that the process won’t have time to shutdown properly and your service may end up in an inconsistent state)
- Parameters
signal – str or int, signal to use for killing the container (SIGKILL by default)
- Returns
None
- logs(follow=False)¶
Get logs from this container. Every item of the iterator contains one log line terminated with a newline. The logs are encoded (they are bytes, not str).
Let’s look at an example:
image = conu.DockerImage("fedora", tag="27") command = ["bash", "-c", "for x in `seq 1 5`; do echo $x; sleep 1; done"] container = image.run_via_binary(command=command) for line in container.logs(follow=True): print(line)
This will output
b'1\n' b'2\n' b'3\n' b'4\n' b'5\n'
- Parameters
follow – bool, provide new logs as they come
- Returns
iterator (of bytes)
- logs_in_bytes()¶
Get output of container in bytes.
- Returns
bytes
- logs_unicode()¶
Get output of container decoded using utf-8.
- Returns
str
- mount(mount_point=None)¶
mount container filesystem
- Parameters
mount_point – str, directory where the filesystem will be mounted
- Returns
instance of DockerContainerViaExportFS
- start()¶
start current container - the container has to be created
- Returns
None
- stop()¶
stop this container
- Returns
None
- wait(timeout=None)¶
Block until the container stops, then return its exit code. Similar to the
docker wait
command.- Parameters
timeout – int, Request timeout
- Returns
int, exit code
- wait_for_port(port, timeout=10, **probe_kwargs)¶
block until specified port starts accepting connections, raises an exc ProbeTimeout if timeout is reached
- Parameters
port – int, port number
timeout – int or float (seconds), time to wait for establishing the connection
probe_kwargs – arguments passed to Probe constructor
- Returns
None
- write_to_stdin(message)¶
- Write provided text to container’s standard input. In order to make this function work, there needs to be several conditions met:
the container needs to be running
the container needs to have stdin open
the container has to be created using method run_via_binary_in_foreground
For more info see documentation in run_via_binary_in_foreground()
- Parameters
message – str or bytes, text to be written to container standard input
- class conu.DockerRunBuilder(command=None, additional_opts=None)¶
helper to execute docker run – users can easily change or override anything
- __init__(command=None, additional_opts=None)¶
Build docker run command
- Parameters
command – list of str, command to run in the container, examples: - [“ls”, “/”] - [“bash”, “-c”, “ls / | grep bin”]
additional_opts – list of str, additional options for docker run
- get_parameters()¶
Parse DockerRunBuilder options and create object with properties for docker-py run command :return: DockerContainerParameters