hcsshim网络配置实战：HNS与HCN API从入门到精通

hcsshim网络配置实战：HNS与HCN API从入门到精通

【免费下载链接】hcsshimWindows - Host Compute Service Shim项目地址: https://gitcode.com/gh_mirrors/hc/hcsshim

在 Windows 容器与 Hyper-V 容器世界里，hcsshim 网络配置是每个开发者绕不开的核心课题。hcsshim（Host Compute Service Shim）是微软开源的一组 Go 库，它像一座桥梁，把上层容器运行时（如 containerd）与 Windows 底层的 HCS/HNS 服务连接起来。其中，HNS API（v1）与HCN API（v2）是配置容器网络的两代核心接口。本文将带你从零认识这两套 API，掌握网络、端点、负载均衡等对象的创建与排查技巧，最终能独立完成一套完整的 hcsshim 网络配置方案。

一图看懂 HNS 与 HCN 的关系

很多人第一次接触 hcsshim 时，都会被 HNS、HCN 两个缩写绕晕。其实它们的关系非常简单：

简单来说，HNS 是"底层服务"，HCN 是"新一代 API 封装"。hcsshim 项目内部同时维护了两套封装：早期的 internal/hns/ 目录对应 HNS v1，而根目录下的 hcn/ 包则是 HCN v2 的完整实现。它们最终都会调用同一个系统入口vmcompute.HNSCall（见 hcn/hcn.go），只是数据模型与功能丰富度不同。

必须搞懂的核心概念：网络、端点、命名空间

在动手配置 hcsshim 网络之前，先花两分钟搞懂四个基础对象，后续所有操作都围绕它们展开：

• 网络（Network）：一个隔离的 L2/L3 网络域，有 NAT、Transparent、L2Bridge、L2Tunnel、Overlay 等类型（定义见 hcn/hcnnetwork.go）。
• 端点（Endpoint）：容器接入网络的"网卡"，拥有 IP、MAC、DNS 等属性（见 hcn/hcnendpoint.go）。
• 命名空间（Namespace）：把多个端点聚合隔离的逻辑分组，常用于 Pod 沙箱场景（见 hcn/hcnnamespace.go）。
• 负载均衡（Load Balancer）：在多个端点之间分发流量的规则（见 hcn/hcnloadbalancer.go）。

在 Kubernetes + Windows 容器的典型场景里，一个 Pod 通常对应：一个网络 + 一个命名空间 + 若干端点 + 一个负载均衡，这套组合正是 containerd 通过 hcsshim 完成的。

HNS v1 API 快速上手：最简单的一步

如果你是新手，建议从 HNS v1 开始，它的 API 命名非常直白。以 internal/hns/hnsnetwork.go 为例：

• GetHNSNetworkByID(id)/GetHNSNetworkByName(name)：按 ID 或名称查询网络
• HNSNetworkRequest("POST", "", json)：创建网络
• HNSNetworkRequest("DELETE", id, "")：删除网络

端点操作同样简单，internal/hns/hnsendpoint.go 提供了HNSEndpointRequest系列方法，并且定义了完整的端点生命周期状态：Created → Attached → Detached → Destroyed。初学阶段用 v1 跑通"创建网络 → 创建端点 → 挂载到容器"这条链路，能帮你快速建立整体认知。

HCN v2 API 从入门到精通：新一代选择

当你需要更精细的控制（策略、命名空间、负载均衡）时，就该切换到 HCN v2 了。hcsshim 的 hcn/ 包提供了非常友好的 Go 接口，核心操作包括：

实战：创建 NAT 网络与端点

NAT 网络是 Windows 容器最常用的模式，容器通过宿主机的 NAT 网关访问外部网络。核心步骤只有三步：

1. 构造网络对象：设置类型为NAT，指定 IPAM 子网；
2. 调用创建接口：将对象序列化后交给 HCN 服务；
3. 创建端点并附加：在网络上创建端点，再绑定到容器。

整个过程对开发者隐藏了底层句柄管理。值得一提的是，hcsshim 在解析网络对象时会默认把类型初始化为 NAT（见 hcn/hcnnetwork.go 中的相关逻辑），因为 HNS 在返回 JSON 时可能省略 NAT 字段，这种细节体现了封装库的贴心之处。

进阶技巧：命名空间隔离

多容器场景下，用命名空间把端点分组非常实用：

• NewNamespace(nsType)创建命名空间对象
• AddNamespaceEndpoint(namespaceID, endpointID)把端点加入命名空间
• GetNamespaceEndpointIds/GetNamespaceContainerIds快速查询归属

这套 API 在 hcn/hcnnamespace.go 中均有现成实现，测试代码 hcn/hcnnamespace_test.go 还给出了完整的生命周期示例，值得精读。

高级玩法：负载均衡、SDN 路由与安全策略

hcsshim 网络配置的"精通"阶段，集中在三个高级能力上：

① 负载均衡：AddLoadBalancer支持指定前端 VIP、后端端点列表、端口映射协议等参数，还可配置 DSR（Direct Server Return）模式提升转发性能，实现代码见 hcn/hcnloadbalancer.go。

② SDN 路由：通过 hcn/hcnroute.go 的AddRoute，可以为端点集合添加自定义路由规则，支持封装（Encapsulation）选项，适合 Overlay 网络环境。

③ 安全策略：端点支持 ACL、NAT、L4 Proxy 等策略，可通过ModifyEndpointSettings动态增删（见 hcn/hcnendpoint.go）。策略操作遵循统一的"资源类型 + 请求类型"模型，非常规整。

版本兼容性：写出健壮的 hcsshim 网络代码

不同 Windows 版本的 HNS 服务能力差异很大。hcsshim 在 hcn/hcnglobals.go 中维护了一张详尽的"版本-特性"对照表，例如：

调用任何高级特性之前，建议先用 hcn/hcnsupport.go 的GetSupportedFeatures()做能力检测，再决定是否启用，避免在旧系统上报"platform does not support feature"错误。这是专业级 hcsshim 网络配置的必备素养。

常见问题与排查技巧

• 网络/端点找不到：用 hcn/hcnerrors.go 提供的IsNotFoundError/IsElementNotFoundError区分"不存在"与"其他错误"，避免误判。
• 旧系统调用新 API：先查SupportedFeatures，再决定代码分支。
• 调试利器：在代码中开启 logrus 的 Debug 级别，hcsshim 会打印每次hnsCall的请求与响应 JSON（见 hcn/hcnglobals.go），网络配置问题一目了然。

总结

从 HNS v1 到 HCN v2，hcsshim 为 Windows 容器网络配置提供了完整、优雅的 Go 接口。新手可以从 internal/hns/ 的简单 API 起步，进阶用户则应主攻 hcn/ 包的网络、端点、命名空间与负载均衡四大对象，再结合版本检测与错误处理写出健壮的代码。掌握这套体系，你就能从容驾驭 Windows 容器、Hyper-V 容器乃至 Kubernetes Windows 节点的网络运维工作。

如果想动手实践，可以通过git clone https://gitcode.com/gh_mirrors/hc/hcsshim获取完整源码，参考 hcn/ 下丰富的_test.go测试文件，边读边练，很快就能上手。

【免费下载链接】hcsshimWindows - Host Compute Service Shim项目地址: https://gitcode.com/gh_mirrors/hc/hcsshim