Todos os produtos
Search

Este produto

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

    Central de documentação

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

    Última atualização: Sep 02, 2026

    O Application Real-Time Monitoring Service (ARMS) instrumenta automaticamente aplicações Java executadas no Container Service for Kubernetes (ACK) e no Container Compute Service (ACS). Instale o componente ack-onepilot em seu cluster e adicione três rótulos ao seu Deployment. O ARMS coleta traces, topologia da aplicação, métricas de chamadas de API e dados de erro e latência sem exigir alterações no código.

    Nota

    As etapas de instalação para ACK e ACS são idênticas. Este guia utiliza o ACK como exemplo.

    Como funciona

    O componente ack-onepilot (Assistente de Integração do Agente ARMS) executa como um controller no seu cluster. Quando um pod rotulado é iniciado, o ack-onepilot injeta o agente Java do ARMS no pod automaticamente. Ao lançar uma nova versão do agente, o ack-onepilot atualiza o agente na próxima reinicialização da aplicação. Para fixar uma versão específica, consulte Control agent versions manually.

    Para detalhes sobre o mecanismo de injeção, consulte How ack-onepilot works.

    Importante

    O componente legado arms-pilot não recebe mais manutenção. O ack-onepilot é seu substituto e oferece compatibilidade total — a migração não exige alterações na configuração da sua aplicação. Para etapas de migração, consulte Uninstall arms-pilot and install ack-onepilot.

    Visão geral do processo

    A configuração do monitoramento do ARMS envolve três etapas:

    1. Instale o ack-onepilot — Implante o componente de monitoramento pelo console do ACK.

    2. Grant ARMS permissions — Configure a autenticação do cluster para o ARMS (varia conforme o tipo de cluster).

    3. Rotule seu Deployment — Adicione três rótulos ao modelo de pod para ativar a instrumentação automática.

    Pré-requisitos

    Antes de começar, verifique se você possui:

    Etapa 1: Instale o ack-onepilot

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

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

    3. No cartão ack-onepilot, clique em Install.

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

    Nota

    O ack-onepilot suporta até 1.000 pods por padrão. Para cada 1.000 pods adicionais, aloque 0,5 núcleos de CPU e 512 MB de memória ao componente.

    Após a instalação, atualize, configure ou desinstale o ack-onepilot na página Add-ons.

    Etapa 2: Conceda permissões ao ARMS

    As permissões necessárias dependem do tipo de cluster. Identifique o tipo do seu cluster e siga as instruções correspondentes.

    Clusters gerenciados ACK

    Clusters gerenciados ACK com um ARMS Addon Token são autorizados automaticamente. Verifique se o token existe antes de prosseguir.

    Verificar o ARMS Addon Token:

    1. Faça login no console do ACK. Clique em Clusters e, em seguida, clique em nome do cluster.

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

    3. Procure o secret chamado addon.arms.token na página Secrets.

    • Se addon.arms.token existir — o cluster já está autorizado. Pule para Step 3.

    • Se addon.arms.token não existir — adicione manualmente as políticas de permissão necessárias (veja abaixo).

    Nota

    Se um cluster possuir o ARMS Addon Token, o ARMS realiza autorização sem senha no cluster. O ARMS Addon Token pode não existir em alguns clusters gerenciados ACK. Recomendamos verificar se um cluster gerenciado ACK possui o ARMS Addon Token antes de usar o ARMS para monitorar aplicações nesse cluster.

    Adicionar políticas de permissão manualmente:

    1. Na página 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 estas duas políticas e clique em Grant permissions:

      Política

      Escopo de acesso

      AliyunTracingAnalysisFullAccess

      Acesso total ao Managed Service for OpenTelemetry

      AliyunARMSFullAccess

      Acesso total ao ARMS

    Clusters dedicados ACK e clusters registrados

    Clusters dedicados ACK e clusters registrados ACK One exigem dois requisitos:

    • Sua conta Alibaba Cloud deve ter as permissões AliyunARMSFullAccess e AliyunSTSAssumeRoleAccess. Consulte Manage permissions for RAM users.

    • O componente ack-onepilot deve ter um par de AccessKey com permissões do ARMS.

    Forneça o par de AccessKey ao ack-onepilot usando um destes métodos.

    Método 1: Especifique o par de AccessKey no Helm

    1. Faça login no console do ACK. Clique em Clusters e, em seguida, clique em nome do cluster.

    2. No painel de navegação à esquerda, escolha 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. Clique em OK.

      Nota

      Para obter um par de AccessKey, consulte Create an AccessKey pair.

      admissionRegistration:
  failurePolicy: Ignore
  onlyLabel: false
