Kubernetes integration

Practice guide for Service sync modes, annotations, aliases, and Sidecar injection with pole-controller.

Kubernetes integration maps cluster Services and annotations into control-plane resources. SDKs and Pole Sidecar then consume the same governance semantics.

Deploy the controller

make build

# static manifests
cd deploy/kubernetes_v1.22/kubernetes && bash install.sh

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

Configure control-plane address and token (deploy/variables.txt), then verify pods in polaris-system. The controller must reach Control Plane HTTP/gRPC ports.

Sync modes

Mode	Behavior	Best for
`all`	Sync Services broadly	Small clusters, fast catalog unification
`demand`	Opt-in via annotations	Shared production clusters

Prefer demand in shared production clusters to avoid system noise in the governance catalog.

Annotations

Annotation	Purpose
`polarismesh.cn/sync`	`true` / `false`
`polarismesh.cn/aliasService`	Alias service name
`polarismesh.cn/aliasNamespace`	Alias namespace

Example:

metadata:
  annotations:
    polarismesh.cn/sync: "true"
    polarismesh.cn/aliasService: "orders-api"
    polarismesh.cn/aliasNamespace: "prod"

Document alias conventions so names do not collide with real services during incident response.

Control-plane Namespace means environment, not “every Kubernetes Namespace is a tenant”. Common pattern: map cluster namespaces to business names, then land them in dev/prod environments. Keep pole-system out of business catalogs.

Sidecar injection

Mode	Notes
`dns`	DNS interception; lower intrusion
`mesh`	Traffic hijack; deeper governance

Before inject: active releases exist, image/arch match the cluster, readiness probes do not fight lossless rules.

Actual controller configuration

Key fields from community manifests (pole-controller/deploy/kubernetes_v1.22/kubernetes/configmap.yaml):

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

Service annotations are listed above. Fill deploy/variables.txt (POLARIS_HOST, POLARIS_TOKEN, …) before install.

Community demo

Entry	What it does
Static manifests	`pole-controller/deploy/kubernetes_v1.22/kubernetes` + `install.sh`
Helm	`pole-controller/deploy/kubernetes_v1.22/helm` (run `deploy/init_helm.sh` first)
Component guide	Kubernetes Controller

The Console “Kubernetes” page is not the sync implementation. Sync lives in the pole-controller repo.

How to verify

cd pole-controller
# fill deploy/variables.txt, then
cd deploy/kubernetes_v1.22/kubernetes && bash install.sh

kubectl get pods -n polaris-system
# demand mode: opt in a Service
kubectl annotate svc orders -n payments polarismesh.cn/sync=true --overwrite

Then check Controller sync logs, Console Discovery for the service/alias/instances, and SDK/Sidecar Discover INSTANCE.

Expected effects

Action	Effect
`mode=demand` + `sync=true`	Only that Service enters the control-plane catalog
`mode=all`	Broad Service sync (watch for noise)
Alias annotations	Console shows alias namespace/name
`sidecarInject` enabled	Matching Pods get dns/mesh data-plane injection
Remove sync / delete Service	Catalog converges per controller sync policy

Checklist

Controller can reach Control Plane
Sync mode matches cluster scale
Annotation/alias conventions are documented
Console shows synced services
SDK or Sidecar can discover them
Injection (if enabled) preserves readiness and releases