Guide de migration

Ce guide couvre les questions et les pièges les plus courants lors du passage d’une installation d’agent autonome à des agents gérés par Agent Control et le contrôle de la flotte.

Avant de commencer : l’écart de monitoring

Prudence

L’installation d’Agent Control supprime l’agent d’infrastructure autonome.

Le package du système d’exploitation qui installe Agent Control supprime ou arrête l’agent d’infrastructure précédemment installé. À partir de ce moment, l’hôte n’a aucun agent en cours d’exécution jusqu’à ce qu’Agent Control se connecte au contrôle de la flotte, reçoive la configuration de déploiement, et démarre avec succès l’agent d’infrastructure en tant que sous-agent géré.

N’installez pas Agent Control sur un hôte tant que toutes les conditions suivantes ne sont pas remplies :

Le contrôle de la flotte a un déploiement avec un agent d’infrastructure ciblant cet hôte dont la configuration a des paramètres similaires à vos fichiers newrelic-infra.yml, et integrations.d/ existants. Reportez-vous à la section Migration de la configuration pour savoir comment traduire chaque élément.
Vous avez d’abord validé la configuration de déploiement sur au moins un hôte hors production.
Agent Control peut atteindre le point de terminaison du contrôle de la flotte et le registre OCI depuis l’hôte cible. Vérifiez les règles de pare-feu et les paramètres de proxy à l’avance.
Vous avez préparé les étapes de retour en arrière au cas où le déploiement ne démarrerait pas. Consultez la section Retour en arrière.
Le délai entre l’installation d’Agent Control, et le premier démarrage réussi de l’agent géré est généralement de quelques secondes lorsque tout est configuré correctement.

Prudence

La migration nécessite de désinstaller les agents existants avant d’installer Agent Control.

Contrairement aux hôtes où le programme d’installation d’Agent Control remplace l’agent existant, sur Kubernetes, vous désinstallez d’abord manuellement les anciens agents. Il y a une interruption du monitoring à partir du moment où vous exécutez helm uninstall jusqu’à ce qu’Agent Control se connecte au contrôle de la flotte, et applique votre configuration distante.

Ne désinstallez pas vos agents existants tant que toutes les conditions suivantes ne sont pas remplies :

Vous avez sauvegardé vos valeurs Helm existantes : helm get values RELEASE_NAME --namespace NAMESPACE. Celles-ci constituent votre point de restauration.
Le contrôle de la flotte dispose de configurations à distance prêtes pour chaque type d’agent que vous migrez. Reportez-vous à la section Migration de la configuration pour savoir comment modéliser les valeurs Helm vers les configurations du contrôle de la flotte.
Agent Control peut atteindre le point de terminaison du contrôle de la flotte et le registre OCI depuis les nœuds de votre cluster. Vérifiez les stratégies réseau et les règles de sortie à l’avance.
Vous avez préparé les étapes de retour en arrière au cas où le déploiement ne démarrerait pas. Consultez la section Retour en arrière.

Migrer un système précédemment instrumenté

Important

Agent Control ne prend pas en charge la migration automatique des agents existants. La migration est toujours un processus manuel : désinstallez l’agent existant, installez Agent Control, puis recréez votre configuration en tant que configuration distante de contrôle de la flotte.

Lacune de monitoring sur les hôtes Linux et Windows

L’installation d’Agent Control sur un hôte supprime l’agent d’infrastructure autonome. Attendez-vous à une perte temporaire de télémétrie à partir du moment où l’ancien agent s’arrête jusqu’à ce qu’Agent Control se connecte au contrôle de la flotte et démarre l’agent géré. Préparez et validez la configuration de déploiement de votre contrôle de la flotte sur un hôte hors production avant de migrer la production. Pour plus de détails, y compris les étapes de restauration, consultez le guide de migration de l’hôte.

Processus général de migration

Quelle que soit la plateforme, la migration suit ces quatre étapes :

Notez votre configuration existante. Sauvegardez une copie de tous les fichiers de configuration de l’agent et des configurations d’intégration avant de désinstaller quoi que ce soit. Vous les recréerez en tant que configurations à distance Fleet Control.
Désinstallez l’agent existant. Agent Control ne peut pas coexister avec une installation d’agent autonome du même type.
Installer Agent Control et se connecter à une flotte. Suivez le guide d’installation spécifique à la plateforme et sélectionnez une flotte existante ou créez-en une nouvelle.
Recréez votre configuration dans le contrôle de la flotte. Créez une configuration à distance pour votre flotte avec vos paramètres précédents. Agent Control l’appliquera automatiquement.

