注册配置治理 使用 Java Agent 接入Spring Cloud应用

一、前提条件

·已创建 Polaris（北极星）引擎实例。

·登录 TSF 控制台。

·在服务治理中心下的实例列表页面，单击目标引擎的 ID，进入基本信息页面。

二、使用步骤

1. 登录 TSF 控制台。

2. 在左侧导航栏选择Polaris（北极星）后，进入北极星引擎实例列表页。

3. 单击目标引擎的 ID，进入基本信息页面。

容器场景虚拟机场景

三、步骤1：安装 polaris-controller

注意：说明：

注意：1. 添加容器集群会安装 Polaris-Controller 组件，请确保你的集群至少有 1C2G 的空闲资源，否则会添加失败。

注意：2. 容器集群中安装 Polaris-Controller 组件后默认支持 K8s Service 服务同步（按需同步）和 Java Agent 自动注入能力。你也可以在控制台选择全量同步使用 k8s 全量同步方式。

1. 在目标引擎基本信息页顶部页签单击 K8s 集群，单击关联集群，单击查看关于 K8s 集群关联到 Polaris 的相关介绍。

2. 根据自身业务需求选择目标关联的 K8s 集群，支持 TKE (容器集群) / EKS (弹性容器集群)。即在目标集群中完成 polaris-controller 的安装。

3. K8s Service 同步接入：

·全量同步：集群内全部 service 自动同步至北极星。

·按需同步：仅指定的 namespace 或者 service 自动同步至北极星。

四、步骤2：在命名空间开启自动注入功能

·在目标应用所在的 K8s 命名空间，通过以下命令开启自动注入：

kubectl label namespace <命名空间名> polaris-injection=enabled

·通过以下命令查询命名空间是否开启了自动注入：

kubectl get namespace -L polaris-injection输出结果：NAME STATUS AGE POLARIS-INJECTIONdefault Active 3d2h enabled

·注入范围控制列表

·具体yaml示例

apiVersion: v1kind: Namespacemetadata: name: java-agent-test labels: polarismesh.cn/inject: enabled

·黑名单功能，不注入java agent。

apiVersion: apps/v1kind: Deploymentmetadata: name: label-block namespace: java-agent-testspec: selector: matchLabels: app: label-block template: metadata: labels: app: label-block polarismesh.cn/inject: disabled annotations: polarismesh.cn/javaagent: "true" spec: ……

·白名单功能，命名空间未开启自动注入的情况下，实现指定 pod 按需注入。

apiVersion: apps/v1kind: Deploymentmetadata: name: label-allowspec: selector: matchLabels: app: label-allow template: metadata: labels: app: label-allow polarismesh.cn/inject: enabled annotations: polarismesh.cn/javaagent: "true" spec: ……

五、步骤3：SpringCloud 应用 yaml 文件中声明 Java Agent 标签

·找到需要注入 Java Agent 的应用（一般是 deployment 或者 statefulset），编辑 yaml 并增加以下标签：

·配置 yaml 样例：

默认配置：${spring.application.name}的值作为服务名，default作为北极星命名空间。

apiVersion: apps/v1kind: Deploymentmetadata: name: default-ns-name namespace: java-agent-testspec: selector: matchLabels: app: default-ns-name template: metadata: labels: app: default-ns-name annotations: polarismesh.cn/javaagent: "true" spec: ……

·使用 k8s 工作负载名称作为服务名，k8s 命名空间作为北极星服务命名空间注册。

apiVersion: apps/v1kind: Deploymentmetadata: name: k8s-info-inject namespace: java-agent-testspec: selector: matchLabels: app: k8s-info-inject template: metadata: labels: app: k8s-info-inject annotations: polarismesh.cn/javaagent: "true" polarismesh.cn/workloadNamespaceAsServiceNamespace: "true" polarismesh.cn/workloadNameAsServiceName: "true" spec: ……

·使用自定义配置，下面的例子为使用 config 里面的配置，使用 custom-service 作为服务名，custom-ns 作为北极星服务命名空间注册。

apiVersion: apps/v1kind: Deploymentmetadata: name: custom-ns-name namespace: java-agent-testspec: selector: matchLabels: app: custom-ns-name template: metadata: labels: app: custom-ns-name annotations: polarismesh.cn/javaagent: "true" polarismesh.cn/javaagentConfig: '{"spring.cloud.polaris.discovery.namespace": "custom-ns","spring.application.name":"custom-service"}' spec: ……

修改 yaml 后，需要重新部署应用。重新部署后，会自动完成 java-agent 的注入，可以观察应用日志，如果启动的时候出现以下关键字，则证明 java-agent 注入成功。

……2024-02-01 21:19:16 [INFO ](PolarisAgentBootStrap) [Bootstrap] start bootStrapStarter:default……2024-02-01 21:19:16 [INFO ](PluginCreator) [BootStrap] plugin spring-cloud-hoxton-plugin has been loading

六、步骤1：下载 java agent

获取最新的 polaris-java-agent 的版本，并下载二进制 zip 包。点击下载。

七、步骤2：修改配置文件

1. 解压下载后到的 zip 包，进入 polaris-java-agent 的目录，并修改 conf/polaris-agent.conf 文件，填写需要使用的插件名称（需要按照应用的 spring-cloud 版本进行填写），内容示例如下：

plugins.enable=spring-cloud-2023-plugin

2. 进入 conf/plugin/spring-cloud-2023（不同插件有不同目录，需要按照上一步填写的插件来选择目录）目录中，修改 application.properties 文件：

2.1 填写正确的应用名（spring.application.name）。

2.2 填写你购买的北极星服务端的地址信息。服务端地址查看详细参见：引擎管理 > 客户端访问地址。

# 应用名称(必填)spring.application.name=testSvcName# 配置北极星服务端地址spring.cloud.polaris.address=grpc\\://9.134.5.52\\:8091

八、步骤3：添加应用的启动参数

在应用的启动参数中，添加 -javaagent:<java-agent安装目录>/polaris-agent-core-bootstrap.jar，然后重启应用，即可完成 java-agent 的注入。

注意：说明：

注意：如果使用 IDEA 进行本地调试，则需要在 VM Option 下添加 -javaagent 的参数。