名称

podman-kube.unit - 使用 Quadlet 管理 Podman Kubernetes YAML 部署的 systemd 单元文件

简介

名称.kube

描述

Kube 单元以 .kube 扩展名命名，并包含一个 [Kube] 部分，描述 podman kube play 如何作为服务运行。生成的服务文件包含一行类似于 ExecStart=podman kube play … file.yml 的内容，并且此部分中的大多数键都控制传递给 Podman 的命令行选项。然而，一些选项也影响 systemd 设置以运行和与容器交互的细节。

只有一个必填键 Yaml，它定义了 Kubernetes YAML 文件的路径。

使用摘要

.kube 文件在启动或重新加载时由 podman-system-generator 解析，生成一个运行 podman kube play 的 systemd .service。该服务可以像任何其他单元一样进行管理

systemctl --user start name.service

选项

[Kube] 的有效选项如下所示

[Kube] 选项	podman kube play 等效项
AutoUpdate=registry	--annotation “io.containers.autoupdate=registry”
ConfigMap=/tmp/config.map	--config-map /tmp/config.map
ContainersConfModule=/etc/nvd.conf	--module=/etc/nvd.conf
ExitCodePropagation=how	如何传播容器错误状态
GlobalArgs=--log-level=debug	--log-level=debug
KubeDownForce=true	--force (用于 podman kube down)
LogDriver=journald	--log-driver journald
Network=host	--network host
PodmanArgs=--annotation=key=value	--annotation=key=value
PublishPort=8080:80	--publish 8080:80
SetWorkingDirectory=yaml	将单元文件的 WorkingDirectory 设置为 YAML 文件的位置
UserNS=keep-id:uid=200,gid=210	--userns keep-id:uid=200,gid=210
Yaml=/tmp/kube.yaml	podman kube play /tmp/kube.yaml

[Kube] 部分中支持的键是

AutoUpdate=

指示容器是否将自动更新（podman-auto-update(1)）。AutoUpdate 可以多次指定。支持以下值

• registry：要求使用完全限定的镜像引用（例如，quay.io/podman/stable:latest）来创建容器。这种强制是必要的，以便知道实际检查和拉取哪些镜像。如果使用了镜像 ID，Podman 将不再知道要检查/拉取哪个镜像。

• local：告诉 Podman 将容器正在使用的镜像与本地存储中具有其原始名称的镜像进行比较。如果镜像在本地更新，Podman 只需重新启动执行 Kubernetes Quadlet 的 systemd 单元。

• name/(local|registry)：告诉 Podman 对指定的容器名称执行 local 或 registry 自动更新。

ConfigMap=path

使用路径上的 Kubernetes ConfigMap YAML 来为 pod 中容器内的环境变量值提供源。（此选项不适用于远程 Podman 客户端）

该值只能包含一个路径，但可以是绝对路径或相对于单元文件位置的相对路径。

ContainersConfModule=module

加载指定的 containers.conf(5) 模块。

此选项可以列出多次。

ExitCodePropagation=how

控制 systemd 服务的主 PID 应如何退出。支持以下值

• all：如果所有容器都失败（即，非零退出），则非零退出

• any：如果任何容器失败，则非零退出

• none：零退出并忽略失败的容器

当前的默认值是 none。

GlobalArgs=

此键包含在生成的文件中直接在 podman 命令之后传递的参数列表。它可用于访问生成器不支持的 Podman 功能。由于生成器不清楚这些参数可能导致哪些意外交互，因此不建议使用此选项。

其格式是空格分隔的参数列表，可以选择单独转义以允许包含空格和其他控制字符。

此键可以列出多次。

KubeDownForce=true

在调用 podman kube down 时移除所有资源，包括卷。等效于 Podman 的 --force 选项。

LogDriver=driver

容器的日志驱动程序。当前可用选项有 k8s-file、journald、none、passthrough 和 passthrough-tty，其中 json-file 作为 k8s-file 的别名用于脚本兼容性。（默认 journald）。

下面的 podman info 命令显示了系统的默认日志驱动。

$ podman info --format '{{ .Host.LogDriver }}'
journald

passthrough 驱动程序将标准流（stdin、stdout、stderr）传递给容器。它不允许与远程 Podman 客户端一起使用，包括 Mac 和 Windows（不包括 WSL2）机器，以及在 tty 上，因为它容易受到通过 TIOCSTI 的攻击。

passthrough-tty 驱动与 passthrough 相同，只是它也允许在 TTY 上使用，如果用户确实需要。

