Configuration et installation du contrôle des agents

Présentation

Agent Control simplifie la gestion de vos agents d'instrumentation. Ce guide vous guidera dans le processus d'installation et de désinstallation d'Agent Control sur vos clusters Kubernetes, hôtes Linux ou hôtes Windows à l'aide de différentes méthodes.

Installer Agent Control

Installation guidée

1. Connectez-vous à New Relic.
2. Assurez-vous que le bon compte est sélectionné.

3. Dans Intégration et agents, cliquez sur Installer Agent Control ou recherchez Agent Control.

   

4. Suivez les étapes pour terminer le processus d'installation et de configuration.

5. Téléchargez la configuration générée sur votre ordinateur et exécutez la commande fournie dans votre terminal pour installer Agent Control. Après l'installation, cliquez sur Continue.
6. Testez la connexion pour confirmer que l'installation a réussi. Cette étape peut prendre 5 à 10 minutes.

Remarque sur l'authentification

New Relic Control nécessite l'utilisation d'identités système, qui sont des identités non humaines utilisées pour authentifier et établir la confiance entre les services et les applications.

Lors du processus d'installation guidée d'Agent Control, la première identité système est créée à l'aide des identifiants client, qui sont inclus dans les valeurs du chart Helm. Les identifiants de cette identité système expirent après 12 heures. Lorsqu'ils expirent, le déploiement du chart Helm Agent Control ne parviendra pas à s'authentifier auprès du service Fleet Control, entraînant l'erreur suivante :

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

Dans ce cas, le graphique Helm doit être mis à jour avec les nouvelles informations d'identification d'identité du système.

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

Vérifier l'installation

Maintenant qu'Agent Control est installé et en cours d'exécution, vous êtes prêt à configurer et à gérer vos agents ou à déployer des modifications sur vos agents à l'aide du contrôle de la flotte](/docs/new-relic-control/fleet-control/overview).

Kubernetes

1. Exécutez les commandes suivantes pour vérifier l’état de votre pod :

Agent Control installe des sous-agents dans un espace de noms différent pour des raisons de sécurité. Pour vérifier que tout fonctionne, vérifiez que les pods Agent Control s'exécutent dans le namespace newrelic-agent-control et que les pods de sous-agent s'exécutent dans un namespace différent, tel que newrelic.

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

2. connectez-vous à New Relic et accédez au Fleet Control.
3. Accédez à la page Flottes et sélectionnez la flotte que vous avez choisie lors de l'installation.
4. Dans la table Entities , confirmez que votre cluster Kubernetes apparaît dans la liste.
5. Vérifiez que l’état de l’instrumentation de votre cluster est sain.

Prise en charge des installations Flux existantes

Par défaut, le chart Helm Agent Control utilise une instance intégrée de Flux CD pour gérer le cycle de vie de vos agents dans Kubernetes. Cependant, si votre organisation utilise déjà Flux v2 pour GitOps, vous pouvez configurer Agent Control pour tirer parti de votre installation existante.

Cette approche découple Agent Control du moteur de livraison continue intégré, vous permettant de maintenir une instance Flux unique pour vos opérations de cluster tout en bénéficiant des capacités de gestion d'Agent Control.

Exigences et compatibilité

Pour utiliser une installation externe de Flux avec Agent Control, votre environnement doit répondre aux exigences suivantes. Les configurations qui s'écartent de ces spécifications ne sont pas validées.

• Version Flux : Flux v2 ou supérieur.

• Composants requis : Votre installation Flux doit inclure :

  • Contrôleur Helm : Avec la CRD HelmRelease (helm.toolkit.fluxcd.io/v2).
  • Contrôleur de source : Avec la CRD HelmRepository (source.toolkit.fluxcd.io/v1).

• Portée de l'espace de noms : Votre instance Flux doit être configurée pour surveiller l'espace de noms dans lequel Agent Control sera installé (ou configurée pour surveiller tous les espaces de noms).

Configuration

Pour activer ce mode, vous devez désactiver explicitement les composants Flux inclus dans la configuration du chart Helm Agent Control.

Dans votre fichier values.yaml, définissez agentControlCd.enabled sur false:

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

# Disable the embedded Flux instance
agentControlCd:
  enabled: false

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

Permissions pour Flux externe

Lorsque vous utilisez votre propre installation Flux, le compte de service Flux de votre cluster est responsable de l'application des configurations générées par Agent Control. Par conséquent, votre instance Flux existante nécessite des autorisations spécifiques pour déployer des ressources New Relic. Nous recommandons vivement l'une des approches ci-dessous :

