Todos os produtos
Search
Central de documentação

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

Última atualização: Sep 09, 2026

Ao executar aplicações Python em clusters do Container Service for Kubernetes (ACK) ou do Container Compute Service (ACS), o Application Real-Time Monitoring Service (ARMS) oferece rastreamento distribuído, mapas de topologia de aplicação e análise de chamadas de API. Para coletar esses dados, instale o agente Python do ARMS usando o componente ack-onepilot.

Estão disponíveis dois métodos de instalação:

Método

Versão do ack-onepilot

Alterações no Dockerfile

Injeção automática (recomendado)

Posterior à 5.0.0

Não necessárias

Instalação manual

3.2.4 ou posterior

Necessárias

Nota

Para dúvidas sobre o agente Python, consulte FAQ about the Python agent. Você também pode entrar em contato conosco pelo grupo do DingTalk (ID: 159215000379).

Pré-requisitos

Compatibilidade de frameworks Python

Verifique estes requisitos específicos de framework antes de prosseguir.

uvicorn

Se sua aplicação iniciar com uvicorn, escolha uma das seguintes abordagens:

Abordagem A: Importar o agente no código. Adicione esta instrução de importação na primeira linha do arquivo de entrada do uvicorn:

from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize

**Abordagem B: Alternar para gunicorn com o prefixo aliyun-instrument.** Substitua o comando 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
Nota

O prefixo aliyun-instrument gerencia a inicialização e a instrumentação não intrusiva do agente Python do ARMS.

uWSGI

Se sua aplicação iniciar com uWSGI, consulte Install the Python agent for a Django or Flask project that starts with uWSGI.

gevent

Ao usar corrotinas gevent, defina a variável de ambiente GEVENT_ENABLE como true.

Por exemplo, se o código contiver:

from gevent import monkey
monkey.patch_all()

Defina a seguinte variável de ambiente na implantação:

GEVENT_ENABLE=true

Etapa 1: Instalar o ack-onepilot

O ack-onepilot é o componente do lado do cluster que gerencia a instalação do agente ARMS.

  1. Faça login no console ACK. Na página Clusters, clique em nome do cluster.

  2. No painel de navegação à esquerda, clique em Add-ons. Pesquise ack-onepilot no canto superior direito.

    Importante

    Certifique-se de que a versão do ack-onepilot seja 3.2.4 ou posterior.

  3. Clique em Install no cartão do ack-onepilot.

    Nota

    Por padrão, o ack-onepilot suporta 1.000 pods. Para cada 1.000 pods adicionais, adicione 0,5 núcleo de CPU e 512 MB de memória ao componente.

  4. Na caixa de diálogo, configure os parâmetros e clique em OK. Recomendamos usar os valores padrão.

    Nota

    Após a instalação, você pode atualizar, configurar ou desinstalar o ack-onepilot na página Add-ons.

  5. Escolha a próxima etapa conforme a versão do ack-onepilot:

    • Versão posterior à 5.0.0: Acesse Step 3: Grant permissions. Nenhuma alteração no Dockerfile é necessária. Isso proporciona uma experiência de instalação totalmente não intrusiva para aplicações Python.

    • Outras versões (3.2.4 ou posterior): Continue para Step 2: Modify the Dockerfile.

Etapa 2: Modificar o Dockerfile (ack-onepilot 5.0.0 ou anterior)

Nota

Ignore esta etapa se a versão do ack-onepilot for posterior à 5.0.0.

Adicione o agente Python do ARMS ao Dockerfile e atualize o comando de inicialização.

  1. Instale o instalador do agente via PyPI:

       RUN pip3 install aliyun-bootstrap
  2. Instale o agente. Substitua <region-id> pelo ID da região Alibaba Cloud (por exemplo, cn-hangzhou):

    Nota

    Para instalar uma versão específica do agente, execute: aliyun-bootstrap -a install -v <version> Para todas as versões lançadas, consulte Python agent release notes.

       RUN ARMS_REGION_ID=<region-id> aliyun-bootstrap -a install
  3. Atualize o comando de inicialização para usar o prefixo aliyun-instrument:

       CMD ["aliyun-instrument", "python", "app.py"]
  4. Compile a imagem.

