APIs e CLI

O Fleet Control oferece acesso programático abrangente por meio de APIs e de uma interface de linha de comando, permitindo automatizar as operações de frota, integrar-se às ferramentas existentes e gerenciar sua instrumentação em escala sem depender da interface do usuário.

Opções de acesso programático

O Fleet Control oferece três métodos para acesso programático:

• API NerdGraph: Para operações de gerenciamento de frotas, incluindo criar frotas, gerenciar membros e controlar implantações
• API de Blob Storage: Para operações de configuração do agente, incluindo criação, versionamento e recuperação de configurações
• Fleet Control CLI: Para gerenciamento interativo de linha de comando e scripts de automação

Quando usar APIs vs. CLI

Entender qual método de acesso melhor se adapta ao seu caso de uso ajudará você a trabalhar com mais eficiência com o Fleet Control.

APIs (NerdGraph + API de Blob Storage)

As APIs são melhores para:

• Automação e integração: Incorporar operações do Fleet Control em pipelines de CI/CD, ferramentas personalizadas ou outros fluxos de trabalho automatizados
• Infraestrutura como Código: Gerenciamento de configurações de frota juntamente com suas definições de infraestrutura
• Integração sistema a sistema: Conectando o Fleet Control a outras plataformas, sistemas de tickets ou ferramentas de orquestração
• Fluxos de trabalho complexos: Criação de automação sofisticada que combina múltiplas operações ou se integra a fontes de dados externas
• Acesso programático: Quando você precisa incorporar recursos do Fleet Control aos seus próprios aplicativos ou serviços

CLI do Fleet Control

A CLI é melhor para:

• Operações interativas: Tarefas rápidas, conduzidas por humanos, a partir da linha de comando
• Gerenciamento ad-hoc: Operações administrativas pontuais ou solução de problemas
• Fluxos de trabalho baseados em terminal: Se você prefere trabalhar diretamente no seu terminal
• Teste local: Experimentar operações de frota antes de automatizá-las
• Scripts de shell: Operações sequenciais simples (embora APIs possam ser melhores para automação complexa)
• Aprendizado e exploração: A CLI fornece feedback imediato e estruturado que ajuda você a entender as operações do Fleet Control

A CLI é construída sobre as mesmas APIs, portanto, funcionalmente, elas oferecem os mesmos recursos. A escolha é sobre preferência de interface e caso de uso: CLI para interação humana e conveniência, APIs para integração programática e automação.

API NerdGraph (Operações de frota)

O NerdGraph é a API GraphQL da New Relic que fornece acesso às operações do Fleet Control para gerenciar frotas, membros e implantações. Diferentemente das configurações de agente (que utilizam a API do Blob Storage), todas as operações em nível de frota utilizam o NerdGraph.

Acessando o NerdGraph Explorer

O NerdGraph Explorer é um IDE GraphQL interativo onde você pode descobrir APIs do Fleet Control disponíveis, criar consultas e testar operações.

Para acessar o NerdGraph Explorer:

1. Navegue até o NerdGraph Explorer para a sua região:

   • Região dos EUA: https://one.newrelic.com/nerdgraph-graphiql
   • Região da UE: https://one.eu.newrelic.com/nerdgraph-graphiql

2. Insira sua Chave de API de Usuário quando solicitado. Isso inicia o explorador de API com acesso no escopo da sua conta.

3. No painel esquerdo, expanda mutation e navegue até fleetControl para ver todas as operações disponíveis do Fleet Control.

Mutações disponíveis do Fleet Control

A API NerdGraph fornece as seguintes mutações do Fleet Control:

Gerenciamento de frota

• fleetControlCreateFleet - Criar uma nova frota
• fleetControlUpdateFleet - Atualizar as propriedades de uma frota existente
• fleetControlDeleteFleet - Excluir uma frota

Gerenciamento de membros da frota

• fleetControlAddFleetMembers - Adicionar entidades gerenciadas a um anel de frota
• fleetControlRemoveFleetMembers - Remover entidades gerenciadas de um anel de frota

