paunch 7.0.4

特性

• 仅单主机，操作通过podman客户端执行。

• 无外部状态，在确定操作将在哪些容器上执行时，只使用运行中的容器的标签。

• 单线程和阻塞，未配置为分离的容器将停止进一步配置，直到它们退出。

• 与其他容器配置工具共存。只有由paunch创建的容器将由paunch修改。如果想要的名称已被占用，将分配唯一的容器名称，当想要的名称变得可用时，容器将被重命名。

• 可通过paunch命令行实用程序或通过导入python包paunch来访问。

• 内置的debug命令可以让您看到单个容器是如何运行的，获取它们的配置信息，并以任何您需要的方式运行它们。

运行Paunch命令

paunch 只知道它为正在运行的容器设置的标签状态，因此用户需要跟踪哪些 paunch 配置应该运行，以便在清理时删除其他配置。在这些示例中，我们将把这种状态保存在一个简单的文本文件中。

$ touch paunch-state.txt

首先，我们将删除先前通过 paunch apply 调用启动的所有容器。

$ paunch --verbose cleanup $(cat paunch-state.txt)

接下来，我们将应用在 examples/hello-world.yml 中找到的简单 hello-world 配置，该配置包含以下内容：

hello:
  image: hello-world
  detach: false

通过以下方式应用：

$ paunch --verbose apply --file examples/hello-world.yml --config-id hi
$ echo hi >> paunch-state.txt

将创建一个名为 hello 的容器，打印一条“Hello World”消息，然后退出。您可以通过运行 podman ps -a 来确认它仍然存在。

现在让我们尝试运行相同的 paunch apply 命令。

$ paunch --verbose apply --file examples/hello-world.yml --config-id hi

由于 paunch 的幂等行为，这不会进行任何更改。

让我们再次尝试使用唯一的 –config-id。

$ paunch --verbose apply --file examples/hello-world.yml --config-id hi-again
$ echo hi-again >> paunch-state.txt

现在运行 podman ps -a 将显示现在有 2 个容器，一个名为 hello，另一个名为 hello-(random 后缀)。让我们删除与 hi config-id 相关的容器。

$ cat paunch-state.txt
$ echo hi-again > paunch-state.txt
$ cat paunch-state.txt
$ paunch --verbose cleanup $(cat paunch-state.txt)

运行 podman ps -a 将显示原始 hello 容器已被删除，hello-(random 后缀) 已被重命名为 hello。

通常，会首先运行 paunch cleanup 来删除不再应用的配置的容器。然后可以运行一系列 paunch apply 命令。如果这些 apply 调用是作为实时升级的一部分，并且旧的和新容器的混合将继续运行，则可以在下一次运行到 paunch cleanup 时通过更新的 config-id 状态列表完成升级。

paunch 还可以被其他工具用作库。默认情况下，运行 paunch 命令不会影响这些其他容器，因为这些容器上设置了不同的 managed_by 标签。例如，如果您想作为 heat-agents docker-cmd 钩子 运行 paunch 命令，则可以运行：

paunch --verbose apply --file examples/hello-world.yml --config-id hi --managed-by docker-cmd

这将在下一次 docker-cmd 钩子执行自己的 cleanup 运行时删除 hello 容器，因为它不会意识到名为 hi 的 config_id。

幂等行为

在许多情况下，用户将希望使用相同的 –config-id 与更改后的配置数据。幂等行为的目的是在配置没有更改时保留容器运行，但替换已修改配置的容器。

当使用相同的 --config-id 但修改后的配置数据运行 paunch apply 时，应用以下逻辑：

• 对于每个具有匹配的 config_id 和 managed_by 的现有容器：* 删除配置中不再存在的容器 * 删除缺少 config_data 标签的容器 * 删除 config_data 标签与当前配置不同的容器

• 由于删除已发生，进行完整重命名到所需的名称

• 只有在没有以该名称运行的容器时，才从配置创建容器

• exec 动作将会被执行，因此它们运行的命令可能需要自己的幂等性行为。

在 apply 期间，只有配置数据用于判断是否发生变化以触发替换容器。这意味着，如果配置数据中（如 env_file 中指定的路径）没有其他变化，那么改变 env_file 中引用的文件的内容将不会触发替换。

重启容器最常见的原因是让它们运行更新后的镜像。因此，建议在指定 image 时不要使用如 latest 这样的稳定镜像标签，并且在配置数据中更改发布版本标签是推荐的方式，以便将镜像更改传播到正在运行的容器。

使用 Paunch 进行调试

paunch debug 命令允许您在指定的容器上执行特定操作。这可以用来

• 以特定配置运行容器。

• 将给定容器的配置以 json 或 yaml 格式导出。

• 输出启动容器时使用的 podman 命令行。

• 以您希望添加的任何配置添加项运行容器，以便您可以用 shell 作为任何用户等运行它。

您可能会感兴趣的配置选项包括

--file <file>         YAML or JSON file containing configuration data
--action <name>       Action can be one of: "dump-json", "dump-yaml",
                      "print-cmd", or "run"
--container <name>    Name of the container you wish to manipulate
--interactive         Run container in interactive mode - modifies config
                      and execution of container
--shell               Similar to interactive but drops you into a shell
--user <name>         Start container as the specified user
--overrides <name>    JSON configuration information used to override
                      default config values

file 是包含您希望使用的容器配置的配置文件的名称。

以下是一个使用 paunch debug 在测试容器内部启动 root shell 的示例

# paunch debug --file examples/hello-world.yml --interactive --shell --user root --container hello --action run

这将使您进入一个交互式会话，在 hello world 容器中启动 /bin/bash，以 root 身份运行。

要查看容器通常是怎样启动的

# paunch debug --file examples/hello-world.yml --container hello --action print-cmd

您还可以将此配置导出到文件，以便您可以编辑它并使用不同的配置重新运行它。当单个文件中有多个配置时，这更有用。

# paunch debug --file examples/hello-world.yml --container hello --action dump-json > hello.json

编辑后，您可以使用 hello.json 作为 --file 参数。

您还可以在命令行上添加任何您希望添加的配置元素，以测试 paunch 或调试容器等。在这个例子中，我使用 net=host 运行 hello 容器。

# paunch debug --file examples/hello-world.yml --overrides '{"net": "host"}' --container hello --action run

配置格式

当前格式基于对 docker-compose v1 格式 的子集的修改。目的是让格式进化，以忠实实现现有的格式，例如 Kubernetes Pod 格式。

YAML 格式的顶层是一个字典，其中的键（通常）对应于要创建的容器的名称。以下配置创建名为 hello1 和 hello2 的两个容器

hello1:
  image: hello-world
hello2:
  image: hello-world

值是一个字典，它指定了在启动容器时使用的参数。支持的键符合 docker-compose v1 格式，如下所示

command

字符串或列表。覆盖默认命令。

detach

布尔值，默认为 true。如果为 true，则容器将在后台运行。如果为 false，则 paunch 将阻塞，直到容器退出。

environment

格式为 [‘KEY1=value1’，‘KEY2=value2’] 的列表。设置在容器中启动的过程可用的环境变量。

env_file

包含以行分隔的环境变量的文件路径列表。

image

字符串，必需。指定启动容器所需的镜像。可以是存储库/标签或部分镜像 ID。

net

字符串。设置容器的网络模式。

pid

字符串。设置容器的 PID 模式。

uts

字符串。设置容器的 UTS 命名空间。

privileged

布尔值，默认为 false。如果为 true，则给予此容器扩展权限。

restart

字符串。容器退出时应用的重启策略。

remove

布尔值：运行后删除容器。

interactive

布尔值：以交互模式运行容器。

tty

布尔值：为容器分配一个 tty 以与其交互。

user

字符串。设置用于指定命令的用户名或 UID，可选地设置用户组名或 GID。

volumes

字符串列表。指定此容器的挂载绑定。

volumes_from

字符串列表。从指定的容器中挂载卷。

log_tag

字符串。设置指定容器的日志标签。