Polaris

​

Overview

​

Architecture

• Polaris server — A standard workload serving the Iceberg REST API and the Polaris management API on port 8181, and Quarkus health and metrics on port 8182. Stateless, with a replicas knob.
• Bootstrap workload — Runs the official polaris-admin-tool image once to create the realm schema and the root principal, then idles. Always one replica, and idempotent — a restart or upgrade re-runs it harmlessly.
• Metastore — A single-instance postgres by default, or postgres-highly-available with one flag.
• Realm — Polaris isolates tenants by realm. This template ships exactly one and does not require the Polaris-Realm header, which is what makes Trino’s Iceberg REST connector work against it.

​

What Gets Created

• Standard Polaris Workload — replicas interchangeable replicas serving 8181 and 8182.
• Standard Bootstrap Workload — One replica, no ports, unreachable from anywhere. It initializes the realm and then sleeps.
• Bootstrap Script Secret — An opaque secret holding the shell script the bootstrap workload runs, mounted as a file.
• Two Identities & Two Policies — Split for least privilege: only the bootstrap principal can reveal your root credentials, and only the server principal can reveal the token signing key and the object-storage credentials.
• PostgreSQL Metastore — The postgres or postgres-highly-available subchart, with its own workload, volume set and config secret.
• No Volume Set for Polaris — The server writes nothing to local disk that must survive a restart.

​

Prerequisites

cpln secret create-dictionary --name my-polaris-root-credentials \
  --entry CLIENT_ID=root --entry CLIENT_SECRET="$(openssl rand -hex 24)"

printf '%s' "$(openssl rand -hex 32)" | \
  cpln secret create-opaque --name my-polaris-signing-key --encoding plain -f -

• Object-storage credentials for the bucket holding your Iceberg data — a dictionary secret with AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. See Object Storage. Polaris runs without it; catalogs can be added later.
• A cloud account and bucket only if you turn on the metastore’s backup pass-through. See Backing Up.

​

Installation

​

Configuration

image: apache/polaris:1.7.0

# Stateless replicas behind one metastore. All replicas share the token signing
# key below, so a token minted by one is accepted by every other.
replicas: 1

resources:
  minCpu: 500m
  maxCpu: 1000m
  minMemory: 1Gi
  maxMemory: 2Gi # JVM heap is a percentage OF THIS — see jvm.maxRAMPercentage

jvm:
  maxRAMPercentage: 70 # max heap as a percentage of resources.maxMemory; allowed range 40–80

# Polaris isolates tenants by realm. PERMANENT after first install.
realm: POLARIS

rootCredentials:
  secretName: my-polaris-root-credentials # dictionary secret with CLIENT_ID and CLIENT_SECRET

tokenSigningKey:
  secretName: my-polaris-signing-key # opaque secret (encoding: plain), payload = 32+ random chars

# Credentials Polaris uses for its OWN metadata I/O against S3-compatible storage.
storage:
  credentialsSecretName: "" # e.g. my-seaweedfs-s3-credentials
  region: us-east-1 # AWS_REGION; S3-compatible servers ignore the value but the SDK requires one

# Runs the official admin tool once against the metastore, then idles.
bootstrap:
  image: apache/polaris-admin-tool:1.7.0 # keep this tag in lockstep with `image`
  resources:
    minCpu: 100m
    maxCpu: 400m
    minMemory: 128Mi
    maxMemory: 1Gi

publicAccess:
  enabled: false # true = Iceberg REST + management API on the auto *.cpln.app HTTPS endpoint

internalAccess: # who may reach Polaris from inside Control Plane
  type: same-gvc # options: none, same-gvc, same-org, workload-list
  workloads: [] # used with workload-list, e.g. //gvc/GVC_NAME/workload/WORKLOAD_NAME

