Podman Quadlet: Network units 详析

知识 | Knowledge 2025年11月17日

1 First | 序

Podman Quadlet 的 .network 单元文件是一种声明式配置文件，用于描述一个具名的 Podman 网络并将这些网络资源无缝集成到 systemd 。

1.1 描述 (Description)

.network 单元的工作机制清晰且高效。当 systemd 启动时，Quadlet 生成器会解析一个名为 $NAME.network 的文件，并据此生成一个名为 $NAME-network.service 的 systemd 服务单元。此服务本质上是一个一次性执行的任务，其唯一目标是确保一个特定名称的 Podman 网络在主机上存在。默认情况下，该网络名为 systemd-$NAME（其中 $NAME 是单元文件的基本名称），但此名称可通过文件内的 NetworkName 选项进行覆盖。如果该网络不存在，服务会自动执行 podman network create 命令来创建它；如果网络已存在，则服务不执行任何操作并成功退出。

有两点注意事项：

停止服务不移除网络：执行 systemctl stop $NAME-network.service 命令并不会删除已创建的 Podman 网络。网络资源默认是持久化的。
不支持 reload ：Quadlet 不支持对一个已存在的 Podman 网络进行参数更新。若要修改网络配置，必须首先手动使用 podman network rm 命令删除旧网络，然后重启相应的 systemd 服务来重新创建。

2. .Network options

本章节将系统性地剖析 .network 中的配置指令。

为了便于理解和实际应用，下文将选项按照其功能逻辑划分为四个类别：

基础与核心配置
IP 地址与子网管理
DNS 与连接性
高级与生命周期管理

2.1 基础与核心配置

NetworkName=

功能解析：用于指定 Podman 网络的（可选）自定义名称。如果未指定此项，Quadlet 将使用默认值。
对应 Podman 命令：podman network create $name
使用场景：当您需要一个可预测且易于引用的网络名称，而不是由 Quadlet 自动生成的格式化名称时使用。这对于脚本自动化或在多个单元文件中引用同一网络非常有用。
默认值：systemd-$NAME（其中 $NAME 是 .network 单元文件的基本名称）。
注意事项：无。

Driver=

功能解析：指定管理该网络的驱动程序。目前支持 bridge、macvlan 和 ipvlan。
对应 Podman 命令：--driver $driver
使用场景：
- bridge：创建标准的、基于 NAT 的隔离网络，是容器间通信最常用的模式。
- macvlan/ipvlan：将容器直接连接到物理网络，使其拥有与主机在同一网段的 IP 地址，适用于需要容器作为网络一等公民的场景。
默认值：bridge
注意事项：选择的驱动将决定网络的行为模式和可用的其他配置选项。

InterfaceName=

功能解析：此选项的含义完全取决于 Driver 的设置。对于 bridge 驱动，它为新创建的虚拟网桥设备命名。对于 macvlan 和 ipvlan 驱动，它则指定了必须已经存在的主机物理网络接口（如 eth0），作为容器连接到外部网络的父接口。
对应 Podman 命令：--interface-name $name
使用场景：在创建 macvlan 或 ipvlan 网络时，使用此选项来指定一个物理网络接口（如 eth0），以将容器网络桥接到该物理链路上。
默认值：未指定。
注意事项：对于 macvlan 和 ipvlan 驱动，此设置在底层等效于为网络传递 --opt parent=$name 选项。

2.2 IP 地址与子网管理

此类别下的选项专注于网络的逻辑地址空间规划，包括以下内容:

定义子网
网关
IP 分配范围
启用 IPv6 支持

Subnet=

功能解析：以 CIDR 表示法定义网络的子网。
对应 Podman 命令：--subnet $subnet
使用场景：为网络规划一个明确的 IP 地址范围，例如 10.88.0.0/16。这有助于避免 IP 冲突，并为后续定义网关和 IP 分配范围提供基础。此选项可多次指定以创建多个子网。
默认值：未指定。
注意事项：无。

Gateway=

功能解析：为指定的子网定义一个网关地址。
对应 Podman 命令：--gateway $ip
使用场景：当容器需要与网络外部通信时，需要为其子网指定一个网关。例如，为子网 192.168.55.0/24 指定网关 192.168.55.1。此选项可多次指定。
默认值：未指定。
注意事项：必须与 Subnet 选项一同使用。

IPRange=

功能解析：指定一个从中分配容器 IP 地址的范围。该范围必须是 Subnet 的子集。
对应 Podman 命令：--ip-range $range
使用场景：将容器的动态 IP 地址限制在子网内的一个特定小范围，以保留其他地址用于静态分配或未来扩展。支持 CIDR 格式（如 10.88.0.0/24）或范围格式（如 10.88.0.100-10.88.0.200）。此选项可多次指定。
默认值：未指定。
注意事项：必须与 Subnet 选项一同使用。

IPAMDriver=

功能解析：设置网络的 IP 地址管理（IPAM）驱动。目前支持 host-local、dhcp 和 none。
对应 Podman 命令：--ipam-driver $driver
使用场景：
- host-local：Podman 在本地管理 IP 分配。
- dhcp：使用外部 DHCP 服务器来为容器分配 IP。
- none：禁用 IP 地址管理。
默认值：未指定。
注意事项：虽然 Quadlet 未指定默认值，但 Podman 在未明确指定驱动时通常会使用 host-local 驱动，要检查现有网络的 IPAM 驱动程序，可以使用 podman network inspect <network_name> 并查看该 ipam_options 字段。

