Skip to main content

Install G8 on OKD or OpenShift

G8 is installed on OKD or OpenShift with its Helm chart: one Deployment that serves the console and the API, a Route in front of it, and a PostgreSQL database you provide. The gateway cluster G8 will manage is installed first, as OKD environment describes, and G8 is pointed at its Admin API. This page is the procedure, step by step, and it ends where Sign in and first setup begins.

The procedure on this page was run in our lab on a single-node OKD cluster, against the gateway cluster the OKD guide installs, with the example values below replaced by the lab's own. Every command and every answer quoted here is what that run printed.

Before you start​

  • A gateway cluster on the same OKD or OpenShift cluster, installed as OKD environment describes. Its Admin API is reachable inside the cluster as the Service the guide creates, apisix-admin on port 9180 in the gateway's namespace. Its admin key comes from the guide's Admin key section.
  • A PostgreSQL database for G8, reachable from the cluster: a database, a role that owns it, and the role's password. G8 applies its own schema at start, so the database starts empty. In the lab this was a PostgreSQL on a virtual machine, listening with TLS, with one role and one database for G8.
  • The chart package, a file named after the version, and the digest of the product image for the same version. Both come from G8 with the release, with the package's checksum; the same two are what an upgrade takes later. The chart deploys by digest, never by tag, and refuses to render without one.
  • oc signed in as a cluster administrator, and helm.
  • A host name for the console under the cluster's application domain; this page uses g8.apps.example.com.
  • Whoever runs the cluster, for the application domain and for the address the router reaches pods from, which step 3 shows how to read.

Steps​

1. Create the namespace​

oc new-project g8

The namespace needs no special security context: the pod runs as a non-root user with a read-only root file system and drops every capability, which the default restricted-v2 SCC allows.

2. Create the three Secrets​

The chart creates no Secrets; it reads three, and the Deployment stays in CreateContainerConfigError until they exist. The names below are the chart's defaults.

oc -n g8 create secret generic g8-engine \
  --from-literal=G8_ENGINE_ADMIN_KEY='<the admin key of the gateway cluster>'

oc -n g8 create secret generic g8-db \
  --from-literal=G8_PG_DSN='postgres://g8:<password>@db.example.com:5432/g8?sslmode=require'

oc -n g8 create secret generic g8-secrets \
  --from-literal=G8_SECRETS_KEY=$(openssl rand -hex 32)

The last one is the key that seals every stored secret, the gateway's admin key among them. Keep a copy of it with your backups; a restored database is useless without the key it was sealed under, as Back up and restore explains. The connection string ends in the TLS mode PostgreSQL calls require, which encrypts the connection without verifying the database's certificate. Use one of the stricter modes when your database has a certificate the server can verify.

3. Write the values file​

values.yaml
environment: production
engine:
  adminURL: http://apisix-admin.g8-gateway.svc:9180
image:
  digest: sha256:<the digest your G8 contact gave you>
db:
  internal:
    enabled: false
route:
  host: g8.apps.example.com
trustedProxies:
  - 10.128.0.2/32
ValueWhat it is
environmentThe slug of the first environment, 3 to 32 lowercase letters, digits or hyphens. It names the environment in the console and in the names of its request records and counts, so choose it before the stores are prepared, as Environments explains. It is read at the first start only.
engine.adminURLThe Admin API of the gateway cluster, as the in-cluster Service address.
image.digestThe product image, by digest.
db.internal.enabledfalse points the server at your PostgreSQL. The chart's own PostgreSQL, which true enables, is a lab store with one replica and no backup, and its notes say so.
host under routeThe console's host name. The Route terminates TLS at the router and reaches the pod over plain HTTP inside the cluster.
trustedProxiesThe address the router's requests reach the pod from. On a cluster with the OVN network, that is the second address of each node's pod subnet; read the subnets with the command below and list that address for every node that runs a router. In the lab, one node with the subnet starting at 10.128.0.0 gave 10.128.0.2. Without the list, the console's first write is refused with cross_site_request and the server's log names the address to list; step 7 shows that log line.
oc get nodes -o jsonpath='{range .items[*]}{.metadata.name}{" "}{.metadata.annotations.k8s\.ovn\.org/node-subnets}{"\n"}{end}'

