Types d’agents

Agent Control lui-même n’a aucune connaissance intégrée d’un agent particulier. Il ne sait pas comment démarrer l’agent d’infrastructure, rendre une configuration OpenTelemetry Collector, ou découvrir un binaire d’intégration Redis. Une définition de type d’agent est ce qui le lui apprend. C’est un fichier YAML qui décrit comment Agent Control doit identifier, télécharger, configurer, et exécuter un type d’agent, sur une plateforme. C’est ce qui lui permet de gérer un catalogue croissant d’agents sans modification de code à chaque fois qu’un nouvel agent est ajouté.

Le sous-agent est une instance nommée de cette définition, par exemple nr-infra-agent référençant newrelic/com.newrelic.infrastructure:0.1.0. C’est ce que vous ajoutez, supprimez, ou reconfigurez réellement. Agent Control transforme cela en artefacts d’exécution que la définition décrit, par exemple un processus, et ses fichiers sur un hôte, ou des objets Kubernetes sur un cluster, et les maintient synchronisés chaque fois que la configuration du sous-agent change.

Chaque définition de type d’agent se compose de trois sections principales : metadata, variables, et deployment, plus un champ protocol_version de niveau supérieur qui versionne le langage de schéma dans lequel le fichier est écrit.

Version du protocole

protocol_version est un champ de premier niveau qui déclare la version du type d’agent. Il est découplé à la fois du type d’agent version (le semver de la définition) et de la version de sortie d’Agent Control.

Il s’agit d’une chaîne MAJOR.MINOR entre guillemets (par ex. "1.0").

Il est analysé et validé de manière autonome, avant que le reste du document ne soit interprété, de sorte qu’il peut bloquer les fichiers dont les métadonnées ou d’autres sections utilisent une forme que cet Agent Control ne comprendrait pas autrement. Chaque sortie d’Agent Control comprend une seule version maximale du protocole, et le protocol_version est traité comme une seule valeur MAJOR.MINOR ordonnée. Les règles de compatibilité sont :

• Plus récent que pris en charge (major supérieur, ou même major avec un minor supérieur) : rejeté — le fichier est plus récent que ce que cet Agent Control comprend.
• Égal ou antérieur à la version prise en charge : accepté, Agent Control comprend chaque version de protocole jusqu’à la version prise en charge incluse.

Par exemple, un Agent Control prenant en charge 1.6 accepte tout jusqu’à 1.6 (y compris 0.9, et 1.0..=1.6), et rejette tout ce qui est plus récent (1.7, 2.0,…).

Métadonnées

La section des métadonnées identifie le type d’agent : ses name, namespace, version, sa cible platform (host ou kubernetes), et operating_system (requis pour les types basés sur l’hôte). Agent Control utilise ces champs pour adresser de manière unique la définition et l’envoyer au moteur de déploiement correct.

Variables

La section des variables déclare les entrées configurables que les opérateurs peuvent définir lors de l’ajout d’un sous-agent à leur configuration. Chaque variable possède ces champs :

• description: une explication de la variable lisible par un humain.
• type: le type de données que cette variable accepte, comme string, bool, number, yaml, ou string_map.
• required: si les opérateurs doivent définir la variable (lorsqu’elle est définie sur false, Agent Control se rabat sur la valeur dans default).
• default (facultatif) : la valeur utilisée lorsque required est false et que l’opérateur n’en définit aucune.
• classification (facultatif) : une étiquette décrivant le type de valeur que contient la variable, telle que config ou multi-config. Agent Control accepte et ignore ce champ ; il est lu par le contrôle de la flotte pour déterminer la façon dont la variable est présentée aux opérateurs.
• deprecated (facultatif) : marque la variable comme obsolète (deprecated: true). Agent Control accepte et ignore également ce champ : il n’a aucun comportement d’exécution, et n’affecte pas la résolution, la validation, ou les valeurs par défaut.

Les variables sont référencées tout au long de la section de déploiement en utilisant ${nr-var:variable_name}.

déploierons

La section de déploiement décrit comment Agent Control installe et exécute l’agent. Sa forme est entièrement différente selon la cible platform déclarée dans les métadonnées du type d’agent.

Pour la référence complète du schéma et tous les champs disponibles, consultez la référence du schéma de type d’agent.

Déploiement sur Kubernetes

Sur Kubernetes, Agent Control gère les objets Kubernetes. La section de déploiement est composée de :

• objects: les objets Kubernetes qu’Agent Control crée, et maintient à jour.
• health: une liste explicite de vérifications, chacune ciblant une ressource Kubernetes par name, namespace, et kind.

