tencent cloud

Service Registry and Governance

DocumentationService Registry and GovernancePolaris Java Application DevelopmentUse Java AgentUse Java Agent to Access

Use Java Agent to Access

PDF
Focus Mode
Font Size
Last updated: 2026-05-07 18:12:22

Feature Overview

Spring Cloud Tencent's Java Agent supports injection for applications deployed in containers and on virtual machines. For Spring Cloud applications (native Spring Cloud applications or other Spring Cloud extended applications), you can use Spring Cloud Tencent's features without making any changes to the application code or dependencies. The following sections describe the usage methods for container scenarios and virtual machine scenarios respectively.

Prerequisite

The Polaris (North Star) engine instance has been created.
Log in to the Tencent Service Framework (TSF) console.
On the Instance List page under Service Governance Center, click the ID of the target engine to go to the Basic Information page.

Usage Steps

1. Log in to the Tencent Service Framework (TSF) console.
2. After Polaris (North Star) is selected in the left sidebar, go to the Polaris engine instance list page.
3. Click the target engine's ID to go to the Basic Information page.
Container Environment
Virtual Machine Scenarios

Step 1: Install polaris-controller

Note:
1. Adding a TKE cluster will install the Polaris-Controller component. Ensure that your cluster has at least 1C2G of idle resources; otherwise, the cluster will fail to be added.
2. After the Polaris-Controller component is installed in a TKE cluster, it supports K8s Service synchronization (on-demand) and Java Agent auto-injection capability by default. You can also select full synchronization in the console to use the k8s full synchronization mode.
1. On the Basic Information page of the target engine, click the K8s Cluster tab at the top, click Associate Cluster, then click to view the introduction about Associating K8s Clusters with Polaris.
2. Select the target K8s cluster to be associated based on your business requirements. Supported cluster types include TKE (TKE cluster) / EKS (Elastic Kubernetes Service cluster). This means completing the installation of polaris-controller in the target cluster.
3. K8s Service synchronization:
Full Synchronization: All services in the cluster are automatically synchronized to Polaris.

On-demand synchronization: Only specified namespaces or services are automatically synchronized to Polaris.


Step 2: Enable the Auto-injection Feature in the Namespace

In the K8s namespace where the target application resides, enable auto-injection with the following command:
kubectl label namespace <namespace name> polaris-injection=enabled
Use the following command to check whether auto-injection is enabled for the namespace:
kubectl get namespace -L polaris-injection

Output results:
NAME             STATUS   AGE    POLARIS-INJECTION
default          Active   3d2h   enabled
Injection scope control list
label Key
Scope
label Value
Meaning
polaris-controller Version
polarismesh.cn/inject
Pod
disabled
Declares that when default injection is enabled for the namespace, it serves as a blocklist feature to specify that the pod does not inject javaagent.
v1.7.3 and later versions
polarismesh.cn/inject
Pod
enabled
Declares that when default injection is not enabled for the namespace, it serves as an allowlist feature to individually specify that the pod injects javaagent.
v1.7.3 and later versions
polarismesh.cn/inject
Namespace
enabled
Declares that pods under the namespace are injected with javaagent by default.
v1.7.3 and later versions
polaris-injection
Namespace
enabled
Declares that pods under the namespace are injected with javaagent by default.
Supported by all versions, to be deprecated, use polarismesh.cn/inject instead.
yaml example
apiVersion: v1
kind: Namespace
metadata:
  name: java-agent-test
  labels:
    polarismesh.cn/inject: enabled
Blocklist feature, do not inject java agent.
apiVersion: apps/v1
kind: Deployment
metadata:
  name: label-block
  namespace: java-agent-test
spec:
  selector:
    matchLabels:
      app: label-block
  template:
    metadata:
      labels:
        app: label-block
        polarismesh.cn/inject: disabled
      annotations:
        polarismesh.cn/javaagent: "true"
    spec:
    ......
Allowlist feature: when automatic injection is not enabled in the namespace, it allows on-demand injection for specified pods.
apiVersion: apps/v1
kind: Deployment
metadata:
  name: label-allow
spec:
  selector:
    matchLabels:
      app: label-allow
  template:
    metadata:
      labels:
        app: label-allow
        polarismesh.cn/inject: enabled
      annotations:
        polarismesh.cn/javaagent: "true"
    spec:
    ......

Step 3: Declare Java Agent Tag in Spring Cloud Application yaml File

