容器

容器资源的模型和管理器。

class Container(attrs: Mapping[str, Any] | None = None, client: APIClient | None = None, collection: Manager | None = None, podman_client: PodmanClient | None = None)

基类：PodmanResource

由 Podman 服务管理的容器的详细信息和配置。

初始化 PodmanResource 的基类。

参数:

• attrs – Podman 服务资源属性的映射。

• client – Podman 服务的配置连接。

• collection – 此类资源的管理器，为了兼容性命名为 collection

• podman_client – 配置为连接到 Podman 对象的 PodmanClient()。

attach(**kwargs) → str | Iterator[str]

连接到容器的 tty。

关键字参数:

• stdout (bool) – 包含标准输出。默认值：True

• stderr (bool) – 包含标准错误。默认值：True

• stream (bool) – 返回字符串迭代器而非单个字符串。默认值：False

• logs (bool) – 包含之前的容器输出。默认值：False

抛出:

NotImplementedError – 方法未实现。

attach_socket(**kwargs)

未实现。

抛出:

NotImplementedError – 方法未实现。

commit(repository: str = None, tag: str = None, **kwargs) → Image

将容器保存到给定仓库。

参数:

• repository – 保存镜像的仓库

• tag – 随镜像推送的标签

关键字参数:

• author (str) – 提交作者姓名

• changes (list[str]) – 提交期间要应用的指令

• comment (str) – 随镜像附带的提交消息，覆盖关键字消息

• conf (dict[str, Any]) – 忽略。

• format (str) – 镜像清单和元数据的格式

• message (str) – 随镜像附带的提交消息

• pause (bool) – 在提交前暂停容器

diff() → list[dict[str, int]]

报告容器文件系统的更改。

抛出:

APIError – 当服务报告错误时

exec_run(cmd: str | list[str], *, stdout: bool = True, stderr: bool = True, stdin: bool = False, tty: bool = False, privileged: bool = False, user=None, detach: bool = False, stream: bool = False, socket: bool = False, environment: Mapping[str, str] | list[str] = None, workdir: str = None, demux: bool = False) → tuple[int | None, Iterator[bytes | tuple[bytes, bytes]] | Any | tuple[bytes, bytes]]

在容器内运行给定命令并返回结果。

参数:

• cmd – 要执行的命令

• stdout – 连接到标准输出。默认值：True

• stderr – 连接到标准错误。默认值：True

• stdin – 连接到标准输入。默认值：False

• tty – 分配一个伪TTY。默认值：False

• privileged – 以特权模式运行。

• user – 执行命令的用户。

• detach – 如果为 True，则从 exec 命令分离。默认值：False

• stream – 流式传输响应数据。如果 detach 为 True 则忽略。默认值：False

• socket – 返回连接套接字以允许自定义读/写操作。默认值：False

• environment – 字典或列表[str]，格式为 ["PASSWORD=xxx"] 或 {"PASSWORD": "xxx"}。

• workdir – 此 exec 会话的工作目录路径

• demux – 分别返回标准输出和标准错误

返回:

元组 (response_code, output)。 response_code

所提供命令的退出代码。如果 stream 为 None。

输出:

如果 stream 为 True，则是一个生成器，生成响应块。如果 demux 为 True，则是一个元组 (stdout, stderr)。否则为响应内容。

抛出:

• NotImplementedError – 方法未实现。

• APIError – 当服务报告错误时

export(chunk_size: int = 2097152) → Iterator[bytes]

将容器的文件系统内容下载为 tar 存档。

参数:

chunk_size – 生成器每次迭代返回的字节数。

生成:

tarball，按大小/chunk_size 分块

抛出:

• NotFound – 当容器已从服务中移除时

• APIError – 当服务报告错误时

get_archive(path: str, chunk_size: int = 2097152) → tuple[Iterable, dict[str, Any]]

从容器的文件系统下载文件或文件夹。

参数:

• path – 文件或文件夹的路径。

• chunk_size – 生成器每次迭代返回的字节数。

返回:

第一项是原始 tar 数据流。第二项是包含指定路径的 os.stat() 信息的字典。

init() → None

初始化容器。

inspect() → dict

检查容器。

抛出:

APIError – 当服务报告错误时

kill(signal: str | int | None = None) → None

向容器发送信号。

抛出:

APIError – 当服务报告错误时

logs(**kwargs) → bytes | Iterator[bytes]

从容器获取日志。

关键字参数:

• stdout (bool) – 包含标准输出。默认值：True

• stderr (bool) – 包含标准错误。默认值：True

• stream (bool) – 返回字符串生成器作为响应。默认值：False

• timestamps (bool) – 在输出中显示时间戳。默认值：False

• tail (Union[str, int]) – 输出日志末尾指定行数。整数表示要显示的行数，或字符串 "all"。默认值："all"

