API et CLI

Fleet Control offre un accès programmatique complet via des API et une interface en ligne de commande, vous permettant d'automatiser les opérations de flotte, de vous intégrer aux outils existants et de gérer votre instrumentation à grande échelle sans dépendre de l'interface utilisateur.

Options d'accès par programmation

Fleet Control offre trois méthodes d'accès programmatique :

• API NerdGraph : Pour les opérations de gestion de flotte, y compris la création de flottes, la gestion des membres et le contrôle des déploiements
• API Blob Storage : Pour les opérations de configuration de l'agent, notamment la création, la gestion des versions et la récupération des configurations
• Fleet Control CLI : Pour la gestion interactive en ligne de commande et les scripts d'automatisation

Quand utiliser les API vs la CLI

Comprendre quelle méthode d'accès est la mieux adaptée à votre cas d'utilisation vous aidera à travailler plus efficacement avec Fleet Control.

API (NerdGraph + API Blob Storage)

Les API sont idéales pour :

• Automatisation et intégration : Intégration des opérations de Fleet Control dans les pipelines CI/CD, les outils personnalisés ou d'autres workflows automatisés
• Infrastructure as Code : Gérer les configurations de flotte parallèlement à vos définitions d'infrastructure
• Intégration système à système : connexion de Fleet Control à d'autres plateformes, systèmes de gestion de tickets ou outils d'orchestration
• Workflows complexes : Création d'une automatisation sophistiquée combinant plusieurs opérations ou s'intégrant à des sources de données externes
• Accès programmatique : Lorsque vous devez intégrer les fonctionnalités de Fleet Control à vos propres applications ou services

Fleet Control CLI

La CLI est idéale pour :

• Opérations interactives : Tâches rapides, pilotées par l'humain, depuis la ligne de commande
• Gestion ad hoc : Opérations administratives ponctuelles ou dépannage
• Workflows basés sur le terminal : Si vous préférez travailler directement dans votre terminal
• Tests locaux : Expérimenter les opérations de flotte avant de les automatiser
• Scripts shell : Opérations séquentielles simples (bien que les API soient plus adaptées pour une automatisation complexe)
• Apprentissage et exploration : La CLI fournit un retour immédiat et structuré qui vous aide à comprendre les opérations de Fleet Control

La CLI repose sur les mêmes API, elles offrent donc fonctionnellement les mêmes capacités. Le choix dépend de la préférence d'interface et du cas d'utilisation : la CLI pour l'interaction humaine et la praticité, les API pour l'intégration programmatique et l'automatisation.

API NerdGraph (Opérations sur la flotte)

NerdGraph est l'API GraphQL de New Relic qui permet d'accéder aux opérations de Fleet Control pour gérer les flottes, les membres et les déploiements. Contrairement aux configurations de l'agent (qui utilisent l'API Blob Storage), toutes les opérations au niveau du parc utilisent NerdGraph.

Accéder au NerdGraph Explorer

Le NerdGraph Explorer est un IDE GraphQL interactif où vous pouvez découvrir les API Fleet Control disponibles, créer des requêtes et tester des opérations.

Pour accéder au NerdGraph Explorer :

1. Accédez au NerdGraph Explorer pour votre région :

   • Région États-Unis : https://one.newrelic.com/nerdgraph-graphiql
   • Région UE : https://one.eu.newrelic.com/nerdgraph-graphiql

2. Saisissez votre clé d'API utilisateur lorsque vous y êtes invité. Cela lance l'explorateur d'API avec un accès limité à votre compte.

3. Dans le volet de gauche, développez mutation et accédez à fleetControl pour afficher toutes les opérations Fleet Control disponibles.

Mutations Fleet Control disponibles

L'API NerdGraph fournit les mutations Fleet Control suivantes :

Gestion de flotte

• fleetControlCreateFleet - Créer une nouvelle flotte
• fleetControlUpdateFleet - Mettre à jour les propriétés d'une flotte existante
• fleetControlDeleteFleet - Supprimer une flotte

Gestion des membres de Fleet

• fleetControlAddFleetMembers - Ajouter des entités gérées à un anneau de flotte
• fleetControlRemoveFleetMembers - Retirer des entités gérées d'un anneau de flotte

Gestion des déploiements

• fleetControlCreateFleetDeployment - Créer un nouveau déploiement pour une flotte
• fleetControlUpdateFleetDeployment - Mettre à jour un déploiement existant
• fleetControlDeleteFleetDeployment - Supprimer un déploiement
• fleetControlDeploy - Déclencher un déploiement à diffuser sur les anneaux de la flotte

Authentification

Toutes les requêtes de l'API NerdGraph nécessitent une authentification à l'aide d'une clé d'API utilisateur New Relic. Pour générer une clé API :