La façon dont Agent Control effectue le rendu de objects dépend de si Flux est activé :

• Avec Flux (par défaut, ou avec une installation Flux existante) : les types d’agent déclarent un objet HelmRelease. Agent Control convertit vos variables de configuration en valeurs de chart Helm pour ce HelmRelease, et crée ou met à jour la ressource. Flux réconcilie ensuite le chart, et crée les ressources sous-jacentes Deployment, ConfigMap, Secret, et autres ressources.
• Sans Flux : les types d’agents déclarent directement des objets Kubernetes simples (par exemple un ConfigMap, un Secret, ou un Deployment) au lieu d’un HelmRelease. Agent Control applique ces objets au cluster lui-même. Il n’y a pas de chart Helm, ni de réconciliation Flux impliquée. L’utilisateur doit gérer le cycle de vie de l’agent dans ce cas.

Déploiement sur l’hôte (Linux et Windows)

Sur les hôtes, Agent Control installe et exécute l’agent directement sur le système d’exploitation de la machine. La section de déploiement est composée de plusieurs sous-sections :

• executables: la liste des processus qu’Agent Control va démarrer, monitorer, et redémarrer. Un type d’agent sans cette section est traité comme une intégration gérée (OHI) : Agent Control gère ses artefacts, mais délègue l’exécution à un autre agent.
• enable_file_logging: si le logging de fichier est activé.
• health: comment Agent Control détermine si l’agent est sain, via la présence du processus, une vérification du point de terminaison HTTP, ou les deux.
• filesystem: fichiers ou répertoires individuels qu’Agent Control écrit sur l’hôte avant de démarrer l’agent, tels que des fichiers de configuration ou des certificats.
• shared_filesystem: les entrées écrites dans une zone de dépôt partagée accessible aux autres agents gérés par la même instance d’Agent Control. Utilisé par les types d’agent OHI pour transmettre leur configuration et leurs binaires à l’agent d’infrastructure.
• packages: artefacts OCI à télécharger avant le démarrage de l’agent — généralement le binaire de l’agent ou le package d’intégration.

Stockage de l'état de l'agent

Sur Kubernetes

L'état réside sous forme d'objets Kubernetes, mais la nature de ces objets dépend de l'activation de Flux.

Avec Flux (par défaut, ou avec une installation Flux existante), le type d’agent déclare généralement des ressources personnalisées Flux comme un HelmRepository pointant vers le chart, et un HelmRelease contenant votre configuration rendue sous forme de valeurs de chart Helm. Agent Control ne crée pas directement les objets Deployment, ConfigMap, ou Secret de l’agent. Il transmet le HelmRelease à Flux, et Flux installe le chart, et maintient ces ressources générées synchronisées avec celui-ci.

• Une mise à jour de configuration corrige le HelmRelease sur place. Agent Control ne réapplique l’objet que si son contenu a changé. Flux réconcilie ensuite le chart pour qu’il corresponde.
• La suppression d’un sous-agent supprime chaque objet étiqueté comme lui appartenant — son HelmRelease, HelmRepository, et tout Secret, ou ConfigMap créé pour lui, et Flux/Helm finalise le nettoyage des workload que ce chart avait installés.

Sans Flux, il n’y a pas de HelmRelease ou de HelmRepository. Le type d’agent déclare directement des objets Kubernetes simples, et Agent Control les crée et les met à jour lui-même. Il n’y a pas de chart Helm ni de réconciliation Flux. Dans ce mode, l’utilisateur est responsable du cycle de vie de l’agent. Agent Control n’installe ni ne met à niveau le Deployment de l’agent, il maintient uniquement synchronisés les objets de configuration qu’il gère.

• Une mise à jour de configuration corrige l’objet géré (ConfigMap/Secret) sur place. Agent Control ne le réapplique que si son contenu a changé. Comme il n’y a pas de réconciliation Flux, rien ne redémarre automatiquement l’agent pour prendre en compte la modification, à moins que l’agent lui-même ne la surveille.
• La suppression d’un sous-agent supprime chaque objet étiqueté comme lui appartenant — juste ses objets ConfigMap/Secret, puisqu’il n’y a pas de HelmRelease, de HelmRepository, ou de workload installé par un chart à nettoyer.

Sur l’hôte

Système de fichiers sur l’hôte

Chaque sous-agent obtient un répertoire dédié sur le disque où Agent Control écrit les fichiers déclarés par la section filesystem de son type d’agent.

