Realm Operations

This guide covers the complete lifecycle of managing realms with spirlctl, including creating realms, assigning team administrators, and understanding realm-scoped access control.

Understanding Realms

Realms provide a way to organize clusters within a trust domain and delegate access control to teams. They introduce an optional organizational level in the Defakto hierarchy:

Organization
  └─ Trust Domain
       └─ Realm (optional organizational level)
            └─ Cluster
                 └─ Workloads (with SVIDs)

Key Benefits

• Team Autonomy - Teams manage their own clusters without waiting for platform teams
• Security Isolation - Teams cannot access or modify other teams' clusters
• Least Privilege Access - Grant teams exactly the access they need, no more
• Flexible Organization - Structure infrastructure by team, product, or business unit

info

For a comprehensive overview of realms, including when to use them and how they work, see the Realms concept guide.

Realm Lifecycle Overview

A typical realm workflow includes:

1. Create - Defakto Administrators create realms within trust domains
2. Assign - Administrators assign Realm Admin roles to users, service accounts, or IdP groups
3. Manage - Realm Admins create and manage clusters within their realm(s)
4. Monitor - List and view realm information
5. Delete - Remove realms after clusters are removed

Creating Realms

Create a Realm

Only users with Administrator or Owner organization roles can create realms.

spirlctl trust-domain realm create payments --trust-domain example.com

Example output:

Realm "payments" created successfully under trust domain "example.com"
ID: rlm-doudrudq4t

Realm Naming Requirements

Realm names must be valid SPIFFE ID path segments:

• Allowed: Lowercase letters (a-z), digits (0-9), hyphens (-)
• Not allowed: Uppercase letters, spaces, underscores, special characters
• Cannot start or end with: Hyphen
• Pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$

Valid examples:

• payments
• team-platform
• webapp
• customer-portal

Invalid examples:

• Payments (uppercase)
• team_platform (underscore)
• -payments (starts with hyphen)
• payments- (ends with hyphen)

Realm Names Are Immutable

Once created, realm names cannot be changed. Choose names based on your organizational structure, not temporary project names or changing team structures.

Listing Realms

List All Realms in a Trust Domain

View all realms in a trust domain:

spirlctl trust-domain realm list --trust-domain example.com

Example output:

Name         ID              TrustDomainID    Created At
payments     rlm-doudrudq4t  td-pxr42qhpfg    2024-01-15T10:30:00Z
webapp       rlm-kxm29sjwpl  td-pxr42qhpfg    2024-01-15T10:31:00Z
team-data    rlm-nvz85tkqgm  td-pxr42qhpfg    2024-01-15T10:32:00Z

3 realms found.

Filter by Realm Name

You can filter the list to search for specific realm names:

spirlctl trust-domain realm list \
  --trust-domain example.com \
  --name payments

Managing Realm Access

Understanding Realm Roles

Realms use a Realm Admin role that grants delegated administrative control over clusters within a specific realm. The role can be assigned to users, service accounts, or IdP groups. Principals with this role can:

• Create, read, update, and delete clusters within the assigned realm
• View workloads and configurations for clusters in the assigned realm
• Register new cluster versions within the assigned realm

Realm Admins cannot:

• Access clusters in other realms
• Create or delete realms
• Modify realm role assignments
• Elevate their own privileges

Common Delegation Pattern

Assign users the Auditor organization role (read-only everywhere) and then assign them as Realm Admin for specific realms. This grants them read-only access across the organization while giving them full CRUD access to clusters in their assigned realm(s).

For detailed information about realm roles and permissions, see the Roles documentation.

Assign User to Realm Admin Role

Assign a user as administrator for a specific realm:

spirlctl iam user role assign realm payments-lead@example.com \
  --trust-domain example.com \
  --realm-name payments \
  --role-name Administrator

Example output:

Successfully assigned realm role Administrator to user payments-lead@example.com in realm payments (example.com)
Assignment ID: rra-kxm29sjwpl

Assign Service Account to Realm Admin Role

Assign a service account as administrator for a specific realm (useful for CI/CD pipelines):

spirlctl iam service-account role assign realm payments-cicd \
  --trust-domain example.com \
  --realm-name payments \
  --role-name Administrator

Example output:

Successfully assigned realm role Administrator to service account payments-cicd in realm payments (example.com)
Assignment ID: rra-nvz85tkqgm

Remove User from Realm Admin Role

Remove a user's Realm Admin role assignment:

spirlctl iam user role remove realm payments-lead@example.com \
  --trust-domain example.com \
  --realm-name payments \
  --role-name Administrator