• since (Union[datetime, int]) – 显示给定日期时间或整数纪元（以秒为单位）以来的日志

• follow (bool) – 跟踪日志输出。默认值：False

• until (Union[datetime, int]) – 显示在给定日期时间或整数纪元（以秒为单位）之前发生的日志

pause() → None

暂停容器内的进程。

put_archive(path: str, data: bytes = None) → bool

上传包含文件或文件夹的 tar 存档，以写入容器。

参数:

• path – 写入数据的文件

• data – 要写入文件的内容，当 None 时将在客户端读取 path 以构建 tarfile。

返回:

成功时为 True

抛出:

APIError – 当服务器报告错误时

reload(**kwargs) → None

从服务刷新此对象的数据。

关键字参数:

compatible (bool) – 使用 Docker 兼容端点

remove(**kwargs) → None

删除容器。

关键字参数:

• v (bool) – 也删除关联的卷。

• link (bool) – 忽略。

• force (bool) – 在删除之前终止正在运行的容器。

rename(name: str) → None

重命名容器。

容器已原地更新以避免 reload()。

参数:

name – 容器的新名称。

resize(height: int = None, width: int = None) → None

调整 tty 会话的大小。

参数:

• height – tty 会话的新高度。

• width – tty 会话的新宽度。

restart(**kwargs) → None

重启容器中的进程。

关键字参数:

timeout (int) – 在终止容器之前等待容器停止的秒数。

start(**kwargs) → None

启动容器中的进程。

关键字参数:

detach_keys – 覆盖分离容器的按键序列（仅限 Podman）

stats(**kwargs) → bytes | dict[str, Any] | Iterator[bytes] | Iterator[dict[str, Any]]

返回容器的统计信息。

关键字参数:

• decode (bool) – 如果为 True 且 stream 为 True，则 stream 将解码为字典。默认值：False。

• stream (bool) – 流式传输统计信息直到取消。默认值：True。

抛出:

APIError – 当服务报告错误时

stop(**kwargs) → None

停止容器。

关键字参数:

• all (bool) – 为 True 时，停止所有容器。默认值：False（仅限 Podman）

• ignore (bool) – 为 True 时，如果容器已停止则忽略错误（仅限 Podman）

• timeout (int) – 在终止容器之前等待容器停止的秒数。

top(**kwargs) → Iterator[dict[str, Any]] | dict[str, Any]

报告容器中正在运行的进程。

关键字参数:

• ps_args (str) – 给定时，参数将传递给 ps

• stream (bool) – 为 True 时，重复返回结果。默认值：False

抛出:

• NotFound – 当容器不再存在时

• APIError – 当服务报告错误时

unpause() → None

取消暂停容器中的进程。

update(**kwargs) → None

更新容器的资源配置。 :keyword 请参阅 Podman API 文档了解详细信息： :keyword https://docs.podman.org.cn/en/latest/_static/api.html#tag/containers/operation/ContainerUpdateLibpod :keyword restart_policy: 容器的新重启策略。 :kwtype restart_policy: str :keyword restart_retries: 容器重启策略的新重试次数。

仅当 restartPolicy 设置为 on-failure 时允许

关键字参数:

• tuple (blkio_weight_device) – 块 IO 权重（相对设备权重），形式为：(device_path, weight)

• blockio (dict) –

  适用于 Linux cgroup 'blkio' 资源管理的 LinuxBlockIO 示例：blockio = {

  "leafWeight": 0 "throttleReadBpsDevice": [{

  "major": 0, "minor": 0, "rate": 0

  }], "throttleReadIopsDevice": [{

  "major": 0, "minor": 0, "rate": 0

  }], "throttleWriteBpsDevice": [{

  "major": 0, "minor": 0, "rate": 0

  }], "throttleWriteIopsDevice": [{

  "major": 0, "minor": 0, "rate": 0

  }], "weight": 0, "weightDevice": [{

  "leafWeight": 0, "major": 0, "minor": 0, "weight": 0

  }],

  }

• cpu (dict) –

  用于 Linux cgroup 'cpu' 资源管理的 LinuxCPU 示例：cpu = {

  "burst": 0, "cpus": "string", "idle": 0, "mems": "string", "period": 0 "quota": 0, "realtimePeriod": 0, "realtimeRuntime": 0, "shares": 0

  }

• device_read_bps (list(dict)) – 限制从设备读取速率（每秒字节数），形式为：[{“Path”: “string”, “Rate”: 0}]

• device_read_iops (list(dict)) – 限制从设备读取速率（每秒 IO 操作数），形式为：[{“Path”: “string”, “Rate”: 0}]

• device_write_bps (list(dict)) – 限制写入设备的速率（每秒字节数），形式为：[{“Path”: “string”, “Rate”: 0}]

