这是本节的多页打印视图。 点击此处打印.

返回本页常规视图.

K8s 和网格代理

1 - 安装 Polaris Controller

k8s controller的作用

北极星提供K8s controller的机制，可以安装在k8s集群中，通过接收集群内k8s apiserver的事件回调，将K8s Service以及POD注册成北极星的服务以及实例。

安装说明

k8s controller包含以下组件：

  • polaris-controller：北极星controller服务端，主要是安装在k8s集群上，提供回调接口供k8s controller manager进行调用。

开始安装

部署包下载

到polaris-controller的下载页面，根据您这边的 kubernetes 版本号（版本号 <= 1.21.x，选择k8s1.21.zip；版本号 >= 1.22.x，选择k8s1.22.zip），下载最新版本polaris-controller安装包。

部署包安装

安装前，需确保 kubectl 命令已经加入环境变量Path中，并且可以访问 kubernetes 的 APIServer。

以polaris-controller-release_${version}.k8s1.21.zip为例：

解压并进入部署包：

unzip polaris-controller-release_${version}.k8s1.21.zip
cd polaris-controller-release_${version}.k8s1.21

查询用户token，由于controller需要直接访问polaris的控制台OpenAPI，因此需要填写token。

  • 打开北极星控制台，选择用户->用户列表->选择polaris用户->查看token，即可获取到token。

修改variables.txt文件，填写polaris的地址（只填IP或者域名，无需端口），如果在同一个集群中，则可以填写集群内域名，同时需要填写上一步所查询到的token

#polaris地址，只填IP或者域名，无需端口
POLARIS_HOST:polaris.polaris-system
#polaris的用户token
POLARIS_TOKEN:4azbewS+pdXvrMG1PtYV3SrcLxjmYd0IVNaX9oYziQygRnKzjcSbxl+Reg7zYQC1gRrGiLzmMY+w+aCxOYI=

执行安装部署。

./install.sh

安装后验证

安装成功后，可以在k8s集群中，polaris-system命名空间，看到polaris-controller的statefulset已经部署完成。

同时，打开北极星的控制台，可以看到k8s上面的service已经被自动同步到北极星上。

2 - K8s 服务同步

支持两种 K8s Service 同步模式：

  • all：全量同步服务。将 K8s Service 全部同步到北极星。
  • demand：按需同步服务。默认不会将 K8s Service 同步到北极星，需要在 Namespace 或者 Service 上添加北极星的 annotation。

北极星支持跨 K8s 集群的服务发现和治理，多个 K8s 集群的 Service 可以同步到一个北极星集群，同步规则如下：

  • K8s Namespace 和 Service 名称作为北极星的命名空间名称
  • 如果多个 K8s 集群存在相同的 Namespace 和 Service，全部 Pod 同步到一个北极星服务中
  • polaris-controller 在北极星服务实例上添加 clusterName 标签，用于区分来自不同 K8s 集群的服务实例
  • 如果存在多个 K8s Service 同步到一个北极星服务的情况，每个 K8s 集群的 polaris-controller 需要配置不同的 clusterName

注解

注解名称 注解描述
polarismesh.cn/sync 是否同步这个服务到 polarismesh。true 同步，false 不同步，默认不同步
polarismesh.cn/aliasService 把 k8s service 同步到 polarismesh 时，同时创建的服务别名的名字
polarismesh.cn/aliasNamespace 创建的别名所在的命名空间，配合 polarismesh.cn/aliasService 使用

使用指南

全量同步服务

以全量同步服务的模式启动 polaris-controller，将 K8s Service 全部同步到北极星，则 polaris-controller 的启动配置如下：

polaris-controller 启动配置文件：configmap.yaml

apiVersion: v1
kind: ConfigMap
data:
  mesh: |-
    ...
    serviceSync
      mode: "all"
    ...

按需同步服务

以按需同步服务的模式启动 polaris-controller，默认不会将 K8s Service 同步到北极星，则 polaris-controller 的启动配置如下：

polaris-controller 启动配置文件：configmap.yaml