Gerenciamento de implantação

• fleetControlCreateFleetDeployment - Criar uma nova implantação para uma frota
• fleetControlUpdateFleetDeployment - Atualizar uma implantação existente
• fleetControlDeleteFleetDeployment - Excluir uma implantação
• fleetControlDeploy - Acione uma implantação para distribuir aos anéis de frota

Autenticação

Todas as solicitações da API NerdGraph exigem autenticação usando uma chave de API de usuário do New Relic. Para gerar uma chave de API:

1. Acesse one.newrelic.com
2. Clique em seu nome no canto inferior esquerdo
3. Selecione API Keys
4. Crie uma chave de User (não uma chave de Browser ou de Licence)

Inclua sua chave de API nos cabeçalhos da solicitação ao fazer chamadas de API fora do NerdGraph Explorer.

Para mais informações sobre o uso do NerdGraph, consulte nossa documentação Introdução ao NerdGraph.

API do Blob Storage (Configurações do agente)

A API Blob Storage é uma interface RESTful projetada especificamente para gerenciar configurações de agentes no Fleet Control. Esta API gerencia todas as operações relacionadas à configuração, incluindo criação de configurações, versionamento, recuperação de conteúdo e exclusão.

Endpoint base

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

Autenticação

Todas as solicitações da API de Blob Storage exigem autenticação via cabeçalho Api-Key com sua chave de API de usuário da New Relic:

Api-Key: your-user-api-key

Principais operações

A API do Blob Storage suporta as seguintes operações para configurações de agente:

Criar configuração do agente

Cria uma nova configuração de agente em uma organização.

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

Cabeçalhos obrigatórios:

• Api-Key - Sua Chave de API de Usuário
• Content-Type - application/x-yaml
• NewRelic-Entity - JSON com metadados de configuração (name, agentType, managedEntityType, configurationType)

Corpo da requisição: Conteúdo em texto simples da configuração do agente (formato YAML)

Criar versão da configuração do agente

Cria uma nova versão de uma configuração de agente existente.

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

Cabeçalhos obrigatórios:

• Api-Key - Sua Chave de API de Usuário
• Content-Type - application/x-yaml

Corpo da requisição: Conteúdo em texto simples da nova versão de configuração (formato YAML)

Nota: O ID da configuração pai é especificado no caminho da URL. Nenhum cabeçalho NewRelic-Entity é necessário para criar versões.

Obter conteúdo da versão de configuração

Recupera o conteúdo de uma versão de configuração específica.

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

Cabeçalhos obrigatórios:

• Api-Key - Sua Chave de API de Usuário

Resposta: Retorna o conteúdo da configuração como texto simples/YAML

Excluir versão de configuração

Exclui uma versão de configuração específica.

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

Cabeçalhos obrigatórios:

• Api-Key - Sua Chave de API de Usuário

Resposta: status 2xx para exclusão bem-sucedida, 404 se a versão da configuração não for encontrada

Valores de campo válidos

Ao criar configurações de agente, você precisará especificar valores válidos para determinados campos:

Tipos de agente

Os seguintes tipos de agente são suportados:

Agentes de infraestrutura (para tipos de entidade gerenciada HOST e KUBERNETESCLUSTER):

• NRInfra - Agente do New Relic Infrastructure
• NRDOT - Distribuição New Relic do OpenTelemetry Collector
• FluentBit - Agente de log do Fluent Bit
• NRPrometheusAgent - Agente do Prometheus
• PipelineControlGateway - Gateway de Controle de Pipeline
• NRApmOperator - APM Operator para Kubernetes
• NReBPFAgent - agente eBPF

Agentes de Aplicação (para o tipo de entidade gerenciada APPLICATION):

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

Tipos de entidades gerenciadas

• HOST - Entidades de host/servidor individuais (podem usar apenas Agentes de Infraestrutura)
• KUBERNETESCLUSTER - Entidades do cluster Kubernetes (podem usar apenas Agentes de Infraestrutura)
• APPLICATION - Entidades de aplicação (podem usar apenas Agentes de Aplicação)