Agent Control obtient le contenu pour créer un fichier à partir de variables de type yaml, et le contenu pour plusieurs fichiers dans un répertoire à partir de variables de type string_map.

Exemple

/var/lib/newrelic-agent-control/filesystem/nr-infra-agent/
├── newrelic-infra.yaml     # content from variable of type `yaml`
└── logging.d/              # content from variable of type `string_map`
    ├── file1.yaml
    └── file2.yaml

Le comportement de ce répertoire dépend de l’événement de cycle de vie et du type de variable derrière chaque chemin :

• Un redémarrage ne touche pas au répertoire. Agent Control ne réécrit rien à moins que le redémarrage n’ait été déclenché par une mise à jour de configuration provenant du contrôle de la flotte.
• Une mise à jour de configuration réécrit les fichiers yaml sur place, mais régénère entièrement les répertoires string_map. Pour un contenu yaml, Agent Control réécrit uniquement le contenu du fichier. Pour un contenu string_map, Agent Control supprime l’ensemble du répertoire (comme logging.d ci-dessus) et le recrée de zéro, de sorte que tout fichier que vous (ou le sous-agent) avez ajouté ou modifié à l’intérieur disparaît lors de la prochaine écriture.
• Les fichiers qu’Agent Control ne gère pas sont laissés intacts. Il n’écrase que les chemins exacts que le type d’agent déclare ; tout ce que l’agent en cours d’exécution crée par lui-même dans son répertoire (fichiers cache, état local) n’est pas touché.
• La suppression d’un sous-agent supprime l’intégralité de son répertoire, y compris tous les fichiers créés par le sous-agent lui-même, ou par un utilisateur.

Système de fichiers partagé sur l’hôte

La plupart des types d’agents sont autonomes : Agent Control écrit leur configuration dans un répertoire qui leur appartient en propre, et démarre un processus qui y lit les données. Mais certaines intégrations n’ont pas de modèle d’exécution propre. Il n’y a aucun processus à démarrer pour Agent Control. Elles dépendent entièrement d’un autre agent déjà en cours d’exécution (par exemple, l’agent d’infrastructure) pour récupérer leurs fichiers, et les exécuter. Cette dépendance est la raison pour laquelle un second emplacement partagé existe. Il s’agit d’une zone de dépôt commune dans laquelle tout sous-agent sur le même hôte peut écrire, et à partir de laquelle tout autre sous-agent peut lire, utilisée spécifiquement pour transmettre des artefacts entre les agents, plutôt que pour stocker l’état privé propre à un agent.

Utilisez filesystem pour tout ce dont le propre processus d’un type d’agent a besoin, et ne recourez à shared_filesystem que lorsqu’un type d’agent transmet délibérément des fichiers à un autre, comme l’intégration sur hôte décrite plus bas.

Tous les sous-agents obtiennent un répertoire partagé sur le disque où Agent Control écrit les fichiers déclarés par le shared_filesystem de son type d’agent.

Puisque tous les sous-agents ont accès à ce répertoire partagé, ils peuvent voir les fichiers des uns et des autres.

Exemple

/var/lib/newrelic-agent-control/shared_filesystem/
├── data/                  # All sub-agents can see `data` and `other-data` folders
│   └── file.yaml
└── other-data/
    └── file2.yaml

Le répertoire partagé suit les mêmes règles que le répertoire du système de fichiers par agent lors des redémarrages, des mises à jour de configuration, et des fichiers non gérés. Le comportement ne change que lors de la suppression d’un sous-agent : ses fichiers sont toujours supprimés, puisque chaque fichier appartient sans équivoque au sous-agent qui l’a écrit, mais les dossiers ne sont supprimés que lorsqu’aucun autre sous-agent ne les utilise.

Types d’agents liés sur l’hôte

Deux types d’agents sont liés lorsque l’un écrit des artefacts (configuration, binaires ou autres fichiers) dans le système de fichiers partagé et que l’autre est configuré pour lire à partir de ces mêmes chemins. L’agent d’écriture peut n’avoir aucune section executables, Agent Control gère ses artefacts mais ne démarre jamais de processus pour lui. Au lieu de cela, l’agent lecteur possède la logique intégrée pour découvrir et exécuter les binaires et la configuration à partir d’un chemin bien connu dans le système de fichiers partagé, exécutant ainsi l’extension pour le compte de l’agent d’écriture.

Les noms des sous-répertoires sont choisis par convention entre les types d’agents liés.

Intégrations sur hôte (OHI)

