Install Java agent for ACK and ACS - Cloud Monitor - Alibaba Cloud Documentation Center

Install the ack-onepilot component to monitor Java applications in Container Service for Kubernetes ACK or Container Compute Service ACS, and then view application topology, API calls, abnormal transactions, and slow transactions.

Note

The installation steps for ACK and ACS are identical. This guide uses ACK as the example.

ack-onepilot component

The ack-onepilot component automatically prepares Application Monitoring agent packages for different languages and configures the reporting environment within containers. For more information, see How the ack-onepilot component works.

When an application restarts, ack-onepilot automatically upgrades the agent to the latest version. To pin a specific agent version, see Control the agent version.

Step 1: Install the agent helper (ack-onepilot)

Log on to the ACK console. On the Clusters page, click the name of the cluster.
In the left-side navigation pane, click Add-ons. Then, find ack-onepilot.
Important
The ack-onepilot component must be version 5.1.0 or later.
Click Install on the ack-onepilot card.
Note
- By default, the ack-onepilot component supports 1,000 pods. For every additional 1,000 pods in the cluster, you must add 0.5 CPU cores and 512 MB memory for the component.
- If you install ack-onepilot in an ACS cluster, configure accessKey and accessKeySecret at the bottom of the installation card. Use the AccessKey ID and AccessKey secret of your Alibaba Cloud account. For information about how to obtain them, see Create an AccessKey. Make sure that the Alibaba Cloud account has the AliyunARMSFullAccess and AliyunSTSAssumeRoleAccess permissions.
On the page that appears, you can configure the parameters. We recommend that you use the default values. Click OK.
Note
After you install ack-onepilot, you can upgrade, configure, or uninstall it on the Add-ons page.

Step 2: Grant permissions to access ARMS resources

ACK managed cluster

If your ACK managed cluster lacks an ARMS addon token, follow these steps to grant the required permissions. If an ARMS addon token already exists, skip to Step 3.

Check whether ARMS Addon Token exists in a cluster.

Log on to the ACK console. On the Clusters page, click the name of the cluster to go to the cluster details page.
In the left-side navigation pane, choose Configurations > Secrets. In the upper part of the page, set Namespace to kube-system and check whether addon.arms.token exists.

Note

If a cluster has ARMS Addon Token, ARMS performs password-free authorization on the cluster. ARMS Addon Token may not exist in some ACK managed clusters. We recommend that you check whether an ACK managed cluster has ARMS Addon Token before you use ARMS to monitor applications in the cluster. If the cluster has no ARMS Addon Token, you must authorize the cluster to access ARMS.

Manually add permission policies

Log on to the ACK console. On the Clusters page, click the name of the cluster.
On the Basic Information tab of the Cluster Information page, click the link next to Worker RAM Role in the Cluster Resources section.
On the Permissions tab, click Grant Permission.
In the Grant Permission panel, add the following two access policies and click Confirm Grant Permission.
- AliyunTracingAnalysisFullAccess: full access to Managed Service for OpenTelemetry.
- AliyunARMSFullAccess: full access to ARMS.

Dedicated cluster/registered cluster

To monitor applications in an ACK dedicated cluster or an ACK One registered cluster, make sure the associated Alibaba Cloud account has the AliyunARMSFullAccess and AliyunSTSAssumeRoleAccess permissions. For more information, see Manage RAM user permissions.

After installing ack-onepilot, configure it with the AccessKey ID and AccessKey secret of an Alibaba Cloud account that has ARMS permissions.

Method 1: Enter AccessKey pair in Helm

Log on to the ACK console. In the left navigation pane, click Clusters.
On the Clusters page, click the name of the target cluster. In the left-side navigation pane, choose App > Helm. Find the ack-onepilot component and click Update.
Replace the placeholders for accessKey and accessKeySecret with your AccessKey pair, and then click OK.
Note
For information about how to obtain an AccessKey pair, see Create an AccessKey.
In the YAML editor, find accessKey: __ACCESSKEY__ and accessKeySecret: __ACCESSKEY_SECRET__ in the controller section and replace the placeholders with your actual AccessKey information.
Restart the application Deployment.

Method 2: Import AccessKey pair via Kubernetes secret

Log on to the Container Service for Kubernetes console, and in the left navigation bar, select Clusters.
On the Clusters page, click the name of the target cluster. In the left-side navigation pane, choose Configurations > Secrets.
Select the ack-onepilot namespace and create a secret containing your AccessKey pair.
Note
For information about how to obtain an AccessKey pair, see Create an AccessKey.
Set the Secret Name to ack-onepilot-aksk and the Type to Opaque. In the Data section, add two entries: set the keys to ak and sk, and enter the corresponding AccessKey ID and AccessKey secret as their values. Then, click OK.
In the left-side navigation pane, choose Workload > Deployment. Click the ack-onepilot component (usually named ack-onepilot-ack-onepilot in the ack-onepilot namespace).
On the ack-onepilot-ack-onepilot page, click Edit in the upper-right corner. In the Environment Variables section, add ONE_PILOT_ACCESSKEY and ONE_PILOT_ACCESSKEY_SECRET, and configure them to reference the values stored in the secret. Then, click OK.
Select the secret ack-onepilot-aksk. For the ONE_PILOT_ACCESSKEY variable, select the key ak. For the ONE_PILOT_ACCESSKEY_SECRET variable, select the key sk.

ASK/ECI cluster

To monitor applications in an ACK Serverless cluster (ASK) or a cluster that uses ECI, complete the authorization on the Cloud Resource Access Authorization page, and then restart all pods of the ack-onepilot component.