Example output:

Successfully removed realm role Administrator from user payments-lead@example.com in realm payments (example.com)

Remove Service Account from Realm Admin Role

Remove a service account's Realm Admin role assignment:

spirlctl iam service-account role remove realm payments-cicd \
  --trust-domain example.com \
  --realm-name payments \
  --role-name Administrator

Example output:

Successfully removed realm role Administrator from service account payments-cicd in realm payments (example.com)

Assign an IdP Group to the Realm Admin Role

Group-based role assignments require group discovery. A realm role assignment can then name an IdP group as its principal, and every user whose discovered groups include that group inherits the role at login, with no per-user assignment:

spirlctl iam group role assign realm platform-admins \
  --trust-domain example.com \
  --realm-name payments \
  --role-name Administrator

Example output:

Successfully assigned realm role Administrator to group platform-admins in realm payments (example.com)
Assignment ID: rra-p9w4hs2lbd

The group name must be the exact string your IdP emits in the groups claim. Matching is byte-exact and case-sensitive. Copy the value as it appears on a user who has logged in, not the display name in your IdP's admin console.

A group name is a free-form value, not a stored entity, so it is never checked against your directory. Only its length is validated, at 1 to 256 characters. You can therefore grant a role to a group nobody belongs to yet, which is what lets you set up access ahead of a team's first login. The trade-off is that a misspelled group name still reports success and appears in list-assignments, while granting no access. If a grant seems to have no effect, compare its group string against the groups discovered on a real member's user detail.

Group inheritance is computed at authorization time from each user's stored groups, as of their last login. There is no membership copy to reconcile: Joining a group in your IdP grants the access on the user's next login, and leaving a group removes it the same way. Because a user's groups are snapshotted at login, someone removed from a group in your IdP keeps the access until they log in again, or until their session expires after at most 72 hours.

Creating and managing group assignments requires the organization Administrator role or above, the same bar as assigning a realm role to a user.

You can also grant a realm role from the realm's detail page in the Defakto Console: Use Grant access on the Delegated admins card and choose Group as the principal type.

With Terraform, the spirl_realm_role_assignment resource takes an idp_group attribute. Exactly one of user_email, service_account_name, or idp_group must be set:

# Assign a realm role to an IdP group; members of the group inherit the role
# at login based on the groups on their session
resource "spirl_realm_role_assignment" "group_admin" {
  trust_domain_id = spirl_trust_domain.my_domain.id
  realm_name      = spirl_realm.production.name
  role_name       = "Administrator"
  idp_group       = "platform-team"
}

Changing the principal replaces the assignment rather than updating it in place.

Remove an IdP Group from the Realm Admin Role

Remove a group's Realm Admin role assignment:

spirlctl iam group role remove realm platform-admins \
  --trust-domain example.com \
  --realm-name payments \
  --role-name Administrator

Example output:

Successfully removed realm role Administrator from group platform-admins in realm payments (example.com)

Removing the assignment severs the derived access for every member of the group at once, and takes effect immediately: The grant is looked up on each request, so no one has to log in again for it to apply. This is the difference between revoking the grant and removing someone from the group in your IdP, which only takes effect on their next login.

Revoking a group's access is also available in the Console, from the realm's Delegated admins card, and by removing the spirl_realm_role_assignment resource in Terraform.

List IdP Group Role Assignments

List the realm role assignments granted to IdP groups, across the organization or for a single group:

# List all group realm role assignments
spirlctl iam group role list-assignments

# List the assignments a single group holds
spirlctl iam group role list-assignments platform-admins

Example output:

Group            Assignment ID   Realm ID        Trust Domain ID  Realm Name  Role ID        Created
platform-admins  rra-p9w4hs2lbd  rlm-doudrudq4t  td-pxr42qhpfg    payments    rr------admin  2024-01-15T10:30:00Z
sre              rra-t6c1nkz8vy  rlm-kxm29sjwpl  td-pxr42qhpfg    webapp      rr------admin  2024-01-15T10:31:00Z
2 group role assignments found.

Review All Delegated Admins

To audit every delegated admin across the organization's realms, regardless of principal type:

spirlctl iam delegated-admin list

# Narrow the listing to specific realms (repeat the flag for more than one)
spirlctl iam delegated-admin list --realm-id rlm-doudrudq4t

Example output:

Realm ID        Principal Type   Principal ID     Assignment ID   Created
rlm-doudrudq4t  user             u-7f3kq2mx8p     rra-kxm29sjwpl  2024-01-15T10:30:00Z
rlm-doudrudq4t  service-account  sa-4b8ntw6rjc    rra-nvz85tkqgm  2024-01-15T10:31:00Z
rlm-doudrudq4t  idp-group        platform-admins  rra-p9w4hs2lbd  2024-01-15T10:32:00Z
3 delegated admins found.

Working with Realm Clusters

Registering Clusters in a Realm

Register a cluster within a specific realm:

spirlctl cluster register payments-us-west-2 \
  --trust-domain example.com \
  --realm payments \
  --platform k8s

This creates a cluster in the payments realm. All workload SPIFFE IDs will include the realm:

spiffe://example.com/payments/payments-us-west-2/ns/default/sa/app
                     └───────┘
                       Realm

SPIFFE ID Changes Are Disruptive

If you register a cluster without a realm and later assign it to one, all SPIFFE IDs will change. This can break authorization policies, service mesh configurations, and federation trust relationships.

Plan your realm structure before registering clusters.

For complete cluster management documentation, see Cluster Management.

Listing Clusters in a Realm

View all clusters within a specific realm:

spirlctl cluster list \
  --trust-domain example.com \
  --realm payments

Deleting Realms

Prerequisites

Before deleting a realm you must remove all clusters from the realm. You cannot delete a realm with associated clusters.

Delete a Realm

Permanently remove a realm:

spirlctl trust-domain realm delete rlm-doudrudq4t

Example output:

Realm "rlm-doudrudq4t" deleted successfully.

Complete Cleanup Process

If you encounter errors about associated clusters:

1. List clusters in the realm:

   spirlctl cluster list --trust-domain example.com --realm payments

2. Disable and delete each cluster:

   spirlctl cluster disable payments-cluster-1 --trust-domain example.com
   spirlctl cluster delete payments-cluster-1 --trust-domain example.com

3. Delete the realm:

   spirlctl trust-domain realm delete rlm-doudrudq4t

Common Workflows

Multi-Team Organization Setup

Set up realms for different teams in your organization:

# Create realms for each team
spirlctl trust-domain realm create payments --trust-domain example.com
spirlctl trust-domain realm create webapp --trust-domain example.com
spirlctl trust-domain realm create team-data --trust-domain example.com

# Assign team leads as Realm Admins
spirlctl iam user role assign realm payments-lead@example.com \
  --trust-domain example.com \
  --realm-name payments \
  --role-name Administrator

spirlctl iam user role assign realm webapp-lead@example.com \
  --trust-domain example.com \
  --realm-name webapp \
  --role-name Administrator

spirlctl iam user role assign realm data-lead@example.com \
  --trust-domain example.com \
  --realm-name team-data \
  --role-name Administrator

# Register clusters for each team
spirlctl cluster register payments-prod \
  --trust-domain example.com \
  --realm payments \
  --platform k8s

spirlctl cluster register webapp-prod \
  --trust-domain example.com \
  --realm webapp \
  --platform k8s

spirlctl cluster register data-pipeline \
  --trust-domain example.com \
  --realm team-data \
  --platform k8s

CI/CD Pipeline Access

Grant a CI/CD service account access to deploy only to a specific realm:

# Create service account
spirlctl service-account create payments-deploy \
  --trust-domain example.com

# Assign to realm
spirlctl iam service-account role assign realm payments-deploy \
  --trust-domain example.com \
  --realm-name payments \
  --role-name Administrator

Now the payments-deploy service account can:

• Create, update, and delete clusters in the payments realm
• View clusters in other realms (if it has Auditor org role)
• Cannot modify clusters in other realms

Product-Based Organization

Organize realms by product or service:

# Create product-specific realms
spirlctl trust-domain realm create customer-portal --trust-domain prod.example.com
spirlctl trust-domain realm create analytics --trust-domain prod.example.com
spirlctl trust-domain realm create api-gateway --trust-domain prod.example.com

# Assign product teams
spirlctl iam user role assign realm portal-team@example.com \
  --trust-domain prod.example.com \
  --realm-name customer-portal \
  --role-name Administrator

Troubleshooting

Cannot Create Realm

Error: "realm with this name already exists"

# List existing realms to check
spirlctl trust-domain realm list --trust-domain example.com

# Use a different name or delete the existing realm
spirlctl trust-domain realm delete rlm-existing-id

---

Error: "invalid realm name"

Cause: The realm name doesn't meet SPIFFE ID path segment requirements.

Solution:

• Use only lowercase letters, digits, and hyphens
• Don't start or end with a hyphen
• Avoid spaces, underscores, and special characters

