Manage Fleet Control access

This guide provides patterns for setting up role-based access control (RBAC) for Fleet Control operations. It covers three implementation patterns, from basic to enterprise, with both UI and NerdGraph examples.

Prerequisites

Before you set up any of the patterns below:

• Full platform users: Every Fleet Control permission requires the full platform user type.
• Pro or Enterprise edition: Required to create the custom roles and custom groups these patterns use.
• Authentication domain manager role: Users with the Authentication domain manager role can create access grants, which assign groups and roles to specific fleets. This is a New Relic platform requirement for all access grant operations.
• Initial Agent Control setup: Requires the Authentication domain manager role, one time, to create system identities.
• Create fleets and configurations: Requires the Organization product admin role, which is automatically granted to anyone in the default User group.
• Run deployments: Requires the Organization Manager role, which is automatically granted to anyone in the default Admin group. Alternatively, the Fleet manager role or a custom role carrying Deploy grants it on specific fleets, without organization-wide reach.

How Fleet Control permissions are organized

When you create a custom role, Fleet Control permissions display as a table: a row for the resource, and columns for Read, Modify, Delete, and Other. Each checkbox grants a set of related actions rather than an individual permission. The row you get depends on the role's scope.

Organization-scoped roles get the Fleets (all) row, covering every fleet in the organization:

Entity-scoped roles targeting a fleet get the Fleets (individual) row, covering only the fleets the role is granted on:

Approving configurations and setting the approval policy are available only to organization-scoped roles, so approval authority can't be scoped to a particular fleet. See config approvals for the details and delegate approval authority for how to grant it.

Basic pattern: Single fleet permission (FGA)

Fleet Control supports fine-grained access (FGA) through entity-scoped access grants. The built-in Fleet manager role can be scoped to specific fleet entities, which gives a group full operational control of those fleets, deployments included, without Organization Manager.

This allows you to grant access to a team to manage a specific fleet without giving them access to all fleets in the organization.

UI walkthrough

1. Create the fleet, if not already created:
   1. Go to All capabilities > New Relic Control > Fleets
   2. Click Create a fleet
   3. Name it, for example production-us-east-fleets
   4. Save and note the fleet GUID
2. Create or identify the target group:
   1. Go to Administration > Access management > Groups
   2. Create a new group, for example prod-us-east-fleet-operators, or use an existing one
   3. In the Create a group modal, add users now via the Add users dropdown, or add them later by editing the group
   4. Note the group ID
3. Grant entity-scoped access:
   1. Go to New Relic Control > Fleets
   2. On the fleet's row, open the kebab menu and select Fleet permissions
   3. In the Fleet permissions modal, pick a group and select Fleet manager as the role. Add as many group and role pairs as needed
   4. Click Save, which creates one access grant per pair

Result: Members of prod-us-east-fleet-operators can now run deployments and manage members for production-us-east-fleets only. They can't modify other fleets. They will still see that other fleets exist, because read access comes from their organization-scoped role rather than from this grant.

NerdGraph automation

mutation GrantFleetAccess {
  authorizationManagementGrantAccess(
    grantAccessOptions: {
      grantee: { type: GROUP, id: "YOUR_GROUP_ID" }
      entityAccessGrants: {
        entity: { id: "YOUR_FLEET_GUID", type: "fleet" }
        roleId: "YOUR_ROLE_ID"
      }
    }
  ) {
    accessGrants {
      id
    }
  }
}

How to find IDs:

• Fleet GUID: Visible in the fleet details page URL, or query fleets via the NerdGraph Fleet Control tutorial
• Group ID: Administration > Access management > Groups, click the group, ID is in the URL
• Role ID: Query for it using the workaround in known issues

Advanced pattern: Custom roles for lifecycle separation

Create two custom entity-scoped roles with different Fleet Control permissions, then grant each to a different group on the same fleet entities. Fleet manager carries Modify, Delete, and Deploy together, so when that's more authority than a group should have, split it.

