Manage fleets

Once you've created your first fleet using the setup guide, you'll perform most of your day-to-day work from the Fleet Control UI. While these operations can also be performed programmatically via the API, this page focuses on the UI workflows for managing your fleets, deployments, and configurations.

Understanding fleet types

Fleet Control supports three types of fleets, each designed for a specific managed entity type:

• Kubernetes Cluster fleets: Manage Kubernetes clusters where agents are deployed as Helm charts.
• Linux Host fleets: Manage Linux servers where agents run as host-based processes. (Public preview)
• Windows Host fleets: Manage Windows servers where agents run as Windows services or host-based processes. (Public preview)

When you create a fleet, you select its managed entity type. This choice has important implications for how you work with that fleet:

• Entity assignment: You can only add managed entities that match the fleet's type. For example, a Windows Host fleet can only contain Windows hosts, and a Kubernetes Cluster fleet can only contain Kubernetes clusters.
• Configuration filtering: During deployment, you'll only be presented with configurations that match the fleet's type. If you're working with a Windows Host fleet, only Windows Host configurations will appear in the configuration selector. This automatic filtering prevents misconfigurations and streamlines the deployment process.
• Agent availability: The list of available agents to deploy will be filtered based on the fleet type and what's supported for that environment. For example, certain agents may only be available for Kubernetes environments or specific host operating systems.

This design ensures consistency across all managed entities in a fleet and prevents misconfigurations, such as accidentally trying to deploy a Kubernetes Helm chart configuration to a Windows host.

Sorting data in tables

Many of the data tables throughout the Fleet Control UI are sortable. To sort a table by a specific column, mouse over the column header. If a faint gray up or down arrow appears, you can click the header to reorder the table rows based on that column's data.

The Fleets page

When you navigate to New Relic Control → Fleets, you land on the main Fleets page, which provides a high-level overview of your entire Fleet Control environment. From here, you can:

• Search for fleets: Use the search bar to find a specific fleet by name.
• View summary counts: See your total fleet count and the number of unassigned managed entities.
• See fleet distribution: View a breakdown of your fleets by type (Kubernetes Cluster or Host).

Fleet actions

From the main Fleets page, you can click the ellipses (...) on the far right of any fleet to reveal a menu of actions:

• Edit settings: Allows you to change a fleet's name and description.
• Edit permissions: Allows you to manage the fine-grained access controls (FGA) for the fleet by changing the associated group or role.
• Delete a fleet: Permanently removes the fleet. Before a fleet can be deleted, the following conditions must be met:
  • All managed entities must be removed from the fleet.
  • The fleet cannot have any deployments currently in progress.

Fleet permissions (fine-grained access)

Fleet Control uses fine-grained access (FGA) to allow administrators to delegate the management of specific fleets to certain users or groups. This is useful when you want to empower a team to manage their own fleets without granting them broad, organization-level permissions.

The primary method for delegating access is by assigning the predefined Fleet Manager role to a user group for a specific fleet. This gives users in that group full control over that fleet, including the ability to create deployments, manage configurations, and add or remove managed entities.

Prerequisites for admin

To set up fleet permissions, you must have the Organization Manager and AuthDomain Manager roles.

Setup workflow

The process involves two main steps: first, an administrator creates a user group, and second, they assign that group the Fleet Manager role for a specific fleet.

Step 1: Create a user group

1. From the bottom of the left navigation menu, click your user name, then select Administration.
2. On the Administration page, select Access Management.
3. Go to the groups tab and click Create a new group.
4. Give the group a meaningful name (for example, k8s-platform-team-fleet-managers).
5. Under the members section, add the users you want to delegate fleet management to.
6. Click Add user to the group. You do not need to assign any account or organization-level roles here. Permissions will be granted at the fleet level.

Step 2: Assign a group and a role to a fleet

You can assign permissions either when you create a new fleet or by editing an existing one.

