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.

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 (e.g., Kubernetes clusters vs. hosts).

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 (e.g., 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 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 (e.g., 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 page for that specific deployment, where you can find:

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

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:

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 the Create deployment button.
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 the Start deployment button 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.

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 version.
• Change 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 the Remove button 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.

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.

fleet-control-canary-action

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 (e.g., 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 the Create configuration button.

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 (e.g., Kubernetes or 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 Environment you select (Kubernetes or Host).

• For Kubernetes, 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 the Create configuration button.
2. In the modal that appears, you must:
   • Select the Environment (Kubernetes or Host).
   • Select the Agent type (e.g., New Relic Infrastructure, NRDOT collector, Fluent Bit).
   • 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 the Copy button 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 the Create config version button.
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.

1. To delete a configuration version:
2. Navigate to the Configurations page.
3. Click on the name of the configuration you wish to modify to open its details pane.
4. 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.
5. Select Delete from the menu.
6. 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 button.
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 (e.g., 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 (e.g., 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.