A Polaris realm is a top level administrative boundary that lets a single Polaris service host separate sets of principals, roles, catalogs, and configuration. Realms reduce accidental cross tenant visibility at the catalog layer, they do not replace network isolation, separate encryption keys, storage policies, database controls, or resource quotas. Production tenancy requires those other boundaries to be aligned with realms. The Polaris realm feature is documented as unreleased at the time of writing, so verify behavior against the linked primary documentation and test upgrades with realm routing enabled.
Polaris realms introduce a logical multi tenant organization inside the Polaris control plane. Realms provide independent catalogs, identity mappings, role definitions, and configuration overrides per realm. Practically, a realm lets you run multiple independent tenant catalogs on one Polaris cluster without those catalogs sharing catalog objects, role names, or principal assignments by default.
That said, realms are not a complete tenancy boundary. They operate at the Polaris control plane and catalog level. They do not, by themselves, guarantee isolation of the following:
For production tenancy you must combine realms with network, storage, and compute isolation. The Polaris documentation marks the realms guide as unreleased, so confirm exactly which resources are scoped to realms in the version you run. I checked the official realm documentation, the production configuration guide, and the Polaris 1.7.0 release notes while preparing this article. See the Sources section for links and verification statements, checked on September 22, 2026 where freshness matters.
The simplest mental model is this: a realm is an umbrella for named collections of control plane artifacts. That includes catalogs, principal stores, role definitions, and realm scoped configuration. Realm scoping changes how Polaris resolves principals and catalogs from incoming requests. The control plane holds many realms and routes an API request into the appropriate realm based on routing keys described in configuration.
Key decision points you must make when adopting realms:
Polaris resolves request context before applying catalog or role logic. The usual flow is: incoming request arrives, an ingress or Polaris front end extracts a realm routing key, Polaris loads realm specific catalogs and configuration, and Polaris enforces RBAC using the realm principal and role mappings. This means a misrouted request may be evaluated against the wrong realm, so routing correctness is critical. Upgrade testing must include realm routing, because routing behavior can change across versions. This caution comes directly from the current unreleased realm documentation and the production configuration guide, which advise testing realms across upgrades.
Polaris governs metadata and access decisions, it does not move or host your data. Realms partition the control plane, but they do not, by default, create separate data paths. Engines or query runners continue to read data from the storage locations that catalogs point to. That separation creates four possible relationships between realm and data plane:
You must decide which model you need. If you need cryptographic separation, assign unique KMS keys and storage credentials per tenant. If you need network separation, use VPC, private link, or separate storage accounts. Polaris realms are one ingredient; you still need storage-side policies and compute-side quotas to achieve a full tenancy posture. The Polaris production configuration guide lists recommended production hardening steps that are complementary to realms. See Sources for that link, and review it for details before rolling realms into production.
How requests get assigned to a realm matters. Polaris can accept an explicit realm identifier in API requests if your clients provide it. More common in production is to use an ingress or identity provider that sets a header or adds a realm claim to an authentication token. Choose one and standardize it across your ecosystem.
Common patterns:
Example: realm aware request pattern
POST /api/v1/catalogs HTTP/1.1
Host: tenant-a.polaris.example.com
Authorization: Bearer eyJhbGciOi... (JWT includes iss and realm claim)
Content-Type: application/json
{"name":"tenant_a_sales","storageConfig":{...}}In this pattern the ingress routes traffic by hostname. The JWT includes a realm claim. Polaris checks that the incoming hostname maps to realm tenant-a and it validates the token issuer and realm claim match. After that Polaris creates or updates the catalog inside the tenant-a realm. If the ingress or token were misconfigured and the request lands in tenant-b realm, the API will either fail a realm validation check or create a catalog in the wrong realm, depending on configuration. That is why routing tests are part of any upgrade or deploy checklist.
For how engines discover the catalog and interact with the catalog API, the Polaris REST API documentation explains the typical engine to catalog flows and may help when you design how clients obtain realm scoped endpoints.
Below is a practical checklist you can use when onboarding a tenant into a Polaris realm. Each step maps to a decision or test you should run. Do not treat realms as sufficient by themselves, add these items to your standard tenancy onboarding.
For a deeper discussion of Polaris role patterns and credential vending, the Dremio article on Polaris access control outlines operational patterns and is a good companion to the checklist.
Testing isolation is the most important operational task. Test the control plane and the data plane independently and together. Include tests in CI that run on every upgrade candidate. Here are focused test cases you can automate.
Automate these tests in a CI pipeline and gate releases on them. Include ephemeral tenants and quotas so test runs do not consume production resources.
Here are practical failure modes I have seen in similar multi tenant control planes and how they map to Polaris realms.
Monitoring and alerting should include realm identifiers in logs and metrics. Track error rate and unauthorized access attempts per realm. Track catalog creation rate and unusual spikes in cross realm activity, because rapid unexpected catalog changes are often an indicator of routing misconfiguration or an automated script gone wrong.
Each stage should have an explicit rollback plan and a measured success criteria. Success criteria include zero unauthorized accesses in audit logs, passing isolation test cases, and acceptable performance under representative load.
Observability matters. Add these measurements to your dashboards and SLOs after enabling realms.
Include alerts for behavioral anomalies, not only hard failures. Examples: a sudden rise in catalog creation in one realm, or repeated 401s for a realm, which can indicate either credential expiration or an attempted attack.
This worked example walks through onboarding tenant "acme" into a Polaris cluster using host header routing, per tenant storage prefixes, and per tenant KMS keys. It is intentionally concrete but does not invent commands. Where commands or keys would appear in a real runbook I specify the parameters to verify instead.
1) Confirm Polaris version and realm documentation behavior for that version. Verify whether realm routing supports host header, path prefix, and token claims in your release. The realm docs are marked unreleased; check them first.
2) DNS: create tenant-acme.polaris.example.com and provision TLS certificate. Ensure ingress will map that hostname to the Polaris front end.
3) Identity provider: configure an OIDC client to emit a realm claim with value acme. Create a service account and user accounts for the tenant. Provide a token that includes realm=acme for testing.
4) Storage: create a storage prefix acme/ in your object storage, provision a tenant specific service principal or IAM role, and create or assign a KMS key dedicated to the tenant metadata and data if you require cryptographic separation.
Post onboarding, monitor the metrics listed earlier for at least two weeks before raising the tenant to full SLA status. If you need more detailed patterns for engine to catalog interactions, consult the Dremio post on the Polaris REST API, which explains how engines discover and authenticate to the catalog. That helps you design how clients should obtain realm aware endpoints.
Do not assume behaviors that the documentation does not state. Verify the following in your Polaris release during testing:
If the documentation does not specify one of the above, add a test case for it and file a verification ticket with the Polaris maintainers if you find ambiguous behavior.
These Dremio resources are useful when you plan and operate realms. I include each once in the article where it helps the reader.
This section gives a concrete sequence you can follow to add realm-aware request handling to an existing Polaris deployment, using the realm-aware request pattern and the tenant configuration checklist you already have. The steps assume Polaris 1.7.0 or later, with the realm feature present in the unreleased documentation. Verify your Polaris binary and documentation for realm feature flags before you begin, since the documentation is marked unreleased and behavior may change.
Summary, before you touch production: add a realm header parser near the API edge, validate realms against your tenant configuration store, issue realm-scoped tokens, and route to a realm-aware control plane or enforcement proxy. Test routing and token handling end to end in a staging cluster where you can break components deliberately.
1) Record current state. Export Polaris control plane and data plane configs, and save current routing rules for API gateways. Keep copies of tenant configuration artifacts referenced in your tenant configuration checklist.
2) Add realm detection at the API gateway. If you use Envoy, add a vhost or listener filter that extracts the realm from a header such as X-Polaris-Realm or from the first path segment. Decide on a canonical source. Document that in your internal API contract. For example, choose header extraction if you will send requests through browser clients that cannot alter path prefixes.
3) Implement validation against tenant configuration. The gateway should call your tenant registry service or a cached copy to validate the realm string and fetch tenant-specific limits, default project IDs, and allowed storage buckets. This is the place to enforce the tenant configuration checklist items such as allowed external storage and request quotas.
4) Issue realm-scoped tokens. When your authentication flow issues Polaris access tokens, include realm claims. Polaris routing and enforcement components will need to read that claim. Use short lived tokens for interactive flows, and a rotation scheme for machine tokens. The unreleased realms docs describe expected token behavior, so verify claim names and formats when you test.
5) Route requests using realm. Update your service mesh or load balancer to forward the realm header to the Polaris API server and any enforcement proxies. Ensure the header is immutable after the gateway, for example by stripping it from external requests and re-inserting a gateway-signed header. This prevents spoofing by clients.
6) Make Polaris control plane realm-aware. Configure Polaris using the documented production configuration guide, mapping realm identifiers to Polaris tenant objects. Because realms docs are currently unreleased, verify that the Polaris version you have exposes the realm mapping keys, and test that operations like project creation and query execution resolve to the expected tenant context.
7) Enforce data plane boundaries. Polaris will route metadata and planning through the control plane, but storage access often happens via connectors configured per tenant. Ensure connectors are configured only with tenant-authorized credentials, and validate that the connector config respects the tenant configuration checklist item about storage bucket isolation.
8) Gradually roll traffic. Start with a small percentage of tenant requests or a single noncritical tenant, then increase after verifying metrics listed below. Include upgrade routing tests as part of this ramp, since realm routing behavior may change across Polaris releases.
Do these checks in a reproducible script so you can run them after upgrades. If the realm feature changes between releases, your script will highlight the change quickly.
Realms reduce a large class of misrouting and configuration errors, but they do not eliminate all risks. Use targeted failure injection to validate real-world resilience. Below are five focused tests that exercise routing, tokens, control plane mapping, and storage enforcement. Run these in staging with realistic data volumes.
What to do: Send requests that set the realm header to another tenant, and requests that omit the header entirely. Also replay a previously captured request with a valid header but expired token.
What to expect: The gateway must reject external headers or overwrite them with a gateway-signed header. Polaris should reject requests with invalid or missing realm claims when the endpoint requires them.
Why it matters: Attackers or buggy clients may attempt to change realm identifiers. If the header is mutable downstream, cross-tenant access is possible.
What to do: Issue tokens whose realm claim differs from the header, and tokens with no realm claim. Test both interactive tokens and machine tokens used by connectors.
What to expect: Your authentication layer and Polaris should agree on which claim source is authoritative. One side should reject the request, or the gateway should canonicalize the realm before token verification.
Why it matters: Tokens are the canonical auth signal. If gateway and control plane disagree, you get silent misattribution and potential data leaks.
What to do: Simulate a configuration sync failure where Polaris control plane sees stale tenant mappings. Create a new tenant in the gateway registry but not in Polaris, then run tenant operations.
What to expect: Operations should fail fast with a clear error indicating missing tenant mapping. If they do not fail, you need stronger validation at the gateway or deployment automation to prevent drift.
Why it matters: Drift between the gateway registry and Polaris mapping will cause unexpected resource creation or silent routing to a default tenant.
What to do: Replace a tenant connector credential with a credential that has broader access, then attempt to read another tenant's storage. Also revoke a tenant credential while a long-running query is active.
What to expect: Reads must fail if the connector credential lacks permission. Long-running queries should either complete using existing credentials cached by the executor, or fail predictably if credential revocation is immediate. Observe which behavior your connector and execution stack follow and document it.
Why it matters: Data plane isolation depends on connector configuration and cloud IAM. Polaris realms cannot replace per-connector credential controls.
What to do: Perform a canary upgrade of Polaris or the gateway that handles realm headers. During the canary window, run a mix of realm-scoped and non-realm requests, including requests that exercise default project bindings and storage access.
What to expect: Any change in routing or realm interpretation must be observable in your test harness. If behavior differs, rollback. Because realm documentation is unreleased, be particularly careful with upgrades across minor or major Polaris releases.
Why it matters: Upgrades are when implicit assumptions break. If your deployment relies on the unreleased realm behavior, test it explicitly before broad rollout.
This decision table helps you choose whether realms are sufficient, and lists additional controls you should add depending on tenant risk profile. Think of realms as a logical scoping mechanism that simplifies routing and configuration. They do not replace network segmentation, cloud IAM, or billing isolation.
Low risk tenants, such as internal analytics teams, where data sensitivity is low:
Medium risk tenants, multi-team environments with mixed sensitivity:
High risk tenants, external customers or regulated workloads:
When deciding, also consider operational cost. The stricter the controls, the higher the runbook overhead. Realms simplify policy mapping, but strict isolation requires per-tenant configuration and verification tasks from the tenant configuration checklist.
Label of fact check: I checked the Polaris realm documentation links and the Polaris 1.7.0 release notes on September 22, 2026 for feature presence and recommended production configuration behavior. Because the realm documentation is marked unreleased, you must verify specific configuration keys and token claim names in your deployed Polaris version.
No. Realms isolate control plane artifacts but do not substitute for network, storage, KMS, or compute boundaries. You must combine realms with those controls for production tenancy.
At the time of writing, the realms documentation is marked unreleased. Behavior can change across Polaris versions. Verify behavior in your target release and include realm routing in upgrade tests. Facts checked on September 22, 2026 where freshness matters.
Common patterns are host header routing, path prefix routing, and token claim routing. Which ones Polaris honors may vary by release. Validate ingress and token claim extraction in your environment.
They can, technically, if you design catalogs to use prefixes and storage access is correctly scoped. Sharing storage increases complexity and risk, so prefer separate buckets or strong ACLs and KMS separation if you need strict isolation.
Include routing smoke tests and full isolation test cases in staged upgrades. Verify that realm routing, catalog resolution, and RBAC work identically before and after upgrade. The unreleased realm docs specifically call out upgrade testing as necessary.
Track per realm request rate, error rate, unauthorized attempts, catalog churn, storage access failures, compute usage, and audit trail completeness. Use these to detect misrouting, attacks, and noisy neighbor issues.
These guides cover adjacent implementation details that are outside this article's main scope.
For a deeper treatment, download Apache Polaris: The Definitive Guide, co-authored by Alex Merced and available free from Dremio.
To put the catalog and table-format ideas into practice, explore Dremio Open Catalog.
Deploy agentic analytics directly on Apache Iceberg data with no pipelines and no added overhead.
Editor’s note, September 2026. This post was published in September 2023 and some product details have changed since. Nessie is still available and self-deployable under the Apache-2.0 licence, and it remains the clearest implementation of catalog-level branching. It is not an Apache Software Foundation project, and its development has slowed considerably. For how the current […]
With its capabilities in on-prem to cloud migration, data warehouse offload, data virtualization, upgrading data lakes and lakehouses, and building customer-facing analytics applications, Dremio provides the tools and functionalities to streamline operations and unlock the full potential of data assets.
Apache Iceberg 1.12.0 expands v3 engine support, REST catalog operations, streaming reliability, and v4 groundwork. Learn how to upgrade safely.