Step 3: Enable Application Monitoring for Java applications

The following YAML example shows how to create a Deployment with Application Monitoring enabled:

Expand to view the complete sample YAML file (Java)

apiVersion: v1
kind: Namespace
metadata:
  name: arms-demo
---
apiVersion: apps/v1 # for versions before 1.8.0 use apps/v1beta1
kind: Deployment
metadata:
  name: arms-springboot-demo
  namespace: arms-demo
  labels:
    app: arms-springboot-demo
spec:
  replicas: 2
  selector:
    matchLabels:
      app: arms-springboot-demo
  template:
    metadata:
      labels:
        app: arms-springboot-demo
        armsPilotAutoEnable: "on"
        armsPilotCreateAppName: "arms-k8s-demo"
        armsPilotAppWorkspace: "workspace"   # Replace with the name of your workspace.
        one-agent.jdk.version: "OpenJDK18"
    spec:
      containers:
        - resources:
            limits:
              cpu: 0.5
          image: registry.cn-hangzhou.aliyuncs.com/arms-docker-repo/arms-springboot-demo:v0.1
          imagePullPolicy: Always
          name: arms-springboot-demo
          env:
            - name: SELF_INVOKE_SWITCH
              value: "true"
            - name: COMPONENT_HOST
              value: "arms-demo-component"
            - name: COMPONENT_PORT
              value: "6666"
            - name: MYSQL_SERVICE_HOST
              value: "arms-demo-mysql"
            - name: MYSQL_SERVICE_PORT
              value: "3306"
---
apiVersion: apps/v1 # for versions before 1.8.0 use apps/v1beta1
kind: Deployment
metadata:
  name: arms-springboot-demo-subcomponent
  namespace: arms-demo
  labels:
    app: arms-springboot-demo-subcomponent
spec:
  replicas: 2
  selector:
    matchLabels:
      app: arms-springboot-demo-subcomponent
  template:
    metadata:
      labels:
        app: arms-springboot-demo-subcomponent
        armsPilotAutoEnable: "on"
        armsPilotCreateAppName: "arms-k8s-demo-subcomponent"
        armsPilotAppWorkspace: "workspace"   # Replace with the name of your workspace.
        one-agent.jdk.version: "OpenJDK18"
    spec:
      containers:
        - resources:
            limits:
              cpu: 0.5
          image: registry.cn-hangzhou.aliyuncs.com/arms-docker-repo/arms-springboot-demo:v0.1
          imagePullPolicy: Always
          name: arms-springboot-demo-subcomponent
          env:
            - name: SELF_INVOKE_SWITCH
              value: "false"
            - name: MYSQL_SERVICE_HOST
              value: "arms-demo-mysql"
            - name: MYSQL_SERVICE_PORT
              value: "3306"
---
apiVersion: v1
kind: Service
metadata:
  labels:
    name: arms-demo-component
  name: arms-demo-component
  namespace: arms-demo
spec:
  ports:
    - name: arms-demo-component-svc
      port: 6666
      targetPort: 8888
  selector:
    app: arms-springboot-demo-subcomponent
---
apiVersion: apps/v1 # for versions before 1.8.0 use apps/v1beta1
kind: Deployment
metadata:
  name: arms-demo-mysql
  namespace: arms-demo
  labels:
    app: mysql
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mysql
  template:
    metadata:
      labels:
        app: mysql
    spec:
      containers:
        - resources:
            limits:
              cpu: 0.5
          image: registry.cn-hangzhou.aliyuncs.com/arms-docker-repo/arms-demo-mysql:v0.1
          name: mysql
          ports:
            - containerPort: 3306
              name: mysql
---
apiVersion: v1
kind: Service
metadata:
  labels:
    name: mysql
  name: arms-demo-mysql
  namespace: arms-demo
spec:
  ports:
    - name: arms-mysql-svc
      port: 3306
      targetPort: 3306
  selector:
    app: mysql
---

Log on to the ACK console. In the left navigation pane, click Clusters.
On the Clusters page, click the name of your cluster. In the left navigation pane, click Workloads > Deployments.
On the Stateless page, click > YAML Edit next to the target application. To create an application, click Create from YAML.

In the YAML file, add the following labels to the spec.template.metadata section.

labels:
  armsPilotAutoEnable: "on"
  armsPilotCreateAppName: "deployment-name"    # Replace deployment-name with the name of your application.
  armsPilotAppWorkspace: "workspace"  # Replace with the name of your workspace.
  aliyun.com/app-language: java

apiVersion: v1
kind: Namespace
metadata:
  name: arms-demo
---
apiVersion: apps/v1 # for versions before 1.8.0 use apps/v1beta1
kind: Deployment
metadata:
  name: arms-springboot-demo
  namespace: arms-demo
  labels:
    app: arms-springboot-demo
spec:
  replicas: 2
  selector:
    matchLabels:
      app: arms-springboot-demo
  template:
    metadata:
      labels:
        app: arms-springboot-demo
        armsPilotAutoEnable: "on"
        armsPilotCreateAppName: "arms-k8s-demo"
        armsPilotAppWorkspace: "workspace"
    spec:
      containers:
        - resources:
            limits:
              cpu: 0.5
          image: registry.cn-hangzhou.aliyuncs.com/arms-docker-repo/arms-springboot-demo:v0.1

Click Update.

View monitoring details

Log on to the Cloud Monitor 2.0 console, and select a workspace. In the left navigation pane, choose Application Center > Application Observability > Application Insights.
On the Application List page, find your application and click its Application Name to view detailed monitoring data.