Automatically install the Go probe in generic Kubernetes environments - Application Real-Time Monitoring Service

ARMS Application Monitoring provides observability for Go applications running in generic Kubernetes environments. After you complete the setup, you can monitor application topology, API calls, abnormal and slow transactions, and SQL analysis from the ARMS console.

This guide covers three steps: compile your Go binary with the instgo instrumentation tool, deploy the ack-onepilot monitoring component to your cluster, and label your workloads to enable automatic probe injection.

Note

This guide applies to generic (non-ACK) Kubernetes clusters only. If your cluster runs on Container Service for Kubernetes (ACK), see Install the Go probe for ACK and Container Compute Service (ACS) clusters using the ack-onepilot component.

Prerequisites

Kubernetes kube-apiserver version 1.10 or later
Go 1.18 or later
Helm 3 installed on your workstation
If your Kubernetes cluster is not deployed on Alibaba Cloud, the cluster must have internet access or be connected to an Alibaba Cloud Virtual Private Cloud (VPC) through Cloud Enterprise Network (CEN) or an equivalent method

Step 1: Build the instrumented Go image

ARMS uses instgo, a compile-time instrumentation tool, to inject monitoring capabilities into your Go binary. Prefix your build command with instgo and compile as usual.

1.1 (Optional) Prepare vendor mode dependencies

Skip this sub-step if you do not use vendor mode or the -mod=vendor flag.

If your project compiles with -mod=vendor, verify that the google.golang.org/protobuf dependency exists in your go.mod (directly or indirectly). If it does not, add it:

Add the following blank imports to your project's main.go file:

   import (
       _ "google.golang.org/protobuf/proto"
       _ "google.golang.org/protobuf/runtime/protoimpl"
   )

Download the missing dependencies and sync them to the vendor folder:
```
   go mod tidy
   go mod vendor
```
Make sure -mod=vendor is included in your go build flags.

1.2 Download instgo

Download the instgo binary that matches your build environment's OS and architecture. The binary is identical across all regions. If your build environment can reach Alibaba Cloud Object Storage Service (OSS) endpoints over the internet, use any region's internet download address (for example, China (Hangzhou)).

Note

instgo auto-updates at compile time. Save it in a directory where you have write permissions.

Select the tab for your platform, then run the wget command for your region.

Linux (AMD64)

Linux (ARM64)

Mac (ARM64)

Mac (AMD64)

Windows (AMD64)

1.3 Grant execute permissions

Linux/Mac:

chmod +x instgo

Windows: No additional permissions are required.

1.4 Configure the LicenseKey for production deployments

Important

If you skip this step, instgo runs in dev mode and installs the latest ARMS agent by default. For production deployments, configure the LicenseKey.

Get your LicenseKey by calling the DescribeTraceLicenseKey API operation. On the DescribeTraceLicenseKey page, click Debug, select a region, and click Initiate Call to retrieve the LicenseKey.
Set the LicenseKey: Replace <your-license-key> with the LicenseKey value from the previous step.
```
   instgo set --licenseKey=<your-license-key>
```

1.5 Compile with instgo

Prefix your existing go build command with instgo:

instgo go build <your-build-flags>

This also works with go install:

instgo go install <your-build-flags>

1.6 Build the container image

Build your container image using the instrumented binary from the previous step.

Step 2: Install the ack-onepilot component

The ack-onepilot component runs in your cluster and handles automatic probe injection. It supports only two workload types: Deployment (stateless) and StatefulSet (stateful).

Download and extract the ack-onepilot Helm chart:

   wget 'https://aliacs-app-catalog.oss-cn-hangzhou.aliyuncs.com/charts-incubator/ack-onepilot-5.1.1.tgz'
   tar xvf ack-onepilot-5.1.1.tgz

Edit ack-onepilot/values.yaml and set the following parameters: Replace the placeholders with your actual values:

Important

The Alibaba Cloud account (root account) must have the AliyunARMSFullAccess and AliyunSTSAssumeRoleAccess permissions.

Placeholder	Description	Example
`<region-id>`	Alibaba Cloud region ID. See Supported regions.	cn-hangzhou
`<cluster-id>`	A unique identifier for your Kubernetes cluster. Recommended format: `<uid>-<clusterid>`.	1234567890-myk8s
`<access-key-id>`	AccessKey ID of your Alibaba Cloud account (root account). See Create an AccessKey pair.	LTAI5tXxx
`<access-key-secret>`	AccessKey Secret of your Alibaba Cloud account (root account).	xXxXxXx
`<account-uid>`	Alibaba Cloud account (root account) ID. Hover over your profile picture in the upper-right corner of the Alibaba Cloud console to find it.	1234567890

   registry: registry-<region-id>.ack.aliyuncs.com/acs/
   cluster_id: <cluster-id>
   accessKey: <access-key-id>
   accessKeySecret: <access-key-secret>
   uid: "<account-uid>"
   region_id: <region-id>

Install the chart. Run this command from outside the ack-onepilot directory:

   helm3 upgrade --install ack-onepilot ack-onepilot --namespace ack-onepilot --create-namespace