• device_write_iops (list(dict)) – 限制写入设备的速率（每秒 IO 操作数），形式为：[{“Path”: “string”, “Rate”: 0}]

• devices (list(dict)) –

  设备配置设备允许列表。示例：devices = [{

  access: “string” allow: 0, major: 0, minor: 0, type: “string”

  }]

• health_cmd (str) – 为容器设置健康检查命令（'None' 禁用现有健康检查）

• health_interval (str) – 为健康检查设置间隔（值为 disable 会导致不设置自动计时器）（更改此设置会重置计时器。）（默认 "30s"）

• health_log_destination (str) – 设置健康检查日志的目标。目录路径，local 或 events_logger（local 使用容器状态文件）（警告：更改此设置可能导致丢失之前的日志。）（默认 "local"）

• health_max_log_count (int) – 设置健康检查日志文件中的最大尝试次数。（'0' 值表示日志文件中的无限次尝试）（默认 5）

• health_max_logs_size (int) – 设置存储的健康检查日志的最大长度（以字符为单位）。（'0' 值表示无限日志长度）（默认 500）

• health_on_failure (str) – 容器变得不健康时要采取的操作（默认 "none"）

• health_retries (int) – 在健康检查被认为不健康之前允许的重试次数（默认 3）

• health_start_period (str) – 容器引导所需的初始化时间（默认 "0s"）

• health_startup_cmd (str) – 为容器设置启动健康检查命令

• health_startup_interval (str) – 为启动健康检查设置间隔。更改此设置会重置计时器，具体取决于容器的状态。（默认 "30s"）

• health_startup_retries (int) – 设置启动健康检查重新启动容器之前允许的最大重试次数

• health_startup_success (int) – 设置启动健康检查被标记为成功并开始正常健康检查之前的连续成功次数（0 表示任何成功都会开始常规健康检查）

• health_startup_timeout (str) – 设置启动健康检查在被视为失败之前可能花费的最大时间（默认 "30s"）

• health_timeout (str) – 完成健康检查所需的最大时间，超过此时间间隔即视为失败（默认 "30s"）

• no_healthcheck (bool) – 禁用容器上的健康检查

• hugepage_limits (list(dict)) –

  巨页限制（以字节为单位）。如果支持，则默认为预留限制。.. 警告:: 示例

  huugepage_limits = [{“limit”: 0, “pageSize”: “string”}]

• memory (dict) –

  用于 Linux cgroup 'memory' 资源管理的 LinuxMemory 示例：memory = {

  "checkBeforeUpdate": True, "disableOOMKiller": True, "kernel": 0, "kernelTCP": 0, "limit": 0, "reservation": 0, "swap": 0, "swappiness": 0, "useHierarchy": True,

  }

• network (dict) –

  LinuxNetwork 识别和优先级配置 示例：network = {

  "classID": 0, "priorities": {

  "name": "string", "priority": 0

  }

  )

• pids (dict) –

  用于 Linux cgroup 'pids' 资源管理 (Linux 4.3) 的 LinuxPids .. 警告:: 示例

  pids = {

  "limit": 0

  }

• rdma (dict) –

  Rdma 资源限制配置。Limits 是一组键值对，用于定义 RDMA 资源限制，其中键是设备名称，值是资源限制。示例：rdma = {

  "property1": {

  "hcaHandles": 0 "hcaObjects": 0

  }, "property2": {

  "hcaHandles": 0 "hcaObjects": 0

  }

• unified (dict) –

  统一资源。示例：unified = {

  "property1": "value1", "property2": "value2", ...

  }

wait(**kwargs) → int

阻塞直到容器进入给定状态。

关键字参数:

• condition (Union[str, list[str]]) – 容器状态，在此状态下释放。以下一项或多项："configured"、"created"、"running"、"stopped"、"paused"、"exited"、"removing"、"stopping"。

• interval (int) – 轮询完成之前等待的时间间隔。

返回:

"Error" 键有一个字典值，其键为 "Message"。

抛出:

• NotFound – 未找到容器时

• ReadTimeoutError – 超时超出时

• APIError – 服务返回错误时

property id

返回对象的标识符。

类型:

str

property image

返回用于创建容器的 Image 对象。

类型:

podman.domain.images.Image

property labels

返回与容器关联的标签。

类型:

dict[str, str]

property name

返回容器的名称。

类型:

str

property ports

返回容器暴露的端口。

类型:

dict[str, int]

property short_id

返回截断的标识符。当包含在 id 中时，保留“sha256”。

不尝试确保返回的值对所有资源都具有语义意义。

类型:

str

property status

Literal["created", "initialized", "running", "stopped", "exited", "unknown"]: 返回容器的状态。