apiVersion: v1
kind: ConfigMap
data:
  mesh: |-
    ...
    serviceSync
      mode: "demand"
    ...

如果需要将某个 Namespace 中的全部 Service 同步到北极星，请在 Namespace 上添加北极星的 annotation，配置方式如下：

apiVersion: v1
kind: Namespace
metadata:
  name: default
  annotations:
    polarismesh.cn/sync: "true"

如果需要将某个 Service 同步到北极星，请在 Service 上添加北极星的 annotation，配置方式如下：

apiVersion: v1
kind: Service
metadata:
  namespace: default
  name: test
  annotations:
    polarismesh.cn/sync: "true"

如果需要将某个 Namespace 中的 Service同步到北极星并且排除某个 Service，配置方式如下：

apiVersion: v1
kind: Namespace
metadata:
  name: default
  annotations:
    polarismesh.cn/sync: "true"

---
apiVersion: v1
kind: Service
metadata:
  namespace: default
  name: test
  annotations:
    polarismesh.cn/sync: "false"

创建服务别名

北极星支持服务别名的功能，允许为一个服务设置一个或者多个服务别名，使用服务别名进行服务发现的效果等同使用服务名称进行服务发现的效果。

polaris-controller 将 K8s Service 同步到北极星的名称映射规则如下：

  • K8s Namespace作为北极星的命名空间名称
  • K8s Service作为北极星的服务名称

如果需要在 Service 同步到北极星时，为其创建一个服务别名，配置方式如下：

apiVersion: v1
kind: Service
metadata:
  namespace: default
  name: test
  annotations:
    polarismesh.cn/aliasNamespace: aliasDefault
    polarismesh.cn/aliasService: aliasTest

3 - K8s 配置同步（Beta）

提示

该文章仅适用于北极星服务端版本 >= 1.18.0, polaris-controller 版本 >= 1.7.0

支持两种 K8s ConfigMap 同步模式：

  • all：全量同步配置。将 K8s ConfigMap 全部同步到北极星。
  • demand：按需同步配置。默认不会将 K8s ConfigMap 同步到北极星，需要在 Namespace 或者 ConfigMap 上添加北极星的 annotation。

注解

注解名称 注解描述
polarismesh.cn/sync 是否同步这个配置到 polarismesh。true 同步，false 不同步，默认不同步

使用指南

controller 配置解析

configSync:
  # 是否开启配置同步
  enable: true
  # 北极星服务端地址
  serverAddress: #POLARIS_HOST#
  # 北极星开启鉴权时需要配置
  accessToken: #POLARIS_TOKEN#
  # 是否开启删除操作，即允许删除 ConfigMap 或者北极星上的配置文件
  allowDelete: false
  # 配置同步方向: kubernetesToPolaris|polarisToKubernetes|both
  # kubernetesToPolaris: 只能将 ConfigMap 同步到北极星中
  # polarisToKubernetes: 只能将北极星配置文件中带有 internal-sync-to-kubernetes: true 标签的配置文件同步到 ConfigMap
  # both: 上述两种同时开启
  syncDirection: both
  defaultGroup: "#CLUSTER_NAME#"

全量同步服务

以全量同步配置的模式启动 polaris-controller，将 K8s ConfigMap 全部同步到北极星，则 polaris-controller 的启动配置如下：

polaris-controller 启动配置文件：configmap.yaml

apiVersion: v1
kind: ConfigMap
data:
  mesh: |-
    ...
    configSync
      mode: "all"
    ...

按需同步配置

以按需同步配置的模式启动 polaris-controller，默认不会将 K8s ConfigMap 同步到北极星，则 polaris-controller 的启动配置如下：

polaris-controller 启动配置文件：configmap.yaml

apiVersion: v1
kind: ConfigMap
data:
  mesh: |-
    ...
    configSync
      mode: "demand"
    ...

如果需要将某个 Namespace 中的全部 ConfigMap 同步到北极星，请在 Namespace 上添加北极星的 annotation，配置方式如下：