Les intégrations sur hôte (OHI) sont le principal exemple de types d’agents liés. Alors qu’un sous-agent classique possède un processus qu’Agent Control démarre et monitore, une OHI n’en a aucun. Agent Control gère uniquement son cycle de vie (son téléchargement, sa configuration, sa mise à niveau, et sa désinstallation), tandis que l’agent d’infrastructure découvre et exécute ses binaires à partir du système de fichiers partagé pour son compte.

La relation entre l’agent d’infrastructure et l’agent OHI

1. Lorsqu'un type d'agent OHI est installé, Agent Control télécharge le binaire d'intégration via OCI, et écrit deux entrées dans le système de fichiers partagé :

   • Un fichier de configuration sous infra-agent-ohi-configs/ (par ex. nri-redis.yaml)
   • Le binaire d’intégration sous infra-agent-ohi-binaries/ (par ex. nri-redis)

2. Le sous-agent de l’agent d’infrastructure est configuré avec des variables d’environnement qui le pointent vers ces répertoires partagés :

   Variable	Chemin du système de fichiers partagé	But
   NRIA_PLUGIN_DIR	…/infra-agent-ohi-configs	Découverte de la configuration de l’intégration
   NRIA_CUSTOM_PLUGIN_INSTALLATION_DIR	…/infra-agent-ohi-binaries	Découverte du binaire de l’intégration
   NRIA_SAFE_BIN_DIR	…/infra-agent-ohi-binaries	Chemin d'exécution de binaire autorisé

3. L’agent d’infrastructure récupère la configuration et le binaire lors de son prochain cycle d’analyse et commence à exécuter l’intégration.

   shared-filesystem/
   ├── infra-agent-ohi-configs/      # Integration YAML configs (read by NRIA_PLUGIN_DIR)
   │   ├── nri-redis.yaml
   │   └── nri-mysql.yaml
   └── infra-agent-ohi-binaries/     # Integration binaries (read by NRIA_CUSTOM_PLUGIN_INSTALLATION_DIR)
       ├── nri-redis
       └── nri-mysql

   Copier

Récupération des définitions de type d'agent

Agent Control récupère les définitions de type d’agent à partir d’un registre OCI distant, identifiées par le namespace, le name, et le version déclarés dans la section des métadonnées de la définition, en tenant compte de l’environnement dans lequel il s’exécute (Kubernetes, Linux, ou Windows).

Par défaut, Agent Control récupère depuis docker.io à l’aide du référentiel newrelic/agent-control-agent-types, après avoir vérifié la signature avec la clé publique de New Relic.

Les définitions de type d’agent peuvent être extraites d’un miroir, comme expliqué dans Configurer un miroir de registre OCI pour Agent Control.

Types d'agents pris en charge

Support actuel

Le tableau suivant indique les types d’agents pris en charge par Agent Control et leur disponibilité dans les différents environnements.

Autorisations requises par type d’agent

Le tableau suivant répertorie les autorisations clés requises par chaque type d’agent et les environnements dans lesquels il s’applique.

Configuration de Fluent Bit sur les hôtes

Sur les hôtes, Fluent Bit n’est pas déployé en tant que type d’agent de niveau supérieur à part entière (voir le tableau de prise en charge ci-dessus). Au lieu de cela, lorsque le transfert de logs est activé, Fluent Bit est généré et géré par l’ agent d’infrastructure New Relic lui-même, de la même manière que lorsqu’il est installé de façon autonome. Agent Control modifie uniquement l’ emplacement où l’agent d’infrastructure, ses données, ainsi que le binaire et le plug-in Fluent Bit résident sur le disque.

Pour savoir comment configurer le transfert de logs lui-même (syntaxe logging.d/*.yml, entrées, filtres, attributs, etc.), consultez :

• Activer la gestion des logs
• Transférer les logs avec Fluent Bit

Où placer votre configuration

Le seul détail spécifique à Agent Control est l’emplacement où vont les fichiers de transfert de logs : ils atterrissent dans le dossier logging.d du sous-agent, une entrée par source de log, via le champ config_logging de la configuration de l’agent d’infrastructure. Définissez-le directement dans la configuration du sous-agent (par exemple, son local_config.yaml) et envoyez-le à Agent Control :

config_logging:
  syslog.yaml: |
    logs:
      - name: syslog
        file: /var/log/syslog
        attributes:
          logtype: linux_syslog
  app.yaml: |
    logs:
      - name: app-log
        file: /var/log/app.log
        attributes:
          service: api
          env: production

Où réside Fluent Bit et comment il est mis à jour