NerdGraph tutorial: Managing Fleet Control

Feature Availability

Fleet Control for Kubernetes clusters is generally available (GA). Support for managing agents on Linux and Windows hosts is currently in public preview.

For a complete list of supported agents and their environments, see our agent type compatibility documentation.

The public preview feature is provided pursuant to our pre-release policies.

You can use NerdGraph to programmatically manage Fleet Control fleets, members, and deployments. These mutations provide complete control over fleet operations, enabling you to automate fleet management, integrate with CI/CD pipelines, and manage instrumentation at scale.

This tutorial provides examples of the available Fleet Control mutations and queries. You can use these to create fleets, manage fleet members, and deploy agent configurations.

Prerequisites

A New Relic account with access to your API user key
The Organization Manager role or a custom role with fleet management permissions
Familiarity with GraphQL and NerdGraph

팁

You can also use the Fleet Control CLI for command-line fleet management. The CLI is built on the same NerdGraph API.

중요

Agent configurations are managed through the Blob Storage API, not NerdGraph. All configuration operations use a separate REST API.

Fleet management mutations

Use the fleetControlCreateFleet mutation to create a new fleet for managing groups of Kubernetes clusters or hosts.

Input parameters

Parameter	Data type	Is it tequired?	Description
`fleetEntity`	Object	Yes	The fleet entity creation input containing fleet configuration.
`fleetEntity.name`	String	Yes	The fleet name. Must be unique within your organization.
`fleetEntity.managedEntityType`	Enum	Yes	The type of entities this fleet will manage. Options: `HOST` (for Linux/Windows hosts) or `KUBERNETESCLUSTER`.
`fleetEntity.scope`	Object	Yes	The entity scope defining whether the fleet is account-scoped or organization-scoped.
`fleetEntity.scope.type`	Enum	Yes	Scope type. Options: `ACCOUNT` or `ORGANIZATION`.
`fleetEntity.scope.id`	ID	Yes	The account ID or organization ID, depending on scope type.
`fleetEntity.description`	String	No	A description of the fleet's purpose.
`fleetEntity.operatingSystem`	Object	No	Operating system type for HOST fleets. Required if `managedEntityType` is `HOST`.
`fleetEntity.operatingSystem.type`	Enum	Yes (if operatingSystem provided)	OS type. Options: `LINUX` or `WINDOWS`.
`fleetEntity.tags`	Array	No	List of tag objects for categorizing the fleet.

Sample request

mutation CreateFleet {
  fleetControlCreateFleet(
    fleetEntity: {
      name: "Production Web Servers"
      description: "Fleet for all production Linux web server hosts"
      managedEntityType: HOST
      operatingSystem: { type: LINUX }
      scope: { type: ACCOUNT, id: "YOUR_ACCOUNT_ID" }
      tags: [
        { key: "environment", values: ["production"] }
        { key: "team", values: ["platform"] }
      ]
    }
  ) {
    entity {
      id
      name
      description
      managedEntityType
    }
  }
}

Sample response

{
  "data": {
    "fleetControlCreateFleet": {
      "entity": {
        "id": "<YOUR_FLEET_ID>",
        "name": "Production Web Servers",
        "description": "Fleet for all production Linux web server hosts",
        "managedEntityType": "HOST"
      }
    }
  }
}

Use the fleetControlUpdateFleet mutation to update an existing fleet's name, description, or tags.

Input parameters

Parameter	Data type	Is it required?	Description
`id`	ID	Yes	The fleet entity ID to update.
`fleetUpdate`	Object	Yes	The fleet update input containing fields to modify.
`fleetUpdate.name`	String	No	Updated fleet name.
`fleetUpdate.description`	String	No	Updated fleet description.
`fleetUpdate.tags`	Array	No	Updated list of tags.

Sample request

mutation UpdateFleet {
  fleetControlUpdateFleet(
    id: "<YOUR_FLEET_ID>"
    fleetUpdate: {
      description: "Updated: Production web servers with enhanced monitoring"
      tags: [
        { key: "environment", values: ["production"] }
        { key: "region", values: ["us-east-1", "us-west-2"] }
      ]
    }
  ) {
    entity {
      id
      name
      description
    }
  }
}

Use the fleetControlDeleteFleet mutation to delete a fleet. This removes the fleet but does not uninstall agents from managed entities.

Input parameters

Parameter	Data type	Is it required?	Description
`id`	ID	Yes	The fleet entity ID to delete.

Sample request

mutation DeleteFleet {
  fleetControlDeleteFleet(id: "<YOUR_FLEET_ID>") {
    id
  }
}

Fleet member management mutations

Use the fleetControlAddFleetMembers mutation to add managed entities to fleet rings. Rings allow you to organize entities within a fleet for staged rollouts (for example, canary, staging, production).

Input parameters

Parameter	Data type	Is it required?	Description
`fleetId`	ID	Yes	The fleet entity ID.
`members`	Array	Yes	List of ring inputs specifying which entities to add to which rings.
`members[].ring`	String	Yes	The ring name (for example, "canary", "production").
`members[].entityIds`	Array	Yes	List of entity GUIDs to add to the ring.

Sample request

mutation AddFleetMembers {
  fleetControlAddFleetMembers(
    fleetId: "<YOUR_FLEET_ID>"
    members: [
      {
        ring: "canary"
        entityIds: ["<YOUR_ENTITY_ID_1>", "<YOUR_ENTITY_ID_2>"]
      }
      { ring: "production", entityIds: ["<YOUR_ENTITY_ID_3>"] }
    ]
  ) {
    items {
      id
      name
      ring
    }
  }
}

Use the fleetControlRemoveFleetMembers mutation to remove managed entities from fleet rings.

Input parameters