apiVersion: v1
kind: Namespace
metadata:
  name: default
  annotations:
    polarismesh.cn/sync: "true"

如果需要将某个 ConfigMap 同步到北极星，请在 ConfigMap 上添加北极星的 annotation，配置方式如下：

apiVersion: v1
kind: ConfigMap
metadata:
  namespace: default
  name: test
  annotations:
    polarismesh.cn/sync: "true"

如果需要将某个 Namespace 中的 ConfigMap 同步到北极星并且排除某个 ConfigMap，配置方式如下：

apiVersion: v1
kind: Namespace
metadata:
  name: default
  annotations:
    polarismesh.cn/sync: "true"

---
apiVersion: v1
kind: ConfigMap
metadata:
  namespace: default
  name: test
  annotations:
    polarismesh.cn/sync: "false"

4 - Envoy 网格接入

在 Polaris 的服务网格方案中，Polaris 是您的控制平面，Envoy Sidecar 代理是您的数据平面。

  • 服务数据同步：polaris-controller 安装在用户的Kubernetes集群中，可以同步集群上的 Namespace，Service，Endpoints 等资源到 polaris 中，同时 polaris-controller 提供了 Envoy Sidecar 注入器功能，可以轻松地将 Envoy Sidecar 注入到您的 Kubernetes Pod 中，Envoy Sidecar 会自动去 Polaris 同步服务信息。

  • 规则数据下发：polaris控制面通过XDS v3标准协议与 envoy 进行交互，支持官方开源的 envoy 直接接入，当前支持的 envoy 版本为 1.26.2

环境准备

部署polaris

如果已经部署好了polaris，可忽略这一步。

polaris支持在kubernetes环境中进行部署，注意必须保证暴露HTTP端口为8090，gRPC端口为8091。具体部署方案请参考：

部署 polaris-controller

快速接入

服务调用关系说明

启用 sidecar 自动注入功能

  • 创建命名空间 bookinfo ：kubectl create namespace bookinfo

  • 为 bookinfo 命名空间启用注入：

kubectl label namespace bookinfo polaris-injection=enabled

使用一下命令来验证 bookinfo 命名空间是否已经正确启用：

kubectl get namespace -L polaris-injection

此时应该返回：

NAME             STATUS   AGE    POLARIS-INJECTION
bookinfo          Active   3d2h   enabled

启用 Envoy 按需加载机制

在 POD 中添加以下 annonations sidecar.polarismesh.cn/openOnDemand: true 即可启用 Envoy 的按需加载

apiVersion: v1
kind: Pod
metadata:
  name: annotations-demo
  annotations:
    sidecar.polarismesh.cn/openOnDemand: "true"

部署样例

  • 下载样例部署文件：bookinfo

  • 执行部署：kubectl create -f bookinfo.yaml

  • 查看容器注入是否注入成功

启动自动注入后，polaris-controller 会将 Envoy Sidecar、Polaris Sidecar 容器注入到在此命名空间下创建的 pod 中。

可以看到运行起来的 pod 均包含三个容器，其中第一个容器是用户的业务容器，另外两个容器是由 Polaris Controller 注入器注入的 Envoy Sidecar 容器和 Polaris Sidecar 容器。您可以通过下面的命令来获取有关 pod 的更多信息：

kubectl describe pods -l app=productpage --namespace=bookinfo

此时应返回：

... ...
Init Containers:
# polaris-bootstrap-writer 产生 Envoy 的 Bootstrap 配置
polaris-bootstrap-writer:
... ... 
# istio-init 为 envoy sidecar 设置流量拦截
istio-init:
... ... 
Containers:
# demo 的业务容器
productpage:
... ...
# Envoy 是代理流量的容器
envoy:
... ...
  • 打开productpage界面

通过productpage暴露的地址，可以访问productpage的主界面，进入Normal User或者TestUser后，可以看到（红、黑、无）三种形态的星星，代表demo已经部署成功。

使用服务治理能力

流量调度

