Kubernetes Python 客户端 V1IPBlock 模型全解：NetworkPolicy 的 CIDR 白名单/黑名单字段、序列化与实战用法

后端云原生容器编排【免费下载链接】pythonOfficial Python client library for kubernetes项目地址https://gitcode.com/gh_mirrors/python1/python点击查看免费下载V1IPBlock 是官方 Kubernetes Python 客户端含 asyncio 变体中用于表达NetworkPolicy 规则里 IP 地址段CIDR放行与排除的核心数据模型cidr声明允许访问的网段except声明在cidr范围内仍需排除的网段。本文以 doc/source/kubernetes.aio.client.models.v1_ip_block.rst 对应的异步aio模型为主线逐字段拆解其属性约束、Pydantic 校验行为、JSON/字典双向序列化接口并结合V1NetworkPolicyPeer给出构造 NetworkPolicy 的完整可运行示例。读完本文你将掌握V1IPBlock的全部公开 API、输入别名规则与序列化细节能够准确地在 asyncio 程序中创建和解析基于 IP 网段的网络策略。一、模型定位NetworkPolicy 中的 IP 网段描述在 Kubernetes 中NetworkPolicy 通过podSelector圈定策略作用的 Pod 集合再通过 ingress/egress 规则控制进出流量。V1IPBlock正是这些规则中描述放行哪一个 IP 网段的类型。其官方文档语义见 V1IPBlock.md为IPBlock describes a particular CIDR (Ex. 192.168.1.0/24,2001:db8::/64) that is allowed to the pods matched by a NetworkPolicySpecs podSelector. The except entry describes CIDRs that should not be included within this rule.即cidr是允许访问或允许被访问的地址块except列出该地址块内需要排除的子网。两个字段均为 CIDR 字符串同时支持 IPv4如192.168.1.0/24与 IPv6如2001:db8::/64。在 OpenAPI 规格文件 scripts/swagger.json 的v1.IPBlock定义中第 15018–15037 行可以确认该模型的结构v1.IPBlock: { description: IPBlock describes a particular CIDR ... , properties: { cidr: { description: ..., type: string }, except: { description: ... Except values will be rejected if they are outside the cidr range, items: { type: string }, type: array, x-kubernetes-list-type: atomic } }, required: [cidr], type: object }要点cidr是必填字段except是字符串数组切片可选且标注了x-kubernetes-list-type: atomic表示该列表在服务端按整体原子替换处理若except中的 CIDR 超出了cidr的地址范围请求会被拒绝。二、字段详解与属性约束V1IPBlock只包含两个属性完整参数表如下字段名、类型与说明均以 v1_ip_block.py 为准属性名Python线协议字段JSON类型必填说明cidrcidrStrictStrstr是表示 IPBlock 的 CIDR 字符串合法示例192.168.1.0/24、2001:db8::/64var_exceptexceptOptional[List[StrictStr]]否不应包含在 IPBlock 内的 CIDR 切片合法示例同上超出cidr范围的取值会被拒绝默认None源码中的字段声明如下v1_ip_block.pycidr: StrictStr Field( descriptioncidr is a string representing the IPBlock Valid examples are 192.168.1.0/24 or 2001:db8::/64 ) var_except: Optional[List[StrictStr]] Field( defaultNone, validation_aliasAliasChoices(except, _except), serialization_aliasexcept, descriptionexcept is a slice of CIDRs that should not be included within an IPBlock ... Except values will be rejected if they are outside the cidr range, alias_except, )三个值得注意的细节字段名避开 Python 关键字except是 Python 保留字无法作为属性名因此内部字段被命名为var_except。但通过validation_aliasAliasChoices(except, _except)与serialization_aliasexcept对外 JSON 始终使用except键。cidr使用StrictStrPydantic 严格字符串校验传入非字符串类型不会被宽松转换从而保证序列化给 API Server 的 CIDR 始终是字符串。模型级校验配置v1_ip_block.pymodel_config ConfigDict( validate_by_nameTrue, # 允许按 Python 字段名传参 validate_by_aliasTrue, # 也允许按别名except/_except传参 validate_assignmentTrue, # 赋值时同样触发校验 extraforbid, # 禁止未知字段 protected_namespaces(), )extraforbid意味着传入任何既非cidr、也非except/var_except的键都会直接报错有助于在编写策略代码时尽早发现拼写错误。三、输入别名预处理except与_except的兼容逻辑由于历史原因该模型同时接受except与_except两个线协议键。__preprocess_input_names类方法v1_ip_block.py在模型校验前完成归一化if except in obj and _except in obj: raise ValueError(%s received both %r and %r % (cls.__name__, except, _except)) if except not in obj and _except in obj: obj[except] obj[_except] obj.pop(_except, None)规则总结同时给出except与_except会抛出ValueError只给_except时自动映射为except最终以except作为唯一输入键进入模型校验。这意味着从from_dict反序列化时两种键写法都能被接受但应避免二者同时出现。该处理同时服务于从 JSON 反序列化与从 Python dict 构造两条路径。四、序列化与反序列化 API 全览V1IPBlock继承pydantic.BaseModel并额外实现了 OpenAPI Generator 生成模型标准的一组方法v1_ip_block.py方法作用to_str()返回pprint.pformat(self.to_dict())的可读字符串表示__repr__亦复用之to_json()返回按别名cidr、except序列化的 JSON 字符串from_json(json_str)从 JSON 字符串创建V1IPBlock实例to_dict(serializeFalse)返回字典serializeFalse时键为cidr/_except公开名serializeTrue时键为cidr/except线协议名from_dict(obj)从字典创建实例内部先走__preprocess_input_names归一化再调用model_validate__eq__/__ne__基于to_dict()的结果比较两个模型是否相等其中to_dict的两种输出模式对应生成器的legacy / modern兼容设计默认返回 Python 公开名_except需要交给 API 客户端时可用serializeTrue得到线协议名except。from_json是from_dict(json.loads(json_str))的便捷封装。一个完整的构造与往返示例可直接复制运行from kubernetes.aio.client.models.v1_ip_block import V1IPBlock # 方式一按字段名直接构造except 是关键字需用 var_except block V1IPBlock( cidr192.168.1.0/24, var_except[192.168.1.10/32, 192.168.1.11/32], ) # 方式二按线协议键通过 dict 构造 block2 V1IPBlock.from_dict({ cidr: 2001:db8::/64, except: [2001:db8::1/128], # 或 _except: [...] }) print(block) # to_str() - pprint 输出 print(block.to_json()) # {cidr: 192.168.1.0/24, except: [...]} d block.to_dict(serializeTrue) # {cidr: ..., except: [...]} restored V1IPBlock.from_dict(d) assert block restored # 同时传入 except 与 _except 会抛 ValueError # V1IPBlock.from_dict({cidr: 10.0.0.0/8, except: [], _except: []})五、在 NetworkPolicy 中的实际使用V1IPBlock本身并不单独出现在策略 YAML 顶层而是作为peer对端的一个可选项被引用。查看 v1_network_policy_peer.py 可见class V1NetworkPolicyPeer(BaseModel): ip_block: Optional[V1IPBlock] Field( defaultNone, validation_aliasAliasChoices(ipBlock, ip_block), serialization_aliasipBlock, ) namespace_selector: Optional[V1LabelSelector] ... pod_selector: Optional[V1LabelSelector] ...OpenAPI 对v1.NetworkPolicyPeer的约束scripts/swagger.json明确指出If this field [ipBlock] is set then neither of the other fields can be.也就是说V1NetworkPolicyPeer中ipBlock、namespaceSelector、podSelector三选一ipBlock一旦设置其余两个选择器字段必须为空。V1NetworkPolicyPeer随后被V1NetworkPolicyIngressRulefrom列表与V1NetworkPolicyEgressRuleto列表引用形成完整的 ingress/egress 规则。下面是一个在 asyncio 客户端中构造允许从192.168.1.0/24访问但排除其中两个管理地址的 NetworkPolicy 示例import asyncio from kubernetes import config from kubernetes.aio import client as aio_client from kubernetes.aio.client.models import ( V1IPBlock, V1NetworkPolicy, V1NetworkPolicyPeer, V1NetworkPolicyIngressRule, V1NetworkPolicySpec, ) async def create_ip_policy(): await config.load_kube_config() # 或用 load_incluster_config() async with aio_client.ApiClient() as api_client: api aio_client.NetworkingV1Api(api_client) peer V1NetworkPolicyPeer( ip_blockV1IPBlock( cidr192.168.1.0/24, var_except[192.168.1.10/32, 192.168.1.11/32], ) ) policy V1NetworkPolicy( api_versionnetworking.k8s.io/v1, kindNetworkPolicy, metadata{name: allow-app-cidr, namespace: default}, specV1NetworkPolicySpec( pod_selector{matchLabels: {app: my-app}}, ingress[V1NetworkPolicyIngressRule(from_[peer])], policy_types[Ingress], ), ) await api.create_namespaced_network_policy( namespacedefault, bodypolicy ) # 读取回查确认服务端接受的 IPBlock got await api.read_namespaced_network_policy( nameallow-app-cidr, namespacedefault ) print(got.spec.ingress[0].from_[0].ip_block.to_dict(serializeTrue)) asyncio.run(create_ip_policy())等价于以下 Kubernetes YAML 语义apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: allow-app-cidr namespace: default spec: podSelector: matchLabels: app: my-app policyTypes: [Ingress] ingress: - from: - ipBlock: cidr: 192.168.1.0/24 except: - 192.168.1.10/32 - 192.168.1.11/32六、同步与异步客户端的模型一致性仓库同时维护两个版本的V1IPBlock异步asynciokubernetes/aio/client/models/v1_ip_block.py同步kubernetes/client/models/v1_ip_block.py两者内容完全一致均基于 OpenAPI release-1.37 规格生成字段、别名、校验逻辑与方法签名完全相同。差异仅体现在上层 API 客户端的使用方式同步客户端直接调用kubernetes.client.NetworkingV1Api而 asyncio 客户端使用kubernetes.aio.client.NetworkingV1Api并配合async with与await。因此本文所有关于V1IPBlock的字段与序列化结论对两种模式同样适用选择哪个包取决于你的应用是否基于事件循环。七、常见陷阱与最佳实践except必须落在cidr范围内这是 Kubernetes API Server 的硬性校验。例如cidr: 10.0.0.0/8搭配except: [172.16.0.0/16]会被拒绝应在本地编码时就校验可借助ipaddress模块import ipaddress cidr ipaddress.ip_network(192.168.1.0/24) for exc in [192.168.1.10/32]: assert ipaddress.ip_network(exc).subnet_of(cidr), f{exc} 超出 {cidr}同时支持 IPv4 与 IPv6cidr与except类型均为普通字符串客户端不做 CIDR 语法校验校验由 API Server 完成但示例写法应遵循标准 CIDR 格式如2001:db8::/64。不要同时传except与_except__preprocess_input_names会直接抛ValueError。推荐统一使用except键或 Python 侧构造时用var_except。extraforbid会拒绝未知字段构造时传入cidr、except以外的键如笔误的cidrs会立即报错属于客户端提供的第一道防线。优先使用from_dict处理来自 API 的响应读取 NetworkPolicy 后拿到的响应 dict 可通过V1IPBlock.from_dict(...)/from_json(...)还原为类型化对象便于后续比较基于to_dict()逐字段比较。八、相关资源文档入口doc/source/kubernetes.aio.client.models.v1_ip_block.rst异步模型实现kubernetes/aio/client/models/v1_ip_block.py同步模型实现kubernetes/client/models/v1_ip_block.py模型速查文档kubernetes/aio/docs/V1IPBlock.md引用方V1NetworkPolicyPeerkubernetes/client/models/v1_network_policy_peer.pyOpenAPI 原始定义v1.IPBlockscripts/swagger.json赞分享后端云原生容器编排【免费下载链接】pythonOfficial Python client library for kubernetes项目地址https://gitcode.com/gh_mirrors/python1/python点击查看免费下载相关推荐Kubernetes Python 客户端 V1CustomResourceDefinitionNames 模型详解CRD 命名配置的字段、别名与实战用法Kubernetes Python 客户端 V1CustomResourceDefinitionNames 模型详解CRD 命名配置的字段、别名与实战用法 导后端云原生容器编排Kubernetes Python 客户端aioV1StorageOSVolumeSource 模型详解StorageOS 卷的字段、别名映射与序列化机制Kubernetes Python 客户端aioV1StorageOSVolumeSource 模型详解StorageOS 卷的字段、别名映射与序列化机制后端云原生容器编排python-kubernetes aio 客户端中 V1StatefulSet 模型详解字段、序列化与异步用法python kubernetes aio 客户端中 V1StatefulSet 模型详解字段、序列化与异步用法 V1StatefulSet 是 kubern后端云原生容器编排上一篇革命性API安全审计APIKit智能扫描引擎深度解析下一篇跨平台资源下载终极指南res-downloader让你的数字收藏变得简单高效创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考