configuration:
  downloadTimeout: "90"
controller:
  accessKey: __ACCESSKEY__
  accessKeySecret: __ACCESSKEY_SECRET__
  accessSource: ACSKS
  cluster_id: c0c3c907a2e30
  clusterProfile: __ACK_CLUSTER_PROFILE__
  clusterType: __ACK_CLUSTER_TYPE__
  imagePullPolicy: Always
  is_finance: <no value>
  logLevel: 1

    4. Reinicie o Deployment da aplicação.

    Método 2: Use um Secret do Kubernetes

    1. Faça login no console do ACK. Clique em Clusters e, em seguida, clique em nome do cluster.

    2. No painel de navegação à esquerda, escolha Configurations > Secrets. Selecione o namespace ack-onepilot e crie um Secret para armazenar seu AccessKey ID e AccessKey secret.

      Nota

      Para obter um par de AccessKey, consulte Create an AccessKey pair.

      Ao criar o Secret, defina Name como ack-onepilot-aksk, selecione Opaque para Type e adicione duas linhas à tabela de dados: a chave ak corresponde ao seu AccessKey ID, e a chave sk corresponde ao seu AccessKey secret.

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

    4. No canto superior direito, clique em Edit. Na seção Environment Variables, adicione estas duas variáveis e referencie os valores do Secret: Clique em OK.

      Variável de ambiente

      Descrição

      ONE_PILOT_ACCESSKEY

      Referencia o AccessKey ID armazenado no Secret

      ONE_PILOT_ACCESSKEY_SECRET

      Referencia o AccessKey secret armazenado no Secret

    Clusters serverless ACK (ASK) e clusters integrados com ECI

    Conclua a autorização na página Autorização de Acesso a Recursos e reinicie todos os pods do componente ack-onepilot.

    Etapa 3: Rotule seu Deployment

    Adicione três rótulos à seção spec.template.metadata.labels do YAML do seu Deployment para ativar o monitoramento do ARMS:

    labels:
  armsPilotAutoEnable: "on"
  armsPilotCreateAppName: "<your-deployment-name>"    # Replace <your-deployment-name> with your application name.
  aliyun.com/app-language: java

    Rótulo

    Valor

    Descrição

    armsPilotAutoEnable

    "on"

    Ativa a injeção automática do agente para o pod

    armsPilotCreateAppName

    "<your-deployment-name>"

    Nome da aplicação exibido no console do ARMS. Substitua pelo nome da sua aplicação.

    aliyun.com/app-language

    java

    Especifica a linguagem da aplicação para o agente
    Nota

    Os rótulos devem estar em spec.template.metadata.labels (modelo de pod), não em metadata.labels (metadados do Deployment). Colocar rótulos no local errado é uma causa comum para o não aparecimento de dados de monitoramento.

    Aplique os rótulos a um Deployment existente

    1. Faça login no console do ACK. Clique em Clusters e, em seguida, clique em nome do cluster.

    2. No painel de navegação à esquerda, escolha Workloads > Deployments.

    3. Na página Stateless, clique em more icon > YAML Edit ao lado da aplicação alvo.

    4. Adicione os três rótulos em spec.template.metadata.labels e clique em Update.

    Nota

    Para mais informações sobre segurança de aplicações, consulte What is application security?.

    Para mais informações sobre faturamento de segurança de aplicações, consulte Billing overview.

    apiVersion: v1
kind: Namespace
metadata:
  name: arms-demo
---
apiVersion: apps/v1 # for versions before 1.8.0 use apps/v1beta1
kind: Deployment
metadata:
  name: arms-springboot-demo
  namespace: arms-demo
  labels:
    app: arms-springboot-demo