北极星网格支持根据http请求的头部字段进行路由，支持通过path, header, query这3种类型的属性来进行路由。

  1. 使用场景

demo 项目中，productpage 会访问 reviews 服务，reviews 服务共有三个实例，三个实例分别部署了三个版本（会显示红、黑、无三种颜色的星星），需要保证特定的灰度用户（用户名为jason），请求到特定版本的 reviews 服务。

  1. 配置路由规则

为 reviews 服务创建路由规则。将请求中 header 包含字段 end-user=jason 的请求，路由到 version=v2 的服务实例中。同时再创建一条路由规则，指定标签键值为任意请求，路由到 version=v1 的服务实例中。

路由规则的标签填写格式要求：

  • 对于Path：标签KEY需要填写 $path
  • 对于Header：标签KEY需要带上前缀 $header，如 $header.end-user
  • 对于Query：标签KEY需要带上前缀 $query，如 $query.end-user
  1. 验证路由是否生效

未登陆时，刷新 productpage 的页面，可以看到只返回没有颜色的星星（version=v1）。当使用 jason 登陆后，productpage 请求 reviews 时，会带上 header，end-user=jason，此时再刷新 productpage 页面，发现只会显示黑色的星星，即上面 version=v2 的实例。

访问限流

  1. 使用场景: demo项目中，为 detail 服务设置流量限制，对于jason用户的请求，设置访问的频率为5/m，其余请求不做限制。

  2. 设置限流规则: 指定请求中 header 包含字段 end-user=jason 的请求，设置限流规则为5/m，限流类型为分布式限流。

  3. 验证限流是否生效: 未登陆时，多次刷新界面，不会出现错误。以jason用户身份登陆，一分钟刷新超过5次，detail 界面出现限流的错误信息。

mTLS

北极星网络支持服务间的mTLS认证及加密通讯，提供三种不同的服务粒度模式供用户选择：

模式 解释
Permissive 宽容模式，服务接受纯文本/mTLS服务调用；发起服务调用时，根据对端接受状况自动选择发起mTLS或纯文本服务调用
Strict 严格模式，服务仅接受/发起mTLS服务调用
None 无加密模式（为默认选项），服务仅接受/发起纯文本服务调用

启用方式

只需要在服务的metadata中加入键为polarismesh.cn/tls-mode的label即可开启该功能，可选的值为strict,permissive,none，无此label时或者值错误时，默认为无加密的none模式。

使用示例

部署polaris-security

polaris-security是北极星的证书机构，负责签发证书以供服务使用，是开启双向TLS功能的必要组件。

  • 下载polaris-security
  • 将示例证书/密钥加载为k8s secret：./deploy/load-certs-into-k8s.sh
  • 验证secret加载成功：kubectl get secrets -n polaris-system
  • 使用Helm部署polaris-security, cd deploy/helm && helm install polaris-security .
  • 验证polaris-security部署成功：kubectl get po -n polaris-system | grep polaris-security

部署mTLS版bookinfo示例

  • 下载样例部署文件：mTLS版bookinfo
  • 执行部署：kubectl create -f bookinfo.yaml

mTLS版bookinfo在配置文件中使用polarismesh.cn/tls-mode的label为不同的服务启用了各自的双向TLS模式，部署完成后服务调用图如下所示：

效果验证

  1. Strict模式验证 由于Reviews V3服务使用了None模式，它将向Ratings服务发起纯文本请求，而Ratings服务使用了Strict模式，仅接受mTLS服务调用，因此Reviews V3到Ratings之间的服务调用总会失败。
    因此，使用浏览器访问部署好的ProductPage，无论怎么刷新都无法看到红色的星星评级。

  2. mTLS 验证 使用 Wireshark 抓包验证 mTLS 启用,如下图：

可以看到 Server 向 Client 提供证书后，要求 Client 提供自身证书，验证通过后方可开始加密数据通信。

相关链接

Polaris

Polaris Controller

Polaris Demo

5 - DNS 接入

技术原理

