Configurar e instalar o controle do agente

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.

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. As credenciais para esta identidade de sistema expiram após 12 horas. Quando eles expirarem, a implantação do Helm chart do Agent Control falhará ao se autenticar no serviço Fleet Control, resultando no seguinte erro:

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

Nesse caso, o gráfico do Helm deve ser atualizado com novas credenciais de identidade do sistema.

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:
        ...

Verificar a instalação

Agora que o Agente Control está instalado e em execução, você está pronto para configurar e gerenciar seu agente ou implantar alterações nele usando o Controle de Agentes](/docs/New Relic-control/fleet-control/overview).

Kubernetes

1. Execute os seguintes comandos para verificar o status do seu pod:

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.

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.

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

Lista de verificação de pré-instalação

Antes de instalar o Agent Control no Windows, verifique estes pré-requisitos:

• Privilégios de administrador - Clique com o botão direito no PowerShell e selecione "Run as Administrator"
• Versão do PowerShell - Verifique o PowerShell 5.0 ou superior:

  $PSVersionTable.PSVersion

  Copiar
• Disponibilidade de porta - Certifique-se de que a porta 51200 não esteja em uso:

  netstat -ano | findstr :51200

  Copiar
  Se o comando não retornar nenhuma saída, a porta está disponível.
• Agente de infraestrutura removido - Desinstale o agente de infraestrutura se já estiver instalado:

  Get-Service -Name newrelic-infra -ErrorAction SilentlyContinue

  Copiar
  Se isso retornar um serviço, desinstale o Agente de Infraestrutura primeiro. Os agentes APM podem permanecer instalados.
• Frota criada - Crie uma frota com o tipo "Host - Windows" no Controle de Frota
• Conectividade de rede - Teste o acesso aos serviços da New Relic:

  Test-NetConnection -ComputerName download.newrelic.com -Port 443

  Copiar
• Configuração de antivírus - Adicione exclusões (consulte as notas sobre software de segurança abaixo)

Verificar a instalação

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

   Copiar

   O serviço deve mostrar o status Running. Se o serviço aparecer no estado Stopped ou não existir, prossiga com a solução de problemas abaixo.

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.

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 aparece no Fleet Control

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 Windows na tabela Entities
3. Implante agentes (agente de infraestrutura, NRDOT, etc.) no seu host usando o Fleet Control
4. Aguarde de 5 a 10 minutos para que os agentes implantados iniciem e enviem telemetria para a New Relic

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.

Comandos de gerenciamento de serviços

Gerencie o serviço Windows Agent Control com estes comandos do PowerShell (execute como Administrador):

Inicie o serviço:

Start-Service -Name newrelic-agent-control

Pare o serviço:

Stop-Service -Name newrelic-agent-control

Reinicie o serviço:

Restart-Service -Name newrelic-agent-control

Verifique o status do serviço:

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

Saída esperada quando saudável:

Status    : Running
StartType : Automatic

Visualizar configuração do serviço:

Get-WmiObject -Class Win32_Service -Filter "Name='newrelic-agent-control'" | Format-List Name, State, StartMode, StartName

Estrutura de diretórios

O Agent Control cria a seguinte estrutura de diretórios no Windows:

Arquivos de programas (Executáveis):

C:\Program Files\New Relic\newrelic-agent-control\
├── newrelic-agent-control.exe       # Main service executable
├── uninstall.ps1                     # Uninstallation script
└── local-data\
    └── agent-control\
        └── local_config.yaml         # Local configuration file

Dados do programa (Dados de tempo de execução):

C:\ProgramData\New Relic\newrelic-agent-control\
├── fleet-data\
│   └── agent-control\
│       └── remote_config.yaml        # Configuration synced from Fleet Control
├── logs\
│   └── newrelic-agent-control.log    # Service logs
├── filesystem\                       # Managed agent configurations and data
└── packages\                         # Downloaded agent packages (cached)

Get-ChildItem "C:\ProgramData\New Relic\newrelic-agent-control\logs\" -Filter "newrelic-agent-control.log.*" | Sort-Object LastWriteTime -Descending | Select-Object -First 1 | Get-Content -Tail 100

Recursos específicos do Windows

Coleta de logs: Hosts Windows podem coletar logs por meio do Fluent Bit integrado do Infrastructure Agent. O pacote do Infrastructure Agent inclui binários do Fluent Bit para Windows, permitindo configurar o encaminhamento de logs usando o parâmetro config_logging na configuração do agente. As configurações de log funcionam de forma semelhante aos hosts Linux, mas usam caminhos e formatos específicos do Windows.

Observações de configuração:

• Caminhos de arquivo em configurações do Windows usam barras invertidas (\\) e caminhos no estilo Windows (por exemplo, C:\\ProgramData\\...)
• As variáveis de ambiente são definidas usando as convenções do Windows
• Binários do agente usam extensões .exe
• Os arquivos de configuração são armazenados nos locais mostrados na estrutura de diretórios acima

Parâmetro de configuração

Principais parâmetros de configuração para o Controle do Agente no Windows:

Visualizar a configuração atual:

Get-Content "C:\Program Files\New Relic\newrelic-agent-control\local-data\agent-control\local_config.yaml"

Verifique a configuração do serviço:

Get-WmiObject -Class Win32_Service -Filter "Name='newrelic-agent-control'" | Format-List PathName, StartName, State

Desinstalar Agent Control

Kubernetes

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

$
helm list --all-namespaces

Hosts Linux

$
sudo apt-get remove newrelic-agent-control

$
sudo zypper -n remove newrelic-infra

$
sudo yum remove newrelic-agent-control

Hosts Windows

Para desinstalar o Agent Control do seu host Windows:

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

2. Navegue até o diretório de instalação do Agent Control:

   cd "C:\Program Files\New Relic\newrelic-agent-control"

   Copiar

3. Execute o script de desinstalação:

   .\uninstall.ps1

   Copiar

   Este script irá:

   • Pare o serviço newrelic-agent-control
   • Remova o registro do serviço
   • Exclua o executável do Agent Control

4. (Opcional) Remova manualmente os diretórios de configuração se desejar remover completamente todos os dados do Agent Control:

   Remove-Item -Path "C:\Program Files\New Relic\newrelic-agent-control" -Recurse -Force
   Remove-Item -Path "C:\ProgramData\New Relic\newrelic-agent-control" -Recurse -Force

   Copiar