To assign permissions to an existing fleet:

1. From the main fleets page, find the fleet you want to manage.
2. Click the ellipses (...) at the end of the row and select Edit permissions.
3. In the fleet permissions modal:
   • Select a group: Choose the user group you created in the previous step.
   • Select a role: Choose the Fleet Manager role.
4. Click Save. The users in the selected group now have full management permissions for this fleet.

To assign permissions during fleet creation:

1. Follow the steps for creating a fleet in our setup guide.
2. Before you click Create Fleet, expand the Access management section.
3. Use the dropdowns to select your desired Group and the Fleet Manager role.
4. Click Create Fleet.

Managing a specific fleet

Clicking on a fleet's name takes you to its detailed management page.

The fleet header: Tags and metadata

At the top of the page, the header displays the fleet's name along with the clickable Tags and Metadata buttons. These provide quick access to important identifying information for the fleet.

• Tags: Clicking this reveals a comprehensive set of key-value pair data associated with the fleet, such as the accountId, the fleet's description, and creation or update timestamps.
• Metadata: Clicking this displays the core identifying details for the fleet as a New Relic entity, such as its Entity guid, Account ID, and Managed entities type.

The detailed management page is organized into three main tabs: Summary, Agents, and Deployments.

The Summary tab

This tab provides a snapshot of the fleet's current state, organized into three tables:

• Active deployment table: Shows the name of the most recent deployment, the number of agents/configs included, and the date it was last updated.
• Agents table: Lists the agent types, their associated configurations and versions, and when the configuration was created.
• Managed entities table: Lists all entities assigned to the fleet, their account, type, and current instrumentation status. It also includes a View entity link that takes you to the entity's main page elsewhere in the New Relic platform (for example, the Kubernetes cluster explorer).

The agents tab

This tab provides a detailed view of all agents running on the managed entities within the fleet. You can use the search bar at the top of this tab to find a specific agent by its name or type.

An important detail is that the New Relic Agent Control supervisor is also listed here as an agent type. For each agent, you can see its associated managed entity, instrumentation status, remote configuration status, and when a heartbeat was last received.

View effective configuration

A key feature of the agents tab is the ability to see the effective configuration of any agent. Click on an agent's name to open a detailed view. Here you can see metadata like the Helm chart version, but most importantly, you can view the exact configuration running on the agent in real-time.

The effective configuration can sometimes differ from the configuration you deployed, as it accounts for any overrides from sources like local environment variables. This view is invaluable for troubleshooting configuration-related issues.

The deployments tab

This tab contains the complete deployment history for the fleet. You can use the search bar to find a specific deployment by its name. The table lists each deployment's name, its status, the number of agents/configs, and the last updated date. The most recent successful deployment is marked with an Active label to indicate it's the one currently enforced on the fleet.

Clicking on a deployment's name takes you to a summary view for that specific deployment. This view is organized into two tabs:

Details tab

The details tab provides a summary of the deployment, including:

• Deployment metadata (name, type, description, start/end times, and a deployment ID for troubleshooting).
• An Agents table showing the agent type, the action taken (for example, install, update), and the configuration version.
• A Managed Entities table showing exactly which entities were affected by the deployment and whether they were marked as canaries.

Deployment Events tab

The deployment events tab provides granular, event-level visibility into every action that occurred during the deployment. This tab is essential for troubleshooting deployment issues and understanding root causes. You can:

• View atomic events with details including timestamp, status, managed entity name, agent name, agent type, event type, details, and duration.
• Search for specific events by keyword.
• Filter events by managed entity to focus on a specific cluster or host (useful when troubleshooting failures in large fleets).
• Filter events by status (for example, Completed, Config Applied, Applying).
• Access the underlying NRQL query for advanced troubleshooting by clicking the button to the right of the events table header.

For more information on using the deployment events tab for troubleshooting, see our troubleshooting documentation.

Understanding deployments

