containers_create

Mixin to provide Container create() method.

class CreateMixin[source]

Bases: object

Class providing create method for ContainersManager.

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

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.

    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.

Returns:

A Container object.

Raises:

  • ImageNotFound – when Image not found by Podman service

  • APIError – when Podman service reports an error