1. Allez sur one.newrelic.com
2. Cliquez sur votre nom dans le coin inférieur gauche
3. Sélectionnez API Keys
4. Créez une clé User (et non une clé Browser ou Licence)

Incluez votre clé d'API dans les en-têtes de requête lorsque vous effectuez des appels API en dehors du NerdGraph Explorer.

Pour plus d'informations sur l'utilisation de NerdGraph, consultez notre documentation Introduction à NerdGraph.

API Blob Storage (configurations de l'Agent)

L'API Blob Storage est une interface RESTful spécifiquement conçue pour gérer les configurations des agents dans Fleet Control. Cette API gère toutes les opérations liées à la configuration, y compris la création de configurations, la gestion des versions, la récupération de contenu et la suppression.

Point de terminaison de base

https://blob-api.service.newrelic.com/v1/e

Authentification

Toutes les requêtes de l'API Blob Storage nécessitent une authentification via l'en-tête Api-Key avec votre clé d'API utilisateur New Relic :

Api-Key: your-user-api-key

Opérations clés

L'API Blob Storage prend en charge les opérations suivantes pour les configurations d'agent :

Créer une configuration d'agent

Crée une nouvelle configuration d'agent dans une organisation.

POST /v1/e/organizations/{orgId}/AgentConfigurations

En-têtes requis :

• Api-Key - Votre clé API utilisateur
• Content-Type - application/x-yaml
• NewRelic-Entity - JSON avec métadonnées de configuration (name, agentType, managedEntityType, configurationType)

Corps de la requête : Contenu en texte brut de la configuration de l'agent (format YAML)

Créer une version de configuration de l'agent

Crée une nouvelle version d'une configuration d'agent existante.

POST /v1/e/organizations/{orgId}/AgentConfigurations/{parentConfigurationId}

En-têtes requis :

• Api-Key - Votre clé API utilisateur
• Content-Type - application/x-yaml

Corps de la requête : Contenu en texte brut de la nouvelle version de configuration (format YAML)

Remarque : L'ID de la configuration parente est indiqué dans le chemin de l'URL. Aucun en-tête NewRelic-Entity n'est requis pour créer des versions.

Obtenir le contenu de la version de configuration

Récupère le contenu d'une version de configuration spécifique.

GET /v1/e/organizations/{orgId}/AgentConfigurationVersions/{configurationVersionId}

En-têtes requis :

• Api-Key - Votre clé API utilisateur

Réponse : Renvoie le contenu de la configuration au format texte brut/YAML

Supprimer la version de configuration

Supprime une version de configuration spécifique.

DELETE /v1/e/organizations/{orgId}/AgentConfigurationVersions/{configVersionGuid}

En-têtes requis :

• Api-Key - Votre clé API utilisateur

Réponse : statut 2xx pour une suppression réussie, 404 si la version de configuration est introuvable

Valeurs de champ valides

Lors de la création de configurations d'agent, vous devez spécifier des valeurs valides pour certains champs :

Types d'agents

Les types d'agents suivants sont pris en charge :

Agents d'infrastructure (pour les types d'entités gérées HOST et KUBERNETESCLUSTER) :

• NRInfra - Agent New Relic Infrastructure
• NRDOT - Distribution New Relic du collecteur OpenTelemetry
• FluentBit - Agent de logging Fluent Bit
• NRPrometheusAgent - Agent Prometheus
• PipelineControlGateway - Gateway de contrôle de pipeline
• NRApmOperator - Opérateur APM pour Kubernetes
• NReBPFAgent - Agent eBPF

Agents d'application (pour le type d'entité gérée APPLICATION) :

• NRJavaAgent - Agent APM Java
• NRPythonAgent - Agent APM Python
• NRNodeAgent - Agent APM Node.js
• NRRubyAgent - Agent APM Ruby
• NRDotNetAgent - Agent APM .NET

Types d'entités gérées

