APIs y CLI

Fleet Control proporciona un acceso programático integral a través de API y una interfaz de línea de comandos, lo que le permite automatizar las operaciones de la flota, integrarse con las herramientas existentes y gestionar su instrumentación a escala sin depender de la interfaz de usuario.

Opciones de acceso programático

Fleet Control ofrece tres métodos para el acceso programático:

• NerdGraph API: Para operaciones de gestión de flotas, incluida la creación de flotas, la administración de miembros y el control de despliegues
• API de Blob Storage: Para operaciones de configuración del agente, incluidas la creación, el versionado y la recuperación de configuraciones
• Fleet Control CLI: Para la gestión interactiva de la línea de comandos y scripts de automatización

Cuándo usar API vs. CLI

Comprender qué método de acceso se adapta mejor a su caso de uso le ayudará a trabajar de manera más eficiente con Fleet Control.

APIs (NerdGraph + API de Blob Storage)

Las API son mejores para:

• Automatización e integración: Incorporación de las operaciones de Fleet Control en pipelines de CI/CD, herramientas personalizadas u otros flujos de trabajo automatizados
• Infraestructura como código: Gestionar las configuraciones de la flota junto con las definiciones de su infraestructura
• Integración de sistema a sistema: Conectar Fleet Control con otras plataformas, sistemas de tickets o herramientas de orquestación
• Flujos de trabajo complejos: Creación de automatización sofisticada que combina múltiples operaciones o se integra con fuentes de datos externas
• Acceso programático: Cuando necesite integrar capacidades de Control de flotas en sus propias aplicaciones o servicios

Fleet Control CLI

La CLI es ideal para:

• Operaciones interactivas: Tareas rápidas dirigidas por humanos desde la línea de comandos
• Gestión ad hoc: Operaciones administrativas puntuales o solución de problemas
• Flujos de trabajo basados en la terminal: Si prefiere trabajar directamente en su terminal
• Pruebas locales: Experimentar con las operaciones de la flota antes de automatizarlas
• Scripts de shell: Operaciones secuenciales simples (aunque las API pueden ser mejores para la automatización compleja)
• Aprendizaje y exploración: La CLI proporciona retroalimentación inmediata y estructurada que le ayuda a comprender las operaciones de Fleet Control

La CLI está construida sobre las mismas API, por lo que funcionalmente proporcionan las mismas capacidades. La elección depende de la preferencia de interfaz y del caso de uso: la CLI para la interacción humana y la conveniencia, y las API para la integración programática y la automatización.

API de NerdGraph (Operaciones de flota)

NerdGraph es la API de GraphQL de New Relic que proporciona acceso a las operaciones de Fleet Control para gestionar flotas, miembros y despliegues. A diferencia de las configuraciones del agente (que utilizan la API de Blob Storage), todas las operaciones a nivel de flota utilizan NerdGraph.

Acceder al NerdGraph Explorer

El NerdGraph Explorer es un IDE de GraphQL interactivo donde puede descubrir las API de Fleet Control disponibles, crear consultas y probar operaciones.

Para acceder al NerdGraph Explorer:

1. Ve al NerdGraph Explorer de tu región:

   • Región de EE. UU.: https://one.newrelic.com/nerdgraph-graphiql
   • Región UE: https://one.eu.newrelic.com/nerdgraph-graphiql

2. Ingrese su clave de API de usuario cuando se le solicite. Esto inicia el explorador de API con acceso limitado a su cuenta.

3. En el panel izquierdo, expanda mutation y navegue a fleetControl para ver todas las operaciones disponibles de Fleet Control.

Mutaciones de Fleet Control disponibles

La API de NerdGraph proporciona las siguientes mutaciones de Fleet Control:

Gestión de flotas

• fleetControlCreateFleet - Crear una nueva flota
• fleetControlUpdateFleet - Actualizar las propiedades de una flota existente
• fleetControlDeleteFleet - Eliminar una flota

Gestión de miembros de la flota

• fleetControlAddFleetMembers - Agregar entidades administradas a un anillo de flota
• fleetControlRemoveFleetMembers - Eliminar entidades administradas de un anillo de flota

