All Products
Search

This Product

    Application Real-Time Monitoring Service:Install the Go agent with ack-onepilot

    Document Center

    Application Real-Time Monitoring Service:Install the Go agent with ack-onepilot

    Last Updated:Aug 24, 2026

    To monitor Go applications deployed in Container Service for Kubernetes (ACK) or Container Compute Service (ACS), you must install the ack-onepilot component of Application Real-Time Monitoring Service (ARMS) and compile your Go binary file. You can then view monitoring data, such as application topology, API calls, and database analysis, in ARMS. This topic describes how to install a Go agent for an application deployed in Container Service for Kubernetes (ACK) or Container Compute Service (ACS).

    Note

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

    • If you have questions about the Go agent, contact us in our DingTalk Q&A group (ID: 159215000379).

    Prerequisites

    Step 1: Grant permissions to access ARMS resources

    ACK managed cluster

    If no ARMS Addon Token exists in your ACK managed cluster, you must manually grant the cluster permissions to access ARMS resources.

    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 and registered clusters

    To monitor applications in ACK dedicated clusters and ACK One registered clusters, ensure that the Alibaba Cloud account has the AliyunARMSFullAccess and AliyunSTSAssumeRoleAccess permissions. For more information about how to grant permissions, see Grant permissions to a RAM user.

    After installing the ack-onepilot component, you must also provide it with the AccessKey pair (AccessKey ID and AccessKey secret) from an Alibaba Cloud account that has ARMS permissions.

    Method 1: Specify the AccessKey pair in Helm

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

    2. On the Clusters page, click the name of your target cluster. In the left-side navigation pane, choose Application > Helm. Find the ack-onepilot component and click Update in the Actions column.

    3. Replace accessKey and accessKeySecret with your AccessKey ID and AccessKey secret, and then click OK.

      Note

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

      On the Update Release page, in the YAML configuration editor, locate the accessKey and accessKeySecret fields under the controller section.

    4. Restart the application Deployment.

    Method 2: Reference the AccessKey pair from a secret

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

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

    3. Select the ack-onepilot namespace, create a secret, and then add your AccessKey pair information.

      Note

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

      Set Name to ack-onepilot-aksk and Type to Opaque. In the data table, add key-value pairs named ak and sk, and set their values to the corresponding AccessKey ID and AccessKey secret. Then click OK.

    4. In the left-side navigation pane, choose Workloads > Stateless. Click the ack-onepilot component, which is typically named ack-onepilot-ack-onepilot and located in the ack-onepilot namespace.

    5. In the top-right corner of the ack-onepilot-ack-onepilot page, click Edit. Then, in the Environment Variables section, add ONE_PILOT_ACCESSKEY and ONE_PILOT_ACCESSKEY_SECRET, set their values by referencing the Secret, and click OK.

      Set the referenced secret for both variables to ack-onepilot-aksk. Set the key for ONE_PILOT_ACCESSKEY to ak and the key for ONE_PILOT_ACCESSKEY_SECRET to sk.

    ACK serverless clusters (ASK) and ECI-integrated clusters

    Complete authorization on the Resource Access Authorization page, then restart all pods of the ack-onepilot component.

    Step 2: Install the ack-onepilot component

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

    2. In the left-side navigation pane, click Component Management and search for ack-onepilot.

      Important

      Make sure that the version of ack-onepilot is 3.2.0 or later.

    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 3: Compile the Go application image

    1. (Optional) If your project includes a vendor directory, add -mod=vendor after go build.

    2. Use the wget command to download the instgo compilation tool, and select the download address that corresponds to your compilation environment and the region of your compilation machine.

      Note that instgo automatically updates itself during compilation. Save instgo in a directory where the build user has write permissions.

      Note

      • Instgo is a build tool that ARMS provides for Go applications. After you compile your Go project by using instgo, ARMS can monitor your Go application.

      • The build tool is the same across all regions. If your public network can access the OSS URL, you can download the tool from the public endpoint for the China (Hangzhou) region that matches your operating system and architecture.

      View download commands

      Linux (AMD64)

      Public URL

      wget "http://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo

      Linux (ARM64)

      Public URL

      wget "http://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/instgo/instgo-linux-arm64" -O instgo

      Mac (ARM64)

      Public URL

      wget "http://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/instgo/instgo-darwin-arm64" -O instgo

      Mac (AMD64)

      Public URL

      wget "http://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/instgo/instgo-darwin-amd64" -O instgo

      Windows (AMD64)

      Public URL

      wget "http://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/instgo/instgo-windows-amd64.exe" -O instgo.exe

    3. Grant executable permissions to the build tool.

      Linux and Mac

      # Grant execute permission
