Lattice.Hub

用 Kubernetes Controller 做 Service 同步、注解驱动接入与 Sidecar 注入的完整实践。

Kubernetes 接入的目标不是复制一套服务治理模型，而是把集群中的 Service、annotation 和运行时上下文同步成控制面可理解的资源，再由 SDK 或 Pole Sidecar 消费同一套治理语义。

部署 Controller

仓库：pole-controller。常用路径：

make build

# 静态清单
cd deploy/kubernetes_v1.22/kubernetes && bash install.sh

# 或 Helm
cd deploy && sh init_helm.sh
cd kubernetes_v1.22/helm && helm upgrade -i pole-controller .

部署前在 deploy/variables.txt 等配置中填好控制面地址与凭证，例如 POLARIS_HOST、POLARIS_TOKEN、镜像版本。验证：

kubectl get pods -n polaris-system

Controller 需要能访问 Control Plane 的 HTTP / gRPC 端口；网络不通时同步会停滞。

同步模式选择

模式	行为	适用
`all`	将集群 Service 尽量全量同步到控制面	小集群、希望快速统一目录
`demand`	默认不同步，靠 annotation 显式开启	渐进接入、多团队共享集群

实践建议：生产共享集群优先 demand，避免把系统噪声服务灌进治理目录。

Annotation 实践

注解	作用
`polarismesh.cn/sync`	`true` 同步，`false` 不同步
`polarismesh.cn/aliasService`	同步时创建的服务别名
`polarismesh.cn/aliasNamespace`	别名所在 Namespace

示例（按需同步某个 Service）：

apiVersion: v1
kind: Service
metadata:
  name: orders
  namespace: payments
  annotations:
    polarismesh.cn/sync: "true"
    polarismesh.cn/aliasService: "orders-api"
    polarismesh.cn/aliasNamespace: "prod"
spec:
  # ...

别名适合兼容历史命名或跨环境访问习惯，但要避免别名与真实服务名互相覆盖造成排障困难。

Namespace 映射原则

控制面 Namespace 表示运行环境，不要把每个 Kubernetes Namespace 机械等于一个租户。
常见做法：K8s Namespace 映射到业务名，再通过 annotation/配置落到 dev/prod 等控制面环境。
pole-system 等系统命名空间默认不要当业务目录使用。

Sidecar 注入

Controller 支持给应用 Pod 注入数据面：

模式	说明
`dns`	通过拦截 DNS 实现发现与治理，侵入较低
`mesh`	注入 sidecar（及 Envoy 路径）劫持流量，治理更深

注入前确认：

控制面已有对应服务与所需治理规则的 active release。
注入模板与镜像版本匹配集群架构。
应用就绪探针与无损上下线规则不冲突。

实际配置（Controller）

社区清单里的关键字段（pole-controller/deploy/kubernetes_v1.22/kubernetes/configmap.yaml）：

serviceSync:
  enable: true
  mode: "demand"           # 或 all
  serverAddress: "<control-plane-host>"
  accessToken: "<token>"
configSync:
  enable: true
  syncDirection: both      # kubernetesToPolaris | polarisToKubernetes | both
sidecarInject:
  mode: "dns"              # 或 mesh

按需同步的 Service 注解见上文示例。部署变量写在 deploy/variables.txt（如 POLARIS_HOST、POLARIS_TOKEN）。

社区 Demo

入口	说明
静态清单	`pole-controller/deploy/kubernetes_v1.22/kubernetes` + `install.sh`
Helm	`pole-controller/deploy/kubernetes_v1.22/helm`（先 `deploy/init_helm.sh`）
组件说明	Kubernetes Controller

Console 配置中心里的 “Kubernetes” 页不是同步实现入口；同步能力在 pole-controller 仓库。

怎么触发验证

cd pole-controller
# 填好 deploy/variables.txt 后
cd deploy/kubernetes_v1.22/kubernetes && bash install.sh

kubectl get pods -n polaris-system
# demand 模式：给目标 Service 打 polarismesh.cn/sync=true
kubectl annotate svc orders -n payments polarismesh.cn/sync=true --overwrite

然后：

看 Controller 日志 syncnaming / 同步成功事件。
Console → 注册发现：服务 / 别名 / 实例是否出现。
SDK 或 Sidecar：Discover INSTANCE 能拉到这些实例。

效果是什么

操作	预期效果
`mode=demand` + 打 `sync=true`	仅该 Service 进入控制面目录
`mode=all`	集群 Service 尽量全量出现（注意噪声）
配置别名注解	Console 出现 `aliasService` / `aliasNamespace` 指向
启用 `sidecarInject`	符合模板的 Pod 注入 dns/mesh 数据面
去掉 sync / 删 Service	控制面目录随同步策略收敛（以 Controller 版本行为为准）

观察与排障

看 Controller 日志中的同步成功/失败事件。
在 Console 核对服务是否出现、实例是否更新。
区分“未打 sync 注解”“鉴权失败”“控制面不可达”“别名冲突”。
全量同步场景关注事件处理耗时与噪声服务过滤。

检查清单

Controller 能稳定连接 Control Plane
同步模式与集群规模匹配
注解与别名约定已文档化
Console 中能看到同步后的服务视图
SDK 或 Sidecar 能发现这些服务
注入（如启用）不影响应用就绪与发布

K8s 相关实践