La configuration à distance l'emporte toujours

Le contrôle de la flotte est la source faisant autorité pour la configuration de l’agent. Tous les paramètres de l’agent, les versions, les valeurs de chart et les limites de ressources doivent être définis dans la configuration à distance du contrôle de la flotte, et non dans le fichier d’installation local. Si les deux existent, la configuration distante a la priorité et écrasera toutes les valeurs locales.

Meilleures pratiques

Pour garantir la continuité des données, utilisez le même nom d’entité (nom de cluster ou nom d’hôte) et le même compte New Relic lors de l’installation d’Agent Control. Les GUID d’entité sont liés à ces attributs, et non à la façon dont l’agent est géré. Consultez la section continuité de l’entité et dashboards pour plus de détails. Vous pouvez laisser en place tous les agents ou composants qui ne sont pas encore pris en charge par Agent Control jusqu’à ce que la prise en charge soit disponible.

Kubernetes

Si votre cluster Kubernetes est déjà instrumenté avec New Relic, vous pouvez passer vos agents sous la gestion d’Agent Control. Le processus de migration supprime les installations d’agents existantes, et les remplace par des installations gérées par Agent Control, configurées de manière centralisée via le contrôle de la flotte.

Agent Control peut déployer et gérer les agents suivants à partir du chart Helm nri-bundle :

newrelic-infrastructure, nri-kube-events et kube-state-metrics: gérés comme le type d’ Agent d’infrastructure
newrelic-prometheus-configurator: géré en tant que type d’agent Prometheus
newrelic-logging: géré en tant que type d’agent Fluent Bit
nr-k8s-otel-collector: géré en tant que type d’agent OpenTelemetry Collector

Récupérez votre configuration existante. Si vous avez installé des agents à l’aide de Helm, récupérez votre configuration d’installation à partir du cluster :

bash

$# Find releases in the namespace
$helm list --namespace <namespace-name>
$
$# Get the values for a specific release
$helm get values <release-name> --namespace <namespace-name>

Si vous disposez du fichier de configuration d’origine sauvegardé lors de l’installation, utilisez-le directement. Si vous avez instrumenté le cluster via des manifestes Kubernetes (kubectl ou Kustomize), notez les options définies pour chaque agent : vous les recréerez sous forme de configurations à distance Fleet Control.

Désinstallez vos anciens agents. Avant d’installer Agent Control, supprimez les anciens agents de votre cluster. Pour une installation Helm :

bash

$helm uninstall <release-name> -n <namespace>

Par exemple, pour désinstaller le nri-bundle:

bash

$helm uninstall nri-bundle -n newrelic

Installer Agent Control. Lancez l’ installation guidée d’Agent Control et téléchargez le values.yaml généré. Ce fichier contient uniquement la configuration du superviseur Agent Control (identifiants, ID de flotte et types d’agents à gérer) — n’ajoutez pas de valeurs de chart spécifiques à l’agent ici. Ceux-ci appartiennent à la configuration à distance du contrôle de la flotte.

bash

$helm upgrade --install agent-control-bootstrap -n newrelic newrelic/agent-control-bootstrap --create-namespace --values my_values.yaml

Recréez la configuration de votre agent dans Fleet Control. Une fois Agent Control connecté au contrôle de la flotte, créez les configurations pour chacun de vos anciens agents avec vos paramètres précédents.
Créer un nouveau déploiement en ajoutant les configurations distantes tout juste créées à votre flotte. Agent Control appliquera automatiquement la nouvelle configuration à votre cluster. Suivez ces étapes dans créer et exécuter votre premier déploiement.
Vérifiez que les données circulent. Accédez à Infrastructure > Kubernetes dans l’UI de New Relic. Votre cluster devrait apparaître dans les 1 - 2 minutes suivant l’application de la configuration à distance. S’il n’apparaît pas, consultez le dépannage d’Agent Control.

Linux

Important