Step 3: Label your Deployment to enable the probe

Add the following labels under spec.template.metadata.labels in your Deployment YAML to activate automatic probe injection:

labels:
  aliyun.com/app-language: "golang"       # Identifies the application as a Go workload
  armsPilotAutoEnable: "on"               # Enables automatic probe injection
  armsPilotCreateAppName: "<your-app-name>"  # Sets the application name shown in the ARMS console

Apply labels to an existing Deployment

View the current YAML:
Note
If you do not know your deployment name, list all Deployments: kubectl get deployments --all-namespaces
```
   kubectl get deployment <deployment-name> -o yaml
```

Open the YAML for editing:

   kubectl edit deployment <deployment-name> -o yaml

Add the three labels under spec.template.metadata.labels, then save and exit.

Complete sample YAML

The following example deploys a Go client-server pair with ARMS monitoring enabled:

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

Verify the result

About one minute after you complete the steps, open the ARMS console and go to Application Monitoring > Application List. Your Go application appears in the list and begins reporting data.

Application list showing the connected Go application

Region	Internet address	VPC address
China (Hangzhou)	`wget "http://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`	`wget "http://arms-apm-cn-hangzhou.oss-cn-hangzhou-internal.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`
China (Shanghai)	`wget "http://arms-apm-cn-shanghai.oss-cn-shanghai.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`	`wget "http://arms-apm-cn-shanghai.oss-cn-shanghai-internal.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`
China (Qingdao)	`wget "http://arms-apm-cn-qingdao.oss-cn-qingdao.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`	`wget "http://arms-apm-cn-qingdao.oss-cn-qingdao-internal.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`
China (Beijing)	`wget "http://arms-apm-cn-beijing.oss-cn-beijing.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`	`wget "http://arms-apm-cn-beijing.oss-cn-beijing-internal.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`
China (Zhangjiakou)	`wget "http://arms-apm-cn-zhangjiakou.oss-cn-zhangjiakou.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`	`wget "http://arms-apm-cn-zhangjiakou.oss-cn-zhangjiakou-internal.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`
China (Hohhot)	`wget "http://arms-apm-cn-huhehaote.oss-cn-huhehaote.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`	`wget "http://arms-apm-cn-huhehaote.oss-cn-huhehaote-internal.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`
China (Ulanqab)	`wget "http://arms-apm-cn-wulanchabu.oss-cn-wulanchabu.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`	`wget "http://arms-apm-cn-wulanchabu.oss-cn-wulanchabu-internal.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`
China (Shenzhen)	`wget "http://arms-apm-cn-shenzhen.oss-cn-shenzhen.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`	`wget "http://arms-apm-cn-shenzhen.oss-cn-shenzhen-internal.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`
China (Heyuan)	`wget "http://arms-apm-cn-heyuan.oss-cn-heyuan.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`	`wget "http://arms-apm-cn-heyuan.oss-cn-heyuan-internal.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`
China (Guangzhou)	`wget "http://arms-apm-cn-guangzhou.oss-cn-guangzhou.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`	`wget "http://arms-apm-cn-guangzhou.oss-cn-guangzhou-internal.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`
China (Chengdu)	`wget "http://arms-apm-cn-chengdu.oss-cn-chengdu.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`	`wget "http://arms-apm-cn-chengdu.oss-cn-chengdu-internal.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`
China (Hong Kong)	`wget "http://arms-apm-cn-hongkong.oss-cn-hongkong.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`	`wget "http://arms-apm-cn-hongkong.oss-cn-hongkong-internal.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`
Singapore	`wget "http://arms-apm-ap-southeast-1.oss-ap-southeast-1.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`	`wget "http://arms-apm-ap-southeast-1.oss-ap-southeast-1-internal.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`
Malaysia (Kuala Lumpur)	`wget "http://arms-apm-ap-southeast-3.oss-ap-southeast-3.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`	`wget "http://arms-apm-ap-southeast-3.oss-ap-southeast-3-internal.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`
Indonesia (Jakarta)	`wget "http://arms-apm-ap-southeast-5.oss-ap-southeast-5.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`	`wget "http://arms-apm-ap-southeast-5.oss-ap-southeast-5-internal.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`
Japan (Tokyo)	`wget "http://arms-apm-ap-northeast-1.oss-ap-northeast-1.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`	`wget "http://arms-apm-ap-northeast-1.oss-ap-northeast-1-internal.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`
Germany (Frankfurt)	`wget "http://arms-apm-eu-central-1.oss-eu-central-1.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`	`wget "http://arms-apm-eu-central-1.oss-eu-central-1-internal.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`
UK (London)	`wget "http://arms-apm-eu-west-1.oss-eu-west-1.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`	`wget "http://arms-apm-eu-west-1.oss-eu-west-1-internal.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`
US (Virginia)	`wget "http://arms-apm-us-east-1.oss-us-east-1.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`	`wget "http://arms-apm-us-east-1.oss-us-east-1-internal.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`
US (Silicon Valley)	`wget "http://arms-apm-us-west-1.oss-us-west-1.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`	`wget "http://arms-apm-us-west-1.oss-us-west-1-internal.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo`