Tous les produits
Search
Centre de documentation

Application Real-Time Monitoring Service:Install the ARMS Python agent in ACK and ACS clusters

Dernière mise à jour :Aug 10, 2026

Lorsque vous exécutez des applications Python dans des clusters Container Service for Kubernetes (ACK) ou Container Compute Service (ACS), Application Real-Time Monitoring Service (ARMS) fournit des fonctionnalités de traçage distribué, de cartographie topologique des applications et d'analyse des appels API. Pour collecter ces données, installez l'agent ARMS Python à l'aide du composant ack-onepilot.

Deux méthodes d'installation sont disponibles :

Méthode Version d'ack-onepilot Modifications du Dockerfile
Injection automatique (recommandée) Supérieure à 5.0.0 Non requises
Installation manuelle 3.2.4 ou ultérieure Requises
Remarque

Pour toute question concernant l'agent Python, consultez la rubrique FAQ sur l'agent Python. Vous pouvez également nous contacter via le groupe DingTalk (ID : 159215000379).

Prérequis

Compatibilité des frameworks Python

Vérifiez les exigences spécifiques à chaque framework avant de poursuivre.

uvicorn

Si votre application démarre avec uvicorn, choisissez l'une des approches suivantes :

Approche A : Importer l'agent dans le code. Ajoutez cette instruction d'importation à la première ligne de votre fichier d'entrée uvicorn :

from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize

**Approche B : Basculer vers gunicorn avec le préfixe aliyun-instrument**. Remplacez votre commande uvicorn :

# Before
uvicorn app:app --workers 4 --port=9090 --host 0.0.0.0

# After
aliyun-instrument gunicorn -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 app:app
Remarque

Le préfixe aliyun-instrument gère l'initialisation et l'instrumentation non intrusive de l'agent ARMS Python.

uWSGI

Si votre application démarre avec uWSGI, consultez la rubrique Installer l'agent Python pour un projet Django ou Flask démarré avec uWSGI.

gevent

Si vous utilisez les coroutines gevent, définissez la variable d'environnement GEVENT_ENABLE sur true.

Par exemple, si votre code contient :

from gevent import monkey
monkey.patch_all()

Définissez la variable d'environnement suivante dans votre déploiement :

GEVENT_ENABLE=true

Étape 1 : Installer ack-onepilot

ack-onepilot est le composant côté cluster qui gère l'installation de l'agent ARMS.

  1. Connectez-vous à la console ACK. Sur la page Clusters, cliquez sur le nom de votre cluster.

  2. Dans le volet de navigation de gauche, cliquez sur Add-ons. Recherchez ack-onepilot dans le coin supérieur droit.

    Important

    Assurez-vous que la version d'ack-onepilot est 3.2.4 ou ultérieure.

  3. Cliquez sur Install sur la carte ack-onepilot.

    Remarque

    Par défaut, ack-onepilot prend en charge 1 000 pods. Pour chaque tranche supplémentaire de 1 000 pods, ajoutez 0,5 cœur CPU et 512 Mo de mémoire au composant.

  4. Dans la boîte de dialogue, configurez les paramètres et cliquez sur OK. Les valeurs par défaut sont recommandées.

    Remarque

    Après l'installation, vous pouvez mettre à jour, configurer ou désinstaller ack-onepilot depuis la page Add-ons.

  5. Choisissez l'étape suivante en fonction de la version d'ack-onepilot :

Étape 2 : Modifier le Dockerfile (ack-onepilot 5.0.0 ou antérieur)

Remarque

Ignorez cette étape si votre version d'ack-onepilot est supérieure à 5.0.0.

Ajoutez l'agent ARMS Python à votre Dockerfile et mettez à jour la commande de démarrage.

  1. Installez le programme d'installation de l'agent depuis PyPI :

       RUN pip3 install aliyun-bootstrap
  2. Installez l'agent. Remplacez <region-id> par l'ID de votre région Alibaba Cloud (par exemple, cn-hangzhou) :

    Remarque

    Pour installer une version spécifique de l'agent, exécutez : aliyun-bootstrap -a install -v <version> Pour toutes les versions publiées, consultez les Notes de version de l'agent Python.

       RUN ARMS_REGION_ID=<region-id> aliyun-bootstrap -a install
  3. Mettez à jour la commande de démarrage pour utiliser le préfixe aliyun-instrument :

       CMD ["aliyun-instrument", "python", "app.py"]
  4. Construisez l'image.

Exemple complet de Dockerfile

Avant :

FROM docker.m.daocloud.io/python:3.10

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY ./app.py /app/app.py
EXPOSE 8000
CMD ["python", "app.py"]

