containers_manager¶
Podman资源管理器是容器的子类。
- class ContainersManager(client: APIClient | None = None, podman_client: PodmanClient | None = None)[source]¶
基类:
RunMixin
,CreateMixin
,Manager
用于容器资源的专用管理器。
初始化 Manager() 对象。
- 参数:
client – 配置为连接到 Podman 服务的 APIClient()。
podman_client – 配置为连接到 Podman 对象的 PodmanClient()。
- 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”: “设备路径”, “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”: “设备路径”, “Rate”: 速率}]
device_read_iops – 限制从设备读取速率(每秒IO)。
device_write_bps – 限制向设备写入速率(每秒字节数)。
device_write_iops – 限制向设备写入速率(每秒IO)。
devices (list[str]) –
将主机设备暴露给容器,以列表[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]) – 要在容器内设置的环境变量,可以是字典或列表[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]]) – 使用 {‘容器’: ‘别名’} 格式的链接映射。别名是可选的。此字典中声明的容器将使用提供的别名链接到新容器。默认值: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) – 调整容器的内存交换行为。接受0到100之间的数字。
memswap_limit (Union[int, str]) – 容器允许消耗的最大内存+交换空间。
mounts (list[Mount]) –
要添加到容器的挂载规范。比卷更强大的替代方案。列表中的每个项目都应是一个Mount对象。例如
[
{
“type”: “bind”,
”source”: “/a/b/c1”,
”target” “/d1”,
”read_only”: True,
”relabel”: “Z”
},
{
“type”: “tmpfs”,
# 如果没有传入,则会创建常规目录
# 而不是tmpfs挂载!!!
# 因为这会导致/proc/self/mountinfo中有无效条目
# in /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: 在桥接网络上为容器创建新的网络堆栈。
none: 此容器无网络。
container:<name|id>: 重用另一个容器的网络堆栈。
host: 使用主机网络堆栈。
ns:<path>: 用户定义的网络命名空间路径。
与网络不兼容。
oom_kill_disable (bool) – 是否禁用OOM killer。
oom_score_adj (int) – 一个整数值,包含赋予容器的分数,以调整OOM killer偏好。
pid_mode (str) – 如果设置为host,则在容器内使用主机PID命名空间。
pids_limit (int) – 调整容器的pid限制。设置为-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形式的字符串,其中协议可以是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]]]]) –
要挂载到此容器的秘密。
例如
- 作为字符串列表,每个字符串代表一个秘密的ID或名称
[‘my_secret’, ‘my_secret2’]
- 作为Secret对象列表,从其中读取相应的ID
[Secret, Secret]
- 作为字典列表
[
{
- “source”: “my_secret”, # 代表秘密ID或名称的字符串
# 一个秘密
- ”target”: “/my_secret”, # 可选的挂载目标,
# 默认为/run/secrets/source
- ”uid”: 1000, # 可选的UID,如果未给出则默认为0
# 如果未给出
- ”gid”: 1000, # 可选的GID,默认为0
# 如果未给出
- ”mode”: 0o400, # 应用于目标的optional mode,
# 使用0o前缀表示八进制整数
},
]
secret_env (dict[str, str]) –
要作为环境变量添加到容器中的秘密。
例如:{“VARIABLE1”: “NameOfSecret”, “VARIABLE2”: “NameOfAnotherSecret”}
security_opt (list[str]) – 字符串值列表,用于自定义MLS系统(如SELinux)的标签。
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 服务报告错误时
- get(key: str, **kwargs) Container [source]¶
按名称或ID获取容器。
- 参数:
key – 容器名称或ID。
- 关键字参数:
compatible (bool) – 使用 Docker 兼容端点
- 返回:
对应于key的Container对象。
- 抛出:
NotFound – 当容器不存在时
APIError – 当服务返回错误时
- list(**kwargs) list[Container] [source]¶
报告容器。
- 关键字参数:
all – 如果为 False,则只显示正在运行的容器。默认值:False。
since – 显示在给定容器名称或ID之后创建的容器。
before – 显示在给定容器名称或ID之前创建的容器。
limit – 显示最后N个创建的容器。
filters –
过滤报告的容器。可用过滤器
exited (int): 仅显示具有指定退出代码的容器
status (str): 以下之一:restarting, running, paused, exited
label (Union[str, list[str]]): 格式为“key”、“key=value”或此类列表。
id (str): 容器的ID。
name (str): 容器的名称。
- ancestor (str): 按容器祖先过滤。格式为
<image-name>[:tag], <image-id>, or <image@digest>。
- before (str): 仅显示在特定容器之前创建的容器。
提供容器名称或ID。
- since (str): 仅显示在特定容器之后创建的容器。
提供容器名称或ID。
sparse – 如果为 False,则返回基本的容器信息,而不进行额外的检查请求。这在列出许多容器时可以提高性能,但可能提供较少的详细信息。您可以稍后在单个容器上调用Container.reload()以检索完整的属性。默认值:True。当启用Docker兼容性(compatible=True)时:默认值:False。
ignore_removed – 如果为 True,则忽略由于缺少容器而导致的失败。
- 抛出:
APIError – 服务返回错误时
- prepare_model(attrs: PodmanResource | Mapping[str, Any]) PodmanResourceType ¶
从一组属性创建模型。
- prune(filters: Mapping[str, str] = None) dict[str, Any] [source]¶
删除已停止的容器。
- 参数:
filters – 确定要移除的容器的标准。可用键包括: - until (str): 删除此时间之前的容器 - label (list[str]): 与容器关联的标签
- 返回:
ContainersDeleted (list[str]): 已删除容器的标识符。
SpaceReclaimed (int): 回收的磁盘空间量(以字节为单位)。
- Return type:
键
- 抛出:
APIError – 当服务报告错误时
- remove(container_id: Container | str, **kwargs)[source]¶
删除容器。
仅限 Podman
- 参数:
container_id – 要删除的容器的标识符。
- 关键字参数:
v (bool) – 同时删除相关卷。
link (bool) – 忽略。
force (bool) – 在删除之前杀死正在运行的容器。
- 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() 将等待容器完成并返回其日志。
- 如果 detach=True,run() 将启动容器并返回一个 Container 对象而不是
日志。在这种情况下,如果 remove=True,run() 将监视并在容器运行结束后删除它;在这种情况下,日志将丢失。
- 参数:
image – 要运行的镜像。
command – 在容器中运行的命令。
stdout – 包含标准输出。默认值:True。
stderr – 包含标准错误。默认值:False。
remove – 当容器进程退出时,在客户端删除容器。auto_remove 标志也用于管理守护进程端的删除。默认值:False。
- 关键字参数:
found. (- 当镜像未找到时,这些参数直接用于拉取镜像。) – auth_config (Mapping[str, str]): 覆盖请求中在配置中找到的凭据。auth_config 应包含有效的用户名和密码键。platform (str): 平台,格式为 os[/arch[/variant]]。policy (str): 拉取策略。“missing”(默认)、“always”、“never”、“newer”
arguments. (- 有关其他关键字,请参阅create()方法。)
- 返回:
当 detach 为 True 时,返回一个 Container
如果 stdout 为 True,输出中包含容器的标准输出
如果 stderr 为 True,输出中包含容器的标准错误
当 stream 为 True 时,容器的输出作为生成器返回
否则,容器完成后返回一个迭代器
- 抛出:
ContainerError – 当容器以非零代码退出时
ImageNotFound – 当Podman服务未找到镜像时
APIError – 当 Podman 服务报告错误时
- property resource¶
prepare_model() 将创建 Container 类。
- 类型:
Type[Container]