Configurar e instalar o Agent Control

Visão geral

O Agent Control simplifica o gerenciamento dos seus agentes de instrumentação. Este guia orientará você no processo de instalação e desinstalação do Agent Control em seus clusters Kubernetes, hosts Linux ou hosts Windows usando diferentes métodos.

Instalar o Agent Control

Instalação guiada

1. Faça login na New Relic.
2. Certifique-se de que a conta correta esteja selecionada.
3. Em integração & agente, clique em Install Agent Control ou procure por Agent Control.

4. Siga as etapas para concluir o processo de instalação e configuração.

5. Baixe a configuração gerada para o seu computador e execute o comando fornecido no seu terminal para instalar o Agent Control. Após a instalação, clique em Continue.
6. Teste a conexão para confirmar se a instalação foi bem-sucedida. Esta etapa pode levar de 5 a 10 minutos para ser concluída.
7. Agora que o Agent Control está instalado e em execução, você está pronto para configurar e gerenciar seus agentes ou implantar alterações em seus agentes usando o Controle de Agentes.

O que esperar após a instalação

Após executar o script de instalação, o Agent Control configura apenas o serviço supervisor. Nenhum agente de instrumentação é implantado automaticamente.

Imediato (0-2 minutos):

• 0-30 segundos: O serviço Agent Control se registra e inicia
• 30-60 segundos: Primeira conexão com o Fleet Control estabelecida
• 1–2 minutos: a sincronização da configuração é concluída e o host/cluster aparece no Controle de Agentes

Próximos passos necessários: Depois que o Agent Control estiver instalado e conectado ao Fleet Control, você deve implantar agentes manualmente para começar a coletar telemetria:

1. Faça login no New Relic e navegue até Fleet Control
2. Selecione sua frota e localize seu host/cluster na tabela Entities
3. Implante agentes (agente de infraestrutura, NRDOT, etc.) no seu host/cluster usando o Controle de Agentes
4. Aguarde de 5 a 10 minutos para que os agentes implantados iniciem e enviem telemetria para a New Relic

Nota sobre autenticação

O New Relic Control requer o uso de identidades de sistema, que são identidades não humanas usadas para autenticar e estabelecer confiança entre serviços e aplicações.

Durante o processo de instalação guiada do Agent Control, a primeira identidade do sistema é criada usando as credenciais do cliente, que estão incluídas nos valores do Helm chart ou no comando do host. As credenciais para esta identidade do sistema expiram após 12 horas. Quando elas expirarem, a implantação do Helm chart do Agent Control ou o comando do host falhará ao se autenticar no serviço Controle de Agentes, resultando no seguinte erro:

Error getting system identity auth token. The API endpoint returned 400: Expired client secret.

In this case, the Helm chart or host command must be updated with new system identity credentials.

Helm chart example:

global:
  cluster: "cluster-name"
  licenseKey: "*************************"
agentControlDeployment:
  chartValues:
    systemIdentity:
      organizationId: "00000000-0000-0000-0000-000000000000"
      parentIdentity:
        clientId: "CLIENT_ID"
        clientSecret: "CLIENT_SECRET"
    config:
      fleet_control:
        fleet_id: "SAMPLE_FLEET_ID"
      agents:
        ...

Configuração avançada do Kubernetes

Por padrão, o Helm chart do Agent Control utiliza uma instância embutida do Flux CD para gerenciar o ciclo de vida dos seus agentes no Kubernetes. Dependendo dos requisitos do seu ecossistema, você pode configurar o Controle do Agente para aproveitar uma instalação personalizada existente do Flux v2 ou ignorar totalmente os componentes de infraestrutura de entrega contínua.

Suporte a instalações existentes do Flux

Por padrão, o Helm chart do Agent Control utiliza uma instância embutida do Flux CD para gerenciar o ciclo de vida dos seus agentes no Kubernetes. No entanto, se sua organização já utiliza o Flux v2 para GitOps, você pode configurar o Agent Control para aproveitar sua instalação existente.

Essa abordagem desacopla o Agent Control do mecanismo de entrega contínua embutido, permitindo que você mantenha uma única instância do Flux para as operações do seu cluster, enquanto ainda se beneficia dos recursos de gerenciamento do Agent Control.

Requisitos e compatibilidade Para usar uma instalação externa do Flux com o Agent Control, seu ambiente deve atender aos seguintes requisitos. Configurações que divergem destas especificações não são validadas.

• Versão do Flux: Flux v2 ou superior.

• Componentes obrigatórios: Sua instalação do Flux deve incluir:

  • Controlador Helm: Com o CRD HelmRelease (helm.toolkit.fluxcd.io/v2).
  • Controlador de Origem: Com o CRD HelmRepository (source.toolkit.fluxcd.io/v1).

• Escopo do namespace: Sua instância do Flux deve ser configurada para monitorar o namespace onde o Agent Control será instalado (ou configurada para monitorar todos os namespaces).