Network=mode

设置容器的网络模式。

特殊情况

• 如果网络的 name 以 .network 结尾，则使用名为 systemd-$name 的 Podman 网络，并且生成的 systemd 服务包含对 $name-network.service 的依赖。这种网络可以通过使用 $name.network Quadlet 文件自动创建。注意：相应的 .network 文件必须存在。

• 如果 name 以 .container 结尾，容器将重用由 $name.container 创建的另一个容器的网络堆栈。生成的 systemd 服务包含对 $name.service 的依赖。注意：相应的 .container 文件必须存在。

有效的 mode 值为：

• bridge[:OPTIONS,…]：在默认网桥上创建一个网络堆栈。这是 rootful 容器的默认设置。可以指定以下附加选项

  • alias=名称：为容器添加网络范围的别名。

  • ip=IPv4：为该容器指定静态 IPv4 地址。

  • ip6=IPv6：为该容器指定静态 IPv6 地址。

  • mac=MAC：为该容器指定静态 MAC 地址。

  • interface_name=名称：为容器内部创建的网络接口指定名称。

  • host_interface_name=名称：为容器外部创建的网络接口指定名称。

  任何其他选项将直接传递给 netavark，不进行验证。这对于将参数传递给 netavark 插件可能很有用。

  例如，要设置静态 ipv4 地址和静态 mac 地址，请使用 --network bridge:ip=10.88.0.10,mac=44:33:22:11:00:99。

• <网络名称或ID>[:OPTIONS,...]：连接到用户定义网络；这是由 podman network create 创建的网络名称或ID。可以指定上面桥接模式下描述的相同选项。多次使用 --network 选项可以指定其他网络。
  为了向后兼容，也可以在第一个 --network 参数上指定以逗号分隔的网络，但这会阻止您使用上面 bridge 部分描述的选项。

• none：为容器创建一个网络命名空间，但不为其配置网络接口，因此容器没有网络连接。

• container:id：重用另一个容器的网络堆栈。

• host：使用主机网络命名空间而不是创建隔离命名空间。警告：这会使容器完全访问抽象的 Unix 域套接字和绑定到 localhost 的 TCP/UDP 套接字。由于这些机制通常用于防止外部实体访问敏感系统服务，因此使用此选项可能会被视为安全漏洞。

• ns:path：要加入的网络命名空间的路径。

• private：为容器创建新的命名空间。这对于 rootful 容器使用 bridge 模式，对于 rootless 容器使用 slirp4netns。

• slirp4netns[:OPTIONS,...]：使用 slirp4netns(1) 创建用户网络堆栈。可以指定这些附加选项，也可以在 containers.conf 中使用 network_cmd_options 进行设置

  • allow_host_loopback=true|false：允许 slirp4netns 访问主机回环 IP（默认为 10.0.2.2 或当更改 slirp4netns cidr 子网时的第二个 IP，见下面的 cidr 选项）。默认为 false。

  • mtu=MTU：指定用于此网络的 MTU。（默认值为 65520）。

  • cidr=CIDR：指定用于此网络的 IP 范围。（默认值为 10.0.2.0/24）。

  • enable_ipv6=true|false：启用 IPv6。默认为 true。（outbound_addr6 需要）。

  • outbound_addr=INTERFACE：指定 slirp 绑定的出站接口（仅限 ipv4 流量）。

  • outbound_addr=IPv4：指定 slirp 绑定的出站 ipv4 地址。

  • outbound_addr6=INTERFACE：指定 slirp 绑定的出站接口（仅限 ipv6 流量）。

  • outbound_addr6=IPv6：指定 slirp 绑定的出站 ipv6 地址。

  • port_handler=rootlesskit：使用 rootlesskit 进行端口转发。默认值。
    注意：Rootlesskit 会将传入数据包的源 IP 地址更改为容器网络命名空间中的 IP 地址，通常是 10.0.2.100。如果应用程序需要真实的源 IP 地址，例如 Web 服务器日志，请使用 slirp4netns 端口处理程序。当连接到用户定义网络时，rootlesskit 端口处理程序也用于无根容器。

  • port_handler=slirp4netns：使用 slirp4netns 端口转发，它比 rootlesskit 慢，但保留了正确的源 IP 地址。此端口处理程序不能用于用户定义网络。