This allows you to separate who can change a fleet's definition and membership from who can run deployments, while both groups work on the same fleets.

Example blueprint: Custom roles design

This section provides a recommended example of how you can design custom, lower-privilege roles to separate architecture permissions from deployment execution.

Both roles are entity-scoped and target Fleet:

Neither role can delete a fleet, since Delete is a separate permission you leave unchecked.

Configuration authoring isn't part of either role, because configurations in Fleet Control are organization-level objects rather than belonging to a fleet. Authoring them comes with Organization product admin, which the default User group already has. In practice, your authors write configurations and these fleet-scoped roles control what gets deployed where.

UI walkthrough

1. Create the custom roles. For each one:
   1. Go to Administration > Access management > Roles
   2. Click Add a role
   3. For the role's scope, choose Single item or entity, then click Next
   4. Under Select what you want to configure access to, choose Fleet
   5. Name the role, for example Fleet author
   6. Under Set permissions, expand Fleet Control and select what the role carries on the Fleets (individual) row: Modify for the author role, or Deploy under Other for the deployer role
   7. Save, then repeat for the second role
2. Create groups for each role:
   1. Create group fleet-architects for the authors, adding the relevant users via the Add users dropdown in the Create a group modal, or later by editing the group
   2. Create group fleet-deployment-operators for the deployers, the same way
3. Grant entity-scoped access for each group:
   1. Go to New Relic Control > Fleets, open the kebab menu on the target fleet, and select Fleet permissions
   2. Add a group and role pair: fleet-architects with Fleet author
   3. Add a group and role pair: fleet-deployment-operators with Fleet deployer
   4. Save, and both grants are created together

NerdGraph automation

Custom roles are created in the UI. Role creation takes internal permission identifiers rather than the permission names shown on the checkboxes, so there's no practical API path for building the roles themselves.

Once the roles exist, grant them with the same mutation as the basic pattern, passing each role's ID.

Result: Fleet authors can shape the fleets they own but can't run deployments. Deployment operators can run deployments but can't redefine or delete a fleet.

Enterprise pattern: Delegated group management

Use the Group admin role with group-scoped grants to delegate group membership management.

This allows you to have team leads add and remove members from their team's groups without needing full Authentication domain manager privileges.

UI walkthrough

1. Create a managers group:
   1. Go to Administration > Access management > Groups
   2. Create group fleet-team-leads
   3. Add the team leads as members
2. Grant the Group admin role over target groups:
   1. Go to Administration > Access management > Access grants
   2. Click Create new grant
   3. Choose a group grant, which is the grant type that targets other groups
   4. Select group fleet-team-leads
   5. Role: Group admin
   6. Select the groups that team leads should be able to manage, for example fleet-architects and fleet-deployment-operators
   7. Save

Result: Members of fleet-team-leads can now add and remove users from fleet-architects and fleet-deployment-operators without needing the Authentication domain manager role.

NerdGraph automation

mutation DelegateGroupManagement {
  authorizationManagementGrantAccess(
    grantAccessOptions: {
      grantee: { type: GROUP, id: "YOUR_TEAM_LEADS_GROUP_ID" }
      groupAccessGrants: [
        { groupId: "YOUR_TARGET_GROUP_ID", roleId: "YOUR_GROUP_ADMIN_ROLE_ID" }
      ]
    }
  ) {
    accessGrants {
      id
    }
  }
}

Delegate Fleet Control with multiple business units

This section outlines a scenario we've seen with customers who have multiple autonomous business units and need to delegate Fleet Control management. It provides both the recommended solution and alternative approaches using the patterns above.

The scenario

Example: ByteFlix Entertainment is a large media company with multiple autonomous business units operating under a single New Relic organization:

• ByteFlix+, a streaming service
• BBS, the ByteFlix Broadcast System, a broadcast network
• PixelTV, a cable network

Organizational structure

Central IT:

• Only two or three people have the Organization Manager and Authentication domain manager roles
• They manage New Relic licensing and governance
• They don't configure or create monitoring entities
• They are a bottleneck for access management changes