Après (avec l'agent ARMS) :

FROM docker.m.daocloud.io/python:3.10

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Install the ARMS Python agent
RUN pip3 install aliyun-bootstrap \
    && ARMS_REGION_ID=<region-id> aliyun-bootstrap -a install

COPY ./app.py /app/app.py
EXPOSE 8000

# Start the application with the ARMS agent
CMD ["aliyun-instrument", "python", "app.py"]

Remplacez <region-id> par l'ID de votre région Alibaba Cloud, tel que cn-hangzhou.

Étape 3 : Accorder les autorisations

La configuration des autorisations varie selon le type de cluster.

Clusters ACK managés

Les clusters ACK managés disposant d'un jeton ARMS Addon ne nécessitent aucune configuration d'autorisation supplémentaire.

Vérifier la présence du jeton ARMS Addon :

  1. Connectez-vous à la console ACK. Dans le volet de navigation de gauche, cliquez sur Clusters. Cliquez sur le nom de votre cluster.

  2. Dans le volet de navigation de gauche, accédez à Configurations > Secrets. Sélectionnez kube-system dans la liste déroulante Namespace.

  3. Vérifiez si addon.arms.token apparaît sur la page Secrets.

Remarque

Le jeton ARMS Addon permet une autorisation sans mot de passe. Certains clusters ACK managés peuvent ne pas disposer de ce jeton. Vérifiez sa présence avant de poursuivre.

Ajouter manuellement les politiques d'autorisation :

  1. Connectez-vous à la console ACK. Dans le volet de navigation de gauche, cliquez sur Clusters. Cliquez sur le nom de votre cluster.

  2. Sur l'onglet Basic Information de la page Cluster Information, cliquez sur le lien situé à côté de Worker RAM Role dans la section Cluster Resources.

  3. Sur la page qui s'affiche, cliquez sur Grant Permission dans l'onglet Permissions.

  4. Dans le panneau Grant Permission, ajoutez les politiques suivantes et cliquez sur Grant permissions :

    • AliyunTracingAnalysisFullAccess : Accès complet à Managed Service for OpenTelemetry.

    • AliyunARMSFullAccess : Accès complet à ARMS.

Clusters ACK dédiés et clusters enregistrés

Assurez-vous que les autorisations AliyunARMSFullAccess et AliyunSTSAssumeRoleAccess sont accordées à votre utilisateur Resource Access Management (RAM).

Une fois ack-onepilot installé, configurez votre AccessKey ID et votre AccessKey Secret en utilisant l'une de ces méthodes.

Méthode 1 : Mettre à jour la configuration Helm

  1. Connectez-vous à la console ACK. Dans le volet de navigation de gauche, cliquez sur Clusters.

  2. Cliquez sur le nom de votre cluster. Dans le volet de navigation de gauche, accédez à Applications > Helm. Cliquez sur Update à côté de ack-onepilot.

  3. Remplacez les valeurs accessKey et accessKeySecret par votre AccessKey ID et AccessKey Secret, puis cliquez sur OK.

    Remarque

    L'AccessKey Secret n'est visible que lors de la création initiale de la paire de clés. Conservez-le en toute sécurité ; il ne peut pas être récupéré ultérieurement.

    image

  4. Redémarrez le Deployment.

Méthode 2 : Utiliser les Secrets Kubernetes

  1. Connectez-vous à la console ACK. Dans le volet de navigation de gauche, cliquez sur Clusters.

  2. Cliquez sur le nom de votre cluster. Dans le volet de navigation de gauche, accédez à Configurations > Secrets.

  3. Cliquez sur Create. Dans le panneau, cliquez sur Add et saisissez votre AccessKey ID et AccessKey Secret.

    Remarque

    L'AccessKey Secret n'est visible que lors de la création initiale de la paire de clés. Conservez-le en toute sécurité ; il ne peut pas être récupéré ultérieurement.

    image

  4. Dans le volet de navigation de gauche, accédez à Workloads > Deployments. Cliquez sur le composant ack-onepilot (généralement nommé ack-onepilot-ack-onepilot dans le namespace ack-onepilot).

  5. Dans le coin supérieur droit, cliquez sur Edit.

  6. Faites défiler jusqu'à la section Environments. Cliquez sur Add, puis ajoutez les variables d'environnement suivantes qui font référence aux Secrets que vous avez créés. Cliquez sur OK.

    • ONE_PILOT_ACCESSKEY

    • ONE_PILOT_ACCESSKEY_SECRET

    image

Clusters ACK Serverless (ASK) et Elastic Container Instance (ECI)

  1. Autorisez le cluster à accéder à ARMS sur la page Cloud Resource Access Authorization.

  2. Redémarrez tous les pods sur lesquels ack-onepilot est déployé.

Étape 4 : Activer la surveillance ARMS

Ajoutez des libellés ARMS à votre déploiement Kubernetes pour activer la surveillance.

Important

Avec ack-onepilot version supérieure à 5.0.0, le composant télécharge et injecte automatiquement le package de l'agent Python lors de cette étape ; aucune modification du Dockerfile n'est nécessaire. Un conteneur d'initialisation gère l'injection de l'agent avec les paramètres par défaut suivants :

  • Ressources : 0,5 cœur CPU, 250 Mo de mémoire (libérées après l'initialisation)

  • Temps d'exécution : environ 10 secondes. Pour ajuster les ressources du conteneur d'initialisation, définissez ces variables d'environnement :

    Variable d'environnement

    Description

    Exemple

    PYTHON_INIT_RESOURCE_REQUESTS_CPU

    Demande CPU

    500m

    PYTHON_INIT_RESOURCE_REQUESTS_MEM

    Demande de mémoire

    250Mi

    PYTHON_INIT_RESOURCE_LIMIT_CPU

    Limite CPU

    1000m

    PYTHON_INIT_RESOURCE_LIMIT_MEM

    Limite de mémoire

    500Mi

    Cette fonctionnalité d'injection automatique est en version bêta. Contactez-nous via le groupe DingTalk (ID : 159215000379) si vous avez des questions.

Ajouter des libellés à votre déploiement

  1. Connectez-vous à la console ACK. Dans le volet de navigation de gauche, cliquez sur Clusters.

  2. Cliquez sur le nom de votre cluster. Dans le volet de navigation de gauche, accédez à Workloads > Deployments.

  3. Recherchez votre application, puis choisissez image > Edit YAML dans la colonne Actions. Vous pouvez également cliquer sur Create From YAML pour créer une nouvelle application.

  4. Ajoutez les libellés suivants sous spec.template.metadata : Remplacez <app-name> par un nom descriptif pour votre application, tel que my-python-service.

    Important

    Si vous utilisez ack-onepilot version supérieure à 5.0.0 mais que vous avez déjà installé l'agent manuellement dans votre Dockerfile, désactivez l'injection automatique en ajoutant ce libellé : ``yaml armsAutoInstrumentationEnable: "off" ``

       labels:
         aliyun.com/app-language: python       # Required. Identifies this as a Python application.
         armsPilotAutoEnable: 'on'             # Enables ARMS monitoring.
         armsPilotCreateAppName: "<app-name>"  # Display name in the ARMS console.

    YAML labels configuration

  5. Cliquez sur Update.

Exemple YAML complet

Le YAML suivant déploie deux exemples d'applications Python avec la surveillance ARMS :

Afficher l'exemple YAML complet (cliquez pour développer)

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. Identifies this as a Python application.
        armsPilotAutoEnable: 'on'
        armsPilotCreateAppName: "arms-python-client"    # Display name 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. Identifies this as a Python application.
        armsPilotAutoEnable: 'on'
        armsPilotCreateAppName: "arms-python-server"    # Display name 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
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

Vérifier l'installation

Confirmez que l'agent transmet les données.

  1. Ouvrez la console ARMS.

  2. Dans le volet de navigation de gauche, accédez à Application Monitoring > Applications.

  3. Confirmez que votre application Python apparaît dans la liste et transmet des données. Cela prend généralement environ une minute.

    Application monitoring result

Résoudre les problèmes courants

Si votre application n'apparaît pas dans la console ARMS après quelques minutes :

  • Vérifiez que les libellés sont appliqués au pod (et non au déploiement) : Confirmez la présence de aliyun.com/app-language, armsPilotAutoEnable et armsPilotCreateAppName.

      kubectl get pod <pod-name> -n <namespace> -o jsonpath='{.metadata.labels}'
  • Vérifiez l'état du conteneur d'initialisation (ack-onepilot version supérieure à 5.0.0) : Recherchez le conteneur d'initialisation dans la sortie. Vérifiez qu'il s'est terminé avec succès.

      kubectl describe pod <pod-name> -n <namespace>
  • Vérifiez qu'ack-onepilot est en cours d'exécution : Tous les pods ack-onepilot doivent avoir le statut Running.

      kubectl get pods -n ack-onepilot
  • Vérifiez les autorisations : Assurez-vous que les stratégies RAM requises sont attachées. Consultez l'étape Étape 3 : Accorder les autorisations.

Notes de version

Par défaut, la dernière version de l'agent Python est installée à chaque utilisation de aliyun-bootstrap ou de la méthode d'injection automatique. Pour fixer une version spécifique, consultez la section Comment installer un agent pour une région et une version spécifiques ? dans la rubrique FAQ sur l'agent Python.