# ─── Metastore: single-instance PostgreSQL (default) ──────────────
postgres:
  enabled: true
  config:
    username: polaris
    password: change-me-polaris-db # change before installing
    database: polaris
  resources:
    minCpu: 200m
    maxCpu: 500m
    minMemory: 256Mi
    maxMemory: 512Mi
  volumeset:
    capacity: 10 # initial capacity in GiB (minimum is 10)
  backup:
    enabled: false # true = scheduled DB backups to object storage
    provider: aws # options: aws, gcp, minio
    # plus aws / gcp / minio blocks — see Backing Up

# ─── Metastore: Highly Available PostgreSQL ───────────────────────
# set postgresHA.enabled: true (and postgres.enabled: false) for near-zero-downtime
# upgrades and automatic failover
postgresHA:
  enabled: false
  postgres:
    username: polaris
    password: change-me-polaris-db # change before installing
    database: polaris
  replicas: 3
  volumeset:
    capacity: 10 # initial capacity in GiB per replica (minimum is 10)
  backup:
    enabled: false
    mode: logical # logical or wal-g
    provider: aws # options: aws, gcp, minio

​

Server and Replicas

• image — The official upstream image. The chart is shipped and tested on Polaris 1.7.0.
• replicas — Number of Polaris replicas (default 1, minimum 1). Replicas are interchangeable: they share the metastore and the token signing key, so a token minted by one is accepted by every other and a catalog created through one is immediately visible on the rest. Raise it for capacity and to keep serving through a rolling restart — see Availability.
• resources.minCpu / maxCpu / minMemory / maxMemory — CPU and memory per replica. minMemory may not exceed maxMemory, and maxCpu:minCpu may not exceed 4:1 (a Control Plane limit); the chart refuses to render otherwise, naming the value to fix.

​

JVM and Memory

​

Realm

​

Credentials

• rootCredentials.secretName — Name of the prerequisite dictionary secret holding CLIENT_ID and CLIENT_SECRET. Required.
• tokenSigningKey.secretName — Name of the prerequisite opaque secret whose payload is the shared HMAC signing key. Required.

​

Object Storage

• storage.credentialsSecretName — Name of a dictionary secret with AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, used for Polaris’s own Iceberg metadata reads and writes. Empty by default, which is a valid install: the server runs and answers, but catalogs backed by object storage cannot read or write.
• storage.region — Value of AWS_REGION. S3-compatible servers ignore it, but the AWS SDK requires one.

{
  "Version": "2012-10-17",
  "Statement": [
    { "Effect": "Allow", "Action": ["s3:ListBucket", "s3:GetBucketLocation"], "Resource": "arn:aws:s3:::my-polaris-bucket" },
    { "Effect": "Allow", "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"], "Resource": "arn:aws:s3:::my-polaris-bucket/*" }
  ]
}

​

Bootstrap

​

Access

• publicAccess.enabled — false by default. When true, the Iceberg REST API and the Polaris management API are served over HTTPS on the automatically assigned *.cpln.app canonical endpoint.
• internalAccess.type — Which workloads inside Control Plane may reach Polaris:

​

Metastore

​

Building a Lakehouse

curl -X POST https://<canonical>.cpln.app/api/catalog/v1/oauth/tokens \
  --user "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials -d scope=PRINCIPAL_ROLE:ALL

curl -X POST https://<canonical>.cpln.app/api/management/v1/catalogs \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{
  "catalog": {
    "name": "lakehouse",
    "type": "INTERNAL",
    "properties": { "default-base-location": "s3://my-bucket/warehouse" },
    "storageConfigInfo": {
      "storageType": "S3",
      "allowedLocations": ["s3://my-bucket/warehouse"],
      "endpoint": "http://my-seaweedfs.my-gvc.cpln.local:8333",
      "endpointInternal": "http://my-seaweedfs.my-gvc.cpln.local:8333",
      "pathStyleAccess": true,
      "stsUnavailable": true,
      "region": "us-east-1"
    }
  }
}'