Business units:

• Each unit has separate accounts under the same New Relic organization
• Each unit manages its own observability independently
• Many units use contractors to administer New Relic infrastructure

The challenge

ByteFlix wants to adopt Fleet Control but runs into friction:

1. Strict business unit isolation required: ByteFlix+ teams must not manage BBS or PixelTV infrastructure
2. Contractor delegation: Unit leads need to onboard contractors without involving central IT
3. Lifecycle separation: Platform Ops should shape fleets and App Teams should deploy, but App Teams shouldn't be able to delete or redefine fleets
4. No broad admin grants: Central IT won't grant Authentication domain manager to unit teams due to security concerns

Recommended solution: Separate organizations

Based on ByteFlix's organizational structure, multi-tenancy is the ideal solution.

What this means

Instead of one organization with multiple accounts, ByteFlix creates three separate New Relic organizations:

• ByteFlix+ organization, with its own accounts
• BBS organization, with its own accounts
• PixelTV organization, with its own accounts

Each business unit becomes its own isolated New Relic organization.

Benefits

1. Complete business unit isolation: Organization-scoped features, including Fleet Control, only see data within that unit's organization
2. No cross-unit visibility: ByteFlix+ users can't see BBS or PixelTV entities, guaranteed by organizational boundaries
3. Autonomous administration: Each unit has its own authentication domain managers and organization managers without affecting the others
4. Contractor delegation: Each unit can grant contractor access without involving central IT or the other units
5. Simpler permissions: No entity-scoped grants or custom roles needed to enforce isolation

What about shared services?

New Relic account sharing allows accounts to cross organizational boundaries. If ByteFlix has shared platform services, such as centralized logging or shared infrastructure, that need visibility across units, those accounts can be shared into multiple organizations.

For example, central IT maintains a shared observability organization with the shared platform accounts, and the ByteFlix+, BBS, and PixelTV organizations each have read access to those accounts via account sharing.

Trade-offs

Pros:

• Strongest isolation model, enforced by organizational boundaries
• Simplest permission model, with no entity-scoped grants needed
• Each unit operates completely autonomously

Cons:

• Requires organizational restructuring, not just permission changes
• Separate billing and licensing per organization, which may affect contract structure
• Shared services require account sharing setup
• Some cross-organization reporting requires custom dashboards or Data Plus features

Next steps for separate organizations

To pursue this model, see multi-tenancy, then contact your account representative to work through shared service workflows, a migration plan for moving units to separate organizations, account sharing for any shared platform services, and the contract and billing implications.

Alternative solution: RBAC patterns within a single organization

If ByteFlix can't move to separate organizations, because of contract constraints, timeline, or organizational resistance, they can achieve similar outcomes using the RBAC patterns in this guide within a single organization.

Pattern 1: Entity-scoped access (FGA)

What it solves: Business unit separation within a single organization.

How it works: Use fine-grained access to grant each unit's groups access only to their specific fleet entities.

Example:

• byteflix-plus-platform-ops granted the Fleet manager role, scoped to the byteflix-plus-prod-k8s fleet only
• bbs-platform-ops granted the Fleet manager role, scoped to the bbs-prod-k8s fleet only

Result: ByteFlix+ teams can act only on ByteFlix+ fleets, and BBS teams only on BBS fleets.

Limitation: This requires Authentication domain manager to set up the initial access grants via the Fleet permissions UI. Once established, unit leads can't grant access to new fleets without involving central IT.

Reference: basic pattern.

Pattern 2: Custom lifecycle roles

What it solves: Lifecycle separation, with Platform Ops shaping fleets and App Teams deploying.

How it works: Create two custom entity-scoped roles targeting Fleet:

• Fleet author, carrying Modify, assigned to Platform Ops teams
• Fleet deployer, carrying Deploy, assigned to App Teams and contractors

Both roles are then granted to their groups on specific fleet entities using Pattern 1.