spec:
  replicas: 2
  selector:
    matchLabels:
      app: arms-springboot-demo
  template:
    metadata:
      labels:
        app: arms-springboot-demo
        armsPilotAutoEnable: "on"
        armsPilotCreateAppName: "arms-k8s-demo"
    spec:
      containers:
        - resources:

    Crie um novo Deployment com monitoramento ativado

    Na página Stateless, clique em Create from YAML e inclua os rótulos na definição do seu Deployment.

    Expandir para visualizar o exemplo completo de YAML (Java)

    apiVersion: v1
kind: Namespace
metadata:
  name: arms-demo
---
apiVersion: apps/v1 # for versions before 1.8.0 use apps/v1beta1
kind: Deployment
metadata:
  name: arms-springboot-demo
  namespace: arms-demo
  labels:
    app: arms-springboot-demo
spec:
  replicas: 2
  selector:
    matchLabels:
      app: arms-springboot-demo
  template:
    metadata:
      labels:
        app: arms-springboot-demo
        armsPilotAutoEnable: "on"
        armsPilotCreateAppName: "arms-k8s-demo"
    spec:
      containers:
        - resources:
            limits:
              cpu: 0.5
          image: registry.cn-hangzhou.aliyuncs.com/arms-docker-repo/arms-springboot-demo:v0.1
          imagePullPolicy: Always
          name: arms-springboot-demo
          env:
            - name: SELF_INVOKE_SWITCH
              value: "true"
            - name: COMPONENT_HOST
              value: "arms-demo-component"
            - name: COMPONENT_PORT
              value: "6666"
            - name: MYSQL_SERVICE_HOST
              value: "arms-demo-mysql"
            - name: MYSQL_SERVICE_PORT
              value: "3306"
---
apiVersion: apps/v1 # for versions before 1.8.0 use apps/v1beta1
kind: Deployment
metadata:
  name: arms-springboot-demo-subcomponent
  namespace: arms-demo
  labels:
    app: arms-springboot-demo-subcomponent
spec:
  replicas: 2
  selector:
    matchLabels:
      app: arms-springboot-demo-subcomponent
  template:
    metadata:
      labels:
        app: arms-springboot-demo-subcomponent
        armsPilotAutoEnable: "on"
        armsPilotCreateAppName: "arms-k8s-demo-subcomponent"
    spec:
      containers:
        - resources:
            limits:
              cpu: 0.5
          image: registry.cn-hangzhou.aliyuncs.com/arms-docker-repo/arms-springboot-demo:v0.1
          imagePullPolicy: Always
          name: arms-springboot-demo-subcomponent
          env:
            - name: SELF_INVOKE_SWITCH
              value: "false"
            - name: MYSQL_SERVICE_HOST
              value: "arms-demo-mysql"
            - name: MYSQL_SERVICE_PORT
              value: "3306"
---
apiVersion: v1
kind: Service
metadata:
  labels:
    name: arms-demo-component
  name: arms-demo-component
  namespace: arms-demo
spec:
  ports:
    - name: arms-demo-component-svc
      port: 6666
      targetPort: 8888
  selector:
    app: arms-springboot-demo-subcomponent
---
apiVersion: apps/v1 # for versions before 1.8.0 use apps/v1beta1
kind: Deployment
metadata:
  name: arms-demo-mysql
  namespace: arms-demo
  labels:
    app: mysql
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mysql
  template:
    metadata:
      labels:
        app: mysql
    spec:
      containers:
        - resources:
            limits:
              cpu: 0.5
          image: registry.cn-hangzhou.aliyuncs.com/arms-docker-repo/arms-demo-mysql:v0.1
          name: mysql
          ports:
            - containerPort: 3306
              name: mysql
---
apiVersion: v1
kind: Service
metadata:
  labels:
    name: mysql
  name: arms-demo-mysql
  namespace: arms-demo
spec:
  ports:
    - name: arms-mysql-svc
      port: 3306
      targetPort: 3306
  selector:
    app: mysql

    Verifique os dados de monitoramento

    Na página Stateless, clique em more icon > ARMS Console na coluna Actions da aplicação alvo para visualizar os detalhes de monitoramento da aplicação.

    Perguntas frequentes