Install an ARMS agent for a Python application deployed in ACK or ACS - Application Real-Time Monitoring Service

After you install ack-onepilot and modify the Dockerfile, Application Real-Time Monitoring Service (ARMS) starts to monitor your Python application. You can view the monitoring data, such as the application topology, interface calls, and trace analysis data. This topic describes how to install an ARMS agent for a Python application deployed in Container Service for Kubernetes (ACK) or Container Compute Service (ACS).

Note

If you have any questions when you use an ARMS agent, join the DingTalk group chat (ID: 35568145) to obtain technical support.

Prerequisites

An ACK or ACS cluster is created.
- ACK cluster: You can create an ACK dedicated cluster, ACK managed cluster, or ACK Serverless cluster based on your business requirements.
- ACS cluster: For information about how to create an ACS cluster, see Create an ACS cluster.
A namespace is created in the cluster. For more information, see Manage namespaces and resource quotas. The namespace used in this example is arms-demo.
The versions of Python and the framework are supported. For more information, see Compatibility requirements of the ARMS agent for Python.

Usage notes

If the application is started by using Unicorn, use Gunicorn instead.

Sample command:

unicorn -w 4 -b 0.0.0.0:8000 app:app

New command:

gunicorn -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 app:app

If you use gevent coroutines, set the environment variable GEVENT_ENABLE=true.
Example:
```
from gevent import monkey
monkey.patch_all()
```
Run the following command to set the environment variable:
```
GEVENT_ENABLE=true
```

Procedure

The procedure for installing an ARMS agent on an application deployed in ACK is the same as that for an application deployed in ACS. The following uses the ACK environment as an example.

Step 1: Install ack-onepilot

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.
In the left-side navigation pane, choose Operations > Add-ons. On the Add-ons page, enter ack-onepilot in the upper-right corner.
Important
Make sure that the ack-onepilot version is 3.2.4 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 need to add 0.5 CPU cores and 512 MB memory for the component.

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: Modify the Dockerfile

Download aliyun-bootstrap from PyPI.
```
pip3 install aliyun-bootstrap
```

Install the ARMS agent using aliyun-bootstrap.

# The ID of the region corresponding to your Alibaba Cloud account.
ARMS_REGION_ID=xxx aliyun-bootstrap -a install

Use the ARMS agent to start the application.
```
aliyun-instrument python app.py
```
Build an image.

Sample Dockerfiles:

Dockerfile before modification

# Use a Python 3.10 base image.
FROM docker.m.daocloud.io/python:3.10

# Set the working directory.
WORKDIR /app

# Copy the requirements.txt file and paste it to the working directory.
COPY requirements.txt .

# Use pip to install dependencies.
RUN pip install --no-cache-dir -r requirements.txt

COPY ./app.py /app/app.py
# Expose the 8000 port of the ACK cluster.
EXPOSE 8000
CMD ["python","app.py"]

Dockerfile after modification

# Use a Python 3.10 base image.
FROM docker.m.daocloud.io/python:3.10

# Set the working directory.
WORKDIR /app

# Copy the requirements.txt file and paste it to the working directory.
COPY requirements.txt .

# Use pip to install dependencies.
RUN pip install --no-cache-dir -r requirements.txt
######################### Install the ARMS agent for Python ###############################
# The ID of the region corresponding to your Alibaba Cloud account.
RUN pip3 install aliyun-bootstrap && ARMS_REGION_ID=xxx aliyun-bootstrap -a install
##########################################################

COPY ./app.py /app/app.py


# Expose the 8000 port of the ACK cluster.
EXPOSE 8000
#########################################################
CMD ["aliyun-instrument","python","app.py"]

Step 3: Grant access permissions on ARMS resources