在 Polaris 的 DNS 服务发现接入方案中，Polaris 是您的控制平面，Polaris Sidecar 作为本地 DNS 服务器实现服务发现以及动态路由。

Kubernetes 场景

  • polaris-server: 北极星服务端，处理服务注册以及服务发现请求。
  • polaris-controller: 完成 polaris-sidecar 容器注入到业务 POD 中，并下发 iptables 指令拦截业务容器的 DNS 请求，将其转发到 polaris-sidecar 中
  • polaris-sidecar: 作为本地 DNS 服务器，将 DNS 域名解析为北极星中的服务，实现服务发现。

虚拟机场景

  • polaris-server: 北极星服务端，处理服务注册以及服务发现请求。
  • polaris-sidecar: 作为本地 DNS 服务器，将 DNS 域名解析为北极星中的服务，实现服务发现。

相关配置解读

polaris-sidecar 配置

bind: 0.0.0.0             # DNS 服务器监听IP
port: 53                  # DNS 服务器监听端口
namespace: default        # polaris-sidecar 所在的命名空间
recurse:                  # 递归解析，当 polaris-sidecar 自己无法解析域名时，会转发给上一级 DNS 服务器继续解析
  enable: false
  timeoutSec: 1
logger:                   # 日志配置
  output_paths:           # 标准输出打印
    - stdout
  error_output_paths:     # 错误日志通过标准错误输出打印
    - stderr
  rotate_output_path: logs/polaris-sidecar.log              # 日志持久化输出
  error_rotate_output_path: logs/polaris-sidecar-error.log  # 错误日志持久化输出
  rotation_max_size: 100            # 单个日志文件最大大小，单位 MB
  rotation_max_backups: 10          # 最多保存多少个日志文件
  rotation_max_age: 7               # 单个日志文件最大保存时间，单位天
  output_level: info                # 日志级别
resolvers:                          # DNS 解析插件
  - name: dnsagent                  # 普通的 DNS 解析
    dns_ttl: 10                     # dns 记录的 TTL
    enable: true                    # 插件是否启用
    suffix: "."                      # 决定哪些域名解析会先通过 polaris-sidecar，默认为全部域名，用户可以设置改配置来控制需要经过 polaris-sidecar 解析域名
    option: 
      route_labels: "key: value"    # 当前 polaris-sidecar 的静态标签信息，用于服务路由
  - name: meshproxy                 # 工作在 kubernetes 下的 mesh 模式
    dns_ttl: 120
    enable: false
    option:
      reload_interval_sec: 30       # 定时与北极星服务端进行同步服务列表
      dns_answer_ip: 10.4.4.4       # 返回给 envoy 的 IP 信息

polaris-go SDK 配置

global:
  serverConnector:
    addresses:
      - 127.0.0.1:8091      # 设置北极星服务端 gRPC 服务发现接入地址
  location:                 # 用于就近接入
    provider: env           # 默认从环境变量中读取地理位置信息

快速接入

基于 DNS 的北极星服务发现接入支持虚拟机以及 kubernetes 两种部署环境。您可以根据实际部署场景选择其中一种接入方式。

虚拟机接入

部署 polaris

如果已经部署好了 polaris，可忽略这一步。

安装 polaris-sidecar

  • 虚拟机安装过程需要使用 root 用户或者具有超级管理员权限的用户来执行，并且确保 53（udp/tcp）端口没有被占用。

  • 需要从 Releases 下载最新版本的安装包。

  • 上传安装包到虚拟机环境中，并进行解压，进入解压后的目录。

    unzip polaris-sidecar-release_$version.$os.$arch.zip

  • 修改 polaris.yaml，写入部署好的北极星服务端的地址，端口号使用8091（GRPC端口）。

    global:
  serverConnector:
    addresses:
      - {北极星服务端IP}:8091

  • 关闭系统自身的 dns resolve 进程

    # 关闭 systemd-resolved 进程
systemctl stop systemd-resolved

# 如果想恢复原本的 systemd-resolved，执行下面命令
# systemctl start systemd-resolved

  • 进入解压后的目录，执行 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 记录前面，如下：

    ; generated by /usr/sbin/dhclient-script
