Configurar e instalar Agent Control

Descripción general

Agent Control simplifica la gestión de sus agentes de instrumentación. Esta guía le guiará a través del proceso de instalación y desinstalación de Agent Control en sus clústeres de Kubernetes, hosts Linux o hosts Windows utilizando diferentes métodos.

Instalar Agent Control

Instalación

1. Inicie sesión en New Relic.
2. Cerciorar de que esté seleccionada la cuenta correcta.
3. En integración & agente, haga clic en Install Agent Control o busque Agent Control.

4. Siga los pasos para completar el proceso de instalación y configuración.

5. Descargue la configuración generada a su computadora y ejecute el comando proporcionado en su terminal para instalar Agent Control. Después de la instalación, haga clic en Continue.
6. Pruebe la conexión para confirmar que la instalación fue exitosa. Este paso puede tardar entre 5 y 10 minutos en completar.
7. Ahora que Agent Control está instalado y en ejecución, está listo para configurar y gestionar los agentes o desplegar cambios en los agentes usando control de flota.

Qué esperar después de la instalación

Después de ejecutar el script de instalación, Agent Control configura únicamente el servicio de supervisor. No se despliegan agentes de instrumentación automáticamente.

Inmediato (0-2 minutos):

• 0-30 segundos: El servicio Agent Control se registra e inicia
• 30-60 segundos: Primera conexión a Fleet Control establecida
• 1-2 minutos: se completa la sincronización de la configuración y el host/clúster aparece en el control de flota

Próximos pasos requeridos: Una vez que Agent Control esté instalado y conectado a Fleet Control, debe desplegar los agentes manualmente para comenzar a recopilar telemetría:

1. Inicia sesión en New Relic y ve a Fleet Control
2. Seleccione su flota y ubique su host/clúster en la tabla Entities
3. Despliegue agentes (agente de infraestructura, NRDOT, etc.) en su host/clúster usando control de flota
4. Espere de 5 a 10 minutos a que los agentes desplegados se inicien y envíen telemetría a New Relic

Nota sobre la autenticación

New Relic Control requiere el uso de identidades del sistema, que son identidades no humanas utilizadas para autenticar y establecer confianza entre servicios y aplicaciones.

Durante el proceso de instalación guiada de Agent Control, se crea la primera identidad del sistema utilizando las credenciales del cliente, las cuales se incluyen en los valores del chart de Helm o en el comando del host. Las credenciales para esta identidad del sistema expiran después de 12 horas. Cuando expiren, el despliegue del chart de Helm de Agent Control o el comando del host fallará al autenticarse con el servicio de control de flota, resultando en el siguiente error:

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

En este caso, el chart de Helm o el comando del host deben actualizarse con nuevas credenciales de identidad del sistema.

Ejemplo de chart de Helm:

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

Configuración avanzada de Kubernetes

De forma predeterminada, el chart de Helm de Agent Control utiliza una instancia integrada de Flux CD para gestionar el ciclo de vida de sus agentes en Kubernetes. Dependiendo de los requisitos de su ecosistema, puede configurar el Control del agente para aprovechar una instalación personalizada existente de Flux v2 u omitir por completo los componentes de la infraestructura de entrega continua.

Soporte para instalaciones existentes de Flux

De forma predeterminada, el chart de Helm de Agent Control utiliza una instancia integrada de Flux CD para gestionar el ciclo de vida de sus agentes en Kubernetes. Sin embargo, si su organización ya utiliza Flux v2 para GitOps, puede configurar Agent Control para aprovechar su instalación existente.

Este enfoque desacopla Agent Control del motor de entrega continua integrado, lo que le permite mantener una única instancia de Flux para las operaciones de su clúster mientras sigue beneficiándose de las capacidades de gestión de Agent Control.

Requisitos y compatibilidad Para utilizar una instalación externa de Flux con Agent Control, su entorno debe cumplir con los siguientes requisitos. Las configuraciones que se desvían de estas especificaciones no se validan.

• Versión de Flux: Flux v2 o superior.

• Componentes requeridos: Su instalación de Flux debe incluir:

  • Controlador de Helm: Con el CRD HelmRelease (helm.toolkit.fluxcd.io/v2).
  • Controlador de origen: Con el CRD HelmRepository (source.toolkit.fluxcd.io/v1).

• Alcance del espacio de nombres: Su instancia de Flux debe estar configurada para observar el espacio de nombres donde se instalará Agent Control (o configurada para observar todos los espacios de nombres).

Configuración Para habilitar este modo, debe deshabilitar explícitamente los componentes de Flux incluidos en la configuración del chart de Helm de Agent Control.

En su archivo values.yaml, establezca agentControlCd.enabled en false:

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

# Disable the embedded Flux instance
agentControlCd:
  enabled: false

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

Permisos para Flux externo Al usar su propia instalación de Flux, la Cuenta de servicio de Flux en su clúster es responsable de aplicar la configuración generada por Agent Control. Por lo tanto, su instancia de Flux existente requiere permisos específicos para desplegar recursos de New Relic. Recomendamos ampliamente uno de los siguientes enfoques:

• Administrador del clúster (recomendado): La configuración más sencilla es garantizar que su instancia de Flux se ejecute con privilegios de cluster-admin. Esta es la configuración estándar para el chart de la comunidad de Flux y asegura que pueda gestionar todos los recursos necesarios (Deployments, DaemonSets, Services, etc.) requeridos por los agentes de New Relic.
• Configuración de privilegios mínimos: Si sus políticas de seguridad restringen el uso de cluster-admin, debe crear un ClusterRole específico para garantizar que su cuenta de servicio de Flux tenga los permisos requeridos por el Source Controller, Helm Controller, Agent Control y cada agente específico que planee instalar.