Parameter	Data type	Is it required?	Description
`fleetId`	ID	Yes	The fleet entity ID.
`members`	Array	Yes	List of ring inputs specifying which entities to remove from which rings.
`members[].ring`	String	Yes	The ring name.
`members[].entityIds`	Array	Yes	List of entity GUIDs to remove from the ring.

Sample request

mutation RemoveFleetMembers {
  fleetControlRemoveFleetMembers(
    fleetId: "<YOUR_FLEET_ID>"
    members: [{ ring: "canary", entityIds: ["<YOUR_ENTITY_ID>"] }]
  ) {
    items {
      id
      ring
    }
  }
}

Deployment management mutations

Use the fleetControlCreateFleetDeployment mutation to create a deployment that defines which agent versions and configurations to deploy to a fleet.

Input parameters

Parameter	Data type	Is it required?	Description
`fleetDeployment`	Object	Yes	The deployment configuration.
`fleetDeployment.fleetId`	ID	Yes	The fleet entity ID.
`fleetDeployment.scope`	Object	Yes	The entity scope (same as fleet scope).
`fleetDeployment.agents`	Array	Yes	List of agent configurations to deploy.
`fleetDeployment.agents[].agentType`	String	Yes	Agent type. Options: `NRInfra`, `NRDOT`, `FluentBit`, `NRPrometheusAgent`, `PipelineControlGateway`, `NRApmOperator`, `NReBPFAgent`.
`fleetDeployment.agents[].version`	String	Yes	Agent version to deploy.
`fleetDeployment.agents[].configurationVersionList`	Array	Yes	List of configuration version IDs for this agent.
`fleetDeployment.name`	String	No	Deployment name.
`fleetDeployment.description`	String	No	Deployment description.

Sample request

mutation CreateDeployment {
  fleetControlCreateFleetDeployment(
    fleetDeployment: {
      fleetId: "<YOUR_FLEET_ID>"
      name: "Infrastructure Agent v1.50.0"
      description: "Deploy infra agent 1.50.0 with updated config"
      scope: { type: ACCOUNT, id: "YOUR_ACCOUNT_ID" }
      agents: [
        {
          agentType: "NRInfra"
          version: "1.50.0"
          configurationVersionList: [{ id: "<YOUR_CONFIGURATION_ID>" }]
        }
      ]
    }
  ) {
    entity {
      id
      name
      description
    }
  }
}

Use the fleetControlUpdateFleetDeployment mutation to update an existing deployment's configuration.

Input parameters

Parameter	Data type	Is it required?	Description
`id`	ID	Yes	The deployment ID to update.
`fleetDeploymentUpdate`	Object	Yes	The deployment update input.
`fleetDeploymentUpdate.name`	String	No	Updated deployment name.
`fleetDeploymentUpdate.description`	String	No	Updated description.
`fleetDeploymentUpdate.agents`	Array	No	Updated agent configurations.

Sample request

mutation UpdateDeployment {
  fleetControlUpdateFleetDeployment(
    id: "<YOUR_DEPLOYMENT_ID>"
    fleetDeploymentUpdate: {
      description: "Updated to infra agent 1.50.1"
      agents: [
        {
          agentType: "NRInfra"
          version: "1.50.1"
          configurationVersionList: [{ id: "<YOUR_CONFIGURATION_ID>" }]
        }
      ]
    }
  ) {
    entity {
      id
      name
    }
  }
}

Use the fleetControlDeploy mutation to trigger a deployment to roll out to specific fleet rings.

Input parameters

Parameter	Data type	Is it required?	Description
`id`	ID	Yes	The deployment ID to trigger.
`policy`	Object	Yes	Deployment policy specifying which rings to deploy to.
`policy.ringDeploymentPolicy`	Object	Yes	Ring deployment policy.
`policy.ringDeploymentPolicy.ringsToDeploy`	Array	Yes	List of ring names to deploy to.

Sample request

mutation TriggerDeployment {
  fleetControlDeploy(
    id: "<YOUR_DEPLOYMENT_ID>"
    policy: { ringDeploymentPolicy: { ringsToDeploy: ["canary"] } }
  ) {
    fleetId
  }
}

Use the fleetControlDeleteFleetDeployment mutation to delete a deployment.

Input parameters

Parameter	Data type	Is it required?	Description
`id`	ID	Yes	The deployment ID to delete.

Sample request

mutation DeleteDeployment {
  fleetControlDeleteFleetDeployment(id: "<YOUR_DEPLOYMENT_ID>") {
    id
  }
}

Additional resources

Blob Storage API reference - For managing agent configurations
Fleet Control overview
Fleet Control CLI
Introduction to NerdGraph
NerdGraph Explorer

NerdGraph tutorial: Managing Fleet Control

Feature Availability

Prerequisites

팁

중요

Fleet management mutations

Create a fleet

Input parameters

Sample request

Sample response

Update a fleet

Input parameters

Sample request

Delete a fleet

Input parameters

Sample request

Fleet member management mutations

Add members to a fleet

Input parameters

Sample request

Remove members from a fleet

Input parameters

Sample request

Deployment management mutations

Create a deployment

Input parameters

Sample request

Update a deployment

Input parameters

Sample request

Trigger a deployment

Input parameters

Sample request

Delete a deployment

Input parameters

Sample request

Additional resources

NerdGraph tutorial: Managing Fleet Control

Feature Availability

Prerequisites.css-21sua1{background:none;border:none;width:0;padding:0;}

팁

중요

Fleet management mutations

Update a fleet

Delete a fleet

Fleet member management mutations

Add members to a fleet

Remove members from a fleet

Deployment management mutations

Create a deployment

Update a deployment

Trigger a deployment

Delete a deployment

Additional resources

Prerequisites