Configurer et installer Agent Control

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

À 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/cluster apparaît dans le contrôle de la flotte

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/cluster dans la table Entities
3. Déployez des agents (agent Infrastructure, NRDOT, etc.) sur votre hôte/cluster à 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

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 ou la commande de l'hôte. Les identifiants de cette identité système expirent après 12 heures. Lorsqu'ils expirent, le déploiement du chart Helm Agent Control ou la commande de l'hôte ne parviendra pas à s'authentifier auprès du service de contrôle de la flotte, entraînant l'erreur suivante :

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

Configuration Kubernetes avancée

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. Selon les exigences de votre écosystème, vous pouvez configurer Agent Control pour exploiter une installation Flux v2 personnalisée existante ou contourner entièrement les composants d'infrastructure de livraison continue.

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.

Installer Agent Control sans Flux

Vous pouvez installer Agent Control sans Flux lorsque son rôle se limite à distribuer la configuration aux agents gérés et non à les installer ou à les mettre à niveau. Dans ce mode, Agent Control ne peut pas gérer le cycle de vie des agents — il n'installe ni ne met à niveau les agents et pousse uniquement la configuration via le contrôle de la flotte. Vous êtes vous-même responsable de l'installation et de la mise à niveau d'Agent Control et de tous les agents gérés. Le principal cas d’utilisation est le gateway Contrôle de pipeline: Agent Control fournit les modifications de configuration du gateway Contrôle de pipeline.

Pour installer Agent Control sans Flux, définissez agentControlCd.enabled sur false dans vos valeurs Helm. Agent Control ne créera ni ne monitorera aucun objet Flux.

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

agentControlCd:
  enabled: false

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

Lorsque vous installez le gateway Contrôle de pipeline via l'installation guidée de New Relic, le fichier de valeurs généré définit déjà agentControlCd.enabled: false. Vous n'avez pas besoin de le modifier manuellement.

Vérifier l'installation

Kubernetes

1. Exécutez les commandes suivantes pour vérifier le statut de vos pods : Agent Control installe des sous-agents dans un espace de nommage 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 l’espace de nommage newrelic-agent-control et que les pods de sous-agent s’exécutent dans un espace de nommage 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.

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

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 | Format-List Status, StartType

   Copier

   Sortie attendue lorsque l'état est sain :

   Status    : Running
   StartType : Automatic

   Copier

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.

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

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

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

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

   bash

   Copier

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

   Ce script va :

   • Arrêtez le service newrelic-agent-control
   • Détecter le gestionnaire de paquets
   • Exécutez la purge du gestionnaire de paquets afin que tous les fichiers d'Agent Control soient supprimés du système

Hôtes Windows

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

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

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

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

   Copier

   Ce script va :

   • Arrêtez le service newrelic-agent-control
   • Supprimer l'enregistrement du service
   • Supprimez les répertoires et fichiers Agent Control