Gestión de despliegues

• fleetControlCreateFleetDeployment - Crear un nuevo despliegue para una flota
• fleetControlUpdateFleetDeployment - Actualizar un despliegue existente
• fleetControlDeleteFleetDeployment - Eliminar un despliegue
• fleetControlDeploy - Active un despliegue para implementar en los anillos de la flota

Autenticación

Todas las solicitudes de la API de NerdGraph requieren autenticación mediante una clave de API de usuario de New Relic. Para generar una clave de API:

1. Vaya a one.newrelic.com
2. Haga clic en su nombre en la esquina inferior izquierda
3. Selecciona API Keys
4. Crea una clave de User (no una clave de Browser o Licence)

Incluya su clave de API en los encabezados de la solicitud al realizar llamadas a la API fuera del NerdGraph Explorer.

Para obtener más información sobre el uso de NerdGraph, consulta nuestra documentación Introducción a NerdGraph.

API de Blob Storage (configuraciones del agente)

La API de Blob Storage es una interfaz RESTful diseñada específicamente para administrar configuraciones de agentes dentro de Fleet Control. Esta API gestiona todas las operaciones relacionadas con la configuración, incluida la creación de configuraciones, el versionado, la recuperación de contenido y la eliminación.

Endpoint base

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

Autenticación

Todas las solicitudes de la API de Blob Storage requieren autenticación mediante el encabezado Api-Key con su clave de API de usuario de New Relic:

Api-Key: your-user-api-key

Operaciones clave

La API de Blob Storage admite las siguientes operaciones para las configuraciones de agentes:

Crear configuración del agente

Crea una nueva configuración de agente en una organización.

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

Encabezados requeridos:

• Api-Key - Su clave de API de usuario
• Content-Type - application/x-yaml
• NewRelic-Entity - JSON con metadatos de configuración (name, agentType, managedEntityType, configurationType)

Cuerpo de la solicitud: Contenido de texto plano de la configuración del agente (formato YAML)

Crear versión de configuración del agente

Crea una nueva versión de una configuración de agente existente.

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

Encabezados requeridos:

• Api-Key - Su clave de API de usuario
• Content-Type - application/x-yaml

Cuerpo de la solicitud: Contenido de texto plano de la nueva versión de la configuración (formato YAML)

Nota: El ID de la configuración principal se especifica en la ruta de la URL. No se requiere el encabezado NewRelic-Entity para crear versiones.

Obtener contenido de la versión de configuración

Recupera el contenido de una versión de configuración específica.

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

Encabezados requeridos:

• Api-Key - Su clave de API de usuario

Respuesta: Devuelve el contenido de la configuración como texto plano/YAML

Eliminar versión de configuración

Elimina una versión de configuración específica.

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

Encabezados requeridos:

• Api-Key - Su clave de API de usuario

Respuesta: estado 2xx para eliminación exitosa, 404 si no se encuentra la versión de configuración

Valores de campo válidos

Al crear configuraciones de agentes, deberá especificar valores válidos para ciertos campos:

Tipos de agentes

Se admiten los siguientes tipos de agentes:

Agentes de infraestructura (para los tipos de entidades administradas HOST y KUBERNETESCLUSTER):

• NRInfra - Agente de New Relic Infrastructure
• NRDOT - Distribución de New Relic del Colector de OpenTelemetry
• FluentBit - Agente de logging Fluent Bit
• NRPrometheusAgent - Agente de Prometheus
• PipelineControlGateway - Gateway de Pipeline Control
• NRApmOperator - Operador de APM para Kubernetes
• NReBPFAgent - agente eBPF

Agentes de aplicación (para el tipo de entidad administrada APPLICATION):

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

Tipos de entidades gestionadas

• HOST - Entidades de host/servidor individuales (solo pueden usar agentes de infraestructura)
• KUBERNETESCLUSTER - Entidades del clúster de Kubernetes (solo pueden usar agentes de infraestructura)
• APPLICATION - Entidades de aplicación (solo pueden usar Agentes de aplicación)