Configuração Para habilitar este modo, você deve desabilitar explicitamente os componentes do Flux empacotados na configuração do Helm chart do Agent Control.

No seu arquivo values.yaml, defina agentControlCd.enabled como false:

global:
  cluster: "<YOUR_CLUSTER_NAME>"
  licenseKey: "<YOUR_LICENSE_KEY>"

# Disable the embedded Flux instance
agentControlCd:
  enabled: false

agentControlDeployment:
  chartValues:
    # ... other configurations ...

Permissões para Flux externo Ao usar sua própria instalação do Flux, a Service Account do Flux em seu cluster é responsável por aplicar as configurações geradas pelo Agent Control. Portanto, sua instância existente do Flux requer permissões específicas para implantar recursos da New Relic. Recomendamos fortemente uma das abordagens abaixo:

• Administrador do cluster (recomendado): A configuração mais simples é garantir que sua instância do Flux seja executada com privilégios de cluster-admin. Esta é a configuração padrão para o chart da comunidade Flux e garante que ele possa gerenciar todos os recursos necessários (Deployments, DaemonSets, Services, etc.) exigidos pelos agentes New Relic.
• Configuração de Privilégio Mínimo: Se suas políticas de segurança restringirem o uso de cluster-admin, você deve criar um ClusterRole específico garantindo que sua Conta de Serviço do Flux tenha as permissões exigidas pelo Source Controller, Helm Controller, Agent Control e por cada agente específico que você planeja instalar.

Abaixo está um exemplo ClusterRole demonstrando as permissões mínimas necessárias para que os componentes Agent Control e Flux interoperem:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: external-flux-agent-control-role
rules:
  # Permissions required by Flux to operate Agent Control components
  - apiGroups: ["apiextensions.k8s.io"]
    resources: ["customresourcedefinitions"]
    verbs: ["get"]
  - apiGroups: ["coordination.k8s.io"]
    resources: ["leases"]
    verbs: ["get", "create", "update"]
  - apiGroups: ["rbac.authorization.k8s.io"]
    resources: ["clusterroles", "rolebindings"]
    verbs: ["get", "create", "delete"]
  - apiGroups: [""]
    resources: ["configmaps"]
    verbs: ["watch"]
  - apiGroups: [""]
    resources: ["events"]
    verbs: ["create", "patch"]
  - apiGroups: [""]
    resources: ["namespaces"]
    verbs: ["create"]
  - apiGroups: [""]
    resources: ["serviceaccounts"]
    verbs: ["get", "create", "delete"]
  - apiGroups: [""]
    resources: ["services"]
    verbs: ["get", "create"]
  - apiGroups: ["apps"]
    resources: ["deployments"]
    verbs: ["create"]
  - apiGroups: ["autoscaling"]
    resources: ["horizontalpodautoscalers"]
    verbs: ["get", "create"]
  - apiGroups: ["batch"]
    resources: ["jobs"]
    verbs: ["get", "list", "watch", "create", "delete"]

  # Permissions required by Agent Control logic
  - apiGroups: ["helm.toolkit.fluxcd.io", "newrelic.com", "source.toolkit.fluxcd.io"]
    resources: ["*"]
    verbs: ["*"]
  - apiGroups: [""]
    resources: ["secrets"]
    verbs: ["*"]
  - apiGroups: [""]
    resources: ["configmaps"]
    verbs: ["get", "list", "create", "patch", "update", "delete", "deletecollection"]
  - apiGroups: [""]
    resources: ["namespaces"]
    verbs: ["get"]
  - apiGroups: ["apps"]
    resources: ["daemonsets", "deployments", "statefulsets"]
    verbs: ["get", "list", "watch"]

Limites de suporte Ao usar uma instalação externa do Flux, o suporte da New Relic limita-se ao software Agent Control (a geração de manifestos de configuração válidos). Neste modo, você deve considerar um esquema de responsabilidade compartilhada como o seguinte:

• Responsabilidade da New Relic: Garantimos que o Agent Control interaja corretamente com o backend da New Relic e gere definições válidas de HelmRelease e HelmRepository.
• Responsabilidade do cliente: Você é responsável pela saúde, manutenção de versão, rede e solução de problemas da sua própria instalação do Flux. Problemas decorrentes especificamente da configuração ou falha dos controladores Flux externos estão fora do escopo do suporte do Agent Control.

Instalar o Agent Control sem Flux

Você pode instalar o Agent Control sem o Flux quando sua função se limitar a entregar configuração a agentes gerenciados e não a instalá-los ou atualizá-los. Neste modo, o Agent Control não pode gerenciar o ciclo de vida do agente — ele não instala ou atualiza agentes e apenas envia configurações via Controle de Agentes. Você mesmo é responsável por instalar e atualizar o Agent Control e qualquer agente gerenciado. O principal caso de uso é o gateway do Controle de Pipeline: o Controle de agente entrega as alterações de configuração do gateway do Controle de Pipeline.

