Install

The whole platform — the gateway, control plane, database, identity, observability, and console — is driven by one values file (a base domain, a TLS mode, and a few high-level toggles) and deployed as a coordinated bundle of Helm releases. You deploy that bundle one of two ways: GitOps (recommended) or helmfile.

It's a bundle, not a single helm install

The gateway (Higress), identity (Keycloak), observability (LGTM), and the cert-manager / CloudNativePG / Redis operators are their own upstream releases; the opsta-ai-gateway chart is the Opsta layer on top (control plane, console, gateway config). GitOps and helmfile bring up all of them together from your one values file. Installing only the opsta-ai-gateway chart is an advanced path (see §3).

Prerequisite

Make sure your cluster meets the Requirements first — Kubernetes ≥ 1.28, a default StorageClass, a base domain, and a way to issue a wildcard certificate.

Install modes

The platform is a bundle of Helm releases — the Higress gateway, Keycloak, the LGTM observability stack, the cert-manager / CloudNativePG / Redis operators, and the Opsta AI Gateway governance chart — all driven by your one values file. There are two modes to deploy that bundle; they differ in how the releases are applied and reconciled, not in what runs:

• Helmfile (default, recommended). The tested path: one values file drives helmfile sync, which installs every release in the right order. This is what Requirements, Production deployment (HA), and the deployment runbook target.
• ArgoCD GitOps (production). A continuously-reconciled, drift-correcting, audited deploy via an ArgoCD app-of-apps, with secrets sourced from Vault → External Secrets Operator (kept out of git entirely) and the released OCI chart pinned per environment. Each environment gets its own GitOps repo — scaffold one with the customer:init generator (it writes the app-of-apps, the OCI-chart pin, vendored CRDs, and per-environment values). See the GitOps install walkthrough. Identity is declarative and reproducible (see below): a rebuilt cluster comes back with the same admin + SSO, no out-of-band step. HA Vault and CI-driven multi-cluster promotion continue to harden on the roadmap; the single-cluster production path is what runs Opsta's own gateway.

Which to use

Both are production paths. Use helmfile for a straightforward helmfile sync install; use GitOps when you want continuous drift-correction, an audit trail, and secrets that never touch git. They deploy the same bundle from the same values and share the same declarative identity model.

Deployment topology

1. Add the chart repository

The Opsta layer of the bundle is published as an OCI chart at oci://ghcr.io/opsta/opsta-ai-gateway/charts/opsta-ai-gateway (the control plane, console, and gateway config). The rest of the bundle — Higress, Keycloak, LGTM, and the operators — comes from their public upstream Helm repos (helmfile/GitOps add those for you). The Opsta chart and all product images are public — no registry login is required to pull them. (For an air-gapped install you mirror everything into your own registry instead; see Air-gapped install.)

helm registry login ghcr.io   # only if you mirrored the chart into a private registry

2. Write your values file

Create a values.yaml that captures the decisions for this environment. The minimum is your domain, a TLS mode, identity, and a bootstrap admin:

global:
  baseDomain: ai-gateway.example.com
  subdomainSeparator: "."        # "." for two-level names, "-" for single-level under a parent wildcard
  highAvailability: false        # true for production multi-replica

tls:
  mode: letsencrypt              # letsencrypt | provided | selfsigned
  letsencrypt:
    email: platform@example.com
    dns01:
      provider: cloudflare
      dnsZone: example.com

# Identity — declarative and create-once, then console-authoritative (v1.26.0). The initial admin and
# SSO are seeded from config on the first deploy; afterward you manage them in the console and re-deploys
# never clobber your changes. A rebuilt cluster comes back with the same identity — no out-of-band script.
keycloak:
  platformAdmin:
    enabled: true
    username: admin@example.com    # the first person who can sign in. Created once into the admin group;
                                    # change the password in-console later — re-deploys never reset it.
  bootstrapIdp:                     # optional SSO. You can also add/change providers in-console; those persist.
    enabled: true
    providerId: google             # google | oidc
    clientId: "<your-oauth-client-id>"
    hostedDomain: example.com       # optional: restrict Google logins to your workspace domain

controlPlane:
  enabled: true