A deployment is a controlled set of actions that can install, delete, or update agents and their configurations on the managed entities in your fleet. This section covers key aspects of the deployment lifecycle, including understanding the different deployment statuses, the automatic upgrade process for Agent Control, and how to use advanced features like draft and canary deployments to safely manage changes.

Understanding deployment statuses

The status of each deployment helps you understand its outcome. Here are the possible statuses and what they mean:

Understanding deployment event flow

When you view the deployment events tab, you'll see a series of events that represent the lifecycle of your deployment. All deployment events are written to the FleetDeployment custom event type. Understanding this event flow helps you interpret what you see in the deployment events tab and diagnose issues more effectively.

Fleet Control deploys configuration changes in stages called "rings" to reduce risk. The deployment process works as follows:

• If you've designated canary entities: The deployment uses a canary ring first (containing only the entities you marked as canaries), followed by a default ring for all remaining entities. Each ring must complete successfully before the next ring begins. If the canary ring fails, the deployment stops before proceeding to the default ring, preventing widespread issues.
• If you haven't designated any canary entities: The deployment uses only the default ring, which includes all entities in the fleet. The deployment will run to completion across all entities in that single ring.

Deployment event types

The following events track the progress of a deployment from start to finish:

Agent deployment statuses

When an agent completes its deployment attempt (AgentDeploymentCompleted), it reports one of the following statuses:

How the event flow works

When you initiate a deployment, events are generated in the following sequence:

1. FleetDeploymentStarted — The deployment begins for the entire fleet.
2. RingDeploymentStarted — The first ring (typically canary) starts, and all agents in that ring are identified.
3. AgentDeploymentStarted — For each agent in the ring, a deployment event is recorded. These events occur in parallel for all agents in the ring.
4. AgentDeploymentCompleted — Each agent reports back with its status (CONFIG_APPLIED, FAILED, TIMEOUT, or NOT_REPORTING).
5. RingDeploymentCompleted — Once all agents in the ring complete or time out, the ring is marked complete. If the ring succeeded, the next ring begins. If it failed, the deployment stops.
6. FleetDeploymentCompleted — After all rings complete (or a ring fails), the deployment finishes with a final status of COMPLETED, FAILED, or INTERNAL_FAILURE.

Visual event flow

FleetDeploymentStarted
│
├─▶ RingDeploymentStarted (canary)
│   │
│   ├─▶ AgentDeploymentStarted (agent 1) ──▶ AgentDeploymentCompleted ─┐
│   ├─▶ AgentDeploymentStarted (agent 2) ──▶ AgentDeploymentCompleted ─┤ [parallel]
│   ├─▶ AgentDeploymentStarted (agent 3) ──▶ AgentDeploymentCompleted ─┘
│   │
│   └─▶ RingDeploymentCompleted (canary)
│       │
│       ├─ ✓ If SUCCESS → proceed to default ring
│       └─ ✗ If FAILED → stop deployment
│
├─▶ RingDeploymentStarted (default)
│   │
│   ├─▶ AgentDeploymentStarted (agent 4) ──▶ AgentDeploymentCompleted ─┐
│   ├─▶ AgentDeploymentStarted (agent 5) ──▶ AgentDeploymentCompleted ─┤ [parallel]
│   ├─▶ AgentDeploymentStarted (agent 6) ──▶ AgentDeploymentCompleted ─┘
│   │
│   └─▶ RingDeploymentCompleted (default)
│
└─▶ FleetDeploymentCompleted

Agent deployment status options:

• ✅ CONFIG_APPLIED — Agent successfully applied the configuration
• ❌ FAILED — Agent encountered an error
• ⏱️ TIMEOUT — Agent did not respond in time
• 📡 NOT_REPORTING — Agent was offline when deployment started

Key identifiers: fleetId, deploymentId, ringName

You can view all of these events in detail using the Deployment Events tab. See the Deployments tab section for more information on accessing and using deployment events for troubleshooting.

Automatic Agent Control upgrades

To ensure your managed entities benefit from the latest security patches, performance enhancements, and features, Fleet Control automatically manages the upgrade process for Agent Control. When you initiate a deployment, Fleet Control checks if a newer version of Agent Control is available for the managed entities in your fleet.

If an upgrade is required, it is automatically included as part of your deployment. You will see a notification in the UI during the deployment process informing you that Agent Control will be upgraded. This implicit upgrade happens alongside any deployment actions you are performing (such as installing agents, removing agents, or changing agent configurations), ensuring your environment stays up-to-date with minimal effort.

Create and manage draft deployments

You can save a deployment as a draft to work on it over time without deploying the changes immediately.

Create and resume a draft

1. Navigate to the deployments tab within a specific fleet.
2. Click Create deployment.
3. In the deployment pane, provide a mandatory name and an optional description.
4. Make any desired changes, such as adding agents or updating their configurations.
5. Instead of starting the deployment, click Save draft.
6. You can then close the deployment pane. Your new deployment will be listed in the deployments tab with a status of Draft.

To continue working on the draft, simply click on its name in the deployment history table. This will reopen the deployment pane, allowing you to finish your changes and click Start deployment when you are ready.

Delete a draft

If you no longer need a draft deployment:

1. From the deployments tab, click on the name of the draft you wish to delete.
2. In the deployment pane that opens, click the ellipses (...) button next to Start deployment at the top of the screen.
3. Select Delete draft from the menu.
4. The draft will be permanently removed, and you will be returned to the deployments tab.

Selecting agent versions during deployment

When you add an agent to a deployment, you'll be prompted to select an agent version before choosing a configuration:

1. After selecting the agent type, a Select a version dropdown appears.
2. The latest version is selected by default.
3. You can choose from other available versions for installation.
4. Additional metadata may be displayed for each version, such as:
   • Release notes highlighting new features and improvements
   • Security update information
   • Other version-specific details

This version selection capability works across all supported infrastructure types (Kubernetes clusters, Linux hosts, and Windows hosts), giving you precise control over which agent version is deployed to your managed entities.

Once you've selected your agent version, click Next to proceed to configuration selection.

Agent actions in a deployment

When you are creating or editing a deployment, the Agents table in the deployment pane provides several actions for each agent. Click the ellipses (...) on the right side of an agent's row to access the following options:

• Edit configuration: Opens the configuration editor, allowing you to modify the configuration for this agent as part of the deployment.
• Use most recent version: If you have created multiple versions of a configuration, this option automatically updates the deployment to use the latest saved configuration version.
• Change configuration version: Allows you to manually select a specific, older version of the configuration to use for the deployment.
• Remove from deployment: Removes the agent and its configuration from this deployment entirely.

Manage entities in a fleet

Remove entities from a fleet

1. Navigate to the summary tab of the fleet that currently contains the entity.
2. In the managed entities table, use the checkbox to select one or more entities you wish to remove.
3. Click Remove that appears.
4. A verification modal will appear, listing the entities to be removed. To confirm, type remove into the text field.
5. Click Remove entities. The entity is now unassigned from the fleet.

Add unassigned managed entities to a fleet

You add an unassigned managed entity to a fleet by creating a new deployment. This process associates the entity with the fleet and its deployed configurations.

1. Navigate to the fleet where you want to add the entity and click Create a deployment.
2. Give the deployment a meaningful name and description.
3. In the managed entities table at the bottom of the deployment screen, click the Add managed entities button.
4. A pane will open, displaying a list of all your unassigned managed entities.
5. Use the selection boxes to choose one or more entities you wish to add to the fleet.
6. Click Add to deployment. The selected entities will now appear in the managed entities table for this deployment.
7. Click Save draft and then Start deployment to complete the process. The entities will now be assigned to the new fleet.

   Important: Inheriting the last active deployment

   When you add a managed entity to a fleet, an implicit deployment occurs in the background. This deployment automatically installs, updates, or removes instrumentation on the new entity to ensure it perfectly matches the fleet's last active deployment. For example, if the fleet's active deployment includes the Infrastructure and Fluent Bit agents, but the new entity previously had only the OTel agent, the OTel agent will be removed, and the Infrastructure and Fluent Bit agents will be installed.

