Skip to main content

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 SPIRL 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 - SPIRL Administrators create realms within trust domains
  2. Assign - Administrators assign Realm Admin roles to users or service accounts
  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. Users or service accounts 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)

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​

CommandDescription
trust-domain realm createCreate a new realm in a trust domain
trust-domain realm listList all realms in a trust domain
trust-domain realm deleteDelete a realm (must be empty)

Realm Access Control Commands​

CommandDescription
iam user role assign realmAssign user to Realm Admin role
iam user role remove realmRemove user from Realm Admin role
iam service-account role assign realmAssign service account to Realm Admin role
iam service-account role remove realmRemove service account from Realm Admin role

Realm-Aware Cluster Commands​

CommandDescription
cluster register --realmRegister cluster in a specific realm
cluster list --realmList clusters in a specific realm
cluster infoView cluster details (includes realm if assigned)

Next Steps​