Locate the application that requires Java Agent injection (typically a deployment or statefulset), edit the yaml file, and add the following Tag:
Annotation Key
Annotation Value
Meaning
polaris-controller Version
polarismesh.cn/javaagent
Supported values: "true", "false". Required.
Declares that Java Agent needs to be injected into this POD.
Supported by all versions
polarismesh.cn/workloadNamespaceAsServiceNamespace
Supported values: "true", "false". Optional.
Declares that the Kubernetes namespace is used as the service namespace for registration to Polaris. If it conflicts with the configuration in polarismesh.cn/javaagentConfig, this configuration does not take effect.
v1.7.3 and later versions
polarismesh.cn/workloadNameAsServiceName
Supported values: "true", "false". Optional.
Declares that the Kubernetes workload name is used as the service name for registration to Polaris. If it conflicts with the configuration in polarismesh.cn/javaagentConfig, this configuration does not take effect.
v1.7.3 and later versions
polarismesh.cn/javaagentFrameworkName
If not specified, the application framework type is automatically identified.
Supported value: spring-cloud.
Declares the application framework type. For SpringCloud applications, fill in spring-cloud. Currently, only the SpringCloud type is supported.
Supported by all versions
polarismesh.cn/javaagentFrameworkVersion
If not specified, the application framework version is automatically identified.
Also supports manual declaration of the framework version, for example: 2023, 2022, hoxton, etc.
Declares the application framework version.
Supported by all versions
polarismesh.cn/javaagentVersion
For example: 2.0.1.0.
Note:
For production environments, specify a validated version. If no version is specified, the latest version is automatically injected each time an instance restarts. This may introduce compatibility issues with the new version, potentially causing the instance to fail to start properly.
Declares the image version of the Java Agent package.
Supported by all versions
polarismesh.cn/javaagentConfig
For specifying the namespace, service name, and configuring lossless deployment:
'{"spring.cloud.polaris.lossless.enabled":"true","spring.cloud.polaris.lossless.delay-register-interval":"30000","spring.cloud.polaris.discovery.namespace":"custom-ns","spring.application.name":"custom-service"}'
Supports user-defined Java Agent configurations, including specifying the namespace, service name, service instance metadata, lossless deployment configurations, and more. The format is JSON.
Configurations not specified use the default configurations.
Supported by all versions
yaml configuration example:
Default configuration: the value of ${spring.application.name} is used as the service name, and default is used as the Polaris namespace.
apiVersion: apps/v1
kind: Deployment
metadata:
  name: default-ns-name
  namespace: java-agent-test
spec:
  selector:
    matchLabels:
      app: default-ns-name
  template:
    metadata:
      labels:
        app: default-ns-name
      annotations:
        polarismesh.cn/javaagent: "true"
    spec:
        ......

Using the k8s workload name as the service name and the k8s namespace as the Polaris service namespace for registration.
apiVersion: apps/v1
kind: Deployment
metadata:
  name: k8s-info-inject
  namespace: java-agent-test
spec:
  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:
        ......

Use custom configurations. The example below uses the configuration in config, with custom-service as the service name and custom-ns as the Polaris service namespace for registration.
apiVersion: apps/v1
kind: Deployment
metadata:
  name: custom-ns-name
  namespace: java-agent-test
spec:
  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:
        ......

After the yaml is modified, the application needs to be redeployed. After redeployment, the java-agent injection will be completed automatically. You can observe the application logs; if the following keywords appear during startup, it proves that the java-agent injection was successful.
......
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

Step 1: Download java agent

Obtain the latest version of polaris-java-agent and download the binary zip package. click to download.

Step 2: Modify the configuration file

1. Unzip the downloaded zip package, go to the polaris-java-agent directory, and modify the conf/polaris-agent.conf file to fill in the required plugin names (which need to be filled in according to the application's spring-cloud version). An example of the content is as follows:
plugins.enable=spring-cloud-2023-plugin
2. Go to the conf/plugin/spring-cloud-2023 directory (different plugins have different directories; select the directory based on the plugin specified in the previous step) and modify the application.properties file:
2.1 Fill in the correct application name (spring.application.name).
2.2 Enter the address information of the Polaris server you purchased. For details on viewing the server address, see: Engine Management > Client Access.
# Application name (required)
spring.application.name=testSvcName
# Configuration of Polaris Server Address
spring.cloud.polaris.address=grpc\\://9.134.5.52\\:8091

Step 3: Add Application's Startup Parameters

Add -javaagent:<java-agent installation directory>/polaris-agent-core-bootstrap.jar to the application's startup parameters, then restart the application to complete the java-agent injection.
Note:
If you use IDEA for local debugging, you need to add the -javaagent parameter under VM Options.

Previous Topic: Java Agent OverviewNext Topic: Java Agent supports zero-downtime launch/shutdown

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback