---
title: NerdGraph tutorial: Managing Fleet Control
source: https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-fleet-control-tutorial
---

> #### ⚠️ 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](https://docs.newrelic.com/docs/new-relic-control/agent-control/agent-types).
>
> The public preview feature is provided pursuant to our [pre-release policies](https://docs.newrelic.com/docs/licenses/license-information/referenced-policies/new-relic-pre-release-policy).

You can use [NerdGraph](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-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](https://newrelic.com/signup) with access to your API user key
-   The **Organization Manager** role or a custom role with fleet management permissions
-   Familiarity with [GraphQL](https://graphql.org/learn/) and [NerdGraph](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/)

> #### 💡 TIP
>
> You can also use the [Fleet Control CLI](https://github.com/newrelic/newrelic-cli/tree/main/internal/fleetcontrol) for command-line fleet management. The CLI is built on the same NerdGraph API.

> #### ⚠️ IMPORTANT
>
> Agent configurations are managed through the [Blob Storage API](https://docs.newrelic.com/docs/apis/intro-apis/blob-storage-api), not NerdGraph. All configuration operations use a separate REST API.

## Fleet management mutations

**Create a fleet**

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

```graphql
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

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

**Update a fleet**

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

```graphql
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
    }
  }
}
```

**Delete a fleet**

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

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

## Fleet member management mutations

**Add members to a fleet**

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

```graphql
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
    }
  }
}
```

**Remove members from a fleet**

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

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

## Deployment management mutations

**Create a deployment**

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

```graphql
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
    }
  }
}
```

**Update a deployment**

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

```graphql
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
    }
  }
}
```

**Trigger a deployment**

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

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

**Delete a deployment**

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

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

## Additional resources

-   [Blob Storage API reference](https://docs.newrelic.com/docs/apis/intro-apis/blob-storage-api) - For managing agent configurations
-   [Fleet Control overview](https://docs.newrelic.com/docs/new-relic-control/fleet-control/overview)
-   [Fleet Control CLI](https://github.com/newrelic/newrelic-cli/tree/main/internal/fleetcontrol)
-   [Introduction to NerdGraph](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph)
-   [NerdGraph Explorer](https://one.newrelic.com/nerdgraph-graphiql)