Result: Platform Ops shape the fleets they own, App Teams run deployments, and neither can delete a fleet.

Limitation: Creating custom roles requires Pro or Enterprise edition. Granting them on fleets requires Authentication domain manager, via the Fleet permissions UI.

Reference: advanced pattern.

Pattern 3: Group admin delegation

What it solves: Contractor delegation without Authentication domain manager.

How it works: Grant unit leads the Group admin role scoped to their unit's operational groups.

Example for ByteFlix+:

• Group: byteflix-plus-bu-leads
• Role: Group admin
• Scope: can manage membership of byteflix-plus-platform-ops and byteflix-plus-app-teams

Result: Unit leads can add and remove contractors from groups without involving central IT and without needing Authentication domain manager.

Limitation: Unit leads can manage who is in a group, but can't create new access grants or assign groups to new fleets. When a new fleet is created, central IT must still create the access grant for it.

Reference: enterprise pattern.

Combined RBAC architecture

Using all three patterns together within a single organization, ByteFlix's architecture looks like this:

Organization: ByteFlix Entertainment

├── ByteFlix+ (Streaming BU):
│   ├── Groups:
│   │   ├── byteflix-plus-bu-leads (Group admin over operational groups)
│   │   ├── byteflix-plus-platform-ops (Fleet author role)
│   │   └── byteflix-plus-app-teams (Fleet deployer role, includes contractors)
│   └── Fleets (entity-scoped to ByteFlix+ groups only):
│       ├── byteflix-plus-prod-k8s
│       └── byteflix-plus-stage-k8s
│
├── BBS (Broadcast BU):
│   ├── Groups:
│   │   ├── bbs-bu-leads (Group admin)
│   │   ├── bbs-platform-ops (Fleet author role)
│   │   └── bbs-app-teams (Fleet deployer role)
│   └── Fleets (entity-scoped to BBS groups only):
│       ├── bbs-prod-k8s
│       └── bbs-stage-k8s
│
└── PixelTV (Cable BU):
    ├── Groups:
    │   ├── pixeltv-bu-leads (Group admin)
    │   ├── pixeltv-platform-ops (Fleet author role)
    │   └── pixeltv-app-teams (Fleet deployer role)
    └── Fleets (entity-scoped to PixelTV groups only):
        ├── pixeltv-prod-k8s
        └── pixeltv-stage-k8s

Custom entity-scoped roles, created once by central IT:
├── Fleet author (Modify)
└── Fleet deployer (Deploy)

RBAC trade-offs

Pros:

• No organizational restructuring required
• Single contract and billing relationship
• Achieves operational separation between units with correctly configured grants

Cons:

• Requires initial setup by central IT, meaning authentication domain manager involvement
• New fleets still require central IT to create access grants, an ongoing dependency
• A more complex permission model than separate organizations
• Separation depends on correct access grant configuration, and isn't enforced by organizational boundaries

Role requirements

Roles are additive, so a user who holds several has the sum of their permissions. For what each standard role covers, see user management concepts.

Known issues and workarounds

Cannot query role IDs directly

Problem: NerdGraph doesn't provide a direct query to list role IDs by name.

Workaround: Read them off the groups that already hold the role:

{
  actor {
    organization {
      authorizationManagement {
        authenticationDomains(id: "YOUR_AUTH_DOMAIN_ID") {
          authenticationDomains {
            groups {
              groups {
                displayName
                roles {
                  roles {
                    roleId
                    displayName
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Finding fleet GUIDs

Problem: Fleet GUIDs aren't easily discoverable via the UI.

Workaround: Navigate to the fleet details page, where the GUID is in the URL after /fleets/. To query fleets instead, see the NerdGraph Fleet Control tutorial.

Quick reference: Finding NerdGraph IDs

Organization and authentication domain IDs:

{
  actor {
    organization {
      id
      name
      userManagement {
        authenticationDomains {
          authenticationDomains {
            id
            name
          }
        }
      }
    }
  }
}

Group IDs:

{
  actor {
    organization {
      userManagement {
        authenticationDomains(id: "YOUR_AUTH_DOMAIN_ID") {
          authenticationDomains {
            groups {
              groups {
                id
                displayName
              }
            }
          }
        }
      }
    }
  }
}

Account ID: Visible in the New Relic URL, or:

{
  actor {
    accounts {
      id
      name
    }
  }
}

Automation script template

For teams managing multiple fleets and groups at scale, here's a template using the New Relic CLI. It creates a group, creates a fleet, and grants the group access to that fleet.

Create the custom roles in the UI first, as described in the advanced pattern, and pass the role ID into the script.

$
#!/bin/bash
$
set -euo pipefail
$

$
# Prerequisites:
$
#   - New Relic CLI installed and profile configured with a user key
$
#   - The Authentication domain manager role, required to create access grants
$
#   - A role created in Administration > Access management > Roles, and its ID
$

$
AUTH_DOMAIN_ID="YOUR_AUTH_DOMAIN_ID"
$
ACCOUNT_ID="YOUR_ACCOUNT_ID"
$
ROLE_ID="YOUR_ROLE_ID"
$
GROUP_NAME="fleet-architects"
$
FLEET_NAME="production-us-east-k8s"
$

$
# 1. Create the group. Note the returned group ID.
$
echo "Creating group ${GROUP_NAME}..."
$
newrelic nerdgraph query 'mutation CreateGroup($authDomainId: ID!, $displayName: String!) {
$
  userManagementCreateGroup(createGroupOptions: {
$
    authenticationDomainId: $authDomainId
$
    displayName: $displayName
$
  }) {
$
    group { id displayName }
$
  }
$
}' --variables "{\"authDomainId\": \"${AUTH_DOMAIN_ID}\", \"displayName\": \"${GROUP_NAME}\"}"
$

$
# 2. Create the fleet. Note the returned fleet GUID.
$
echo "Creating fleet ${FLEET_NAME}..."
$
newrelic nerdgraph query 'mutation CreateFleet($name: String!, $scopeId: ID!) {
$
  fleetControlCreateFleet(fleetEntity: {
$
    name: $name
$
    description: "Created by setup script"
$
    managedEntityType: KUBERNETESCLUSTER
$
    scope: { type: ACCOUNT, id: $scopeId }
$
  }) {
$
    entity { id name }
$
  }
$
}' --variables "{\"name\": \"${FLEET_NAME}\", \"scopeId\": \"${ACCOUNT_ID}\"}"
$

$
# 3. Grant the group access to the fleet, using the IDs returned above.
$
GROUP_ID="GROUP_ID_FROM_STEP_1"
$
FLEET_GUID="FLEET_GUID_FROM_STEP_2"
$

$
echo "Granting entity-scoped access..."
$
newrelic nerdgraph query 'mutation GrantFleetAccess($groupId: ID!, $fleetGuid: ID!, $roleId: ID!) {
$
  authorizationManagementGrantAccess(grantAccessOptions: {
$
    grantee: { type: GROUP, id: $groupId }
$
    entityAccessGrants: {
$
      entity: { id: $fleetGuid, type: "fleet" }
$
      roleId: $roleId
$
    }
$
  }) {
$
    accessGrants { id }
$
  }
$
}' --variables "{\"groupId\": \"${GROUP_ID}\", \"fleetGuid\": \"${FLEET_GUID}\", \"roleId\": \"${ROLE_ID}\"}"
$

$
echo "Setup complete."

Pass values with --variables rather than building query strings by hand, so names containing spaces or quotes don't break the request. To run the steps unattended, capture each response and read the IDs out of it before the next call.

For a fuller set of fleet operations, including updating and deleting fleets and managing deployments, see Fleet Control APIs and CLI.

What's next

• Manage fleets for the fleet permissions UI and config approvals
• Fleet Control APIs and CLI for programmatic access
• Fleet Control security for how configurations and credentials are protected
• User permissions and user management concepts for how groups, roles, and access grants work across New Relic