Container Service for Kubernetes:Python application monitoring

Choose an installation path

ARMS supports two ways to instrument your Python application. Choose one based on your ack-onepilot version:

Prerequisites

Before you begin, ensure that you have:

• A namespace in your ACK cluster. This guide uses a namespace named arms-demo. See Manage namespaces and resource quotas.

• Python 3.8 or later. ARMS is not compatible with earlier Python versions.

• ARMS activated. See Activate ARMS.

Step 1: Install the ack-onepilot add-on

ack-onepilot replaces the deprecated arms-pilot component and is fully compatible with it—no application configuration changes are needed.

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

2. On the Clusters page, click the name of the target cluster. In the left navigation pane, click Add-ons.

3. In the Logs and Monitoring section, find ack-onepilot and click Install. In the dialog box that appears, use the default values and click OK.

Use ack-onepilot version 3.2.4 or later. By default, ack-onepilot supports up to 1,000 pods. For every additional 1,000 pods, increase ack-onepilot's CPU by 0.5 cores and memory by 512 MB.

After installation, you can upgrade, configure, or uninstall ack-onepilot from the Add-ons page.

For migration from arms-pilot, see How do I uninstall arms-pilot and install ack-onepilot?

Step 2: Authorize ARMS to access resources

ARMS uses addon.arms.token for password-free authorization. Most ACK managed clusters include this secret by default. Some older clusters may not.

Check whether your cluster has the token:

If the token is missing, grant permissions manually:

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

2. On the Clusters page, click the name of the target cluster. In the left navigation pane, click Cluster Information.

3. On the Basic Information tab, under Cluster Resources, click the link next to Worker RAM Role.

4. On the Permissions tab, click Grant Permission.

5. Select the AliyunARMSFullAccess policy and click Grant permissions.

If your cluster is connected to an Elastic Container Instance (ECI), go to the RAM Quick Authorization page and complete the authorization. Then restart the pods created for ack-onepilot.

Step 3: Integrate the Python agent into the Dockerfile

Modify your Dockerfile to install and start the Python agent. The changes involve three lines:

• Install aliyun-bootstrap from PyPI — the installer tool for the ARMS Python agent.

• Run the agent installer — downloads and configures the agent using your Alibaba Cloud region ID.

• Change the startup command — wrap your application with aliyun-instrument to activate monitoring.

# 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"]

# 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 ARMS Python agent.
# Replace xxx with your Alibaba Cloud region ID (for example, cn-hangzhou).
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
# Start the application with the ARMS Python agent enabled.
CMD ["aliyun-instrument","python","app.py"]

To install a specific agent version, run aliyun-bootstrap -a install -v <version> instead of aliyun-bootstrap -a install. For available versions, see Python agent release notes.

After editing the Dockerfile, build your image and push it to your registry.

Step 4: Enable ARMS application monitoring

Add labels to your Deployment's pod template to activate monitoring.

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

2. On the Clusters page, click the name of the target cluster. In the left navigation pane, choose Workloads > Deployments.

3. On the Deployments page, click > Edit YAML for the target application.

4. Under spec.template.metadata, add the following labels:

   labels:
     aliyun.com/app-language: python        # Required. Identifies this as a Python application.
     armsPilotAutoEnable: 'on'
     armsPilotCreateAppName: "deployment-name"    # The display name of the application in ARMS.

   Replace deployment-name with the name you want to display in the ARMS console.

   

armsAutoInstrumentationEnable: "off"

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
        armsPilotAutoEnable: 'on'
        armsPilotCreateAppName: "arms-python-client"
    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
        armsPilotAutoEnable: 'on'
        armsPilotCreateAppName: "arms-python-server"
    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
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

The following YAML creates two Deployments (arms-python-client and arms-python-server) and two Services in the arms-demo namespace, with ARMS monitoring enabled.

Step 5: View monitoring data

After about one minute, your application appears in the ARMS console.

1. Go to the ARMS console and navigate to Application Monitoring > Application List.

   

2. Click the application name to view detailed metrics. For a full description of the monitoring page, see Application Overview.

Troubleshooting

If your application does not appear in the ARMS console after one minute, check the following:

Verify that pods are running and labels are applied:

kubectl get pods -n arms-demo
kubectl describe pod <pod-name> -n arms-demo | grep -A 10 "Labels:"

Confirm the pod labels include armsPilotAutoEnable: on and aliyun.com/app-language: python.

Common causes of missing monitoring data:

(Optional) Release resources

To stop monitoring, uninstall the Python agent. See Uninstall the Python agent.

What's next

• Application Overview — explore metrics, traces, and topology in ARMS

• Python agent release notes — track agent version updates

• What is Application Real-Time Monitoring Service? — learn more about ARMS capabilities