A continuación se muestra un ejemplo ClusterRole que demuestra los permisos mínimos requeridos para que los componentes Agent Control y Flux interoperen:

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

Límites de soporte Al utilizar una instalación externa de Flux, el soporte de New Relic se limita al software Agent Control (la generación de manifiestos de configuración válidos). En este modo, debe considerar un esquema de responsabilidad compartida como el siguiente:

• Responsabilidad de New Relic: Garantizamos que Agent Control interactúe correctamente con el backend de New Relic y genere definiciones válidas de HelmRelease y HelmRepository.
• Responsabilidad del cliente: Usted es responsable de la salud, el mantenimiento de versiones, las redes y la resolución de problemas de su propia instalación de Flux. Los problemas derivados específicamente de la configuración o la falla de los controladores Flux externos están fuera del alcance del soporte de Agent Control.

Instalar Agent Control sin Flux

Puede instalar el Control de agente sin Flux cuando su función se limita a entregar configuración a los agentes administrados y no a instalarlos ni actualizarlos. En este modo, Agent Control no puede administrar el ciclo de vida del agente: no instala ni actualiza agentes y solo envía la configuración a través del control de flota. Usted mismo es responsable de instalar y actualizar Agent Control y cualquier agente administrado. El caso de uso principal es el gateway de Control de pipelines: Control del agente entrega los cambios de configuración del gateway de Control de pipelines.

Para instalar Control del agente sin Flux, establezca agentControlCd.enabled en false en sus valores de Helm. Control del agente no creará ni monitoreará ningún objeto de Flux.

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

agentControlCd:
  enabled: false

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

Cuando instala el gateway de Control de pipelines a través de la instalación guiada de New Relic, el archivo de valores generado ya establece agentControlCd.enabled: false. No es necesario editarlo manualmente.

Verificar la instalación

Kubernetes

1. Ejecute los siguientes comandos para comprobar el estado de sus pods: Agent Control instala subagentes en un namespace diferente por motivos de seguridad. Para verificar que todo esté funcionando, compruebe que los pods de Agent Control se estén ejecutando en el namespace newrelic-agent-control y que los pods del subagente se estén ejecutando en un namespace diferente, como newrelic.

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

2. Inicie sesión en New Relic y vaya a Fleet Control.
3. Vaya a la página Flotas y seleccione la flota que eligió durante la instalación.
4. En la tabla de Entities , confirme que su clúster de Kubernetes aparezca en la lista.
5. Verifique que el estado de la instrumentación de su clúster sea saludable.

Linux

• Verifique el estado del servicio newrelic-agent-control:

  bash

  Copia

  $
  sudo systemctl status newrelic-agent-control

  Si el servicio aparece en estado Failed o Stopped, esto significa que el agente se instaló pero hay un problema que impide su funcionamiento normal. Verifique los logs de los servicios del agente utilizando journalctl (o cualquier herramienta de Linux similar):

  bash

  Copia

  $
  journalctl -u newrelic-agent-control

  Si no hay información disponible, consulta cómo ejecutar el agente en modo de depuración para acceder a logs detallados y obtener más información sobre por qué no se puede iniciar el servicio.

• Si el servicio no está instalado, intente agregar --debug al final del comando de instalación de la CLI de la instalación guiada y ejecútelo nuevamente. Esto habilita el logging detallado para el script de instalación y puede proporcionar contexto adicional que explique el error.

• Opcionalmente, responda yes cuando se le solicite enviar logs a New Relic para ayudar a solucionar problemas de la instalación. Una vez enviados, se puede acceder a los logs con la siguiente consulta NRQL:

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

  Copia

Windows

1. Verifique el estado del servicio newrelic-agent-control:

   Abra PowerShell con privilegios de administrador y ejecute:

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

   Copia

   Salida esperada cuando está saludable:

   Status    : Running
   StartType : Automatic

   Copia

2. Verifique el endpoint de salud de Agent Control:

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

   Copia

   Un Agent Control saludable debería devolver una respuesta JSON con "healthy": true.

3. Inicie sesión en New Relic y vaya a Fleet Control.

4. Vaya a la página Flotas y seleccione la flota que eligió durante la instalación.

5. En la tabla Entities, confirme que su host de Windows aparece en la lista.

6. Verifique que el estado de instrumentación de su host sea saludable.

Si el servicio Agent Control no se conecta a Fleet Control en 2 o 3 minutos, consulta la solución de problemas en hosts Windows.

Desinstalar Agent Control

Kubernetes

Para desinstalar el Agente Control de su clúster de Kubernetes, ejecute los siguientes comandos:

$
helm list --all-namespaces

Hosts Linux

Para desinstalar Agent Control de su host Linux:

1. Ejecute el script de desinstalación:

   bash

   Copia

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

   Este script realizará lo siguiente:

   • Detenga el servicio newrelic-agent-control
   • Detecte el administrador de paquetes
   • Ejecute la purga del administrador de paquetes para que todos los archivos de Agent Control se eliminen del sistema

Hosts de Windows

Para desinstalar Agent Control de su host Windows:

1. Abra PowerShell con privilegios de administrador.

2. Ejecute el script de desinstalación:

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

   Copia

   Este script realizará lo siguiente:

   • Detenga el servicio newrelic-agent-control
   • Eliminar el registro del servicio
   • Elimine los directorios y archivos de Agent Control