Docker-Py 网络管理 API 详解

概述

在 Docker 生态系统中，网络管理是一个核心功能。docker-py 作为 Docker 官方 Python SDK，提供了完整的网络管理 API，使开发者能够以编程方式管理 Docker 网络。本文将深入解析 docker-py 中的 NetworkApiMixin 类，帮助开发者掌握 Docker 网络管理的各种操作。

网络列表查询

networks() 方法提供了查询 Docker 网络中所有网络的能力，类似于 docker network ls 命令。

def networks(self, names=None, ids=None, filters=None):

参数说明

• names: 按网络名称过滤，接受字符串列表
• ids: 按网络 ID 过滤，接受字符串列表
• filters: 高级过滤条件字典，支持以下过滤项：
  • driver: 按驱动类型过滤
  • label: 按标签过滤，支持键值对或键列表
  • type: 按网络类型过滤（"custom" 或 "builtin"）

使用示例

# 查询所有网络
all_networks = client.networks()

# 查询特定名称的网络
named_networks = client.networks(names=['my-network'])

# 使用复杂过滤条件
filtered = client.networks(filters={
    'driver': 'bridge',
    'label': 'environment=production'
})

创建网络

create_network() 方法允许创建新的 Docker 网络，功能等同于 docker network create 命令。

def create_network(self, name, driver=None, options=None, ipam=None,
                   check_duplicate=None, internal=False, labels=None,
                   enable_ipv6=False, attachable=None, scope=None,
                   ingress=None):

核心参数解析

1. 基础配置

   • name: 网络名称（必填）
   • driver: 网络驱动类型（如 bridge、overlay 等）
   • options: 驱动特定选项的键值对

2. IP 地址管理(IPAM)

   • ipam: 自定义 IP 地址管理配置
   • 可配置子网、网关、IP 范围等

3. 高级特性

   • internal: 是否创建内部网络（限制外部访问）
   • enable_ipv6: 启用 IPv6 支持
   • attachable: 允许工作节点上的非服务容器连接
   • ingress: 创建 swarm 模式下的路由网格网络

创建示例

基础网络创建:

client.create_network("backend", driver="bridge")

带 IPAM 的高级网络:

from docker.types import IPAMPool, IPAMConfig

ipam_pool = IPAMPool(
    subnet='192.168.100.0/24',
    gateway='192.168.100.1',
    iprange='192.168.100.128/25'
)
ipam_config = IPAMConfig(pool_configs=[ipam_pool])

client.create_network(
    name="secure-net",
    driver="bridge",
    ipam=ipam_config,
    internal=True,
    labels={"environment": "production"}
)

网络维护操作

删除网络

remove_network() 方法用于删除指定网络：

def remove_network(self, net_id):

示例：

client.remove_network("network_id_or_name")

清理未使用网络

prune_networks() 方法可清理所有未使用的网络：

def prune_networks(self, filters=None):

示例：

# 清理所有未使用网络
result = client.prune_networks()
print(f"释放空间: {result['SpaceReclaimed']}字节")

# 带过滤条件的清理
client.prune_networks(filters={"until": "24h"})

网络详情查询

inspect_network() 提供网络的详细信息：

def inspect_network(self, net_id, verbose=None, scope=None):

示例：

details = client.inspect_network("my-network")
print(details['IPAM']['Config'][0]['Subnet'])

容器网络连接管理

连接容器到网络

def connect_container_to_network(self, container, net_id,
                                 ipv4_address=None, ipv6_address=None,
                                 aliases=None, links=None,
                                 link_local_ips=None, driver_opt=None,
                                 mac_address=None):

关键参数:

• aliases: 网络内访问容器的别名
• ipv4_address/ipv6_address: 指定静态 IP
• mac_address: 指定 MAC 地址

示例：

client.connect_container_to_network(
    container="webapp",
    net_id="backend",
    aliases=["web", "appserver"],
    ipv4_address="172.20.0.5"
)

断开容器连接

def disconnect_container_from_network(self, container, net_id,
                                      force=False):

强制断开连接示例：

client.disconnect_container_from_network(
    container="webapp",
    net_id="backend",
    force=True
)

版本兼容性说明

docker-py 网络 API 实现了版本兼容性检查，主要特性与 Docker API 版本的对应关系：

• 网络标签: API 1.23+
• IPv6 支持: API 1.23+
• 内部网络: API 1.22+
• 可附加网络: API 1.24+
• Ingress 网络: API 1.29+
• 网络作用域: API 1.30+

当使用不兼容的功能时，会抛出 InvalidVersion 异常。

最佳实践

1. 网络隔离：为不同服务创建独立网络，增强安全性
2. IPAM 规划：提前规划子网划分，避免 IP 冲突
3. 标签管理：使用标签标记网络用途和环境
4. 版本检查：在代码中添加版本兼容性检查
5. 资源清理：定期使用 prune 清理未使用网络

总结

docker-py 的网络 API 提供了完整的 Docker 网络管理能力，从基础网络创建到高级 IPAM 配置，再到容器网络连接管理，覆盖了所有常见使用场景。通过合理使用这些 API，开发者可以构建出灵活、安全的容器网络架构，满足各种复杂的部署需求。