文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>注册配置治理>Polaris（北极星）>服务管理（注册中心）>关联 Kubernetes 集群

关联 Kubernetes 集群

最近更新时间：2025-10-31 16:02:52

我的收藏

本页目录：

操作场景

北极星提供将 K8s 集群关联到 Polaris 的能力，关联容器集群后将安装 Polaris Controller 组件，Polaris Controller 可以同步您 Kubernetes 集群上的 Namespace，Service，Endpoints 等资源到 Polaris 中，从而实现 Kubernetes Service 自动注册到 Polaris，使用 Polaris API 和多语言 SDK 可以访问，使用 gRPC 和 Spring Cloud 等开源框架也可以访问。也可以通过 DNS Agent 进行服务发现及通过 Java Agent 实现无侵入接入。
主要适用于以下场景：
异构系统与多技术栈场景下，Spring Cloud 等框架服务调用 K8s 集群服务。
跨集群场景下的服务调用。
本文介绍通过 TSF 控制台使用 K8s 集群的能力。

操作步骤

创建引擎

1. 登录 TSF 控制台，在左侧菜单栏中选择 Polaris（北极星）。
2. 在引擎实例列表页面，单击目标引擎的“ID”，进入基本信息页面。
3. 在顶部页签单击 K8s 集群，单击关联集群。
说明：
1. 添加容器集群会安装 Polaris-Controller 组件，请确保您的集群至少有 1C2G 的空闲资源，否则会添加失败。
2. 容器集群中安装 Polaris-Controller 组件后默认支持 K8s Service 服务同步（按需同步）、DNS Agent 指定域名解析的能力 和 Java Agent 自动注入能力。您也可以在控制台选择全量同步选择 k8s 全量同步方式。
集群选择：可以根据自身业务需求选择目标关联的 K8s 集群，支持 TKE (容器集群) / EKS (弹性容器集群)。
具备能力：K8s Service 同步、DNS Agent 解析、Java Agent 接入。


原理说明

K8s Service 同步

通过关联K8s 集群实现服务自动同步，将K8s服务自动同步至北极星，支持按需同步/全量同步，可以通过 Polaris API/多语言 SDK/DNS Agent/开源框架（gRPC/Spring Cloud 等）访问服务。

polaris-controller

在 TSF 控制台关联 tke/eks 集群后，会自动在您对应的 tke/eks 集群中部署 polaris-controller 。具体请参见 资源清单。
polaris-controller 默认会同步 K8s 集群所有的 namespace，service 和 endpoints 。具体请参见 polaris-controller 同步行为。
您可以在 K8s 的 service 指定注解，操作 polaris-controller 同步的行为。具体指引和示例请参见 polaris-controller 支持的注解。

1. 
资源清单

在您的 tke/eks 集群创建的 K8s 资源清单如下：
资源类型
资源名
资源用途
namespace
polaris-system
polaris-controller 和其相关配置都在这个命名空间下
deployment
polaris-controller
提供同步服务的工作负载
configmap
injector-mesh, polaris-sidecar-injector
polaris-controller 使用的配置文件
serviceAccount
polaris-controller
提供访问 K8s 资源需要的权限
clusterRole
polaris-controller
提供访问 K8s 资源需要的权限
clusterRoleBinding
polaris-controller
提供访问 K8s 资源需要的权限
mutatingWebhookConfiguration
polaris-sidecar-injector
提供自动注入能力
可以使用下面图片中的命令查看到上述的资源。



2. 
polaris-controller 同步行为

polaris-controller 默认会同步 K8s 集群所有的 namespace，service 和 endpoints 。
资源类型
资源行为
namespace
创建 namespace 时，会在 polarismesh 创建一个同名的命名空间。
删除 namespace 时，不会移除 polarismesh 的同名命名空间。
service
创建 service 时，不论创建的 service 的类型，都会在 polarismesh 对应的命名空间下创建一个同名的服务。
删除 service 时，不会移除 polarismesh 对应命名空间下的服务，会移除 polarismesh 中对应服务的实例（只移除本 K8s 集群同步到 polarismesh 对应服务下的实例）。
endpoints
某个 service 的 endpoints 创建时，会把 endpoints 列表中 IP 和 port 每个组合，作为 polarismesh 对应服务下的一个服务实例，同步到 polarismesh 。如果 IP 在 endpoints 的就绪地址列表中，则 polarismesh 服务实例状态为健康，如在未就绪地址列表中，则 polarismesh 状态为不健康。
某个 service 的 endpoints 地址列表变化时，会动态的同步到 polarismesh 。地址列表增加，则在 polarismesh 服务下注册新实例；地址列表减少，则反注册 polarismesh 服务下对应的实例。
某个 service 的 endpoints 被移除时，本 K8s 集群同步到 polarismesh 对应服务下的实例都会从 polarismesh 的服务中移除。
3. 
polaris-controller 支持的注解