Agent Control ne prend pas en charge la migration automatique des agents existants sous Linux. Si l'agent Infrastructure New Relic est déjà installé sur votre hôte Linux, vous devez le désinstaller manuellement avant d'installer Agent Control. Agent Control distribue les agents via des packages conformes à l'OCI par le biais de Fleet Control — il ne remplace ni n'hérite de l'installation existante du package newrelic-infra.

Notez votre configuration existante

Avant de désinstaller, sauvegardez une copie de :

Votre configuration d’agent : /etc/newrelic-infra/newrelic-infra.yml
Toutes les configurations d’intégration sur hôte : /etc/newrelic-infra/integrations.d/

Vous les recréerez en tant que configuration distante du contrôle de la flotte à l’étape 4. Pour savoir comment chaque fichier de configuration et paramètre correspond au format du contrôle de la flotte, consultez la section Migration de la configuration.

Désinstallez l’agent d’infrastructure existant

bash

$sudo apt-get remove newrelic-infra -y

bash

$sudo zypper -n remove newrelic-infra

bash

$sudo yum remove newrelic-infra -y

Installer Agent Control. Suivez le guide d’installation de Linux. Assurez-vous de sélectionner ou de créer une flotte de type Host - Linux.
Recréez la configuration de votre agent dans Fleet Control. Une fois qu’Agent Control est connecté au contrôle de la flotte, créez la configuration pour chacun de vos anciens agents avec vos paramètres précédents. Utilisez vos fichiers de configuration enregistrés à l’étape 1 comme référence. Consultez la section Migration de la configuration pour savoir comment chaque paramètre correspond au format du contrôle de la flotte.
Créer un nouveau déploiement en ajoutant les configurations distantes tout juste créées à votre flotte. Agent Control appliquera automatiquement la nouvelle configuration à votre hôte, téléchargera et installera les packages OCI pour chacun des agents. Suivez ces étapes dans créer et exécuter votre premier déploiement.
Vérifiez que les données circulent. Accédez à Infrastructure > Hosts dans l’UI de New Relic. Votre hôte devrait apparaître sous 1 à 2 minutes. S’il n’apparaît pas, consultez le dépannage d’Agent Control.

Les dashboards personnalisés, et les alertes faisant référence aux données de l’agent d’infrastructure continueront de fonctionner tant que vous utilisez le même compte, et le même nom d’hôte. Les GUID d’entité sont dérivés du nom d’hôte, et du compte, et non de la façon dont l’agent est géré. Pour une explication détaillée, et les étapes de restauration, reportez-vous au guide de migration de l’hôte.

Windows

Important

Agent Control ne prend pas en charge la migration automatique des agents existants sous Windows. Si l’agent New Relic Infrastructure est déjà installé sur votre hôte Windows, vous devez le désinstaller manuellement avant d’installer Agent Control. Les agents APM ne sont pas gérés par Agent Control et peuvent rester installés.

Notez votre configuration existante

Avant de désinstaller, sauvegardez une copie de :

Votre configuration d’agent : C:\Program Files\New Relic\newrelic-infra\newrelic-infra.yml
Toutes les configurations d’intégration sur hôte : C:\Program Files\New Relic\newrelic-infra\integrations.d\

Désinstallez l’agent d’infrastructure existant

Ouvrez Add or Remove Programs et désinstallez l’agent New Relic Infrastructure. Sinon, utilisez le désinstalleur MSI depuis PowerShell :

# Replace {PRODUCT_CODE} with the GUID from Add/Remove Programs
msiexec /x {PRODUCT_CODE} /quiet

Installer Agent Control. Suivez le guide d’installation de Windows. Assurez-vous de sélectionner ou de créer une flotte de type Host - Windows.
Recréez la configuration de votre agent dans Fleet Control. Une fois qu’Agent Control est connecté au contrôle de la flotte, créez la configuration pour chacun de vos anciens agents avec vos paramètres précédents. Utilisez vos fichiers de configuration enregistrés à l’étape 1 comme référence. Consultez la section Migration de la configuration pour savoir comment chaque paramètre correspond au format du contrôle de la flotte.
Créer un nouveau déploiement en ajoutant les configurations distantes tout juste créées à votre flotte. Agent Control appliquera automatiquement la nouvelle configuration à votre hôte, téléchargera et installera les packages OCI pour chacun des agents. Suivez ces étapes dans créer et exécuter votre premier déploiement.
Vérifiez que les données circulent. Accédez à Infrastructure > Hosts dans l’UI de New Relic. Votre hôte devrait apparaître sous 1 à 2 minutes. S’il n’apparaît pas, consultez le dépannage d’Agent Control.