• HOST - Entités hôtes/serveurs individuelles (peuvent uniquement utiliser des agents d'infrastructure)
• KUBERNETESCLUSTER - Entités de cluster Kubernetes (ne peuvent utiliser que des agents d'infrastructure)
• APPLICATION - Entités d'application (ne peuvent utiliser que des Agents d'application)

Type de configuration

• Instrumentation - Actuellement le seul type de configuration pris en charge

Meilleures pratiques

• Vérifiez toujours les codes d'état HTTP : L'API renvoie 200 pour les opérations réussies
• Stockez les GUID d'entité renvoyés : vous en aurez besoin pour les opérations de gestion des versions et de suppression
• Validez le formatage JSON : Assurez-vous que le formatage JSON est correct dans l'en-tête NewRelic-Entity
• Vérifiez la compatibilité du type d'agent : Assurez-vous que votre type d'agent est compatible avec le type d'entité gérée
• Utilisez le Content-Type approprié : Utilisez toujours application/x-yaml pour le contenu de configuration
• Sécurisez votre clé API : N'exposez jamais votre clé API utilisateur dans le code côté client ou dans des dépôts publics

Fleet Control CLI

La CLI Fleet Control est une interface en ligne de commande complète pour gérer toutes les entités Fleet Control, y compris les flottes, les configurations, les déploiements, les membres et les requêtes d'entités. La CLI fournit un workflow structuré basé sur le terminal, tant pour les opérations interactives que pour l'automatisation.

Hiérarchie des commandes

Les commandes de Fleet Control sont organisées par type de ressource pour une navigation intuitive :

newrelic fleetcontrol
├── fleet                    # Fleet management
│   ├── create              # Create a new fleet
│   ├── get                 # Get fleet details
│   ├── search              # Search fleets
│   ├── update              # Update fleet
│   ├── delete              # Delete fleet(s)
│   └── members             # Manage fleet members
│       ├── add             # Add entities to ring
│       ├── remove          # Remove entities from ring
│       └── list            # List fleet members
│
├── configuration            # Configuration management
│   ├── create              # Create configuration
│   ├── get                 # Get configuration content
│   ├── delete              # Delete configuration
│   └── versions            # Manage configuration versions
│       ├── list            # List all versions
│       ├── add             # Add new version
│       └── delete          # Delete specific version
│
├── deployment               # Deployment management
│   ├── create              # Create deployment
│   ├── update              # Update deployment
│   ├── deploy              # Trigger deployment
│   └── delete              # Delete deployment
│
└── entities                 # Entity queries
    ├── get-managed         # List managed entities
    └── get-unassigned      # List available entities

Fonctionnalités clés

La CLI Fleet Control vous permet de :

• Centralisez les opérations des agents : Installez, supervisez, configurez et mettez à jour tous les agents et intégrations depuis la ligne de commande
• Gérer les flottes : Regroupez les entités par besoins d'instrumentation et mettez à jour les versions de l'agent pour des flottes entières
• Créer et versionner des configurations : Créez des configurations d'agent et gérez plusieurs versions
• Contrôlez les déploiements : créez, mettez à jour et déclenchez des déploiements avec des déploiements par anneaux
• Interroger les entités : Listez les entités gérées et non assignées pour comprendre le paysage de votre parc.

Prérequis

Avant d'utiliser les commandes CLI Fleet Control, vous aurez besoin de :

Variables d'environnement requises :

$
# Your New Relic User API Key
$
export NEW_RELIC_API_KEY="NRAK-YOUR-API-KEY-HERE"
$

$
# Your New Relic Account ID
$
export NEW_RELIC_ACCOUNT_ID="your-account-id"
$

$
# Optional: Specify region (defaults to US)
$
export NEW_RELIC_REGION="US"  # or "EU" for European accounts

Obtenir vos identifiants :

1. Clé d'API : générez une clé d'API utilisateur depuis one.newrelic.com → Cliquez sur votre nom → API Keys → Create a "User" key
2. ID de compte : Trouvez votre ID de compte dans l'URL New Relic après /accounts/ ou dans les paramètres du compte
3. ID d'organisation : La plupart des commandes acceptent un flag --organization-id facultatif. S'il n'est pas fourni, la CLI récupérera automatiquement votre ID d'organisation à l'aide de vos identifiants API.

Documentation complète de la CLI

Pour commencer avec la CLI New Relic, y compris l'installation et la configuration, consultez le dépôt New Relic CLI.

Pour une référence détaillée des commandes Fleet Control, les formats de réponse, les règles de validation et des conseils de dépannage, consultez le README de la CLI Fleet Control.

La documentation de la CLI comprend :

• Référence complète des commandes pour toutes les opérations
• Spécifications du format de réponse
• Travailler avec des réponses JSON en utilisant jq
• Exemples pratiques de workflow
• Règles de validation et valeurs autorisées
• Dépannage des problèmes courants
• Syntaxe des flags et modèles d'utilisation

Débuter avec l'accès programmatique

Pour commencer à utiliser Fleet Control par programmation :

1. Generate a User API Key depuis les paramètres de votre compte New Relic

2. Identifiez votre ID de compte et votre ID d'organisation depuis la plateforme New Relic

3. Choisissez votre méthode d'accès :

   • Utilisez le NerdGraph Explorer pour explorer les opérations du parc de manière interactive
   • Passez en revue les opérations de Blob Storage API pour la gestion de la configuration
   • Installer et configurer la Fleet Control CLI pour les workflows basés sur le terminal

4. Commencez par des opérations de lecture pour vous familiariser avec les structures de données (rechercher des flottes, lister des entités, obtenir des configurations)

5. Automatisez progressivement en combinant des opérations dans des scripts ou des workflows

Pour plus d'aide sur les API, consultez notre documentation Introduction à NerdGraph et notre documentation sur les clés d'API.