Install the Python agent for Container Service for Kubernetes (ACK) and Container Compute Service (ACS) by using the ack-onepilot component - Cloud Monitor

To monitor Python applications deployed in Container Service for Kubernetes (ACK) and Container Compute Service (ACS), you must install the ack-onepilot application monitoring component and modify the corresponding Dockerfile. You can then view monitoring data, such as application topology, API calls, and call chain analysis, in Cloud Monitor 2.0. This topic describes how to install the agent for Python applications deployed in Container Service for Kubernetes (ACK) and Container Compute Service (ACS).

About the ack-onepilot component

The Application Monitoring agent installation assistant, ack-onepilot, is a key component for installing agents for different languages. It automatically prepares the Application Monitoring agent package and configures the agent's reporting environment within a container. For more information about the basic principles of ack-onepilot, see Basic principles of the ack-onepilot component.

After the agent is installed, ack-onepilot automatically upgrades the agent to the latest version when the application is restarted and a new version of the agent is available. If you do not want the agent to be automatically updated with each new release, you can control the agent version. For more information, see Control the agent version.

Prerequisites

An ACK or ACS cluster is created.
For ACK clusters: Create an ACK dedicated cluster (new creations are discontinued), Create an ACK managed cluster, or Create an ACK Serverless cluster.
For ACS clusters: Create an ACS cluster.
A namespace is created. For more information, see Manage namespaces and quotas. This topic uses arms-demo as an example namespace name.
Your Python and framework versions are supported. For more information, see Python libraries supported by Application Monitoring.

Notes

If your application starts with uvicorn, choose one of the following configuration methods.
- Method 1: Add the following statement to the first line of the uvicorn entry file to import the Python agent.
```
from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize
```
- Method 2: Replace uvicorn with gunicorn and add the aliyun-instrument prefix to the gunicorn command.
  Example:
```
uvicorn app:app --workers 4 --port=9090 --host 0.0.0.0
```
  Change the command to:
```
aliyun-instrument gunicorn -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 app:app
```
  Note
  The aliyun-instrument instruction handles the initialization and non-intrusive instrumentation of the ARMS Python agent.
If your application starts with uWSGI, see Install the Python agent for a Django or Flask project that starts with uWSGI.
If you use gevent coroutines, you must set the GEVENT_ENABLE=true environment variable.
For example, if your program contains the following code:
```
from gevent import monkey
monkey.patch_all()
```
You must set the environment variable as follows:
```
GEVENT_ENABLE=true
```

Step 1: Install the agent installation assistant (ack-onepilot)

Log on to the ACK console. On the Clusters page, click the name of the cluster.
In the left navigation pane, click add-ons, and then in the upper-right corner, search for ack-onepilot.
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.
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.

(Optional) Step 2: Modify the Dockerfile

Important

For ack-onepilot component version 5.1.0 and later, the component automatically downloads and injects the Python agent package when you enable monitoring for an application. This provides a non-intrusive monitoring experience that does not require you to manually modify the startup command.

Download the agent installer from the Python Package Index (PyPI) repository.
```
pip3 install aliyun-bootstrap
```
Use aliyun-bootstrap to install the agent.
```
# The region ID of the Alibaba Cloud account.
ARMS_REGION_ID=xxx aliyun-bootstrap -a install
```
Note
To install a specific version of the Python agent, run the following command:
```
# Replace ${version} with the actual version number.
aliyun-bootstrap -a install -v ${version}
```
For more information about all released versions of the Python agent, see Python agent release notes.
Start the application using the ARMS Python agent.
```
aliyun-instrument python app.py
```
Build the image.

The following code provides a complete Dockerfile example:

Dockerfile before modification

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

# Set the working directory.
WORKDIR /app

# Copy the requirements.txt file 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 port 8000 of the container.
EXPOSE 8000
CMD ["python","app.py"]

Modified Dockerfile

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

# Set the working directory.
WORKDIR /app

# Copy the requirements.txt file to the working directory.
COPY requirements.txt .

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

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


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

Step 3: Grant access permissions to ARMS resources

ACK managed clusters

If an ARMS Addon Token does not exist in the ACK managed cluster, manually grant permissions to access ARMS resources. If an ARMS Addon Token already exists, skip to Step 4.

Check whether ARMS Addon Token exists in a cluster

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

Log on to the ACK console. In the left-side navigation pane, click Clusters. On the Clusters page, click the name of the cluster.
On the Basic Information tab of the Cluster Information page, click the link next to Worker RAM Role in the Cluster Resources section.
On the page that appears, click Grant Permission on the Permissions tab.
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