Para instalar o Controle do agente sem o Flux, defina agentControlCd.enabled como false em seus valores do Helm. O Controle do agente não criará nem monitorará nenhum objeto do Flux.

global:
  cluster: "<YOUR_CLUSTER_NAME>"
  licenseKey: "<YOUR_LICENSE_KEY>"

agentControlCd:
  enabled: false

agentControlDeployment:
  chartValues:
    # ... other configurations ...

Quando você instala o gateway do Controle de Pipeline pela instalação guiada do New Relic, o arquivo de valores gerado já define agentControlCd.enabled: false. Você não precisa editá-lo manualmente.

Verifique a instalação

Kubernetes

1. Execute os seguintes comandos para verificar o status dos seus pods: o Agent Control instala subagentes em um namespace diferente por motivos de segurança. Para verificar se tudo está funcionando, verifique se os pods do Agent Control estão em execução no namespace newrelic-agent-control e se os pods do subagente estão em execução em um namespace diferente, como newrelic.

$
kubectl get pods -n newrelic-agent-control    # Check Agent Control pods
$
  kubectl get pods -n newrelic                  # Check subagent pods

2. Entre no New Relic e vá em Controle de Agentes.
3. Acesse a página Frotas e selecione a frota que você escolheu durante a instalação.
4. Na tabela Entities , confirme se seu cluster do Kubernetes aparece na lista.
5. Verifique se o status da instrumentação do seu cluster está íntegro.

Linux

• Verifique o status do serviço newrelic-agent-control:

  bash

  Copiar

  $
  sudo systemctl status newrelic-agent-control

  Se o serviço aparecer no estado Failed ou Stopped, isso significa que o agente foi instalado, mas há um problema impedindo seu funcionamento normal. Verifique os logs dos serviços do agente usando journalctl (ou qualquer ferramenta Linux similar):

  bash

  Copiar

  $
  journalctl -u newrelic-agent-control

  Se não houver insights disponíveis, verifique como executar o agente no modo de depuração para acessar logs detalhados e obter mais informações sobre por que o serviço não pode ser iniciado.

• Se o serviço não estiver instalado, tente adicionar --debug ao final do comando de instalação da CLI da instalação guiada e execute-o novamente. Isso habilita o log detalhado para o script de instalação e pode fornecer contexto adicional explicando o erro.

• Opcionalmente, responda yes quando solicitado a enviar logs para a New Relic para ajudar a solucionar problemas na instalação. Uma vez enviados, os logs podem ser acessados com a seguinte consulta NRQL:

  SELECT * FROM Log WHERE hostname = `your-host-name`

  Copiar

Windows

1. Verifique o status do serviço newrelic-agent-control:

   Abra o PowerShell com privilégios de administrador e execute:

   Get-Service -Name newrelic-agent-control | Format-List Status, StartType

   Copiar

   Saída esperada quando saudável:

   Status    : Running
   StartType : Automatic

   Copiar

2. Verifique o endpoint de integridade do Agent Control:

   Invoke-WebRequest -Uri "http://localhost:51200/status" -UseBasicParsing

   Copiar

   Um Agent Control saudável deve retornar uma resposta JSON com "healthy": true.

3. Entre no New Relic e vá em Controle de Agentes.

4. Acesse a página Frotas e selecione a frota que você escolheu durante a instalação.

5. Na tabela Entities, confirme se o seu host Windows aparece na lista.

6. Verifique se o status de instrumentação do seu host está saudável.

Se o serviço Agent Control não se conectar ao Fleet Control em 2 a 3 minutos, consulte solução de problemas de hosts Windows.

Desinstalar Agent Control

Kubernetes

Para desinstalar o agente Control do seu cluster do Kubernetes, execute os seguintes comandos:

$
helm list --all-namespaces

Hosts Linux

Para desinstalar o Agent Control do seu host Linux:

1. Execute o script de desinstalação:

   bash

   Copiar

   $
   sudo sh /usr/lib/newrelic-agent-control/uninstall.sh

   Este script irá:

   • Pare o serviço newrelic-agent-control
   • Detectar o gerenciador de pacote
   • Execute o purge do gerenciador de pacotes para que todos os arquivos do Agent Control sejam removidos do sistema

Hosts Windows

Para desinstalar o Agent Control do seu host Windows:

1. Abra o PowerShell com privilégios de administrador.

2. Execute o script de desinstalação:

   PowerShell.exe -ExecutionPolicy Bypass -File "C:\Program Files\New Relic\newrelic-agent-control\uninstall.ps1"

   Copiar

   Este script irá:

   • Pare o serviço newrelic-agent-control
   • Remova o registro do serviço
   • Exclua os diretórios e arquivos do Agent Control