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 |
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
-
Un cluster ACK ou ACS est créé.
Clusters ACK : Créer un cluster ACK managé, Créer un cluster ACK dédié (la création n'est plus disponible) ou Créer un cluster ACK Serverless
Clusters ACS : Créer un cluster ACS
Un namespace est créé. Consultez la rubrique Gérer les namespaces et les quotas. Les exemples de ce guide utilisent le namespace
arms-demo.Votre version de Python et vos frameworks sont pris en charge. Consultez la rubrique Bibliothèques Python prises en charge par la surveillance des applications.
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
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.
Connectez-vous à la console ACK. Sur la page Clusters, cliquez sur le nom de votre cluster.
-
Dans le volet de navigation de gauche, cliquez sur Add-ons. Recherchez ack-onepilot dans le coin supérieur droit.
ImportantAssurez-vous que la version d'ack-onepilot est 3.2.4 ou ultérieure.
-
Cliquez sur Install sur la carte ack-onepilot.
RemarquePar 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.
-
Dans la boîte de dialogue, configurez les paramètres et cliquez sur OK. Les valeurs par défaut sont recommandées.
RemarqueAprès l'installation, vous pouvez mettre à jour, configurer ou désinstaller ack-onepilot depuis la page Add-ons.
-
Choisissez l'étape suivante en fonction de la version d'ack-onepilot :
Version supérieure à 5.0.0 : Accédez à l'étape Étape 3 : Accorder les autorisations. Aucune modification du Dockerfile n'est nécessaire. Cette méthode offre une expérience d'installation entièrement non intrusive pour les applications Python.
Autres versions (3.2.4 ou ultérieure) : Passez à l'étape Étape 2 : Modifier le Dockerfile.
Étape 2 : Modifier le Dockerfile (ack-onepilot 5.0.0 ou antérieur)
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.
-
Installez le programme d'installation de l'agent depuis PyPI :
RUN pip3 install aliyun-bootstrap -
Installez l'agent. Remplacez
<region-id>par l'ID de votre région Alibaba Cloud (par exemple,cn-hangzhou) :RemarquePour 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 -
Mettez à jour la commande de démarrage pour utiliser le préfixe
aliyun-instrument:CMD ["aliyun-instrument", "python", "app.py"] Construisez l'image.
Exemple complet de Dockerfile
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.
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
Connectez-vous à la console ACK. Dans le volet de navigation de gauche, cliquez sur Clusters.
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.
-
Remplacez les valeurs
accessKeyetaccessKeySecretpar votre AccessKey ID et AccessKey Secret, puis cliquez sur OK.RemarqueL'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.

Redémarrez le Deployment.
Méthode 2 : Utiliser les Secrets Kubernetes
Connectez-vous à la console ACK. Dans le volet de navigation de gauche, cliquez sur Clusters.
Cliquez sur le nom de votre cluster. Dans le volet de navigation de gauche, accédez à Configurations > Secrets.
-
Cliquez sur Create. Dans le panneau, cliquez sur Add et saisissez votre AccessKey ID et AccessKey Secret.
RemarqueL'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.

Dans le volet de navigation de gauche, accédez à Workloads > Deployments. Cliquez sur le composant ack-onepilot (généralement nommé
ack-onepilot-ack-onepilotdans le namespaceack-onepilot).Dans le coin supérieur droit, cliquez sur Edit.
-
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_ACCESSKEYONE_PILOT_ACCESSKEY_SECRET

Clusters ACK Serverless (ASK) et Elastic Container Instance (ECI)
Autorisez le cluster à accéder à ARMS sur la page Cloud Resource Access Authorization.
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.
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_CPUDemande CPU
500mPYTHON_INIT_RESOURCE_REQUESTS_MEMDemande de mémoire
250MiPYTHON_INIT_RESOURCE_LIMIT_CPULimite CPU
1000mPYTHON_INIT_RESOURCE_LIMIT_MEMLimite de mémoire
500MiCette 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
Connectez-vous à la console ACK. Dans le volet de navigation de gauche, cliquez sur Clusters.
Cliquez sur le nom de votre cluster. Dans le volet de navigation de gauche, accédez à Workloads > Deployments.
Recherchez votre application, puis choisissez
> Edit YAML dans la colonne Actions. Vous pouvez également cliquer sur Create From YAML pour créer une nouvelle application.-
Ajoutez les libellés suivants sous
spec.template.metadata: Remplacez<app-name>par un nom descriptif pour votre application, tel quemy-python-service.ImportantSi 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.
Cliquez sur Update.
Exemple YAML complet
Le YAML suivant déploie deux exemples d'applications Python avec la surveillance ARMS :
Vérifier l'installation
Confirmez que l'agent transmet les données.
Ouvrez la console ARMS.
Dans le volet de navigation de gauche, accédez à Application Monitoring > Applications.
-
Confirmez que votre application Python apparaît dans la liste et transmet des données. Cela prend généralement environ une minute.

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,armsPilotAutoEnableetarmsPilotCreateAppName.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.