您可以在 k8s 的 service 指定注解，操作 polaris-controller 同步的行为，当前支持以下注解。
注解名称
注解说明
polarismesh.cn/sync
是否同步这个服务到 polarismesh。true 同步，false 不同步，默认不同步。
polarismesh.cn/aliasService
把 k8s service 同步到 polarismesh 时，同时创建的服务别名的名字。
polarismesh.cn/aliasNamespace
创建的别名所在的命名空间，配合 polarismesh.cn/aliasService 使用。
4. 如何按需同步
polaris-controller 默认会同步 K8s 集群所有的 service。某些场景下，您可能只想同步部分 service 到 polarismesh，这时可以将同步方式选择为（按需同步），同时使用 polarismesh.cn/sync 注解来指定需要同步的服务。
按需同步单个服务：下面的 service 创建时，polaris-controller 会将该服务同步到 polarismesh。
  apiVersion: v1
  kind: Service
  metadata:
    name: details
    annotations:
      polarismesh.cn/sync: true
  ... ...
按需同步命名空间下所有的服务：为命名空间打上标签，polaris-controller 会将该命名空间下所创建的所有服务同步到 polarismesh。
  apiVersion: v1
  kind: Namespace
  metadata:
    name: default
    annotations:
      polarismesh.cn/sync: "true"... ...
5. 创建别名示例
polaris-controller 默认会以 service 名字，创建一个对应的 polarismesh 服务。可能有以下情况，需要创建服务别名：
您不想用 service 名作为 polarismesh 服务的名字。例如您希望 polarismesh 的服务名是大写，但是 K8s 的 service 名限制只能小写。这时可以使用别名注解指定一个大写的 polarismesh 服务名。
您希望将某个 namespace 下的某个 service 暴露到另外命名空间中。这时可以使用别名注解指定另一个命名空间。
下面示例的 service 创建时，polaris-controller 会在 polarismesh 的 development 命名空间下创建一个名为 productpage 的服务。同时也会在 Development 命名空间下创建一个名为 Productpage 的服务别名。
apiVersion: v1
kind: Service
metadata:
  namespace: development
  name: productpage
  annotations:
    polarismesh.cn/aliasService: Productpage
    polarismesh.cn/aliasNamespace: Development
... ...
6. 如何确认 polaris-controller 版本
单击集群 ID，跳转到容器控制台页面，查看 polaris-system 命名空间下 polaris-controller 这个 StatefulSet 的镜像版本。


DNS Agent 接入

在 Polaris 的 DNS Agent服务发现接入方案中，Polaris 是您的控制平面，Polaris Sidecar 作为本地 DNS 服务器实现服务发现。
容器场景：
polaris-server：北极星服务端，处理服务注册以及服务发现请求。
polaris-controller：完成 polaris-sidecar 容器注入到业务 Pod 中，并下发 iptables 指令拦截业务容器的 DNS 请求，将其转发到 polaris-sidecar 中
polaris-sidecar：作为本地 DNS 服务器，将 DNS 域名解析为北极星中的服务，实现服务发现。
虚拟机场景：
polaris-server：北极星服务端，处理服务注册以及服务发现请求。
polaris-sidecar：作为本地 DNS 服务器，将 DNS 域名解析为北极星中的服务，实现服务发现。

说明：如果使用 DNS 进行服务发现，则必须保证命名空间和服务名在北极星上都是以全小写字母进行注册，否则会寻址失败。
1. 配置解读
虚拟机：
polaris-sidecar.yaml 内容和配置介绍如下：
bind: 0.0.0.0             # DNS 服务器监听IP
port: 53                  # DNS 服务器监听端口
namespace: default        # polaris-sidecar 所在的命名空间
polaris:
  addresses:
    - ${POLARIS_ADDRESS}  # Polaris Server访问地址, 示例：127.0.0.1:8091
recurse: # 递归解析，当 polaris-sidecar 自己无法解析域名时，会转发给上一级 DNS 服务器继续解析
  enable: true
  timeoutSec: 1