Tipo de configuración

• Instrumentation - Actualmente, el único tipo de configuración admitido

Mejores practicas

• Verifique siempre los códigos de estado HTTP: La API devuelve 200 para operaciones exitosas
• Almacene los GUID de entidad devueltos: Los necesitará para las operaciones de versionado y eliminación
• Validar el formato JSON: Asegúrese de que el formato JSON sea correcto en el encabezado NewRelic-Entity
• Verifique la compatibilidad del tipo de agente: Asegúrese de que su tipo de agente sea compatible con el tipo de entidad gestionada
• Utilice el Content-Type correcto: Utilice siempre application/x-yaml para el contenido de configuración
• Proteja su clave de API: Nunca exponga su clave de API de usuario en el código del lado del cliente o en repositorios públicos

Fleet Control CLI

La CLI de Fleet Control es una interfaz de línea de comandos integral para administrar todas las entidades de Fleet Control, incluidas flotas, configuraciones, despliegues, miembros y consultas de entidades. La CLI proporciona un flujo de trabajo estructurado basado en la terminal tanto para operaciones interactivas como para la automatización.

Jerarquía de comandos

Los comandos de Fleet Control están organizados por tipo de recurso para una navegación intuitiva:

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

Capacidades clave

La CLI de Fleet Control le permite:

• Centralice las operaciones de los agentes: Instale, monitoree, configure y actualice todos los agentes e integraciones desde la línea de comandos
• Gestionar flotas: Agrupe las entidades por necesidades de instrumentación y actualice las versiones del agente para flotas completas
• Cree y versione configuraciones: Cree configuraciones de agentes y administre múltiples versiones
• Controle los despliegues: Cree, actualice y active despliegues con lanzamientos basados en anillos
• Consultar entidades: Liste las entidades gestionadas y no asignadas para comprender el panorama de su flota

Requisitos previos

Antes de utilizar los comandos de la CLI de Fleet Control, necesitará:

Variables de entorno requeridas:

$
# 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

Obtener sus credenciales:

1. Clave de API: Genere una clave de API de usuario desde one.newrelic.com → Haga clic en su nombre → API Keys → Create a "User" key
2. ID de cuenta: Busca tu ID de cuenta en la URL de New Relic después de /accounts/ o en la configuración de la cuenta
3. ID de la organización: La mayoría de los comandos aceptan un indicador --organization-id opcional. Si no se proporciona, la CLI obtendrá automáticamente el ID de su organización utilizando sus credenciales de API.

Documentación completa de la CLI

Para comenzar con New Relic CLI, incluida la instalación y la configuración, consulte el repositorio de New Relic CLI.

Para obtener una referencia detallada de los comandos de Fleet Control, los formatos de respuesta, las reglas de validación y la guía de solución de problemas, consulta el README de la CLI de Fleet Control.

La documentación de la CLI incluye:

• Referencia completa de comandos para todas las operaciones
• Especificaciones del formato de respuesta
• Trabajar con respuestas JSON usando jq
• Ejemplos prácticos de flujos de trabajo
• Reglas de validación y valores permitidos
• Solución de problemas comunes
• Sintaxis de flags y patrones de uso

Primeros pasos con el acceso programático

Para comenzar a usar Fleet Control programáticamente:

1. Generate a User API Key desde la configuración de tu cuenta de New Relic

2. Identifique su ID de cuenta y su ID de organización en la plataforma de New Relic

3. Seleccione su método de acceso:

   • Use el NerdGraph Explorer para explorar las operaciones de la flota de forma interactiva
   • Revise las operaciones de la Blob Storage API para la gestión de la configuración
   • Instale y configure Fleet Control CLI para flujos de trabajo basados en terminal

4. Comience con operaciones de lectura para familiarizarse con las estructuras de datos (buscar flotas, listar entidades, obtener configuraciones)

5. Construya la automatización gradualmente combinando operaciones en scripts o flujos de trabajo

Para obtener ayuda adicional con las API, consulta nuestra documentación de Introducción a NerdGraph y la documentación de claves de API.