nameserver 127.0.0.1
nameserver x.x.x.x

验证

使用格式为<service>.<namespace>的域名进行访问，预期可以获得服务下某个实例的 IP 地址。

➜ dig polaris.checker.polaris

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

到这里，在虚拟机环境下通过 DNS 接入北极星的服务发现就完成了。

Kubernetes 接入

部署 polaris

如果已经部署好了 polaris，可忽略这一步。

部署 polaris-controller

开启 polaris-sidecar 注入

  • 为某个 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 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, 执行 curl 命令

    kubectl exec -it polaris-dns-consumer-xxx -n default -- /bin/bash

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

使用高级功能

在使用高级功能时，先创建一个测试服务，用于接下来的功能测试

  • 创建测试服务 test.echoserver

使用就近路由

可以通过设置环境变量，指定 polaris-sidecar 实例所处的地理位置信息，当 polaris-sidecar 执行 DNS 服务发现时，会根据自身的地域信息，对目标服务实例进行就近匹配。

假定一个场景：

  • 存在以下三个地域
    • region=region-1、zone=zone-1、campus=campus-1
    • region=region-2、zone=zone-2、campus=campus-2
    • region=region-3、zone=zone-3、campus=campus-3
  • polaris-sidecar 如果处于 region=region-1、zone=zone-1、campus=campus-1，则优先选择相同地域的实例

使用方式

  • 设置地域信息环境变量 
    export POLARIS_INSTANCE_REGION=${ REGION 信息 }
export POLARIS_INSTANCE_ZONE=${ ZONE 信息 }
export POLARIS_INSTANCE_CAMPUS=${ CAMPUS 信息 }
  • 重启 polaris-sidecar 
    bash tool/stop.sh
bash tool/start.sh

  • 调整 polaris-sidecar container 的 ENV 信息 
    containers:
- image: polarismesh/polaris-sidecar:${sidecar 的版本}
  name: polaris-sidecar
...
  env:
    - name: POLARIS_INSTANCE_REGION
      value: "{ REGION 信息 }"
    - name: POLARIS_INSTANCE_ZONE
      value: "{ ZONE 信息 }"
    - name: POLARIS_INSTANCE_CAMPUS
      value: "{ CAMPUS 信息 }"
...
  • 重建 POD 
    kubectl delete pod {POD 名称} --namespace {命名空间}

验证

执行 dig 命令验证

# 地域信息分别为 region=region-1、zone=zone-1、campus=campus-1
➜ dig test.echoserver.default     

...
;; ANSWER SECTION:
test.echoserver.default. 10     IN      A       1.1.1.1
...

# 地域信息分别为 region=region-2、zone=zone-2、campus=campus-2
➜ dig test.echoserver.default     

...
;; ANSWER SECTION:
test.echoserver.default. 10     IN      A       2.2.2.2
...

# 地域信息分别为 region=region-3、zone=zone-3、campus=campus-3
➜ dig test.echoserver.default

...
;; ANSWER SECTION:
test.echoserver.default. 10     IN      A       3.3.3.3
...

使用动态路由

假定一个场景：

  • 希望 env 为 dev 的请求，路由到 env 标签为 dev 的实例上
  • 希望 env 为 pre 的请求，路由到 env 标签为 pre 的实例上
  • 其他则路由到 env 标签为 prod 的实例上

使用方式

  • 调整 polaris-sidecar 配置文件 
    ...
resolvers:
  - name: dnsagent
    ...
    option: 
      route_labels: "env:dev"
  • 重启 polaris-sidecar 
    bash tool/stop.sh
bash tool/start.sh

  • 调整 polaris-sidecar container 的 ENV 信息 
    containers:
- image: polarismesh/polaris-sidecar:${sidecar 的版本}
  name: polaris-sidecar
...
  env:
    - name: SIDECAR_DNS_ROUTE_LABELS
      value: "env:dev"