• Administrateur de cluster (recommandé) : La configuration la plus simple consiste à s'assurer que votre instance Flux s'exécute avec les privilèges cluster-admin. Il s'agit de la configuration standard pour le chart communautaire Flux et elle garantit qu'il peut gérer toutes les ressources nécessaires (Deployments, DaemonSets, Services, etc.) requises par les agents New Relic.
• Configuration du moindre privilège : Si vos politiques de sécurité restreignent l'utilisation de cluster-admin, vous devez créer un ClusterRole spécifique garantissant que votre compte de service Flux dispose des autorisations requises par le Source Controller, le Helm Controller, l'Agent Control et chaque agent spécifique que vous prévoyez d'installer.

Voici un exemple ClusterRole illustrant les permissions minimales requises pour que les composants Agent Control et Flux interagissent :

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 du support

Lors de l'utilisation d'une installation Flux externe, le support New Relic se limite au logiciel Agent Control (la génération de manifestes de configuration valides). Dans ce mode, vous devez prendre en compte un schéma de responsabilité partagée comme suit :

• Responsabilité de New Relic : Nous nous assurons qu'Agent Control interagit correctement avec le backend New Relic et génère des définitions HelmRelease et HelmRepository valides.
• Responsabilité du client : Vous êtes responsable de l'état de santé, de la maintenance des versions, de la mise en réseau et du dépannage de votre propre installation Flux. Les problèmes découlant spécifiquement de la configuration ou de la défaillance des contrôleurs Flux externes ne sont pas couverts par le support d'Agent Control.

Linux

• Vérifiez l'état du service newrelic-agent-control :

  bash

  Copier

  $
  sudo systemctl status newrelic-agent-control

  Si le service apparaît à l'état Failed ou Stopped, cela signifie que l'agent a été installé mais qu'un problème empêche son fonctionnement normal. Vérifiez les logs des services de l'Agent avec journalctl (ou tout autre outil Linux similaire) :

  bash

  Copier

  $
  journalctl -u newrelic-agent-control

  Si aucune information n'est disponible, consultez la procédure pour exécuter l'agent en mode débogage afin d'accéder aux logs détaillés et de mieux comprendre pourquoi le service ne peut pas être démarré.

• Si le service n'est pas installé, essayez d'ajouter --debug à la fin de la commande d'installation CLI de l'installation guidée et relancez-la. Cela active le logs détaillé pour le script d'installation et peut fournir un contexte supplémentaire expliquant l'erreur.

• Facultativement, répondez yes lorsqu'il vous est demandé d'envoyer des logs à New Relic pour aider au dépannage de l'installation. Une fois soumis, les logs sont accessibles avec la requête NRQL suivante :

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

  Copier

Windows

Liste de contrôle de pré-installation

Avant d'installer Agent Control sur Windows, vérifiez ces prérequis :

• Privilèges d'administrateur - Cliquez avec le bouton droit sur PowerShell et sélectionnez "Run as Administrator"
• Version de PowerShell - Vérifier PowerShell 5.0 ou version ultérieure :

  $PSVersionTable.PSVersion

  Copier
• Disponibilité du port - Assurez-vous que le port 51200 n'est pas utilisé :

  netstat -ano | findstr :51200

  Copier
  Si la commande ne renvoie aucune sortie, le port est disponible.
• Agent d'infrastructure supprimé - Désinstallez l'agent d'infrastructure s'il est déjà installé :

  Get-Service -Name newrelic-infra -ErrorAction SilentlyContinue

  Copier
  Si cela renvoie un service, désinstallez d'abord l'agent Infrastructure. Les agents APM peuvent rester installés.
• Parc créé - Créez un parc de type "Host - Windows" dans Fleet Control
• Connectivité réseau - Tester l'accès aux services New Relic :

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

  Copier
• Configuration de l'antivirus - Ajouter des exclusions (voir les notes sur les logiciels de sécurité ci-dessous)

Vérifier l'installation

1. Vérifiez l'état du service newrelic-agent-control :

   Ouvrez PowerShell avec les privilèges d'administrateur et exécutez :

   Get-Service -Name newrelic-agent-control

   Copier

   Le service doit afficher le statut Running. Si le service apparaît à l'état Stopped ou n'existe pas, procédez au dépannage ci-dessous.