postgres:
  enabled: true                  # control plane needs its database

The initial admin password and the SSO client secret are secrets — put them in your separate secrets file (keycloak.platformAdminPassword, keycloak.bootstrapIdpClientSecret), never in values.yaml. If you use tls.mode: letsencrypt with the cloudflare DNS-01 solver above, that same secrets file must also hold your Cloudflare API token (cloudflareApiToken, scoped to Zone:DNS:Edit for the domain) — cert-manager uses it to solve the ACME challenge for your wildcard certificate.

Secrets (provider keys, OIDC client secret, database passwords) live in a separate, git-ignored values file or in pre-existing Kubernetes Secrets — never in the file you commit. See Configuration and Hardening.

Keep secrets out of git

Set secrets.createFromValues: true and supply a local secrets file, or set it to false and reference existing Secrets managed by Vault/sealed-secrets. Do not put credentials in your main values.yaml.

3. Install

The bundle installs, alongside the Opsta chart: the Higress gateway, Keycloak, the LGTM observability stack, the cert-manager / Redis / CloudNativePG operators, and the Gateway API CRDs. Deploy the whole bundle one of two ways — both are complete, from a bare cluster.

Recommended — GitOps (complete, drift-corrected)

Scaffold a per-environment GitOps repo with the customer:init generator; ArgoCD's app-of-apps brings up every release from your values — continuously reconciled, audited, with secrets via Vault → External Secrets. This is the production path, and a rebuilt cluster comes back identical. See the GitOps install walkthrough.

Recommended — helmfile (complete, scripted)

Your one values file drives helmfile sync, which installs every release — operators + gateway + identity + observability + the Opsta chart — in the right order:

helmfile sync   # the tested end-to-end install; runs from the deploy bundle with your values file

Advanced — install the Opsta chart on its own

The opsta-ai-gateway chart is only the Opsta layer (control plane, console, gateway config). Install it alone only if you already run Higress, Keycloak, LGTM, the three operators, and the Gateway API CRDs — it renders resources (Gateway/HTTPRoutes, WasmPlugins, Issuer/Certificate, Redis, a PostgreSQL cluster) that those components reconcile (see Reuse existing operators):

helm install opsta-ai-gateway oci://ghcr.io/opsta/opsta-ai-gateway/charts/opsta-ai-gateway \
  --version 1.27.0 --namespace opsta-ai-gateway --create-namespace \
  -f values.yaml -f secrets-values.yaml

Not a from-scratch install

On a bare cluster this leaves the gateway config, certificates, and database resources with nothing to run them — no gateway, no identity, no TLS, no database. For a fresh cluster use GitOps or helmfile above.

4. Wait for readiness

The control plane runs database migrations and a first reconcile before it reports ready — this guarantees the gateway is never half-configured.

kubectl -n opsta-ai-gateway rollout status deploy/control-plane
kubectl -n opsta-ai-gateway get pods

$ kubectl -n opsta-ai-gateway get pods
NAME                                    READY   STATUS    RESTARTS   AGE
console-7c9b8c476f-9q4md                1/1     Running   0          12m
console-oauth2-proxy-6b746965fd-2xk8p   1/1     Running   0          12m
control-plane-5d5bf75cc8-hg82g          1/1     Running   0          12m
gateway-higress-7d8c9b6f54-p7w2n        1/1     Running   0          14m
keycloak-0                              1/1     Running   0          13m
opsta-pg-1                              1/1     Running   0          13m
redis-0                                 1/1     Running   0          13m

5. Point DNS and sign in

Create a wildcard DNS record for *.your-domain pointing at the gateway's ingress (or configure the Cloudflare Tunnel). Then open https://console.your-domain and sign in:

• With SSO (if you enabled bootstrapIdp) — click Sign in with Google/OIDC.
• As the platform admin — keycloak.platformAdmin.username with the initial password you set. This is a break-glass account created once; change its password in the console afterward and re-deploys won't reset it. Add or remove admins and identity providers in the console — those changes persist across upgrades.

Next steps

• Configuration — the full config surface, grouped by concern.
• TLS & domains — certificates and subdomains in detail.
• High availability — turn on multi-replica production mode.