Tipo de configuração

• Instrumentation - Atualmente, o único tipo de configuração suportado

Práticas medidas

• Sempre verifique os códigos de status HTTP: A API retorna 200 para operações bem-sucedidas
• Armazene os GUIDs de entidade retornados: Você precisará deles para operações de versionamento e exclusão
• Valide a formatação JSON: Garanta a formatação JSON adequada no cabeçalho NewRelic-Entity
• Verifique a compatibilidade do tipo de agente: Certifique-se de que seu tipo de agente é compatível com o tipo de entidade gerenciada
• Use o Content-Type correto: Sempre use application/x-yaml para conteúdo de configuração
• Proteja sua Chave de API: Nunca exponha sua Chave de API de Usuário em código do lado do cliente ou repositórios públicos

CLI do Fleet Control

A CLI do Fleet Control é uma interface de linha de comando abrangente para gerenciar todas as entidades do Fleet Control, incluindo frotas, configurações, implantações, membros e consultas de entidades. A CLI fornece um fluxo de trabalho estruturado e baseado em terminal tanto para operações interativas quanto para automação.

Hierarquia de comandos

Os comandos do Fleet Control são organizados por tipo de recurso para uma navegação 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

Principais capacidades

A CLI do Fleet Control permite que você:

• Centralize as operações do agente: Instale, monitore, configure e atualize todos os agentes e integrações a partir da linha de comando
• Gerencie frotas: Agrupe entidades por necessidades de instrumentação e atualize as versões do agente para frotas inteiras
• Crie e versione configurações: Crie configurações do agente e gerencie múltiplas versões
• Controle implantações: Crie, atualize e acione implantações com rollouts baseados em anéis
• Consultar entidades: Liste entidades gerenciadas e não atribuídas para entender o panorama da sua frota

Pré-requisitos

Antes de usar os comandos da CLI do Fleet Control, você precisará:

Variáveis de ambiente obrigatórias:

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

Obtendo suas credenciais:

1. Chave de API: Gere uma chave de API de usuário no one.newrelic.com → Clique no seu nome → API Keys → Create a "User" key
2. ID da conta: Encontre o ID da sua conta na URL do New Relic após /accounts/ ou nas configurações da conta
3. ID da organização: A maioria dos comandos aceita uma flag --organization-id opcional. Se não fornecido, a CLI buscará automaticamente o ID da sua organização usando suas credenciais de API.

Documentação completa da CLI

Para começar com a New Relic CLI, incluindo instalação e configuração, consulte o repositório da New Relic CLI.

Para referência detalhada de comandos do Fleet Control, formatos de resposta, regras de validação e orientações de solução de problemas, consulte o README da CLI do Fleet Control.

A documentação da CLI inclui:

• Referência completa de comandos para todas as operações
• Especificações do formato de resposta
• Trabalhando com respostas JSON usando jq
• Exemplos práticos de fluxo de trabalho
• Regras de validação e valores permitidos
• Solução de problemas comuns
• Sintaxe da flag e padrões de uso

Primeiros passos com acesso programático

Para começar a usar o Fleet Control programaticamente:

1. Generate a User API Key nas configurações da sua conta New Relic

2. Identifique seu ID da conta e ID da organização na plataforma New Relic

3. Escolha o método de acesso:

   • Use o NerdGraph Explorer para explorar as operações de frota interativamente
   • Analise as operações da Blob Storage API para gerenciamento de configuração
   • Instale e configure a Fleet Control CLI para fluxos de trabalho baseados em terminal

4. Comece com operações de leitura para se familiarizar com as estruturas de dados (pesquisar frotas, listar entidades, obter configurações)

5. Construa a automação gradualmente combinando operações em scripts ou fluxos de trabalho

Para obter ajuda adicional com APIs, consulte nossa documentação de Introdução ao NerdGraph e a documentação de chaves de API.