chmod +x instgo

      Windows

      On Windows, you do not need to grant executable permissions.

    4. (Optional) Configure the UID as a build parameter.

      Important

      If you skip this step, instgo installs the latest version of the ARMS agent by default.

      Use the set command to configure the UID or license key as a build parameter.

      instgo set --uid={YourAliyunUid} // You must use instgo 1.4.5 or a later version. The uid is the UID of your primary Alibaba Cloud account.

    5. Prefix your original build command with instgo.

      instgo go build {arg1} {arg2} {arg3}

      This method also applies if you use go install.

    6. Build an image using the binary file generated in the previous step.

    Step 4: Enable ARMS monitoring for Go applications

    The following YAML template shows a complete example of how to create a stateless (Deployment) application and enable ARMS application monitoring:

    View the complete sample YAML file (Go)

    apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: otel-go-client
  name: otel-go-client
  namespace: default
spec:
  progressDeadlineSeconds: 600
  replicas: 1
  revisionHistoryLimit: 10
  selector:
    matchLabels:
      app: otel-go-client
  strategy:
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%
    type: RollingUpdate
  template:
    metadata:
      labels:
        aliyun.com/app-language: golang
        armsPilotAutoEnable: 'on'
        armsPilotCreateAppName: otel-go-client
        app: otel-go-client
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/private-mesh/hellob:otel-client-arms-go-test-0.0.1
          imagePullPolicy: Always
          name: client
          resources:
            requests:
              cpu: 250m
              memory: 300Mi
          terminationMessagePath: /dev/termination-log
          terminationMessagePolicy: File
      dnsPolicy: ClusterFirst
      restartPolicy: Always
      schedulerName: default-scheduler
      securityContext: {}
      terminationGracePeriodSeconds: 30

---

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: otel-go-server
  name: otel-go-server
  namespace: default
spec:
  progressDeadlineSeconds: 600
  replicas: 1
  revisionHistoryLimit: 10
  selector:
    matchLabels:
      app: otel-go-server
  strategy:
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%
    type: RollingUpdate
  template:
    metadata:
      labels:
        app: otel-go-server
        aliyun.com/app-language: golang
        armsPilotAutoEnable: 'on'
        armsPilotCreateAppName: otel-go-server
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/private-mesh/hellob:otel-server-arms-go-test-0.0.1
          imagePullPolicy: Always
          name: server
          resources:
            requests:
              cpu: 250m
              memory: 300Mi
          terminationMessagePath: /dev/termination-log
          terminationMessagePolicy: File
      dnsPolicy: ClusterFirst
      restartPolicy: Always
      schedulerName: default-scheduler
      securityContext: {}
      terminationGracePeriodSeconds: 30

---

apiVersion: v1
kind: Service
metadata:
  labels:
    app: otel-go-server
  name: otel-server
  namespace: default
spec:
  internalTrafficPolicy: Cluster
  ipFamilies:
    - IPv4
  ipFamilyPolicy: SingleStack
  ports:
    - name: http
      port: 9000
      protocol: TCP
      targetPort: 9000
  selector:
    app: otel-go-server
  sessionAffinity: None
  type: ClusterIP

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

    2. At the top of the Clusters page, select the resource group and region where the target cluster is located, and then click the name of the target cluster. In the left-side navigation pane, click Workloads and select Stateless, StatefulSets, or DaemonSets.

    3. Find the target application and choose image > Edit YAML in the Actions column.

      To create a new application, click Create Resources in YAML.

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

      labels:
  aliyun.com/app-language: golang # Required for Go applications. This indicates that this is a Go application.
  armsPilotAutoEnable: 'on'
  armsPilotCreateAppName: "<YOUR-DEPLOYMENT-NAME>"    # Replace <YOUR-DEPLOYMENT-NAME> with your application name.

    5. Click Update.

    Results

    After about a minute, the agent is connected if your Go application appears on the Application Monitoring > Application List page in the ARMS console and is reporting data.