The chart refuses a value it does not know and a misspelled one, so a typo in this file fails at install time rather than rendering a default. The values above, the three Secrets and audit.retentionDays are every setting the chart passes to the server; the session and sign-in settings Server configuration lists have no chart value and keep their defaults on OKD.

4. Read the install notes before installing​

helm install g8 g8-<version>.tgz -n g8 -f values.yaml --dry-run=client

The dry run prints the chart's notes without touching the cluster: the three Secrets and their keys, the Route's termination, and the audit retention. Read them once; they are the contract between the chart and you.

5. Install​

helm install g8 g8-<version>.tgz -n g8 -f values.yaml
oc -n g8 rollout status deploy/g8 --timeout=180s

The lab run answered:

NAME: g8
NAMESPACE: g8
STATUS: deployed
REVISION: 1
deployment "g8" successfully rolled out

6. Check the server through the Route​

curl -s https://g8.apps.example.com/healthz
curl -s https://g8.apps.example.com/readyz
curl -s https://g8.apps.example.com/version

The lab run answered a status of ok, a status of ready, and a version line naming the release and its commit. Health answers as soon as the server listens; readiness answers only when the database and the sealing key check out, and the Deployment's probes read the same two addresses.

7. Read the first start in the log​

oc -n g8 logs deploy/g8

Four lines matter, in this order:

  • schema ready, with the migrations it applied: the database was empty and the server created its schema.
  • environment seeded from G8_ENVIRONMENT and G8_ENGINE_ADMIN_URL; the table is the source of truth from now on: the first environment exists, with the Admin API address and the sealed key from the Secret. From now on the environment is edited in the console, not in the values file.
  • g8 has no users yet: open the console and create the first administrator with this setup token; every replica of this install prints the same one, with the token beside it. Sign in and first setup uses it.
  • listening, with the address and whether TLS is on.

Two warnings can appear in the same log. The first, G8_ variables this server does not read; check them for a misspelling, names variables the server does not know. On Kubernetes that list carries the names the platform injects for the Service, the ones starting with the Service's name and PORT or SERVICE, and those are not a misspelling. The second, dropped an X-Forwarded-Proto claim from a peer that is not in G8_TRUSTED_PROXIES; list the proxy there if it terminates TLS in front of this server, names the router's address in its peer field. If you see it, put that address into trustedProxies and upgrade the release, as the next step shows.

8. Change a value later​

Edit the values file and apply it; the Deployment replaces its pod, so the console is away for the moment between the old pod stopping and the new one answering.

helm upgrade g8 g8-<version>.tgz -n g8 -f values.yaml
oc -n g8 rollout status deploy/g8 --timeout=180s

In the lab run, the first install left trustedProxies out on purpose. The console's first write was refused with the reason cross_site_request, and the log carried the warning of step 7 with the peer 10.128.0.2. After the upgrade with that address listed, the same write was judged on its own merits.

What you have now​

A G8 server at your host name, one environment pointed at the gateway cluster, and a setup token in the log. Nobody can sign in yet. Sign in and first setup creates the first administrator; Add an environment sets the first environment's gateway address and connects the next clusters.

What to know​

  • The pod runs one replica by default. replicaCount above 1 is supported; the replicas share the database and nothing else, every replica prints the same setup token, and an upgrade stops every replica before starting the new ones.
  • The server's settings are read once at start, from the environment the chart builds out of the values and the Secrets. Server configuration lists every one with its default.
  • To have the pod serve HTTPS itself, set tls.enabled to true, create the g8-tls Secret with the certificate and key, and give route.destinationCA the PEM the router verifies the pod's certificate against. The chart refuses the first without the last.
  • Uninstalling the release removes the Deployment, the Service and the Route and leaves your database and the Secrets in place; a new install on the same database continues where the old one stopped, with the same key.
G8 dev