Use canary deployments

Fleet Control allows you to designate one or more managed entities as a "canary" during the deployment process. This provides a crucial safety mechanism for rolling out changes.

When you create a new deployment, you can use the ellipses (...) next to any managed entity in the list and designate it as a canary.

When the deployment starts:

1. The changes are deployed only to the managed entities marked as canaries.
2. The deployment process pauses and waits for the canary deployments to succeed.
3. If any canary deployment fails, the entire deployment stops immediately, and no other managed entities are affected.
4. If all canary deployments are successful, the deployment proceeds to the rest of the managed entities in the fleet.

The configurations page

When you navigate to New Relic Control → Configurations, you land on the main Configurations page, which is the central hub for managing all your agent configurations.

Main page overview

This page provides a high-level overview of all available configurations in your account. From here, you can:

• View summary counts: See your total configuration count.
• See configuration distribution: View a breakdown of your configurations by agent type (for example, New Relic Infrastructure, Fluent Bit, NRDOT collector).
• Search for configurations: Use the search bar to find a specific configuration by its name or associated agent type.
• Refresh the list: If you have just created a new configuration and don't see it in the table, click the refresh button located to the left of Create configuration.

The page displays a table of your configurations with the following columns:

• Configuration: The name of the configuration.
• Agent: The agent type the configuration applies to.
• Revisions: The number of versions that exist for the configuration.
• Type: The managed entity type (for example, Kubernetes Cluster, Linux Host, or Windows Host).
• Last modified: A timestamp of the last update.

Configuration actions

From the main configurations table, you can click the ellipses (...) on the far right of any configuration to Edit it. This opens the main editing pane where you can modify the configuration file. This view also provides buttons to Download the configuration file to your local machine or Copy its contents to your clipboard.

Understanding configurations

The structure of a configuration file depends on the Managed Entity Type you select (Kubernetes Cluster, Linux Host, or Windows Host).

• For Kubernetes clusters, the configuration you create in the UI is a values.yaml file. During deployment, Fleet Control packages this file with the agent's Helm chart to configure it on your cluster. The templates for Kubernetes agents are structured as a canonical Helm chart values.yaml file. Near the top of the template, you'll find a commented-out link to the agent's Helm chart in the New Relic Helm Charts GitHub repository. This allows you to easily reference the schema, available values, and other agent-specific documentation.
• For hosts, the configuration file format is specific to the agent being deployed.

Create a configuration

To create a new global configuration from scratch:

1. From the main Configurations page, click Create configuration.
2. In the modal that appears, you must:
   • Select the managed entity type (Kubernetes Cluster, Linux Host, or Windows Host). Note that Linux Host and Windows Host support is currently in public preview.
   • Select the Agent type (for example, New Relic Infrastructure, NRDOT collector, Fluent Bit) from the dropdown menu. The available agent types will be filtered based on the managed entity type you selected.
   • Provide a meaningful and unique Name for the configuration.

3. Click Continue. This opens the configuration editing view, which is split into two panes.
   • Left Pane (Active Configuration): This is where you author your configuration. You can type directly into this pane or paste content from another source.
   • Right Pane (Template): This pane contains the latest default template for the agent type you selected. These templates provide the minimal required settings to run the agent, but they also include many additional commented-out options. You can use these examples for reference or uncomment them to build a more custom configuration.
4. A common workflow is to click Copy in the template pane and paste the contents into the active configuration pane on the left to use as a starting point.
5. Once you are satisfied with your configuration in the left pane, click Save. The editing view will close, returning you to the main configurations page where you can find your new configuration.