To monitor an application deployed in an ACK dedicated cluster or registered cluster, make sure that the AliyunARMSFullAccess and AliyunSTSAssumeRoleAccess permissions are granted to your Resouce Access Management (RAM) user.

After installing the ack-onepilot component, enter the AccessKey ID and AccessKey Secret of the account in the configuration file of ack-onepilot.

Method 1: Input in Hem

Log on to the ACK console. In the left navigation pane, click Clusters.
On the Clusters page, click the cluster you want to manage. In the left-side navigation pane of the page that appears, choose Applications > Helm. Then, click Update next to ack-onepilot.
Replace accessKey and accessKeySecret with the AccessKey ID and AccessKey secret of the account and click OK.
Note
The AccessKey Secret is only visible during initial creation of an Alibaba Cloud AccessKey pair and cannot be retrieved afterward. This design mitigates leakage risks. Securely store the Secret immediately.
Restart the Deployment.

Method 2: Import through Kubernetes Secrets

Log on to the ACK console. In the left-side navigation pane, click Clusters.
On the Clusters page, click the cluster you want to manage. In the left-side navigation pane of the page that appears, choose Configurations > Secrets.
Click Create. In the panel that appears, click Add and add the AccessKey ID and AccessKey Secret for ack-onepilot.
Note
The AccessKey Secret is only visible during initial creation of an Alibaba Cloud AccessKey pair and cannot be retrieved afterward. This design mitigates leakage risks. Securely store the Secret immediately.
In the left-side navigation pane, choose Workloads > Deployments. On the page that appears, click the ack-onepilot component. Generally, it is named ack-onepilot-ack-onepilot in the ack-onepilot namespace.
In the upper-right corner of the page that appears, click Edit.
Scroll down until you see the Environments section. Click Add, add the environment variables ONE_PILOT_ACCESSKEY and ONE_PILOT_ACCESSKEY_SECRET, reference the Secrets in Kubernetes Secrets, and click OK.

ASK/ECI cluster

To monitor applications in an ACK Serverless (ASK) cluster or applications in a Kubernetes cluster connected to Elastic Container Instance, 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.

Step 4: Enable Application Monitoring for the Python application

Note

The Python agent package is downloaded and injected by an init container. With the default resource settings, the init container may take about 10 seconds to run. By default, the init container consumes 0.5 cores and 250 MB of resources, which are released after initialization. You can adjust the resource quota of the init container to change its execution speed using the following environment variables:

PYTHON_INIT_RESOURCE_REQUESTS_CPU: The CPU request for the Python application's init container. Example: 500m.
PYTHON_INIT_RESOURCE_REQUESTS_MEM: The memory request for the Python application's init container. Example: 250Mi.
PYTHON_INIT_RESOURCE_LIMIT_CPU: The CPU limit for the Python application's init container. Example: 1000m.
PYTHON_INIT_RESOURCE_LIMIT_MEM: The memory limit for the Python application's init container. Example: 500Mi.

The following is a complete sample YAML template for creating a stateless (deployment) application and enabling Application Monitoring:

Expand to view the complete sample YAML file (Python)

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 for Python applications. Indicates that this is a Python application.
        armsPilotAutoEnable: 'on'
        armsPilotCreateAppName: "arms-python-client"    # The display name of the application in ARMS.
        armsPilotAppWorkspace: "workspace"   # If no workspace is specified, data is reported to the default workspace.
    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 for Python applications. Indicates that this is a Python application.
        armsPilotAutoEnable: 'on'
        armsPilotCreateAppName: "arms-python-server"    # The display name of the application in ARMS.
        armsPilotAppWorkspace: "workspace"  # Replace with your workspace name.
    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

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 Stateless page, find the target application and choose > YAML Edit in the Actions column.
To create a new application, click Create from YAML.

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

labels:
  aliyun.com/app-language: python # Required for Python applications. Indicates that this is a Python application.
  armsPilotAutoEnable: 'on'
  armsPilotCreateAppName: "deployment-name"    # The display name of the application in ARMS.
  armsPilotAppWorkspace: "workspace"    # Replace with your workspace name.

Important

If you do not want to use the non-intrusive injection capability for Python, you can disable it with the following label:

labels:
  armsAutoInstrumentationEnable: "off"  # Disables the non-intrusive injection capability for Python applications.

Click Update.

View monitoring details

Log on to the Cloud Monitor 2.0 console, and select a workspace. In the left navigation pane, choose Application Center > Application Observability > Application Insights.
On the Application List page, click an application name to view its detailed monitoring data.