All Products
Search

This Product

    Application Real-Time Monitoring Service:Install Java agent through ack-onepilot component in Container Service for Kubernetes and Container Compute Service

    Document Center

    Application Real-Time Monitoring Service:Install Java agent through ack-onepilot component in Container Service for Kubernetes and Container Compute Service

    Last Updated:May 14, 2025

    You only need to install the ARMS application monitoring component ack-onepilot to monitor Java applications deployed in Container Service for Kubernetes ACK or Container Compute Service ACS, and view monitoring data such as application topology, interface calls, exception transactions, and slow transactions. This topic describes how to install the agent for Java applications in Container Service for Kubernetes ACK and Container Compute Service ACS.

    Note

    The operations for installing agents in Container Service for Kubernetes ACK and Container Compute Service ACS are the same. This topic uses Container Service for Kubernetes ACK as an example to demonstrate the operations for installing agents.

    Ack-onepilot component description

    ARMS agent access assistant (ack-onepilot) is an important component for connecting various language agents, which helps ARMS users automatically prepare ARMS agent packages and build the agent reporting environment in container environments. For the basic principles of ARMS agent access assistant (ack-onepilot), see Basic principles of ack-onepilot component.

    After installing the ARMS agent, to ensure your optimal user experience, the agent will automatically upgrade to the latest version when your application restarts, following the release of a new agent version. If you do not want to automatically update the agent with each new release, you can manually control the version. For more information, see Control agent version manually.

    Important

    The old application monitoring component arms-pilot is no longer maintained. You can install the upgraded ack-onepilot component to monitor your applications. ack-onepilot is fully compatible with arms-pilot, so you do not need to modify your application configuration to seamlessly connect to ack-onepilot. For more information, see How to uninstall arms-pilot and install ack-onepilot.

    Prerequisites

    Step 1: Install ARMS agent access assistant (ack-onepilot)

    1. Log on to the ACK console. On the Clusters page, click the name of the cluster.

    2. In the left-side navigation pane, choose Operations > Add-ons. On the Add-ons page, search for ack-onepilot.

    3. 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.

    4. In the dialog box that appears, configure the parameters and click OK. We recommend that you use the default values.

      Note

      After you install ack-onepilot, you can upgrade, configure, or uninstall it on the Add-ons page.

    Step 2: Grant access permissions on ARMS resources

    ACK managed cluster

    If ARMS Addon Token does not exist in the ACK managed cluster, perform the following operations to manually grant access permissions on ARMS resources for the cluster. If ARMS Addon Token already exists, skip to Step 3.

    Check whether ARMS Addon Token exists in a cluster

    1. Log on to the ACK console. In the left-side navigation pane, click Clusters. On the Clusters page, click the name of the cluster to go to the cluster details page.

    2. In the left-side navigation pane, choose Configurations > Secrets. In the upper part of the page, select kube-system from the Namespace drop-down list and check whether addon.arms.token is displayed on the Secrets page.

    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

    1. Log on to the ACK console. In the left-side navigation pane, click Clusters. On the Clusters page, click the name of the cluster.

    2. On the Basic Information tab of the Cluster Information page, click the link next to Worker RAM Role in the Cluster Resources section.

    3. On the page that appears, click Grant Permission on the Permissions tab.

    4. In the Grant Permission panel, add the following policies and click Grant permissions.

      • AliyunTracingAnalysisFullAccess: full access to Managed Service for OpenTelemetry.

      • AliyunARMSFullAccess: full access to ARMS.

    ACK dedicated cluster/registered cluster

    If you need to monitor applications in ACK dedicated clusters and ACK One registered clusters, make sure that the corresponding Alibaba Cloud account has the AliyunARMSFullAccess and AliyunSTSAssumeRoleAccess permissions. For information about how to add permissions, see Grant permissions to a RAM user.

    After you install the ack-onepilot agent, you must enter the AccessKey ID and AccessKey secret of the Alibaba Cloud account in the configuration file of the ack-onepilot agent.

    Method 1: Directly enter the AccessKey ID and AccessKey secret in Helm

    1. Log on to the ACK console. In the left-side navigation pane, click Clusters.

    2. On the Clusters page, click the name of the target cluster. In the left-side navigation pane, choose Applications > Helm. On the page that appears, click Update to the right of the ack-onepilot component.

    3. Replace accessKey and accessKeySecret with the AccessKey of the current account, and then click OK.

      Note

      For information about how to obtain an AccessKey, see Create an AccessKey.

      The AccessKey secret of an Alibaba Cloud account is displayed only when you create the AccessKey pair for the Alibaba Cloud account. You cannot query the AccessKey secret in subsequent operations. This helps reduce the risks of AccessKey pair leaks. Record the AccessKey secret and keep it confidential.

      image

    4. Restart the Deployment application.

    Method 2: Import the AccessKey ID and AccessKey secret through a Kubernetes Secret

    1. Log on to the Container Service for Kubernetes console. In the left-side navigation pane, click Clusters.

    2. On the Clusters page, click the name of the target cluster. In the left-side navigation pane, choose Configurations > Secrets.

    3. Select the ack-onepilot namespace, and then create a Secret to add the AccessKey ID and AccessKey secret information.

      Note

      For information about how to obtain an AccessKey, see Create an AccessKey.

      The AccessKey secret of an Alibaba Cloud account is displayed only when you create the AccessKey pair for the Alibaba Cloud account. You cannot query the AccessKey secret in subsequent operations. This helps reduce the risks of AccessKey pair leaks. Record the AccessKey secret and keep it confidential.

      image

    4. In the left-side navigation pane, choose Workloads > Deployments. Click the ack-onepilot component (usually in the ack-onepilot namespace, named ack-onepilot-ack-onepilot).

    5. In the upper-right corner of the ack-onepilot-ack-onepilot page, click Edit. In the Environment Variables section, add ONE_PILOT_ACCESSKEY and ONE_PILOT_ACCESSKEY_SECRET. Replace them with the values saved in the Secret by using the Secret reference method. Click OK.

      image

    ACK Serverless cluster/ECI cluster

    If you need to monitor applications in ACK Serverless clusters or clusters integrated with ECI, complete the authorization on the Cloud Resource Access Authorization page, and then restart all pods under the ack-onepilot component.

    Step 3: Enable Application Monitoring for a Java application

    The following YAML template shows how to create a Deployment and enable Application Monitoring for the application:

    Expand to view the complete YAML file example (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"
    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 
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"
    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:
    # the port that this service should serve on
    - name: arms-demo-component-svc
      port: 6666
      targetPort: 8888
  # label keys and values that must match to receive traffic for this service
  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:
    # the port that this service should serve on
    - name: arms-mysql-svc
      port: 3306
      targetPort: 3306
  # label keys and values that must match to receive traffic for this service
  selector:
    app: mysql
---

    1. Log on to the ACK console. In the left-side navigation pane, click Clusters.

    2. On the Clusters page, find the cluster you want to manage and click its name. In the left-side pane, choose Workloads > Deployments.

    3. On the Deployments page, choose More > View YAML in the Actions column of the target application.

      To create a new application, click Create From YAML.

    4. Add the following labels to the spec.template.metadata level in the YAML file.

      labels:
  armsPilotAutoEnable: "on"
  armsPilotCreateAppName: "<your-deployment-name>"    # Replace <your-deployment-name> with the actual application name. 
  armsSecAutoEnable: "on"    # If you want to connect the application to Application Security, you must configure this parameter.
      Note

      YAML Example

    5. Click Update.

      On the Deployments page, if the ARMS Console button appears in the Actions column of the target application, the application has been connected to ARMS.

      ARMS Console Button

    FAQ