View and version a specific configuration

To see more details about a configuration and manage its versions, click on its name in the main list. This opens a detailed pane for that specific configuration.

This view shows you:

• The configuration's name, agent type, and a list of its available versions.
• The deployment status, which indicates if the configuration has been deployed to any fleets and, if so, which ones.

From this pane, you can also perform several actions like Download, Copy, and Clone. The primary action here is creating a new version of the configuration.

To create a new version:

1. Click Create config version.
2. This opens the editing pane where you can modify the configuration.
3. When you are finished with your edits, click Save.
4. You will be returned to the main configurations page, and you will see the revisions count for that configuration has incremented by one.

If you click back into the configuration, you can now select the new version from the list to view it.

Delete a configuration and its versions

To delete a configuration, you must first delete all of its individual versions. The parent configuration is automatically deleted once its last version is removed.

To delete a configuration version:

1. Navigate to the configurations page.
2. Click on the name of the configuration you wish to modify to open its details pane.
3. On the left, you'll see a list of all its versions. Hover over the version you want to remove and click the ellipses (...) that appears.
4. Select Delete from the menu.
5. Repeat this process for all remaining versions. Once the last version is deleted, the parent configuration will be removed from the list on the main configurations page.

Clone a configuration

Cloning is a fast way to create a new configuration based on an existing one.

1. On the main configurations page, click the ellipses (...) button located next to the main Create configuration.
2. From the dropdown, select the existing configuration you want to use as a starting point for your clone.
3. This opens the same two-pane editing view, pre-populated with the content of the configuration you selected.
4. You can now author your new configuration and save it.

The main managed entities page

When you navigate to New Relic Control → Managed Entities, you get a centralized view of all your managed entities, which are Kubernetes clusters or hosts with Agent Control installed. This page serves as your complete asset inventory for any entity capable of being managed by Fleet Control and is organized into two tabs: Fleet managed and Unassigned.

Fleet managed tab

This tab lists all the managed entities that are currently assigned to a fleet. The table provides the following information:

• Entity name: Clicking the name takes you directly to that entity's explorer experience in the New Relic platform (for example, the Kubernetes cluster explorer).
• Entity type: The type of the managed entity (for example, Kubernetes cluster or host).
• Instrumentation status: The current health status of the instrumentation on the entity.
• Fleet: Which fleet the entity is currently assigned to. You can click the fleet name to navigate directly to that fleet's management page.
• Account name: The New Relic account associated with the managed entity.

Unassigned tab

This tab provides a list of all managed entities that have Agent Control installed but are not currently assigned to any fleet. The table provides the following information:

• Entity name: Clicking the name takes you directly to that entity's explorer experience in the New Relic platform.
• Entity type: The type of the managed entity.
• Instrumentation status: The current health status of the instrumentation.
• Account name: The New Relic account associated with the managed entity.

This view is particularly useful for identifying which of your assets are not yet being managed by Fleet Control. It is a best practice to assign all managed entities to a fleet to ensure they are consistently configured and monitored.

The main agents page

When you navigate to New Relic Control → Agents, you get a global overview of all the agents being managed by Fleet Control across your organization.

At the top of the page, you'll find summary cards that provide a quick look at your agent health, including:

• A count of all connected agents.
• A count of disconnected agents, helping you quickly identify agents that may need troubleshooting.
• A distribution of your top 500 agent types.

Below the summary cards, a comprehensive table lists all your managed agents. You can search this table by agent name and filter it by agent type or reporting status. The table includes the following columns:

• Type: The type of the agent (for example, New Relic infrastructure).
• Agent Name: The specific name of the agent.
• Managed Entity: The managed entity the agent is associated with.
• Connection Status: The current connection status of the agent.
• Fleet: The fleet the agent is a part of.
• Agent Version: The version number of the agent.