containers_manager

PodmanResource manager subclassed for Containers.

class ContainersManager(client: APIClient = None)

Bases: RunMixin, CreateMixin, Manager

Specialized Manager for Container resources.

Initialize Manager() object.

Parameters:

client – APIClient() configured to connect to Podman service.

create(image: Image | str, command: str | List[str] | None = None, **kwargs) → Container

Create a container.

Parameters:

• image – Image to run.

• command – Command to run in the container.

Keyword Arguments:

• auto_remove (bool) – Enable auto-removal of the container on daemon side when the container’s process exits.

• blkio_weight_device (Dict[str, Any]) – Block IO weight (relative device weight) in the form of: [{“Path”: “device_path”, “Weight”: weight}].

• blkio_weight (int) – Block IO weight (relative weight), accepts a weight value between 10 and 1000.

• cap_add (List[str]) – Add kernel capabilities. For example: [“SYS_ADMIN”, “MKNOD”]

• cap_drop (List[str]) – Drop kernel capabilities.

• cgroup_parent (str) – Override the default parent cgroup.

• cpu_count (int) – Number of usable CPUs (Windows only).

• cpu_percent (int) – Usable percentage of the available CPUs (Windows only).

• cpu_period (int) – The length of a CPU period in microseconds.

• cpu_quota (int) – Microseconds of CPU time that the container can get in a CPU period.

• cpu_rt_period (int) – Limit CPU real-time period in microseconds.

• cpu_rt_runtime (int) – Limit CPU real-time runtime in microseconds.

• cpu_shares (int) – CPU shares (relative weight).

• cpuset_cpus (str) – CPUs in which to allow execution (0-3, 0,1).

• cpuset_mems (str) – Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.

• detach (bool) – Run container in the background and return a Container object.

• device_cgroup_rules (List[str]) – A list of cgroup rules to apply to the container.

• device_read_bps – Limit read rate (bytes per second) from a device in the form of: [{“Path”: “device_path”, “Rate”: rate}]

• device_read_iops – Limit read rate (IO per second) from a device.

• device_write_bps – Limit write rate (bytes per second) from a device.

• device_write_iops – Limit write rate (IO per second) from a device.

• devices (List[str]) –

  Expose host devices to the container, as a List[str] in the form <path_on_host>:<path_in_container>:<cgroup_permissions>.

  For example:

  /dev/sda:/dev/xvda:rwm allows the container to have read-write access to the host’s /dev/sda via a node named /dev/xvda inside the container.

• dns (List[str]) – Set custom DNS servers.

• dns_opt (List[str]) – Additional options to be added to the container’s resolv.conf file.

• dns_search (List[str]) – DNS search domains.

• domainname (Union[str, List[str]]) – Set custom DNS search domains.

• entrypoint (Union[str, List[str]]) – The entrypoint for the container.