Continuité de l’entité et dashboards

Vos dashboards, alertes, et workloads existants continuent de fonctionner sans aucune modification.

Les GUID d’entité New Relic sont dérivés d’attributs stables (principalement le nom d’hôte, CloudInstanceId, l’ID de compte, et l’identité de l’intégration) et non de la façon dont l’agent a été installé ou de ce qui supervise son processus. Lorsque Agent Control démarre l’agent d’infrastructure sur le même hôte avec la même configuration, l’agent signale les mêmes attributs qu’il a toujours signalés. New Relic résout ces attributs vers les mêmes GUID d’entité qu’auparavant, donc :

L’entité hôte dans l’interface utilisateur de l’infrastructure est la même entité.
Les entités d’intégration sur hôte (MySQL, NGINX, etc.) conservent leurs GUID.
Tout widget de dashboard, condition d’alerte, ou workload qui effectue une requête, ou filtre par ces entités, continue de fonctionner.
L’historique des signaux dorés est préservé. Il n’y a ni écart, ni duplication dans la chronologie de la métrique de l’entité, à condition que la migration soit effectuée sans chevauchement prolongé, ni écart dans l’exécution de l’agent.

Les GUID d’entité New Relic pour Kubernetes sont dérivés du nom du cluster et de l’ID de compte, et non de la façon dont les agents sont installés ou gérés. Lorsque Agent Control déploie l’agent d’infrastructure sur le même cluster en utilisant le même nom de cluster, l’entité de cluster et toutes les entités de workload se résolvent vers les mêmes GUID qu’auparavant, donc :

L’entité de cluster dans l’interface utilisateur de Kubernetes est la même entité.
Les entités de workload et d’espace de nommage conservent leurs GUID.
Tout widget de dashboard, condition d’alerte, ou workload qui effectue une requête, ou filtre par ces entités, continue de fonctionner.
L’historique des signaux dorés est préservé, à condition que le délai entre la désinstallation des anciens agents et le démarrage des agents gérés par Agent Control soit court.

Migration de la configuration

Ne stockez pas de secrets tels que des clés de licence, des clés API, ou des mots de passe en texte clair dans les configurations du contrôle de la flotte. Référencez-les plutôt en tant que variables d’environnement en utilisant le préfixe nr-env: :

license_key: ${nr-env:NEW_RELIC_LICENSE_KEY}

Agent Control expose automatiquement NEW_RELIC_LICENSE_KEY aux sous-agents, vous n’avez donc pas besoin de définir license_key explicitement ; l’exemple ci-dessus est présenté à titre de référence. Utilisez le même modèle pour tous les autres secrets. Consultez la documentation sur l’interpolation des variables pour connaître la syntaxe complète et les autres sources prises en charge.

Configuration principale de l’agent d’infrastructure

La configuration principale de l’agent d’infrastructure (newrelic-infra.yml) se modélise directement sur le bloc content de la configuration du sous-agent d’infrastructure dans le contrôle de la flotte. Toute clé acceptée par newrelic-infra.yml y est acceptée. Les champs tels que display_name, custom_attributes, et log sont tous repris sans modification.

Lorsqu’Agent Control gère l’agent d’infrastructure, il écrit la configuration effective sur le disque à chaque mise à jour de la configuration à distance. L’agent lit à partir de ce chemin. L’ancienne configuration newrelic-infra.yml reste sur le disque après la migration, mais elle ne sera pas utilisée.

Conseil

Ne supprimez pas newrelic-infra.yml ou les fichiers integrations.d/ avant d’avoir confirmé que les agents gérés rapportent correctement les données. Conserver les originaux sur le disque est ce qui rend la procédure de rollback possible.

Intégrations sur hôte

Chaque configuration d’intégration doit également être créée dans le contrôle de la flotte en sélectionnant le type d’agent correct.

Types d’agents, et modélisation de chart Helm

