Skip to main content

Realms

Realms provide a way to organize clusters within a trust domain and delegate access control to teams. They introduce an optional additional hierarchical level in the SPIRL organizational structure, enabling secure, scalable delegation of administrative control.

What Are Realms?​

A realm is a logical organizational boundary within a trust domain that groups clusters together and enables delegated administration. Realms allow SPIRL Administrators to grant specific teams full control over their clusters without giving them access to the entire organization's infrastructure.

Organizational Hierarchy​

Realms fit into the SPIRL hierarchy as follows:

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

Without realms, clusters exist directly under trust domains. With realms, you add an intermediate organizational layer that provides both logical grouping and access control boundaries.

Why Use Realms?​

Realms solve common challenges in multi-team organizations:

Team Autonomy - Teams can manage their own infrastructure without waiting for central platform teams. A Realm Admin for the payments realm can create, update, and delete clusters within that realm independently.

Security Isolation - Realms provide hard boundaries between teams. The payments team cannot access or modify the webapp team's clusters.

Least Privilege Access - You can grant teams exactly the access they need-no more, no less. A CI/CD pipeline service account for the webapp team can be restricted to only manage webapp clusters.

When to Use Realms​

Good Use Cases for Realms​

Multi-team organizations where different teams need to manage their own infrastructure:

  • Payments team manages payment processing clusters
  • Web application team manages frontend and API clusters
  • Data engineering team manages data pipeline clusters
  • Platform team manages shared infrastructure

Product-based organization where each product has its own infrastructure:

  • Each product team gets a realm for their service
  • Clear ownership boundaries between products
  • Teams can operate independently

Business unit separation in large enterprises:

  • Different business units have separate realms
  • Each unit manages their own infrastructure
  • Central IT retains oversight across all units

CI/CD automation with least privilege:

  • Each CI/CD pipeline gets a service account with realm-specific access
  • Pipelines can only deploy to their designated realm
  • Compromised credentials have limited blast radius

When Realms May Not Be Needed​

Small teams where everyone has the same level of trust and access:

  • If your entire team should have access to all infrastructure, realms add unnecessary complexity
  • Use organization-wide Operator role instead

Single-team organizations:

  • If you don't need to delegate access to multiple teams, realms may be overkill
  • Flat cluster organization under the trust domain is simpler

Environment separation only:

  • If you only want to separate production/staging/development, consider using trust domain naming or cluster naming conventions instead
  • Realms are designed primarily for team delegation, not environment isolation
  • However, realms CAN be used for environment separation if that's your organizational model

How Realms Work​

SPIFFE ID Changes​

The most important aspect of realms is that they become part of workload identities. When a cluster belongs to a realm, the realm name is included in all SPIFFE IDs for workloads in that cluster.

Without realm:

spiffe://example.com/my-cluster/ns/default/sa/app

With realm:

spiffe://example.com/payments/my-cluster/ns/default/sa/app
                     └───────┘
                       Realm

This means:

  • Workload identities explicitly include the realm
  • Authorization policies can use the realm in their rules
  • Different realms have clearly distinct identity namespaces
SPIFFE ID Changes Are Disruptive

If you add a cluster to a realm after initially creating it without one, all SPIFFE IDs will change. This can break:

  • Authorization policies in your service mesh
  • Application configurations that reference specific SPIFFE IDs
  • Federation trust relationships
  • Any hardcoded identity checks

Plan your realm structure before registering clusters. If you're considering adding realms to existing clusters, carefully plan the migration as it will change all workload SPIFFE IDs.

Be Aware of Potential SPIFFE ID collisions: When you add a cluster to a realm, the realm name is automatically prefixed to all SPIFFE IDs. This could create collisions if you have clusters that use custom SPIFFE ID Path Templates. For example, if you have a cluster named payments without a realm using the default kubernetes path template of /{{cluster.name}}/ns/{{kubernetes.pod.namespace}}/sa/{{kubernetes.pod.service_account}}, its SPIFFE IDs look like spiffe://example.com/payments/.... If you later create a payments realm and a cluster using a custom path template of /ns/{{kubernetes.pod.namespace}}/sa/{{kubernetes.pod.service_account}}, the SPIFFE IDs also become spiffe://example.com/payments/....

Access Control Model​

Realms introduce a new role called Realm Admin that works alongside existing organization roles.

Organization roles (Owner, Administrator, Operator, Manager, Auditor) grant permissions across the entire organization, including all trust domains and realms.

Realm Admin role grants permissions only within a specific realm:

  • Create, read, update, and delete clusters in the assigned realm
  • View workloads and configurations for clusters in the assigned realm
  • Cannot access clusters in other realms
  • Cannot create or delete realms themselves
  • Cannot modify realm role assignments

Common delegation pattern:

  1. Assign a user the Auditor organization role
  2. Assign the same user as Realm Admin for specific realms
  3. Now The user can view everything but only modify their assigned realm(s)

Learn more about realm access control in the Roles documentation.

Realm Lifecycle​

Creating realms: Only users with Administrator or Owner organization roles can create realms. Realms are created within a specific trust domain.

Assigning administrators: SPIRL Administrators assign Realm Admin roles to users or service accounts. Each assignment grants access to one specific realm.

Managing clusters: Once assigned, Realm Admins can register clusters within their realm, configure them, and manage their lifecycle.

Deleting realms: Realms can only be deleted after all clusters within them are removed or reassigned. This prevents accidental deletion of active infrastructure.

Realm Naming​

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 carefully based on your organizational structure, not temporary project names or changing team structures.

Example: Multi-Team Setup​

Here's how a typical multi-team organization might structure realms:

Organization: Acme Corp
Trust Domain: acme.com

Realms:
  ├─ payments (Payments Team)
  │   ├─ Realm Admin: payments-lead@acme.com
  │   ├─ Clusters: payments-us-west, payments-eu-central
  │   └─ Workloads: payment-processor, fraud-detection
  │
  ├─ webapp (Web Application Team)
  │   ├─ Realm Admin: webapp-lead@acme.com
  │   ├─ Clusters: webapp-prod, webapp-staging
  │   └─ Workloads: frontend, api-gateway
  │
  └─ team-data (Data Engineering Team)
      ├─ Realm Admin: data-lead@acme.com
      ├─ Clusters: data-pipeline-cluster
      └─ Workloads: spark-jobs, kafka-consumers

In this setup:

  • Each team has full autonomy over their realm
  • Teams cannot interfere with each other's infrastructure
  • SPIRL Administrators retain oversight and can manage all realms
  • Service accounts can be assigned to specific realms for CI/CD automation

Key Considerations​

Before implementing realms in your organization:

  1. Plan your structure carefully - Realm names are immutable and affect SPIFFE IDs
  2. Consider your team organization - Realms should match your actual team structure
  3. Document your realm purpose - Make it clear which team owns each realm
  4. Think about CI/CD access - Plan which service accounts need access to which realms
  5. Understand SPIFFE ID impact - Changing realm assignments changes workload identities
  6. Review your authorization policies - Ensure they'll work with realm-namespaced identities

Realms are a powerful tool for delegated administration, but they require thoughtful planning to use effectively.

Next Steps​