Exemplo completo de Dockerfile

Antes:

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

Depois (com agente 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"]

Substitua <region-id> pelo ID da região Alibaba Cloud, como cn-hangzhou.

Etapa 3: Conceder permissões

A configuração de permissões varia conforme o tipo de cluster.

Clusters gerenciados ACK

Clusters gerenciados ACK com um ARMS Addon Token não exigem configuração adicional de permissões.

Verificar o ARMS Addon Token:

  1. Faça login no console ACK. No painel de navegação à esquerda, clique em Clusters. Clique em nome do cluster.

  2. No painel de navegação à esquerda, selecione Configurations > Secrets. Selecione kube-system na lista suspensa Namespace.

  3. Verifique se addon.arms.token aparece na página Secrets.

Nota

O ARMS Addon Token permite autorização sem senha. Alguns clusters gerenciados ACK podem não ter esse token. Verifique antes de prosseguir.

Adicionar políticas de permissão manualmente:

  1. Faça login no console ACK. No painel de navegação à esquerda, clique em Clusters. Clique em nome do cluster.

  2. Na aba Basic Information da página Cluster Information, clique em link ao lado de Worker RAM Role na seção Cluster Resources.

  3. Na página exibida, clique em Grant Permission na aba Permissions.

  4. No painel Grant Permission, adicione as seguintes políticas e clique em Grant permissions:

    • AliyunTracingAnalysisFullAccess: Acesso total ao Managed Service for OpenTelemetry.

    • AliyunARMSFullAccess: Acesso total ao ARMS.

Clusters dedicados ACK e clusters registrados

Certifique-se de que as permissões AliyunARMSFullAccess e AliyunSTSAssumeRoleAccess estejam concedidas ao seu usuário do Resource Access Management (RAM).

Após instalar o ack-onepilot, configure o AccessKey ID e o AccessKey Secret usando um destes métodos.

Método 1: Atualizar a configuração do Helm

  1. Faça login no console ACK. No painel de navegação à esquerda, clique em Clusters.

  2. Clique em nome do cluster. No painel de navegação à esquerda, selecione Applications > Helm. Clique em Update ao lado de ack-onepilot.

  3. Substitua os valores de accessKey e accessKeySecret pelo seu AccessKey ID e AccessKey Secret e clique em OK.

    Nota

    O AccessKey Secret só fica visível quando você cria o par de AccessKey pela primeira vez. Armazene-o com segurança — ele não pode ser recuperado posteriormente.

    image

  4. Reinicie o Deployment.

Método 2: Usar Kubernetes Secrets

  1. Faça login no console ACK. No painel de navegação à esquerda, clique em Clusters.

  2. Clique em nome do cluster. No painel de navegação à esquerda, selecione Configurations > Secrets.

  3. Clique em Create. No painel, clique em Add e insira seu AccessKey ID e AccessKey Secret.

    Nota

    O AccessKey Secret só fica visível quando você cria o par de AccessKey pela primeira vez. Armazene-o com segurança — ele não pode ser recuperado posteriormente.

    image

  4. No painel de navegação à esquerda, selecione Workloads > Deployments. Clique em componente ack-onepilot (geralmente chamado ack-onepilot-ack-onepilot no namespace ack-onepilot).

  5. No canto superior direito, clique em Edit.

  6. Role até a seção Environments. Clique em Add e adicione as seguintes variáveis de ambiente que referenciam os Secrets criados. Em seguida, clique em OK.

    • ONE_PILOT_ACCESSKEY

    • ONE_PILOT_ACCESSKEY_SECRET

    image

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

  1. Autorize o cluster a acessar o ARMS na página Cloud Resource Access Authorization.

  2. Reinicie todos os pods onde o ack-onepilot está implantado.

Etapa 4: Ativar o monitoramento do ARMS

Adicione rótulos do ARMS à sua implantação Kubernetes para ativar o monitoramento.

Importante

Com o ack-onepilot posterior à versão 5.0.0, o componente baixa e injeta automaticamente o pacote do agente Python durante esta etapa — nenhuma alteração no Dockerfile é necessária. Um init container cuida da injeção do agente com estes padrões:

  • Recursos: 0,5 núcleo de CPU, 250 MB de memória (liberados após a inicialização)

  • Tempo de execução: aproximadamente 10 segundos. Para ajustar os recursos do init container, defina estas variáveis de ambiente: | Variável de ambiente | Descrição | Exemplo | |---|---|---| | PYTHON_INIT_RESOURCE_REQUESTS_CPU | Solicitação de CPU | 500m | | PYTHON_INIT_RESOURCE_REQUESTS_MEM | Solicitação de memória | 250Mi | | PYTHON_INIT_RESOURCE_LIMIT_CPU | Limite de CPU | 1000m | | PYTHON_INIT_RESOURCE_LIMIT_MEM | Limite de memória | 500Mi | Este recurso de injeção automática está em beta. Entre em contato conosco pelo grupo do DingTalk (ID: 159215000379) se tiver dúvidas.

Adicionar rótulos à implantação

  1. Faça login no console ACK. No painel de navegação à esquerda, clique em Clusters.

  2. Clique em nome do cluster. No painel de navegação à esquerda, selecione Workloads > Deployments.

  3. Localize a aplicação e selecione image > Edit YAML na coluna Actions. Alternativamente, clique em Create From YAML para criar uma nova aplicação.

  4. Adicione os seguintes rótulos em spec.template.metadata: Substitua <app-name> por um nome descritivo para a aplicação, como my-python-service.

    Importante

    Se você usar o ack-onepilot posterior à versão 5.0.0, mas já tiver instalado o agente manualmente no Dockerfile, desative a injeção automática adicionando este rótulo: ``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. Clique em Update.

Exemplo completo de YAML

O YAML a seguir implanta duas aplicações Python de exemplo com monitoramento ARMS:

Visualize o YAML de exemplo completo (clique em para expandir)

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

Verificar a instalação

Confirme se o agente está relatando dados.

  1. Acesse o console ARMS.

  2. No painel de navegação à esquerda, selecione Application Monitoring > Applications.

  3. Confirme se a aplicação Python aparece na lista e está relatando dados. Isso geralmente leva cerca de um minuto.

    Application monitoring result

Solucionar problemas comuns

Se a aplicação não aparecer no console ARMS após alguns minutos:

  • Verifique se os rótulos foram aplicados ao pod (não ao deployment): Confirme se aliyun.com/app-language, armsPilotAutoEnable e armsPilotCreateAppName estão presentes.

      kubectl get pod <pod-name> -n <namespace> -o jsonpath='{.metadata.labels}'
  • Verifique o status do init container (ack-onepilot posterior à 5.0.0): Procure o init container na saída e verifique se ele foi concluído com sucesso.

      kubectl describe pod <pod-name> -n <namespace>
  • Verifique se o ack-onepilot está em execução: Todos os pods do ack-onepilot devem estar com status Running.

      kubectl get pods -n ack-onepilot
  • Verifique as permissões: Certifique-se de que as políticas RAM necessárias estejam anexadas. Consulte Step 3: Grant permissions.

Notas sobre versões

Por padrão, a versão mais recente do agente Python é instalada sempre que você usa aliyun-bootstrap ou o método de injeção automática. Para fixar uma versão específica, consulte a seção Como instalo um agente para uma região e versão específicas? em FAQ about the Python agent.