containers_create¶
提供 Container create() 方法的 Mixin。
- class CreateMixin[源码]¶
基类:
object
为 ContainersManager 提供 create 方法的类。
- create(image: Image | str, command: str | list[str] | None = None, **kwargs) Container [源码]¶
创建一个容器。
- 参数:
image – 要运行的镜像。
command – 在容器中运行的命令。
- 关键字参数:
auto_remove (bool) – 当容器进程退出时,在守护进程端启用容器的自动移除。
blkio_weight_device (dict[str, Any]) – 块 IO 权重(相对设备权重),形式为:[{“Path”: “device_path”, “Weight”: weight}]。
blkio_weight (int) – 块 IO 权重(相对权重),接受 10 到 1000 之间的权重值。
cap_add (list[str]) – 添加内核能力。例如:[“SYS_ADMIN”, “MKNOD”]
cap_drop (list[str]) – 丢弃内核能力。
cgroup_parent (str) – 覆盖默认父 cgroup。
cpu_count (int) – 可用 CPU 的数量(仅限 Windows)。
cpu_percent (int) – 可用 CPU 的可用百分比(仅限 Windows)。
cpu_period (int) – CPU 周期的长度(微秒)。
cpu_quota (int) – 容器在一个 CPU 周期内可以获得的 CPU 时间(微秒)。
cpu_rt_period (int) – 限制 CPU 实时周期(微秒)。
cpu_rt_runtime (int) – 限制 CPU 实时运行时(微秒)。
cpu_shares (int) – CPU 共享(相对权重)。
cpuset_cpus (str) – 允许执行的 CPU(0-3, 0,1)。
cpuset_mems (str) – 允许执行的内存节点(MEMs)(0-3, 0,1)。仅在 NUMA 系统上有效。
detach (bool) – 在后台运行容器并返回一个 Container 对象。
device_cgroup_rules (list[str]) – 应用于容器的 cgroup 规则列表。
device_read_bps – 限制从设备读取的速率(每秒字节数),形式为:[{“Path”: “device_path”, “Rate”: rate}]
device_read_iops – 限制从设备读取的速率(每秒 IO 数)。
device_write_bps – 限制向设备写入的速率(每秒字节数)。
device_write_iops – 限制向设备写入的速率(每秒 IO 数)。
devices (list[str]) –
将宿主机设备暴露给容器,形式为 list[str],格式为 <宿主机路径>:<容器内路径>:<cgroup 权限>。
- 例如
/dev/sda:/dev/xvda:rwm 允许容器通过容器内的 /dev/xvda 节点对宿主机的 /dev/sda 具有读写访问权限。
dns (list[str]) – 设置自定义 DNS 服务器。
dns_opt (list[str]) – 要添加到容器 resolv.conf 文件的附加选项。
dns_search (list[str]) – DNS 搜索域。
domainname (Union[str, list[str]]) – 设置自定义 DNS 搜索域。
entrypoint (Union[str, list[str]]) – 容器的入口点。
environment (Union[dict[str, str], list[str]) – 在容器内设置的环境变量,以字典或 list[str] 的形式,格式为 [“SOMEVARIABLE=xxx”, “SOMEOTHERVARIABLE=xyz”]。
extra_hosts (dict[str, str]) – 在容器内解析的其他主机名,以主机名到 IP 地址的映射形式。
group_add (list[str]) – 容器进程将作为其运行的附加组名和/或 ID 列表。
healthcheck (dict[str,Any]) – 指定一个测试来检查容器是否健康。
health_check_on_failure_action (int) – 指定健康检查失败时的操作。
hostname (str) – 容器的可选主机名。
init (bool) – 在容器内运行一个 init 进程,该进程会转发信号并回收进程。
init_path (str) – docker-init 二进制文件的路径。
ipc_mode (str) – 设置容器的 IPC 模式。
isolation (str) – 要使用的隔离技术。默认为:None。
kernel_memory (int or str) – 内核内存限制。
labels (Union[dict[str, str], list[str]) – 键值标签的字典(例如 {“label1”: “value1”, “label2”: “value2”})或具有空值的标签名称列表(例如 [“label1”, “label2”])。
links (Optional[dict[str, str]]) – 使用 {‘container’: ‘alias’} 格式的链接映射。别名是可选的。在此字典中声明的容器将使用提供的别名与新容器链接。默认:None。
log_config (LogConfig) – 日志记录配置。
lxc_config (dict[str, str]) – LXC 配置。
mac_address (str) – 分配给容器的 MAC 地址。
mem_limit (Union[int, str]) – 内存限制。接受浮点值(表示创建容器的内存限制,单位为字节)或带有单位标识符的字符串(100000b, 1000k, 128m, 1g)。如果指定的字符串没有单位字符,则假定单位为字节。
mem_reservation (Union[int, str]) – 内存软限制。
mem_swappiness (int) – 调整容器的内存 swappiness 行为。接受 0 到 100 之间的数字。
memswap_limit (Union[int, str]) – 容器允许消耗的内存 + swap 的最大量。
mounts (list[Mount]) –
添加到容器的挂载规范。比 volumes 更强大的替代方案。列表中的每个项都应为 Mount 对象。例如
[
{
“type”: “bind”,
”source”: “/a/b/c1”,
”target” “/d1”,
”read_only”: True,
”relabel”: “Z”
},
{
“type”: “tmpfs”,
# 如果未传递此参数,将创建常规目录
# 而不是 tmpfs 挂载!!!
# 因为这会导致 /proc/self/mountinfo
# 中出现无效条目
”source”: “tmpfs”,
”target” “/d2”,
”size”: “100k”,
”chown”: True
}
]
name (str) – 此容器的名称。
nano_cpus (int) – CPU 配额,单位为 1e-9 CPU。
networks (dict[str, dict[str, Union[str, list[str]]) –
容器创建期间将连接到容器的网络。网络配置的值可以是
字符串
字符串列表(例如,别名)
network_disabled (bool) – 禁用网络。
network_mode (str) –
以下选项之一:
bridge: 在 bridge 网络上为容器创建一个新的网络堆栈。
none: 此容器无网络。
container:<name|id>: 重用另一个容器的网络堆栈。
host: 使用宿主机网络堆栈。
ns:<path>: 用户定义的 netns 路径。
与 network 不兼容。
oom_kill_disable (bool) – 是否禁用 OOM kill。
oom_score_adj (int) – 一个整数值,包含给容器的分数,用于调整 OOM kill 的偏好。
pid_mode (str) – 如果设置为 host,则在容器内使用宿主机 PID 命名空间。
pids_limit (int) – 调整容器的 pids 限制。设置为 -1 表示无限制。
platform (str) – 格式为 os[/arch[/variant]] 的平台。仅在需要拉取所请求镜像时使用。
( (ports) –
- dict[
Union[int, str], Union[
int, Tuple[str, int], list[int], dict[
str, Union[
int, Tuple[str, int], list[int]
]
]
]
]): 要在容器内绑定的端口。
字典的键是要在容器内绑定的端口,可以是整数,也可以是 port/protocol 形式的字符串,其中 protocol 可以是 tcp, udp, 或 sctp。
字典的值是宿主机上要打开的相应端口,可以是
端口号,作为整数。
例如:{‘2222/tcp’: 3333} 将容器内的 2222 端口暴露为宿主机上的 3333 端口。
None,以分配一个随机宿主机端口。
例如:{‘2222/tcp’: None}。
一个 (address, port) 的元组,如果您想指定宿主机接口。
例如:{‘1111/tcp’: (‘127.0.0.1’, 1111)}。
一个整数或 (address, port) 元组的列表,如果您想将多个宿主机端口绑定到一个容器端口。
例如:{‘1111/tcp’: [1234, (“127.0.0.1”, 4567)]}。
- 例如:{‘9090’: 7878, ‘10932/tcp’: ‘8781’,
”8989/tcp”: (“127.0.0.1”, 9091)}
一个字典,包含上述选项,但随机宿主机端口除外。
- 该字典有一个附加选项 “range”,
允许绑定端口范围。
例如
{‘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) – 为此容器授予扩展权限。
publish_all_ports (bool) – 将所有端口发布到宿主机。
read_only (bool) – 将容器的根文件系统挂载为只读。
read_write_tmpfs (bool) – 在 read_only 选项设置为 True 的情况下,将临时文件系统挂载为读写。默认为 False。
remove (bool) – 容器完成后将其移除。默认为 False。
restart_policy (dict[str, Union[str, int]]) –
容器退出时重启容器。配置为一个字典,包含以下键:
Name: on-failure 或 always 之一。
MaximumRetryCount: 失败时重启容器的次数。
例如:{“Name”: “on-failure”, “MaximumRetryCount”: 5}
runtime (str) – 与此容器一起使用的运行时。
secrets (list[Union[str, Secret, dict[str, Union[str, int]]]]) –
要挂载到此容器的 secrets。
例如
- 作为字符串列表,每个字符串代表一个 secret 的 ID 或名称
[‘my_secret’, ‘my_secret2’]
- 作为 Secret 对象列表,从中读取相应的 ID
[Secret, Secret]
- 作为字典列表
[
{
- “source”: “my_secret”, # 一个字符串,代表
# 一个 secret 的 ID 或名称
- ”target”: “/my_secret”, # 一个可选的挂载源的目标,
# 默认为 /run/secrets/source
- ”uid”: 1000, # 一个可选的 UID,如果未给出则默认为 0
# 如果未给出
- ”gid”: 1000, # 一个可选的 GID,如果未给出则默认为 0
# 如果未给出
- ”mode”: 0o400, # 一个可选的模式,应用于目标,
# 使用 0o 前缀表示八进制整数
},
]
secret_env (dict[str, str]) –
要添加为容器内可用环境变量的 secrets。
例如:{“VARIABLE1”: “NameOfSecret”, “VARIABLE2”: “NameOfAnotherSecret”}
security_opt (list[str]) – 用于自定义 MLS 系统(如 SELinux)标签的 list[str] 字符串。
shm_size (Union[str, int]) – /dev/shm 的大小(例如 1G)。
stdin_open (bool) – 即使未附加,也保持 STDIN 打开。
stdout (bool) – 当 detach=False 时,返回 STDOUT 的日志。默认为 True。
stderr (bool) – 当 detach=False 时,返回 STDERR 的日志。默认为 False。
stop_signal (str) – 用于停止容器的停止信号(例如 SIGINT)。
storage_opt (dict[str, str]) – 每个容器的存储驱动程序选项,以键值映射形式。
stream (bool) – 如果为 true 且 detach 为 false,则返回日志生成器而不是字符串。如果 detach 为 true,则忽略。默认为 False。
sysctls (dict[str, str]) – 要在容器内设置的内核参数。
tmpfs (dict[str, str]) –
要挂载的临时文件系统,以字典形式,将容器内的路径映射到该路径的选项。
例如:{‘/mnt/vol2’: ‘’, ‘/mnt/vol1’: ‘size=3G,uid=1000’}
tty (bool) – 分配一个伪 TTY。
ulimits (list[Ulimit]) – 要在容器内设置的 ulimit。
use_config_proxy (bool) – 如果为 True,并且 docker 客户端配置文件(默认为 ~/.config/containers/config.json)包含代理配置,则相应的环境变量将在正在构建的容器中设置。
user (Union[str, int]) – 在容器内作为用户名或 UID 运行命令。
userns_mode (str) – 在启用了用户命名空间重新映射选项时,为容器设置用户命名空间模式。支持的值记录在此处。
uts_mode (str) – 设置容器的 UTS 命名空间模式。这些是支持的值。
version (str) – 要使用的 API 版本。设置为 auto 以自动检测服务器版本。默认:3.0.0
volume_driver (str) – 卷驱动程序/插件的名称。
volumes (dict[str, dict[str, Union[str, list]]]) –
用于配置挂载到容器内的卷的字典。键可以是宿主机路径或卷名,值是一个字典,包含以下键:
bind: 挂载卷到容器内的路径。
- mode: 值为 rw(读/写挂载)或 ro(只读挂载)。
为兼容 docker-py 而保留。
extended_mode: 传递给卷挂载的选项列表。
例如
{
‘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]) – 从中获取卷的容器名称或 ID 列表。
working_dir (str) – 工作目录的路径。
workdir (str) – working_dir 的别名 - 工作目录的路径。
- 返回:
一个 Container 对象。
- 抛出:
ImageNotFound – 当 Podman 服务未找到镜像时
APIError – 当 Podman 服务报告错误时