Valid: payments, team-platform, webapp-prod

Invalid: Payments, team_platform, -payments, payments-

---

Error: "must be an organization owner or admin to perform this operation"

Cause: You don't have sufficient permissions to create realms.

Solution:

• Contact your organization Owner to upgrade your role to Administrator
• Or ask an existing Administrator to create the realm for you

Cannot Delete Realm

Error: "realm has associated clusters and cannot be deleted"

Cause: The realm still has clusters assigned to it.

Solution:

# List clusters in the realm
spirlctl cluster list --trust-domain example.com --realm payments

# Delete each cluster
spirlctl cluster disable payments-cluster --trust-domain example.com
spirlctl cluster delete payments-cluster --trust-domain example.com

# Then delete the realm
spirlctl trust-domain realm delete rlm-doudrudq4t

Cannot Assign Realm Role

Error: "user not found"

Cause: The user email doesn't match any user in your organization.

Solution:

# Verify the email address is correct
spirlctl iam user list

# Invite the user if they're not in your organization
spirlctl iam user invite user@example.com

---

Error: "realm not found"

Cause: The realm name or trust domain is incorrect.

Solution:

# List existing realms to verify the name
spirlctl trust-domain realm list --trust-domain example.com

# Ensure you're using the realm name, not the realm ID
# Correct: --realm-name payments
# Incorrect: --realm-name rlm-doudrudq4t

Realm Admin Cannot Perform Operation

Error: "must have realm admin access to this cluster's realm"

Cause: The user is trying to manage a cluster in a realm where they don't have Realm Admin privileges.

Solution:

• Verify the cluster's realm assignment
• Assign the user as Realm Admin to the correct realm
• Or upgrade the user's organization role to Operator or higher

# Assign user to the cluster's realm
spirlctl iam user role assign realm user@example.com \
  --trust-domain example.com \
  --realm-name payments \
  --role-name Administrator

Best Practices

Realm Design

1. Match Team Structure - Create realms that align with your actual team organization
2. Use Descriptive Names - Name realms after teams or products, not environments (use payments, not prod-1)
3. Plan Before Creating - Realm names are immutable; choose carefully
4. Document Ownership - Keep a record of which team owns each realm
5. Consider CI/CD Access - Plan which service accounts need access to which realms

Access Management

1. Follow Least Privilege - Use the Auditor + Realm Admin pattern for team members
2. Separate CI/CD Accounts - Create dedicated service accounts per realm for automation
3. Regular Access Reviews - Periodically audit realm role assignments
4. Remove Unused Assignments - Clean up role assignments when team members change roles
5. Document Access Patterns - Maintain runbooks for granting and revoking realm access

Cluster Organization

1. Plan Realm Structure First - Define realms before registering clusters
2. Consistent Naming - Use clear cluster names that indicate their realm/purpose
3. Avoid Realm Changes - Don't reassign clusters between realms due to SPIFFE ID changes
4. Group Related Clusters - Keep clusters that need to communicate in the same realm
5. Monitor Realm Usage - Track how many clusters are in each realm

Migration Strategy

If adopting realms for existing infrastructure:

1. Create Realms First - Define realm structure before any changes
2. Test in Development - Practice the migration in a dev environment
3. Update Infrastructure as Code - Modify Terraform/scripts to include realms
4. Communicate Changes - Notify teams about SPIFFE ID format changes
5. Gradual Migration - Consider registering new clusters with realms while leaving existing ones unchanged

Command Reference

Realm Management Commands

Command	Description
trust-domain realm create	Create a new realm in a trust domain
trust-domain realm list	List all realms in a trust domain
trust-domain realm delete	Delete a realm (must be empty)

Realm Access Control Commands

Command	Description
iam user role assign realm	Assign user to Realm Admin role
iam user role remove realm	Remove user from Realm Admin role
iam service-account role assign realm	Assign service account to Realm Admin role
iam service-account role remove realm	Remove service account from Realm Admin role
iam group role assign realm	Assign IdP group to Realm Admin role
iam group role remove realm	Remove IdP group from Realm Admin role
iam group role list-assignments	List realm role assignments held by IdP groups
iam delegated-admin list	List all delegated admins across the organization's realms

Realm-Aware Cluster Commands

Command	Description
cluster register --realm	Register cluster in a specific realm
cluster list --realm	List clusters in a specific realm
cluster info	View cluster details (includes realm if assigned)

Next Steps

• Understand realm concepts and use cases
• Learn about Realm Admin permissions
• Manage clusters within realms
• Configure SPIFFE ID templates
• Set up trust domain operations