2. Vérifier l'endpoint de santé de l'Agent Control :

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

   Copier

   Un Agent Control sain doit renvoyer une réponse JSON avec "healthy": true.

3. connectez-vous à New Relic et accédez au Fleet Control.

4. Accédez à la page Flottes et sélectionnez la flotte que vous avez choisie lors de l'installation.

5. Dans le tableau Entities, confirmez que votre hôte Windows apparaît dans la liste.

6. Vérifiez que le statut de l'instrumentation de votre hôte est sain.

À quoi s'attendre après l'installation

Après avoir exécuté le script d'installation, Agent Control configure uniquement le service de supervision. Aucun agent d'instrumentation n'est déployé automatiquement.

Immédiat (0-2 minutes) :

• 0-30 secondes : Le service Agent Control s'enregistre et démarre
• 30-60 secondes : Première connexion à Fleet Control établie
• 1 à 2 minutes : La synchronisation de la configuration se termine et l'hôte apparaît dans Fleet Control

Prochaines étapes requises : Une fois Agent Control installé et connecté à Fleet Control, vous devez déployer manuellement des agents pour commencer à collecter la télémétrie :

1. Connectez-vous à New Relic et accédez à Fleet Control
2. Sélectionnez votre flotte et localisez votre hôte Windows dans la table Entities
3. Déployez des agents (agent Infrastructure, NRDOT, etc.) sur votre hôte à l'aide de Fleet Control
4. Attendez 5 à 10 minutes que les agents déployés démarrent et envoient la télémétrie à New Relic

Si le service Agent Control ne se connecte pas à Fleet Control dans les 2 à 3 minutes, consultez Dépannage des hôtes Windows.

Commandes de gestion des services

Gérez le service Windows Agent Control avec ces commandes PowerShell (exécuter en tant qu'administrateur) :

Démarrer le service :

Start-Service -Name newrelic-agent-control

Arrêtez le service :

Stop-Service -Name newrelic-agent-control

Redémarrez le service :

Restart-Service -Name newrelic-agent-control

Vérifiez l'état du service :

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

Sortie attendue lorsque l'état est sain :

Status    : Running
StartType : Automatic

Afficher la configuration du service :

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

Structure des répertoires

Agent Control crée la structure de répertoires suivante sous Windows :

Fichiers de programme (exécutables) :

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

Données du programme (données d'exécution) :

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

Fonctionnalités spécifiques à Windows

Collecte de logs : Les hôtes Windows peuvent collecter des logs via le Fluent Bit intégré à l'agent d'infrastructure. Le package de l'agent d'infrastructure inclut les binaires Fluent Bit pour Windows, vous permettant de configurer le transfert de logs à l'aide du paramètre config_logging dans la configuration de votre agent. Les configurations de logs fonctionnent de manière similaire aux hôtes Linux, mais utilisent des chemins et des formats spécifiques à Windows.

Notes de configuration :

• Les chemins de fichiers dans les configurations Windows utilisent des barres obliques inverses (\\) et des chemins de type Windows (par ex. C:\\ProgramData\\...)
• Les variables d'environnement sont définies selon les conventions Windows.
• Les binaires de l'Agent utilisent des extensions .exe
• Les fichiers de configuration sont stockés aux emplacements indiqués dans la structure de répertoires ci-dessus.

Paramètres de configuration

Paramètres de configuration clés pour le contrôle de l'Agent sous Windows :

Afficher la configuration actuelle :

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

Vérifier la configuration du service :

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

Désinstaller Agent Control

Kubernetes

Pour désinstaller Agent Control de votre cluster Kubernetes, exécutez les commandes suivantes :

$
helm list --all-namespaces

Hôtes Linux

$
sudo apt-get remove newrelic-agent-control

$
sudo zypper -n remove newrelic-infra

$
sudo yum remove newrelic-agent-control

Hôtes Windows

Pour désinstaller Agent Control de votre hôte Windows :

1. Ouvrez PowerShell avec les privilèges d'administrateur.

2. Accédez au répertoire d'installation d'Agent Control :

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

   Copier

3. Exécutez le script de désinstallation :

   .\uninstall.ps1

   Copier

   Ce script va :

   • Arrêtez le service newrelic-agent-control
   • Supprimer l'enregistrement du service
   • Supprimez l'exécutable Agent Control

4. (Facultatif) Supprimez manuellement les répertoires de configuration si vous souhaitez supprimer complètement toutes les données d'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

   Copier