To monitor applications in a serverless Kubernetes (ASK) cluster or applications in a Kubernetes cluster connected to Elastic Container Instance (ECI), you must first authorize the cluster to access ARMS on the Cloud Resource Access Authorization page. Then, restart all pods on which the ack-onepilot component is deployed.
To monitor an application deployed in an ACK cluster with no ARMS Addon Token, perform the following operations to authorize the ACK cluster to access ARMS. If ARMS Addon Token exists, go to Step 4.
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 manually 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.
To monitor an application deployed in an ACK dedicated cluster or registered cluster, make sure that the AliyunARMSFullAccess and AliyunSTSAssumeRoleAccess permissions are granted to the Alibaba Cloud account. For more information about how to grant permissions to a RAM user, see Grant permissions to a RAM user.
After you install ack-onepilot, you must enter the AccessKey ID and AccessKey secret of the Alibaba Cloud account in its configuration file.
1. In the left-side navigation pane, choose Applications > Helm. Then, click Update next to ack-onepilot.
2. Replace accessKey and accessKeySecret with the AccessKey ID and AccessKey secret of the Alibaba Cloud account and click OK.
  Note
  For more information about how to obtain an AccessKey pair, see Create an AccessKey.
3. Restart the Deployment.

(Optional) Step 4: Enable Application Monitoring for the application

Log on to the ACK console. In the left-side navigation pane, click Clusters.
On the Clusters page, click the name of the cluster that you want to manage. On the page that appears, choose Workloads > Deployments.
On the Deployments page, find the application and choose More > View in YAML in the Actions column.
To create a new application, click Create from YAML.

Add the following labels to spec.template.metadata:

labels:
  aliyun.com/app-language: python # Required. Specify that the application uses the Python language. 
  armsPilotAutoEnable: 'on'
  armsPilotCreateAppName: "<your-deployment-name>"    # Specify the display name of the Deployment in ARMS.

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

YAML template

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: arms-python-client
  name: arms-python-client
  namespace: arms-demo
spec:
  progressDeadlineSeconds: 600
  replicas: 1
  revisionHistoryLimit: 10
  selector:
    matchLabels:
      app: arms-python-client
  strategy:
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%
    type: RollingUpdate
  template:
    metadata:
      labels:
        app: arms-python-client
        aliyun.com/app-language: python # Required. Specify that the application uses the Python language. 
        armsPilotAutoEnable: 'on'
        armsPilotCreateAppName: "arms-python-client" # Specify the display name of the Deployment in ARMS. 
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/arms-default/python-agent:arms-python-client
          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: arms-python-server
  name: arms-python-server
  namespace: arms-demo
spec:
  progressDeadlineSeconds: 600
  replicas: 1
  revisionHistoryLimit: 10
  selector:
    matchLabels:
      app: arms-python-server
  strategy:
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%
    type: RollingUpdate
  template:
    metadata:
      labels:
        app: arms-python-server
        aliyun.com/app-language: python # Required. Specify that the application uses the Python language. 
        armsPilotAutoEnable: 'on'
        armsPilotCreateAppName: "arms-python-server" # Specify the display name of the Deployment in ARMS. 
    spec:
      containers:
        - env:
          - name: CLIENT_URL
            value: 'http://arms-python-client-svc:8000'
        - image: registry.cn-hangzhou.aliyuncs.com/arms-default/python-agent:arms-python-server
          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: arms-python-server
  name: arms-python-server-svc
  namespace: arms-demo
spec:
  internalTrafficPolicy: Cluster
  ipFamilies:
    - IPv4
  ipFamilyPolicy: SingleStack
  ports:
    - name: http
      port: 8000
      protocol: TCP
      targetPort: 8000
  selector:
    app: arms-python-server
  sessionAffinity: None
  type: ClusterIP

apiVersion: v1
kind: Service
metadata:
  name: arms-python-client-svc
  namespace: arms-demo
  uid: 91f94804-594e-495b-9f57-9def1fdc7c1d
spec:
  internalTrafficPolicy: Cluster
  ipFamilies:
    - IPv4
  ipFamilyPolicy: SingleStack
  ports:
    - name: http
      port: 8000
      protocol: TCP
      targetPort: 8000
  selector:
    app: arms-python-client
  sessionAffinity: None
  type: ClusterIP

Verify the result

After about one minute, log on to the ARMS console. In the left-side navigation pane, choose Application Monitoring > Application List. If the application is displayed on the Application List page, the application is being monitored.

2024-09-23_17-45-22