• environment (Union[Dict[str, str], List[str]) – Environment variables to set inside the container, as a dictionary or a List[str] in the format [“SOMEVARIABLE=xxx”, “SOMEOTHERVARIABLE=xyz”].

• extra_hosts (Dict[str, str]) – Additional hostnames to resolve inside the container, as a mapping of hostname to IP address.

• group_add (List[str]) – List of additional group names and/or IDs that the container process will run as.

• healthcheck (Dict[str,Any]) – Specify a test to perform to check that the container is healthy.

• health_check_on_failure_action (int) – Specify an action if a healthcheck fails.

• hostname (str) – Optional hostname for the container.

• init (bool) – Run an init inside the container that forwards signals and reaps processes

• init_path (str) – Path to the docker-init binary

• ipc_mode (str) – Set the IPC mode for the container.

• isolation (str) – Isolation technology to use. Default: None.

• kernel_memory (int or str) – Kernel memory limit

• labels (Union[Dict[str, str], List[str]) – A dictionary of name-value labels (e.g. {“label1”: “value1”, “label2”: “value2”}) or a list of names of labels to set with empty values (e.g. [“label1”, “label2”])

• links (Optional[Dict[str, str]]) – Mapping of links using the {‘container’: ‘alias’} format. The alias is optional. Containers declared in this dict will be linked to the new container using the provided alias. Default: None.

• log_config (LogConfig) – Logging configuration.

• lxc_config (Dict[str, str]) – LXC config.

• mac_address (str) – MAC address to assign to the container.

• mem_limit (Union[int, str]) – Memory limit. Accepts float values (which represent the memory limit of the created container in bytes) or a string with a units identification char (100000b, 1000k, 128m, 1g). If a string is specified without a units character, bytes are assumed as an intended unit.

• mem_reservation (Union[int, str]) – Memory soft limit.

• mem_swappiness (int) – Tune a container’s memory swappiness behavior. Accepts number between 0 and 100.

• memswap_limit (Union[int, str]) – Maximum amount of memory + swap a container is allowed to consume.

• mounts (List[Mount]) –

  Specification for mounts to be added to the container. More powerful alternative to volumes. Each item in the list is expected to be a Mount object. For example:

  [

  {

  “type”: “bind”,

  ”source”: “/a/b/c1”,

  ”target” “/d1”,

  ”read_only”: True,

  ”relabel”: “Z”

  },

  {

  “type”: “tmpfs”,

  # If this was not passed, the regular directory

  # would be created rather than tmpfs mount !!!

  # as this will cause to have invalid entry

  # in /proc/self/mountinfo

  ”source”: “tmpfs”,

  ”target” “/d2”,

  ”size”: “100k”,

  ”chown”: True

  }

  ]

• name (str) – The name for this container.

• nano_cpus (int) – CPU quota in units of 1e-9 CPUs.

• networks (Dict[str, Dict[str, Union[str, List[str]]) –

  Networks which will be connected to container during container creation Values of the network configuration can be :

  • string

  • list of strings (e.g. Aliases)

• network_disabled (bool) – Disable networking.

• network_mode (str) –

  One of:

  • bridge: Create a new network stack for the container on the bridge network.

  • none: No networking for this container.

  • container:<name|id>: Reuse another container’s network stack.

  • host: Use the host network stack.

  • ns:<path>: User defined netns path.

  Incompatible with network.

• oom_kill_disable (bool) – Whether to disable OOM killer.

• oom_score_adj (int) – An integer value containing the score given to the container in order to tune OOM killer preferences.

• pid_mode (str) – If set to host, use the host PID namespace inside the container.

• pids_limit (int) – Tune a container’s pids limit. Set -1 for unlimited.

• platform (str) – Platform in the format os[/arch[/variant]]. Only used if the method needs to pull the requested image.

• ports (Dict[str, Union[int, Tuple[str, int], List[int], Dict[str, Union[int, Tuple[str, int], List[int]]]]]) –

  Ports to bind inside the container.

  The keys of the dictionary are the ports to bind inside the container, either as an integer or a string in the form port/protocol, where the protocol is either tcp, udp, or sctp.

  The values of the dictionary are the corresponding ports to open on the host, which can be either:

  • The port number, as an integer.

    For example: {‘2222/tcp’: 3333} will expose port 2222 inside the container as port 3333 on the host.

  • None, to assign a random host port.

    For example: {‘2222/tcp’: None}.

  • A tuple of (address, port) if you want to specify the host interface.

    For example: {‘1111/tcp’: (‘127.0.0.1’, 1111)}.

  • A list of integers or tuples of (address, port), if you want to bind multiple host ports to a single container port.

    For example: {‘1111/tcp’: [1234, (“127.0.0.1”, 4567)]}.

    For example: {‘9090’: 7878, ‘10932/tcp’: ‘8781’,

    ”8989/tcp”: (“127.0.0.1”, 9091)}

  • A dictionary of the options mentioned above except for random host port.

    The dictionary has additional option “range”,

    which allows binding range of ports.

    For example:

    • {‘2222/tcp’: {“port”: 3333, “range”: 4}}

    • {‘1111/tcp’: {“port”: (‘127.0.0.1’, 1111), “range”: 4}}

    • {‘1111/tcp’: [

      {“port”: 1234, “range”: 4},

      {“ip”: “127.0.0.1”, “port”: 4567}

      ]

    }

• privileged (bool) – Give extended privileges to this container.

• publish_all_ports (bool) – Publish all ports to the host.

• read_only (bool) – Mount the container’s root filesystem as read only.

• read_write_tmpfs (bool) – Mount temporary file systems as read write, in case of read_only options set to True. Default: False

• remove (bool) – Remove the container when it has finished running. Default: False.

• restart_policy (Dict[str, Union[str, int]]) –

  Restart the container when it exits. Configured as a dictionary with keys:

  • Name: One of on-failure, or always.

  • MaximumRetryCount: Number of times to restart the container on failure.

  For example: {“Name”: “on-failure”, “MaximumRetryCount”: 5}

• runtime (str) – Runtime to use with this container.

• secrets (List[Union[str, Secret, Dict[str, Union[str, int]]]]) –

  Secrets to mount to this container.

  For example:

  • As list of strings, each string representing a secret’s ID or name:

    [‘my_secret’, ‘my_secret2’]

  • As list of Secret objects the corresponding IDs are read from:

    [Secret, Secret]

  • As list of dictionaries:

    [

    {

    “source”: “my_secret”, # A string representing the ID or name of

    # a secret

    ”target”: “/my_secret”, # An optional target to mount source to,

    # falls back to /run/secrets/source

    ”uid”: 1000, # An optional UID that falls back to 0

    # if not given

    ”gid”: 1000, # An optional GID that falls back to 0

    # if not given

    ”mode”: 0o400, # An optional mode to apply to the target,

    # use an 0o prefix for octal integers

    },

    ]

• secret_env (Dict[str, str]) –

  Secrets to add as environment variables available in the container.

  For example: {“VARIABLE1”: “NameOfSecret”, “VARIABLE2”: “NameOfAnotherSecret”}

• security_opt (List[str]) – A List[str]ing values to customize labels for MLS systems, such as SELinux.

• shm_size (Union[str, int]) – Size of /dev/shm (e.g. 1G).

• stdin_open (bool) – Keep STDIN open even if not attached.

• stdout (bool) – Return logs from STDOUT when detach=False. Default: True.

• stderr (bool) – Return logs from STDERR when detach=False. Default: False.

• stop_signal (str) – The stop signal to use to stop the container (e.g. SIGINT).

• storage_opt (Dict[str, str]) – Storage driver options per container as a key-value mapping.

• stream (bool) – If true and detach is false, return a log generator instead of a string. Ignored if detach is true. Default: False.

• sysctls (Dict[str, str]) – Kernel parameters to set in the container.

• tmpfs (Dict[str, str]) –

  Temporary filesystems to mount, as a dictionary mapping a path inside the container to options for that path.

  For example: {‘/mnt/vol2’: ‘’, ‘/mnt/vol1’: ‘size=3G,uid=1000’}

• tty (bool) – Allocate a pseudo-TTY.

• ulimits (List[Ulimit]) – Ulimits to set inside the container.

• use_config_proxy (bool) – If True, and if the docker client configuration file (~/.config/containers/config.json by default) contains a proxy configuration, the corresponding environment variables will be set in the container being built.

• user (Union[str, int]) – Username or UID to run commands as inside the container.

• userns_mode (str) – Sets the user namespace mode for the container when user namespace remapping option is enabled. Supported values documented here

• uts_mode (str) – Sets the UTS namespace mode for the container. These are the supported values.

• version (str) – The version of the API to use. Set to auto to automatically detect the server’s version. Default: 3.0.0

• volume_driver (str) – The name of a volume driver/plugin.

• volumes (Dict[str, Dict[str, Union[str, list]]]) –

  A dictionary to configure volumes mounted inside the container. The key is either the host path or a volume name, and the value is a dictionary with the keys:

  • bind: The path to mount the volume inside the container

  • mode: Either rw to mount the volume read/write, or ro to mount it read-only.

    Kept for docker-py compatibility

  • extended_mode: List of options passed to volume mount.

  For example:

  {

  ‘test_bind_1’:

  {‘bind’: ‘/mnt/vol1’, ‘mode’: ‘rw’},

  ’test_bind_2’:

  {‘bind’: ‘/mnt/vol2’, ‘extended_mode’: [‘ro’, ‘noexec’]},

  ’test_bind_3’:

  {‘bind’: ‘/mnt/vol3’, ‘extended_mode’: [‘noexec’], ‘mode’: ‘rw’}

  }

• volumes_from (List[str]) – List of container names or IDs to get volumes from.

• working_dir (str) – Path to the working directory.

• workdir (str) – Alias of working_dir - Path to the working directory.

Returns:

A Container object.

Raises:

• ImageNotFound – when Image not found by Podman service

• APIError – when Podman service reports an error

exists(key: str) → bool

Returns True if resource exists.

Podman only.

Notes

This method does _not_ provide any mutex mechanism.

get(key: str) → Container

Get container by name or id.

Parameters:

container_id – Container name or id.

Returns:

A Container object corresponding to key.

Raises:

• NotFound – when Container does not exist

• APIError – when an error return by service

list(**kwargs) → List[Container]

Report on containers.

Keyword Arguments:

• all – If False, only show running containers. Default: False.

• since – Show containers created after container name or id given.

• before – Show containers created before container name or id given.

• limit – Show last N created containers.

• filters –

  Filter container reported. Available filters:

  • exited (int): Only containers with specified exit code

  • status (str): One of restarting, running, paused, exited

  • label (Union[str, List[str]]): Format either “key”, “key=value” or a list of such.

  • id (str): The id of the container.

  • name (str): The name of the container.

  • ancestor (str): Filter by container ancestor. Format of

    <image-name>[:tag], <image-id>, or <image@digest>.

  • before (str): Only containers created before a particular container.

    Give the container name or id.

  • since (str): Only containers created after a particular container.

    Give container name or id.

• sparse – Ignored

• ignore_removed – If True, ignore failures due to missing containers.

Raises:

APIError – when service returns an error

prepare_model(attrs: PodmanResource | Mapping[str, Any]) → PodmanResourceType

Create a model from a set of attributes.

prune(filters: Mapping[str, str] = None) → Dict[str, Any]

Delete stopped containers.

Parameters:

filters – Criteria for determining containers to remove. Available keys are: - until (str): Delete containers before this time - label (List[str]): Labels associated with containers

Returns:

• ContainersDeleted (List[str]): Identifiers of deleted containers.

• SpaceReclaimed (int): Amount of disk space reclaimed in bytes.

Return type:

Keys

Raises:

APIError – when service reports an error

remove(container_id: Container | str, **kwargs)

Delete container.

Podman only

Parameters:

container_id – identifier of Container to delete.

Keyword Arguments:

• v (bool) – Delete associated volumes as well.

• link (bool) – Ignored.

• force (bool) – Kill a running container before deleting.

run(image: str | Image, command: str | List[str] | None = None, stdout=True, stderr=False, remove: bool = False, **kwargs) → Container | Generator[str, None, None] | Iterator[str]

Run a container.

By default, run() will wait for the container to finish and return its logs.

If detach=True, run() will start the container and return a Container object rather

than logs.

Parameters:

• image – Image to run.

• command – Command to run in the container.

• stdout – Include stdout. Default: True.

• stderr – Include stderr. Default: False.

• remove – Delete container when the container’s processes exit. Default: False.

Keyword Arguments:

arguments. (- See the create() method for keyword) –

Returns:

• When detach is True, return a Container

• If stdout is True, include stdout from container in output

• If stderr is True, include stderr from container in output

• When stream is True, output from container is returned as a generator

• Otherwise, an iterator is returned after container has finished

Raises:

• ContainerError – when Container exists with a non-zero code

• ImageNotFound – when Image not found by Podman service

• APIError – when Podman service reports an error

property resource

prepare_model() will create Container classes.

Type:

Type[Container]