IPv6=

功能解析：为网络启用 IPv6 双栈（Dual Stack）网络支持。
对应 Podman 命令：--ipv6
使用场景：在需要容器同时支持 IPv4 和 IPv6 通信的环境中使用。
默认值：未指定（默认为禁用）。
注意事项：无。

2.3 DNS 与连接性

这些选项负责管理容器的域名解析能力和网络的外部访问策略。它们是控制容器化服务发现和实现网络安全隔离的工具。

DNS=

功能解析：为此网络中的容器设置一个网络范围的 DNS 解析服务器。
对应 Podman 命令：--dns $ip
使用场景：当你希望网络内的所有容器都使用一个特定的内部或外部 DNS 服务器（如 192.168.1.1 或 8.8.8.8）进行域名解析时使用。此选项可多次指定。
默认值：未指定。
注意事项：无。

DisableDNS=

功能解析：如果启用，将为此网络禁用 Podman 的 DNS 插件。
对应 Podman 命令：--disable-dns
使用场景：当您不希望 Podman 为此网络提供内置的、基于容器名的 DNS 解析服务时，可以禁用此功能，完全依赖手动配置的 DNS 服务器。
默认值：false
注意事项：无。

Internal=

功能解析：限制此网络的外部访问。
对应 Podman 命令：--internal
使用场景：构建一个包含数据库和应用后端的两层应用架构。通过将它们放置在 Internal 网络中，可以确保数据库容器完全无法从外部访问，甚至无法通过主机的 NAT 访问外部世界，从而强制执行严格的安全边界，只允许同一网络内的应用后端进行通信。
默认值：false
注意事项：无。

2.4 高级与生命周期管理

此类别涵盖了一些高级的配置，例如为网络附加元数据标签、传递特定于驱动的参数，以及定义网络资源是否应随其管理的 systemd 服务停止而被自动清理。

Label=

功能解析：在创建的网络上设置一个或多个 OCI 标签（元数据）。
对应 Podman 命令：--label <key=value>
使用场景：为网络添加描述性信息，如 owner=team-alpha 或 environment=production。这些标签可用于后续的查询、筛选或自动化管理。格式与 systemd 的 Environment 类似，可以多次指定。
默认值：无。
注意事项：无。

Options=

功能解析：设置特定于驱动的选项（所有驱动程序都接受 mtu、metric和no_default_route选项）
对应 Podman 命令：--opt <key=value>
使用场景：传递底层网络驱动（如 bridge）支持的特定参数。例如，使用 Options=isolate=true 来增强网络隔离性。
默认值：无。
注意事项：可用选项取决于所选的 Driver。

NetworkDeleteOnStop=

功能解析：当此选项设置为 true 时，Quadlet 会在生成的 systemd 服务单元中添加一个 ExecStopPost 指令。该指令确保在服务停止后，会自动执行 podman network rm 命令来清理对应的网络资源。
对应 Podman 命令：无（此为 systemd 机制，非 podman network create 参数）。
使用场景：适用于临时或测试网络，当关联的应用服务停止后，希望网络资源也随之自动清理，避免资源泄露。
默认值：false
注意事项：请谨慎在生产环境中使用此选项，因为它可能导致在服务重启期间数据丢失或连接中断，特别是当其他持久化服务也依赖此网络时。

⚠️

Options= 选项延申

Options= 选项是位于 podman network create [options] [name]

官方文档内容节选如下:

--opt, -o=option
Set driver specific options.

All drivers accept the mtu, metric, no_default_route and options.

mtu: Sets the Maximum Transmission Unit (MTU) and takes an integer value.

metric Sets the Route Metric for the default route created in every container joined to this network. Accepts a positive integer value. Can only be used with the Netavark network backend.

no_default_route: If set to 1, Podman will not automatically add a default route to subnets. Routes can still be added manually by creating a custom route using --route.

Additionally the bridge driver supports the following options:

vlan: This option assign VLAN tag and enables vlan_filtering. Defaults to none.

isolate: This option isolates networks by blocking traffic between those that have this option enabled.

com.docker.network.bridge.name: This option assigns the given name to the created Linux Bridge

com.docker.network.driver.mtu: Sets the Maximum Transmission Unit (MTU) and takes an integer value.

vrf: This option assigns a VRF to the bridge interface. It accepts the name of the VRF and defaults to none. Can only be used with the Netavark network backend.

mode: This option sets the specified bridge mode on the interface. Defaults to managed. Supported values:

managed: Podman creates and deletes the bridge and changes sysctls of it. It adds firewall rules to masquerade outgoing traffic, as well as setup port forwarding for incoming traffic using DNAT.

unmanaged: Podman uses an existing bridge. It must exist by the time you want to start a container which uses the network. There will be no NAT or port forwarding, even if such options were passed while creating the container.

The macvlan and ipvlan driver support the following options:

parent: The host device which is used for the macvlan interface. Defaults to the default route interface.

mode: This option sets the specified ip/macvlan mode on the interface.

Supported values for macvlan are bridge, private, vepa, passthru. Defaults to bridge.

Supported values for ipvlan are l2, l3, l3s. Defaults to l2.

Additionally the macvlan driver supports the bclim option:

bclim: Set the threshold for broadcast queueing. Must be a 32 bit integer. Setting this value to -1 disables broadcast queueing altogether.