Overview
Apache Polaris is an Apache Iceberg REST catalog: the service that tells a query engine which tables exist, where their metadata lives in object storage, and who may read them. It is the piece that turns a bucket of Parquet files into a lakehouse. Together with SeaweedFS (or any S3-compatible bucket) for storage and Trino for queries, it completes an Iceberg stack wired entirely over internal GVC DNS. The Polaris server is stateless. Every catalog, namespace, table pointer, principal and grant lives in a PostgreSQL metastore that the template deploys for you, single-instance by default or highly available with one flag, so thereplicas knob scales the catalog horizontally with nothing else to coordinate.
What Gets Created
postgresHA.backup.mode: wal-g, no backup cron workload is created; a wal-g-backup sidecar container runs inside RELEASE_NAME-postgres-ha instead. The Polaris server itself has no volume set.
Prerequisites
Three secrets must exist before you install. They are referenced by name and never pass through Helm values. Secrets are org-level, so no GVC flag is involved.Create the root credentials secret
CLIENT_ID and CLIENT_SECRET. These become the realm’s root principal at bootstrap, and they are what Trino, Spark and any other Iceberg REST client authenticate with. Neither value may contain a comma.rootCredentials.secretName to this name.Create the token signing key secret
tokenSigningKey.secretName to this name.Create the metastore credentials secret
username, password and database. The bundled PostgreSQL initializes with it, and the Polaris server and bootstrap workload connect with it:postgres.config.credentialsSecretName (single-instance, the default) or postgresHA.config.credentialsSecretName (HA). database must be URL-safe (letters, digits, _): the JDBC URL is assembled from it at container start. Secret names are org-wide, so give each Polaris release its own secret. PostgreSQL reads the secret only when its data is first initialized — see Rotating the Metastore Password.- Object-storage credentials for the bucket that holds your Iceberg tables. Polaris runs without them and catalogs can be added later — see Building a Lakehouse.
- A bucket and Cloud Account for metastore backups — see Backing Up.
Installation
Install with your three secret names:postgresHA.config.credentialsSecretName instead.
UI
CLI
Terraform
Pulumi
attempt failed (metastore not ready yet?) - retrying in 10s; both recover on their own once the metastore answers, so do not interrupt the install. The HA metastore takes noticeably longer than the single instance.
Configuration
Server
replicas— A fixed number of interchangeable Polaris replicas (minimum1; there is no request-based autoscaling). See Scaling and Availability.resources— Per replica.minMemorymay not exceedmaxMemory, andmaxCpumay not exceed four timesminCpu; the chart refuses to render otherwise and names the value to fix.
JVM
resources.maxMemory (allowed range 40–80), so maxMemory is normally the only number you change.
Realm
Polaris-Realm header: a request without it resolves to this realm, which is what Trino’s Iceberg REST connector needs. A request naming a different realm is rejected with 404. The name may contain only letters, digits, hyphens and underscores.
Credentials
rootCredentials.secretName— The prerequisite dictionary secret holdingCLIENT_IDandCLIENT_SECRET. Required.tokenSigningKey.secretName— The prerequisite opaque secret whose payload is the shared token signing key. Required.
Object Storage
storage.credentialsSecretName— Name of a dictionary secret holdingAWS_ACCESS_KEY_IDandAWS_SECRET_ACCESS_KEY, used for Polaris’s own reads and writes of Iceberg metadata. Empty by default, which is a valid install: the server runs and answers, but catalogs on object storage cannot read or write. Per-provider setup is in Building a Lakehouse.storage.region— The bucket’s region. S3-compatible servers ignore it, but the AWS SDK requires a value.
Bootstrap
bootstrap.image on the same tag as image. The bootstrap workload creates the realm schema and the root principal, then idles. The operation is idempotent: on a restart or upgrade it logs that the realm is already bootstrapped and idles again.
Access
publicAccess.enabled: true, only port 8181 is served on the public endpoint; the health and metrics endpoints on 8182 stay reachable from inside the GVC only. A change to either access setting takes a few minutes to take effect, so re-test rather than trusting the first response.
Single-Instance Metastore
The default metastore. Exactly one ofpostgres and postgresHA must be enabled; the chart refuses to render otherwise.
postgres.config.credentialsSecretName— Name of the prerequisite metastore credentials secret in single-instance mode (see Prerequisites). Polaris connects to the database named by itsdatabasekey. Secret names are organization-wide, so give each Polaris release its own.postgres.backup.*— Optional scheduled backups. See Backing Up.
Highly Available Metastore
postgresHA.enabled: true and postgres.enabled: false for near-zero-downtime upgrades and automatic database failover: 3 Patroni PostgreSQL replicas, 3 etcd replicas and an HAProxy leader endpoint that Polaris connects through.
postgresHA.config.credentialsSecretName— Name of the prerequisite metastore credentials secret in HA mode, the same shape as in single-instance mode. Give each release its own.postgresHA.replicas/postgresHA.volumeset.capacity— PostgreSQL replica count and volume size per replica. The remaining cluster settings take the defaults of the PostgreSQL Highly Available template; its HAProxy endpoint must stay enabled, because it is Polaris’s database address.postgresHA.backup.*— Optional backups as scheduled logical dumps or continuous WAL-G archiving. See Backing Up.
Connecting
access_token; send it as Authorization: Bearer TOKEN. A missing token or a wrong client secret is rejected with 401. The same request works against the public base URL when publicAccess.enabled is true. Reaching Polaris through cpln port-forward has not been exercised against this template; if the tunnel does not answer, run the same request from a workload inside the GVC against the internal base URL.
Building a Lakehouse
Storage, catalog and query engine are three separate templates. This is the path from an empty bucket to queryable Iceberg tables.Prepare a bucket and its credentials
AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. Only S3 and S3-compatible storage are supported by this template.- SeaweedFS
- MinIO
- AWS S3
s3.buckets: [lakehouse]). Its s3.credentialsSecretName secret already holds AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, so set Polaris’s storage.credentialsSecretName to that same secret. There is nothing else to create. Its S3 endpoint is http://SEAWEEDFS_WORKLOAD_NAME.GVC_NAME.cpln.local:8333.cpln helm upgrade, using the same chart version and your other values.Get an access token
TOKEN.Create a catalog
BASE_URL with your internal or public base URL, YOUR_BUCKET with your bucket, and the endpoint with your storage’s S3 endpoint:pathStyleAccess: true and stsUnavailable: true are what an S3-compatible server needs. For AWS S3 itself, drop endpoint, endpointInternal and pathStyleAccess, and set region to the bucket’s region.Point Trino at it
catalogs value. Trino authenticates to Polaris with the root credentials and reaches the bucket with its own S3 keys, because credential vending is off:POLARIS_WORKLOAD_NAME is your Polaris release’s RELEASE_NAME-polaris. iceberg.rest-catalog.warehouse is the catalog name you created.Query it
CREATE SCHEMA, CREATE TABLE, INSERT and SELECT now work against tables stored in the bucket:Other Iceberg Clients
Spark, PyIceberg, Flink and any other Iceberg REST client connect with the same four settings: the REST URI (BASE_URL/api/catalog), the OAuth2 client credential CLIENT_ID:CLIENT_SECRET, the scope PRINCIPAL_ROLE:ALL, and the catalog name as the warehouse. Each also needs its own object-storage credentials. Only the Trino path has been verified with this template. The Spark template’s image does not include the Iceberg Spark runtime, so follow the upstream Iceberg Spark configuration guide to add it.
Operations
Backing Up
Metastore backups are optional and disabled by default. They protect every catalog, namespace, table pointer, principal and grant; the Iceberg data files in your bucket are not part of them. Enable them withpostgres.backup.enabled or postgresHA.backup.enabled, matching your metastore mode, and complete the setup for your provider before enabling. The keys below are written as backup.*; set them inside the enabled metastore block.
In HA mode, postgresHA.backup.mode selects logical (a scheduled dump from the RELEASE_NAME-postgres-ha-backup cron workload) or wal-g (continuous WAL archiving from a wal-g-backup sidecar inside RELEASE_NAME-postgres-ha, with a base backup every walg.intervalSeconds). Single-instance mode takes scheduled logical dumps only.
- AWS S3
- Google Cloud Storage
- S3-compatible (MinIO)
Create a bucket
backup.aws.bucket and backup.aws.region to match.Set up a Cloud Account
backup.aws.cloudAccountName to its name.Create a bucket-scoped IAM policy
YOUR_BUCKET), then set backup.aws.policyName to the policy’s name:Restoring a Backup
The metastore backups are produced by the bundled database templates, so restore them with those templates’ procedures: PostgreSQL for single-instance mode, and PostgreSQL Highly Available for HA mode, using the host from Connecting and the credentials from your metastore credentials secret. Two Polaris-specific constraints apply:- Keep
realmidentical to the value the backup was taken under, or the restored catalogs stay invisible. - Restore into a metastore that does not already hold a bootstrapped realm. A new release bootstraps its realm on first start, so restoring over it collides with the objects the bootstrap created. After a restore, force a redeployment of
RELEASE_NAME-polarisso every replica reconnects.
Upgrading from 1.0.x
Apply every subsection from your version onward, in order, before runningcpln helm upgrade. A removed key is rejected at render, so an upgrade that still carries one fails before anything is applied and the running release is left untouched.
Version 1.1.0 moved the single-instance metastore to the postgres 3.4.1 template, which no longer takes credentials or MinIO keys as values:
config.username was REMOVED in postgres 3.4.0 and tells you to create a secret — that is correct here too. Use the username, password and database your metastore was initialized with, not new ones.
Upgrading from 1.1.0
Version1.2.0 moved the HA metastore to postgres-highly-available 2.5.0, which removed the postgresHA.postgres block. The HA cluster now reads the metastore credentials secret under Prerequisites, named by postgresHA.config.credentialsSecretName.
An upgrade that still carries the postgresHA.postgres block fails with the HA template’s message, which begins postgres-highly-available: the `postgres` block was REMOVED in 2.5.0 and tells you to create a dictionary secret — that is correct here: delete the block and set postgresHA.config.credentialsSecretName to the secret’s name.
Upgrading from 1.2.0
HA MinIO backups only: version1.2.1 replaced postgresHA.backup.minio.accessKey and postgresHA.backup.minio.secretKey with postgresHA.backup.minio.credentialsSecretName, a dictionary secret you create holding accessKey and secretKey — see Backing Up. An upgrade that still carries the old keys fails with backup.minio.accessKey and backup.minio.secretKey were REMOVED in 2.5.0. Create the secret before upgrading, because in wal-g mode the database workload itself references it. Then follow Upgrading from 1.2.1.
Upgrading from 1.2.1
Version1.3.0 removed postgres.credentials: the metastore credentials are now a prerequisite secret, the same one the database templates require on their own. Carrying the old key forward fails the render.
1.2.1 created the metastore secret itself, so this upgrade deletes it. Before upgrading, create a secret under a new name holding the values your database was initialized with — not new ones, or Polaris loses its metastore connection:
postgres.credentials of the 1.2.1 release, and also in the old secret (cpln secret reveal SECRET_NAME -o yaml, where SECRET_NAME is the credentialsSecretName your release used, my-polaris-db-credentials by default) until the upgrade deletes it. Then upgrade with postgres.config.credentialsSecretName (single-instance mode) or postgresHA.config.credentialsSecretName (HA mode) set to the new name, and postgres.credentials removed.
The upgrade restarts the bundled PostgreSQL too (it now reads the new secret), so Polaris briefly loses its database; it reconnects by itself. While access to the new secret propagates, the new version of a workload can wait in get-deployments reporting that it is not allowed to reveal the secret; the previous version keeps serving meanwhile, and it clears by itself. When that wait happens, the PostgreSQL restart (and its brief outage) comes only after it clears.
Upgrading from 1.3.0 or earlier
1.3.1 moves the HA database (postgresHA) to controlplanecorporation/patroni-postgres:0.8, which carries pgvector 0.8.7 (CVE-2026-103484). The fix takes effect when the upgrade restarts the Patroni members; existing data needs nothing. Nothing limits that rollout, so expect a brief interruption of writes while the leader changes. Polaris itself restarts without a gap (the new replica serves before the old one stops); while the leader changes, Polaris’s token endpoint can briefly refuse requests. Upgrade in a quiet window. If you pinned postgresHA.image in your values, set it to the 0.8 tag: tags 0.1 to 0.7 are refused at render. Polaris does not use the vector extension; if you created it yourself in a database, \dx keeps reporting the old version until you run ALTER EXTENSION vector UPDATE; there, which only updates that record. Single-instance mode (postgres) is unchanged.
Rotating the Metastore Password
A running workload keeps the credential values it started with, and PostgreSQL reads the secret only when its data is first initialized, so editing the secret alone does not change the database password. Change one key and keep the others with export, edit, apply:ALTER ROLE for the secret’s username in the database first, then update the secret, then right away force a redeployment of the Polaris server, and wait until get-deployments shows a higher version number, alone and ready (right after the command the status may not show the restart yet, and ready: true alone can still describe the old replica). Do not redeploy the database: restarting it only adds downtime. Connections already open keep working after ALTER ROLE; new ones fail until the redeploy finishes, so rotate in a quiet window.
repl shares the password, and a member that restarts with the old password can be promoted to leader, which splits the cluster. Move the leader to member -0 first, so it restarts last, after every other member already has the new password. pgx runs a command in one member (LOCATION is your GVC’s location, DB_USERNAME the secret’s username):
RELEASE_NAME-polaris, which keeps the old password until it restarts. The app cannot open new database connections from the ALTER ROLE until its own redeploy finishes, so rotate in a quiet window. If a member stays starting, or running without streaming, re-copy it from the leader. This copies the whole database, so it costs network traffic in proportion to its size:
Scaling and Availability
- The server scales horizontally. Replicas share only the metastore and the token signing key, so a token minted by one replica is accepted by every other and a catalog created through one is visible on all of them. At the default
replicas: 1, an upgrade replaces the only replica and requests fail while it restarts; withreplicas: 2or more, a rolling upgrade keeps serving. - Mind the metastore’s connection limit. Each Polaris replica opens up to 20 database connections, plus one for the bootstrap workload, against PostgreSQL’s default limit of 100.
- The bootstrap workload always runs one replica and does nothing after its first run. Do not scale it.
- The metastore is the other half of availability. With the default single-instance
postgres, a database restart takes Polaris down until PostgreSQL is back.postgresHAadds automatic failover behind a stable endpoint, at the cost of a larger footprint. - The first upgrade after an install can restart the bundled database even when no database value changed. Expect a short outage on a single-instance metastore.
- Uninstall deletes the metastore volume sets, taking every catalog definition with them. The Iceberg files in your bucket survive, but nothing indexes them any more. Your three prerequisite secrets are not deleted.
Troubleshooting
Workloads never start and cpln logs returns nothing
Workloads never start and cpln logs returns nothing
RELEASE_NAME-polaris or RELEASE_NAME-polaris-bootstrap never becomes ready and cpln logs returns zero lines.Cause: A prerequisite secret named by tokenSigningKey.secretName, rootCredentials.secretName, the metastore config.credentialsSecretName or storage.credentialsSecretName does not exist. A missing metastore secret also holds RELEASE_NAME-postgres (or RELEASE_NAME-postgres-ha).Fix: Read status.versions[].message with cpln workload get-deployments RELEASE_NAME-polaris --gvc GVC_NAME -o yaml, create the secret it names as shown in Prerequisites, then wait several minutes or force a redeployment.Bootstrap logs that CLIENT_ID or CLIENT_SECRET may not contain a comma
Bootstrap logs that CLIENT_ID or CLIENT_SECRET may not contain a comma
RELEASE_NAME-polaris-bootstrap restarts repeatedly, logging FATAL: neither CLIENT_ID nor CLIENT_SECRET may contain a comma.Cause: The admin tool takes the realm, client ID and client secret as one comma-separated argument.Fix: Recreate the root credentials secret without commas, for example with openssl rand -hex 24 as in Prerequisites, then force a redeployment of RELEASE_NAME-polaris-bootstrap.Install fails with enable exactly one metastore
Install fails with enable exactly one metastore
polaris: enable exactly one metastore.Cause: Both postgres.enabled and postgresHA.enabled are true, or neither is.Fix: Set exactly one of them to true.Token request returns 401 after changing the root credentials
Token request returns 401 after changing the root credentials
CLIENT_ID and CLIENT_SECRET now in your root credentials secret.Cause: Root credentials are applied only when the realm is first bootstrapped. Changing the secret afterwards does not change the root principal.Fix: Use the credentials the realm was bootstrapped with, and create additional principals through the management API.Catalogs disappeared after an upgrade
Catalogs disappeared after an upgrade
realm was changed, so Polaris bootstrapped and now serves a new, empty realm.Fix: Set realm back to its original value and upgrade again; the original catalogs reappear.Catalog operations fail to read or write the bucket
Catalog operations fail to read or write the bucket
storage.credentialsSecretName is empty, the secret lacks the keys AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or an S3-compatible catalog was created without pathStyleAccess and stsUnavailable.Fix: Set storage.credentialsSecretName to a secret with those exact keys, as in Building a Lakehouse, and recreate the catalog with the S3-compatible settings.Upgrade fails with a REMOVED key message
Upgrade fails with a REMOVED key message
helm upgrade stops at render with config.username was REMOVED in postgres 3.4.0, the `postgres` block was REMOVED in 2.5.0, a backup.minio.accessKey and backup.minio.secretKey were REMOVED message, or polaris: postgres.credentials was REMOVED in 1.3.0.Cause: Your values predate template version 1.1.0, 1.2.0, 1.2.1 or 1.3.0 respectively.Fix: Follow Upgrading from 1.0.x, Upgrading from 1.1.0, Upgrading from 1.2.0 or Upgrading from 1.2.1, keeping the credentials the metastore already uses in the secret you create.Important Notes
- Create all three prerequisite secrets before installing, or the workloads wedge silently waiting on a secret that does not exist;
status.versions[].messageincpln workload get-deployments RELEASE_NAME-polaris --gvc GVC_NAME -o yamlnames it. - Editing the metastore credentials secret does not change the database password — run
ALTER ROLEfirst, then force-redeploy Polaris; in HA mode move the leader first (Rotating the Metastore Password). realmis permanent. Renaming it hides every existing catalog behind a new, empty realm.- Root credentials are write-once. Rotate by creating a new principal through the management API.
- Rotating the token signing key invalidates every outstanding token. Clients must request a new one.
- No credential vending. Polaris and each query engine hold their own object-storage credentials; keep
iceberg.rest-catalog.vended-credentials-enabled=falsein Trino. - Polaris does not migrate its own database schema. Treat a future Polaris version change as an explicit schema step, not something startup handles.
- Uninstall deletes the metastore and every catalog definition with it. Enable backups or use
postgresHAfor anything you care about.