# Let the root principal administer the new catalog
curl -X PUT https://<canonical>.cpln.app/api/management/v1/principal-roles/service_admin/catalog-roles/lakehouse \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"catalogRole":{"name":"catalog_admin"}}'

catalogs:
  - name: iceberg
    properties: |
      connector.name=iceberg
      iceberg.catalog.type=rest
      iceberg.rest-catalog.uri=http://my-polaris.my-gvc.cpln.local:8181/api/catalog
      iceberg.rest-catalog.security=OAUTH2
      iceberg.rest-catalog.oauth2.credential=${ENV:POLARIS_CLIENT_ID}:${ENV:POLARIS_CLIENT_SECRET}
      iceberg.rest-catalog.oauth2.scope=PRINCIPAL_ROLE:ALL
      iceberg.rest-catalog.warehouse=lakehouse
      iceberg.rest-catalog.vended-credentials-enabled=false
      fs.native-s3.enabled=true
      s3.endpoint=http://my-seaweedfs.my-gvc.cpln.local:8333
      s3.region=us-east-1
      s3.path-style-access=true
      s3.aws-access-key=${ENV:S3_ACCESS_KEY}
      s3.aws-secret-key=${ENV:S3_SECRET_KEY}
    secrets:
      - env: POLARIS_CLIENT_ID
        secretName: my-polaris-root-credentials
        secretKey: CLIENT_ID
      - env: POLARIS_CLIENT_SECRET
        secretName: my-polaris-root-credentials
        secretKey: CLIENT_SECRET
      - env: S3_ACCESS_KEY
        secretName: my-seaweedfs-s3-credentials
        secretKey: AWS_ACCESS_KEY_ID
      - env: S3_SECRET_KEY
        secretName: my-seaweedfs-s3-credentials
        secretKey: AWS_SECRET_ACCESS_KEY

CREATE SCHEMA iceberg.demo;
CREATE TABLE iceberg.demo.t (a integer, b varchar);
INSERT INTO iceberg.demo.t VALUES (1,'alpha'), (2,'beta'), (3,'gamma');
SELECT count(*) FROM iceberg.demo.t;

-- where the data actually landed
SELECT file_path FROM iceberg.demo."t$files";

​

Connecting

​

Availability

​

Backing Up

{
  "Version": "2012-10-17",
  "Statement": [
    { "Effect": "Allow", "Action": ["s3:ListBucket"], "Resource": "arn:aws:s3:::my-polaris-backup-bucket" },
    { "Effect": "Allow", "Action": ["s3:PutObject","s3:GetObject","s3:DeleteObject"], "Resource": "arn:aws:s3:::my-polaris-backup-bucket/*" }
  ]
}

​

Important Notes

• Create both prerequisite secrets before installing. Without them the workloads wait on a secret that does not exist, and the install looks broken with no useful error.
• Expect a warm-up and do not interrupt it. A default install is ready in about 90 seconds, including a 2-restart, ~32-second crash loop while PostgreSQL boots. The postgresHA metastore takes about 6 minutes before Polaris answers. Both are normal.
• Root credentials are write-once; they are applied only at first bootstrap. 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.
• realm is permanent. Renaming it bootstraps a new, empty realm and hides the existing catalogs.
• Change the metastore password before installing (postgres.config.password or postgresHA.postgres.password) — the default is a placeholder.
• No credential vending in this version. Polaris and each query engine hold their own static object-storage credentials; keep iceberg.rest-catalog.vended-credentials-enabled=false in Trino.
• Health and metrics are in-GVC only. They are served on port 8182, which the public canonical endpoint does not route to.
• Polaris does not migrate its own database schema. Treat a future Polaris version bump as an explicit schema step, not something startup handles.
• Metastore volumes survive restarts, redeploys and upgrades; uninstalling deletes them — and every catalog definition with them. The Iceberg data in your bucket is untouched, but the catalog that indexed it is gone. Use postgresHA and/or backups for anything you care about.
• Uninstall does not delete your prerequisite secrets — they are your resources, created outside the release.

​

External References