use the local image cache mode to accelerate ack-onepilot integration - Application Real-Time Monitoring Service

This document describes how to use the local image cache mode to accelerate ack-onepilot integration for Java applications.

Background

By default, the init-container injected by the ack-onepilot component dynamically pulls agent packages based on rules. This approach maintains flexibility for application integration. However, in some scenarios, dynamically pulling agent packages on the fly can cause issues:

In edge scenarios with poor network quality, the time required to pull the agent package can increase significantly. The pull operation might even fail due to issues such as timeouts.
Integrating many applications at the same time can increase the machine's input/output operations per second (IOPS). This consumes a large amount of the machine's I/O resources over a short period.

Prerequisites

ack-onepilot 5.1.0 or later.
The application is written in Java.
The agent version is 4.2.5 or later.

Procedure

The following example YAML file shows how to use the local image cache mode to accelerate ack-onepilot integration for a simple Java application in Kubernetes.

Example application YAML

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"
        # Enable the local image cache mode. This is required.
        apsara.apm/enable-cached-agent: 'true'
        # In local image cache mode, specify the agent version. Replace this with the required agent version.
        aliyun.com/agent-version: 4.2.5
    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"
        # Enable the local image cache mode. This is required.
        apsara.apm/enable-cached-agent: 'true'
        # In local image cache mode, specify the agent version. Replace this with the required agent version.
        aliyun.com/agent-version: 4.2.5
    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
---

Install ack-onepilot and grant it the required resource access permissions. For more information, see Install the ARMS agent assistant (ack-onepilot).
Log on to the ACK console. In the left navigation pane, click Clusters.
On the Clusters page, find the cluster you want to manage and click its name. In the left navigation pane, choose Workloads > Deployments.
On the Deployments page, for the target application, choose > Edit YAML.
Click Create From YAML to create a new application.

In the YAML file, add the following labels at the spec.template.metadata level, and then click Update.

labels:
  armsPilotAutoEnable: "on"
  armsPilotCreateAppName: "arms-k8s-demo-subcomponent"
  # Enable the local image cache mode. This is required.
  apsara.apm/enable-cached-agent: 'true'
  # In local image cache mode, specify the agent version. You can replace this with the required agent version. For a list of released agent versions, see the agent management documentation.
  aliyun.com/agent-version: 4.2.5

On the Deployments page, click > ARMS Console in the Actions column for the application to view its monitoring details.