• pasta[:OPTIONS,…]：使用 pasta(1) 创建一个用户模式的网络栈。
  这是无根容器的默认设置，并且仅在无根模式下受支持。
  默认情况下，IPv4 和 IPv6 地址以及路由，以及 pod 接口名称，都从主机复制。端口转发保留原始源 IP 地址。pasta(1) 中描述的选项可以作为逗号分隔的参数指定。
  在 pasta(1) 选项方面，默认情况下会提供 --config-net，以便在容器启动时配置网络，并且默认情况下还会假定 --no-map-gw，以避免容器通过网关地址直接访问主机。后者可以通过在 pasta 特定选项中传递 --map-gw 来覆盖（尽管它不是实际的 pasta(1) 选项）。
  为了更好地与 DNS 处理集成，传递 --dns-forward 169.254.1.1，并且此地址作为第一个解析器添加到 resolv.conf(5)。如果应使用不同的 IP 地址，可以显式传递 --dns-forward。为了使 host.containers.internal /etc/hosts 条目起作用并允许连接到主机，传递 --map-guest-addr 169.254.1.2。同样，可以显式设置它以选择不同的 IP 地址。
  此外，如果未配置从主机到容器的 TCP 或 UDP 端口转发（通过 Podman 的 --publish 或直接传递 pasta -t/-u 选项），则分别传递 -t none 和 -u none，以禁用基于绑定端口的自动端口转发。类似地，传递 -T none 和 -U none 以禁用从容器到主机的相同功能。
  所有选项也可以在 containers.conf(5) 中设置；请参阅该文件中网络部分下的 pasta_options 键。
  一些示例：

  • pasta:--map-gw：允许容器使用网关地址直接访问主机。

  • pasta:--mtu,1500：为容器中的 tap 接口指定一个 1500 字节的 MTU。

  • pasta:--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-forward,10.0.2.3,-m,1500,--no-ndp,--no-dhcpv6,--no-dhcp，等同于默认 slirp4netns(1) 选项：禁用 IPv6，将 10.0.2.0/24 分配给容器中的 tap0 接口，网关为 10.0.2.3，启用可在 10.0.2.3 访问的 DNS 转发器，设置 MTU 为 1500 字节，禁用 NDP、DHCPv6 和 DHCP 支持。

  • pasta:-I,tap0,--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-forward,10.0.2.3,--no-ndp,--no-dhcpv6,--no-dhcp，等同于带有 Podman 覆盖的默认 slirp4netns(1) 选项：与上面相同，但将 MTU 保留为 65520 字节

  • pasta:-t,auto,-u,auto,-T,auto,-U,auto：启用基于从主机和容器两侧观察到的绑定端口的自动端口转发

  • pasta:-T,5201：启用从容器到主机的 TCP 端口 5201 的转发，使用回环接口而不是 tap 接口以提高性能

PodmanArgs=

此键包含在生成的文件中直接传递到 podman 命令末尾的参数列表。它可用于访问生成器不支持的 Podman 功能。由于生成器不清楚这些参数可能导致哪些意外交互，因此不建议使用此选项。

其格式是空格分隔的参数列表，可以选择单独转义以允许包含空格和其他控制字符。

此键可以列出多次。

PublishPort=[[ip:][hostPort]:]containerPort[/protocol]

将容器的端口或端口范围发布到主机。

hostPort 和 containerPort 都可以指定为端口范围。当同时指定两者的范围时，范围内的容器端口数必须与范围内的主机端口数匹配。

如果主机 IP 设置为 0.0.0.0 或根本未设置，则端口将绑定到主机上的所有 IP。

默认情况下，Podman 发布 TCP 端口。要发布 UDP 端口，请将 udp 作为协议。要同时发布 TCP 和 UDP 端口，请将 --publish 设置两次，分别使用 tcp 和 udp 作为协议。Rootful 容器还可以使用 sctp 协议发布端口。

不必指定主机端口（例如 podman run -p 127.0.0.1::80）。如果未指定，容器端口将随机分配一个主机端口。

使用 podman port 查看实际映射：podman port $CONTAINER $CONTAINERPORT。

端口发布仅支持通过 bridge 网络或 pasta 和 slirp4netns 网络模式使用其自己的网络命名空间的容器。

SetWorkingDirectory=yaml

设置 Systemd 服务单元文件中 Service 组的 WorkingDirectory 字段。用于允许 podman kube play 正确解析相对路径。支持的值为 yaml 和 unit，分别将工作目录设置为 YAML 或 Quadlet 单元文件所在目录。

或者，用户可以在 .kube 文件中显式设置 Service 组的 WorkingDirectory 字段。请注意，如果设置了 Service 组的 WorkingDirectory 字段，即使设置了 SetWorkingDirectory，Quadlet 也不会设置它

UserNS=mode

为容器设置用户命名空间模式。

如果未设置 --userns，则默认值按以下方式确定。

• 如果设置了 --pod，则忽略 --userns 并使用 pod 的用户命名空间。

• 如果设置了环境变量 PODMAN_USERNS，则使用其值。

• 如果在 containers.conf 中指定了 userns，则使用此值。

• 否则，假定为 --userns=host。

--userns=""（即空字符串）是 --userns=host 的别名。

此选项与 GIDMap=、UIDMap=、SubUIDMap= 和 SubGIDMap= 不兼容。

无根用户 --userns=键映射

键	主机用户	容器用户
auto	$UID	nil（主机用户 UID 未映射到容器中。）
host	$UID	0 (默认用户帐户映射到容器中的 root 用户。)
keep-id	$UID	$UID (将用户帐户映射到容器内的相同 UID。)
keep-id:uid=200,gid=210	$UID	200:210 (将用户帐户映射到容器内指定的 UID, GID 值。)
nomap	$UID	nil（主机用户 UID 未映射到容器中。）

有效的 mode 值为：

auto[:OPTIONS,...]：自动创建唯一的用户命名空间。

• rootful mode：--userns=auto 标志要求在 /etc/subuid 和 /etc/subgid 文件中指定用户名为 containers，并带有一个 Podman 容器允许分配的未使用的从属用户 ID 范围。示例：containers:2147483647:2147483648。

• rootless mode：将使用 /etc/subuid 和 /etc/subgid 文件中的用户范围。请注意，在不使用 --userns=auto 的情况下运行单个容器将使用整个 UID 范围，并且不允许进一步细分。请参阅 subuid(5)。

Podman 从 containers 从属用户 ID 分配唯一的 UID 和 GID 范围。范围的大小基于镜像中所需的 UID 数量。size 选项可以覆盖 UID 和 GID 的数量。

选项 --userns=keep-id 使用用户的所有 subuid 和 subgid。选项 --userns=nomap 使用用户的所有 subuid 和 subgid，除了用户自己的 ID。当任何使用 --userns=nomap 或 --userns=keep-id 且未限制用户命名空间大小的容器存在时，使用 --userns=auto 启动新容器将不起作用。

有效的 auto 选项

• gidmapping=CONTAINER_GID:HOST_GID:SIZE：强制用户命名空间中存在 GID 映射。

• size=SIZE：为自动用户命名空间指定显式大小。例如 --userns=auto:size=8192。如果未指定 size，则 auto 会估计用户命名空间的大小。

• uidmapping=CONTAINER_UID:HOST_UID:SIZE：强制用户命名空间中存在 UID 映射。

gidmapping 和 uidmapping 中的主机 UID 和 GID 可以选择以 @ 符号作为前缀。在这种情况下，podman 将查找对应于主机 ID 的中间 ID，并将其映射到容器 ID。有关详细信息，请参阅 UIDMap=。

container:id：加入指定容器的用户命名空间。

host 或 “”（空字符串）：在调用者的用户命名空间中运行。在容器中运行的进程在主机上与调用用户启动的任何其他进程具有相同的权限。

keep-id：创建一个用户命名空间，其中当前用户的 UID:GID 映射到容器中的相同值。对于由 root 创建的容器，当前映射将创建到新的用户命名空间中。

有效的 keep-id 选项

• uid=UID：覆盖容器内部的 UID，用于映射当前用户。

• gid=GID：覆盖容器内部的 GID，用于映射当前用户。

• size=SIZE：覆盖配置的用户命名空间的大小。这对于避免饱和所有可用 ID 很有用。在作为 root 运行时不支持。

nomap：创建一个用户命名空间，其中当前无根用户的 UID:GID 不映射到容器中。此选项不允许用于由 root 用户创建的容器。

ns:namespace：在给定的现有用户命名空间中运行。

Yaml=path

要使用的 Kubernetes YAML 文件的路径，可以是绝对路径或相对于单元文件位置的相对路径。

示例

从本地 YAML 部署

[Unit]
Description=A kubernetes yaml based service
Before=local-fs.target

[Kube]
Yaml=/opt/k8s/deployment.yml

[Install]
# Start by default on boot
WantedBy=multi-user.target default.target

另请参阅

systemd.unit(5), podman-kube-play(1), podman-kube-generate(1), [podman-quadlet(7)]