Agent Control gère les agents du chart Helm nri-bundle en tant que types d’agents distincts dans le contrôle de la flotte. Chaque type d’agent possède sa propre configuration distante :

composant nri-bundle	Type d’agent de contrôle de la flotte
`newrelic-infrastructure`, `nri-kube-events`, `kube-state-metrics`	Agent d'infrastructure
`newrelic-prometheus-configurator`	Prometheus
`newrelic-logging`	Fluent Bit
`nr-k8s-otel-collector`	OpenTelemetry Collector

Traduction des valeurs Helm vers la configuration du contrôle de la flotte

Les valeurs Helm que vous avez récupérées avec helm get values deviennent le corps de la configuration distante du contrôle de la flotte pour chaque type d’agent. Par exemple, une section values.yaml pour l’agent d’infrastructure :

newrelic-infrastructure:
  customAttributes:
    environment: production
  resources:
    limits:
      memory: 300Mi

devient une configuration distante de contrôle de la flotte pour le type agent d’infrastructure avec ces mêmes clés sous le bloc de configuration de l’agent. Consultez la documentation de chaque agent pour connaître les clés acceptées.

Secrets et clé de licence

Ne stockez pas de secrets en texte clair dans les configurations du contrôle de la flotte. La clé de licence est automatiquement propagée par Agent Control à tous les sous-agents gérés ; vous n’avez pas besoin de la définir dans la configuration distante. Pour les autres secrets (clés API, mots de passe), utilisez des références de variables d’environnement via le préfixe nr-env:. Consultez la documentation sur l’interpolation des variables pour plus de détails.

Retour en arrière

Si Agent Control ne fonctionne pas comme prévu après l’installation, vous pouvez revenir en toute sécurité aux agents autonomes à tout moment.

Désinstaller Agent Control :
bash
```
$sudo sh /usr/lib/newrelic-agent-control/uninstall.sh
```
Le script arrête le service, détecte le gestionnaire de paquets, et purge tous les fichiers d’Agent Control.
Réinstallez le package de l’agent d’infrastructure s’il a été supprimé. Vos fichiers newrelic-infra.yml et integrations.d/ sont conservés sur l’hôte tant que vous ne les avez pas supprimés avant la migration.

Ouvrez PowerShell avec les privilèges d’administrateur et désinstallez Agent Control :
```
PowerShell.exe -ExecutionPolicy Bypass -File "C:\Program Files\New Relic\newrelic-agent-control\uninstall.ps1"
```
Le script arrête le service, supprime l’enregistrement du service, et supprime les fichiers d’Agent Control.
Réinstallez l’agent d’infrastructure à l’aide du programme d’installation MSI s’il a été supprimé. Vos fichiers newrelic-infra.yml et integrations.d\ sont conservés sur l’hôte tant que vous ne les avez pas supprimés avant la migration.

Désinstaller Agent Control :

bash

$helm uninstall agent-control-bootstrap -n newrelic

Réinstallez vos agents précédents à l’aide des valeurs Helm que vous avez enregistrées avant la migration :
bash
```
$helm upgrade --install nri-bundle newrelic/nri-bundle -n newrelic --values saved-values.yaml
```

La continuité de l’entité est préservée lors de la restauration. Étant donné que les GUID d’entité sont dérivés du nom d’hôte, ou du nom de cluster, et du compte (et non de la façon dont l’agent est géré), l’entité d’hôte, ou de cluster, et toutes les entités d’intégration sont les mêmes que celles qui envoyaient des données auparavant. Les Dashboards, les alertes, et les workloads recommencent à fonctionner immédiatement sans interruption, ni historique dupliqué visible dans l’interface utilisateur.

Cette traduction automatique est fournie pour votre commodité.

Avant de commencer : l’écart de monitoring.css-21sua1{background:none;border:none;width:0;padding:0;}

Prudence

Prudence

Migrer un système précédemment instrumenté

Important

Lacune de monitoring sur les hôtes Linux et Windows

Processus général de migration

La configuration à distance l'emporte toujours

Meilleures pratiques

Kubernetes

Linux

Important

Windows

Important

Continuité de l’entité et dashboards

Migration de la configuration

Conseil

Retour en arrière

Avant de commencer : l’écart de monitoring