...
  • 重建 POD 
    kubectl delete pod {POD 名称} --namespace {命名空间}

验证

执行 dig 命令验证

# 设置 route_labels: "env: dev"
➜ dig test.echoserver.default     

...
;; ANSWER SECTION:
test.echoserver.default. 10     IN      A       1.1.1.1
...

# 设置 route_labels: "env: pre"
➜ dig test.echoserver.default     

...
;; ANSWER SECTION:
test.echoserver.default. 10     IN      A       2.2.2.2
...

# 设置 route_labels: ""
➜ dig test.echoserver.default

...
;; ANSWER SECTION:
test.echoserver.default. 10     IN      A       3.3.3.3
...

6 - JavaAgent 接入

提示

该文章仅适用于北极星服务端版本 >= 1.18.0, polaris-controller 版本 >= 1.7.0

技术原理

在 Polaris 的 JavaAgent 接入方案中，Polaris 是您的控制平面，Polaris JavaAgent 将北极星的服务治理能力通过字节码增强的方式，让业务应用无需任何代码改造即可享受到北极星的服务治理体验。

Kubernetes 场景

  • polaris-server: 北极星服务端，处理服务注册以及服务发现请求。
  • polaris-controller: 完成 polaris-javaagent 容器的注入以及在业务 POD 中无侵入的开启 Java Agent 的能力。
  • polaris-javaagent-init: 负责将 polaris-javaagent 物料下载到业务 Container 中，同时初始化 Java Agent 所需要的配置信息。

注入Javaagent所依赖的注解信息

注解名称 注解描述
polarismesh.cn/javaagentVersion 需要注入的Javaagent版本号，对应是polaris-java-agent的release版本号
polarismesh.cn/javaagentFrameworkName 应用所使用的服务框架的名称，比如spring-cloud
polarismesh.cn/javaagentFrameworkVersion 应用所使用的服务框架的版本，一般写的是大版本，比如hoxton, 2020, 2021
polarismesh.cn/javaagentConfig 用户自定义的JavaAgent配置，不填写的配置则使用默认配置，格式为JSON

java-agent的configmap默认配置文件可以参考：javaagent-configmap.yaml

环境准备

部署polaris

如果已经部署好了polaris，可忽略这一步。

polaris支持在kubernetes环境中进行部署，注意必须保证暴露HTTP端口为8090，gRPC端口为8091。具体部署方案请参考：

部署 polaris-controller

快速接入

服务调用关系说明

启用 POD 注入功能

创建命名空间 javaagent

kubectl create namespace javaagent

为 javaagent 命名空间启用注入：

kubectl label namespace javaagent polaris-injection=enabled

使用一下命令来验证 javaagent 命名空间是否已经正确启用：

kubectl get namespace -L polaris-injection

此时应该返回：

NAME             STATUS   AGE    POLARIS-INJECTION
javaagent          Active   3d2h   enabled

启用 JavaAgent 自动注入

在 POD 中添加以下 annonations 即可

apiVersion: v1
kind: Pod
metadata:
  name: annotations-demo
  annotations:
    polarismesh.cn/javaagent: "true"
    polarismesh.cn/javaagentVersion: "{填写 polaris-java-agent 的版本}"
    polarismesh.cn/javaagentFrameworkName: "spring-cloud"
    polarismesh.cn/javaagentFrameworkVersion: "hoxton｜2020｜2021 选择对应的版本填入"

查看 JavaAgent 是否注入成功

使用一下命令来验证 javaagent 命名空间是否已经正确启用：

kubectl describe pod {目标业务POD名称} -n {javaagent}

查看服务是否注册到北极星

通过日志确定

在应用启动日志中，可以搜索"[Bootstrap] javaagent inject successfully"，出现该日志证明agent注入初始化成功。

然后在启动日志中，搜索"[BootStrap] plugin 插件ID has been loading"，代表插件已经加载完毕。

查看北极星控制台确认

验证限流功能

设置限流规则

调用接口触发限流

验证路由功能

设置路由规则

不携带特定参数

携带特定参数