resolvers: # DNS 解析插件
  - name: dnsagent                  # DNS 代理插件
    enable: true                    # 插件是否启用
    dns_ttl: 10                     # dns 记录的客户端 TTL
    suffix: "."                     # 决定哪些域名解析会被 polaris-sidecar 解析，默认为全部域名，示例：".abc"
容器：
DNS Agent 在 k8s 环境下，在主调方的部署 YAML 中支持如下配置，说明和示例如下
递归配置：开启递归解析，请求下一个 nameserver 的超时时间为 5 秒；
DNS 代理解析配置：解析的后缀为.dns-test，客户端 DNS 解析记录TTL 为 3 秒；
spec:
  template:
    metadata:
    labels:
      env:dev
      annotations:
        polarismesh.cn/sidecarConfig: |
          {
            "recurse": {
              "enabled": true,
              "timeout": 5
            },
            "dns": {
              "suffix": ".dns-test",
              "ttl": 3
          }
......


2. 快速接入
虚拟机接入
1）安装polaris-sidecar
确保 53（UDP/TCP）端口没有被占用。
需要从 Releases 下载最新版本的安装包。
上传安装包到虚拟机环境中，并进行解压，进入解压后的目录。
unzip polaris-sidecar-release_$version.$os.$arch.zip
2）修改 polaris-sidecar 配置
修改 polaris.yaml，写入部署好的北极星服务端的地址，端口号使用8091（gRPC端口）。
进入解压后的目录，执行 tool/start.sh 进行启动，然后执行 tool/p.sh 查看进程是否启动成功。

# bash tool/start.sh
# bash tool/p.sh
root     15318     1  0 Jan22 ?        00:07:50 ./polaris-sidecar start
使用 root 权限修改 /etc/resolv.conf，在文件中添加 nameserver 127.0.0.1，并且添加到所有的 nameserver 记录前面，如下：
nameserver 127.0.0.1
nameserver x.x.x.x
3）验证
使用格式为<service>.<namespace>的域名进行访问，预期可以获得服务下某个实例的 IP 地址。

➜ dig polaris.checker.polaris

...
;; ANSWER SECTION:
polaris.checker.polaris. 10 IN AAAA ::ffff:127.0.0.1
...

容器接入
1）关联 k8s 集群
2）开启 polaris-sidecar 注入
说明：
sidecar 需要 polaris controller 版本在V2.1.0.0以上，可以解绑并重新绑定集群来升级 polaris controller 版本，解绑到重新绑定的过程中，不要进行服务注册和反注册。
方式一： 通过 label 命令为某个 Kubernetes 命名空间启用 polaris-sidecar 注入：
# 为某个 kubernetes 命名空间开启 polaris sidecar 的注入
kubectl label namespace ${kubernetes namespace} polaris-injection=enabled
# 设置注入的 polaris sidecar 以 dns 模式运行
kubectl label namespace ${kubernetes namespace} polaris-sidecar-mode=dns 

方式二：通过 kubectl apply -f ns.yaml 创建命名空间
# k8s命名空间部署yaml-命名空间下pod默认注入sidecar
apiVersion: v1
kind: Namespace
metadata:
  name: dns-test
  labels:
    # 往pod中注入polaris sidecar
    polaris-injection: enabled
    # sidecar类型为dns
    polaris-sidecar-mode: dns

3. 验证
下载样例部署文件
服务提供者
验证容器
执行部署：
  kubectl create -f deployment.yaml
查看容器注入是否成功，启动自动注入后，polaris-controller 会将 Polaris Sidecar 容器注入到在此命名空间下创建的 pod 中。可以看到运行起来的 pod 均包含两个容器，其中第一个容器是用户的业务容器，第二个容器是由 Polaris Controller 注入器注入的 Polaris Sidecar 容器。您可以通过下面的命令来获取有关 pod 的更多信息：
  kubectl describe pods -l k8s-app=polaris-dns-provider --namespace=default
进入验证 pod, 被调服务的地址格式为<service>.<namespace>:<port>，如下示例表示对 default 命名空间下的 echoserver 服务的 /echo 接口发起请求
kubectl exec -it polaris-dns-consumer-xxx -n default -- /bin/bash

curl http://echoserver.default:10000/echo


Java Agent 同步

安装 polaris controller 后，支持通过 Java Agent 实现无侵入接入。您可以通过添加注解的方式，在 Spring Cloud 应用里注入 Java Agent。 Java Agent 自动引入 SpringCloud Tencent 依赖，接入北极星注册配置治理中心。请参考 Java Agent 接入概述。


中国站
目录