Install a self-hosted Kubernetes console with Orkiva

Install the supplied Orkiva Helm package, verify pod and storage readiness, and troubleshoot first-start failures on your infrastructure.

Choose an installation layout#

The application serves a web UI and API from a Go process. The supplied container and Helm chart package that application for installation. Start with the standard single-instance layout unless your package and operational qualification explicitly cover a distributed layout.

The chart distinguishes standard and HA profiles. HA is not simply replicaCount greater than one: its validation and settings involve PostgreSQL, separated Delivery roles, shared artifacts and the relevant internal identity configuration. Do not infer a tested customer HA deployment from the presence of a profile.

Prepare the environment#

Provide the exact image and chart version supplied for your release. Do not substitute an unverified latest tag.
Choose the database and durable storage. SQLite requires a persistent database location; local Delivery artifacts also need persistence when used.
Provision a stable JWT signing secret and Orkiva encryption key through your secret-management process. Replacing the encryption key without a rotation/recovery plan can make stored credentials unreadable.
Configure the public hostname, TLS termination, trusted hosts, origins and proxy addresses to match your actual deployment.
Ensure server-side access to the Kubernetes APIs and any Git, image registry, chart repository, database, artifact or inference endpoints you intend to use.

Install from the supplied Helm chart#

Use a reviewed values file tailored to your environment. Run the commands below from the supplied package directory containing charts/orkiva.

helm template orkiva ./charts/orkiva \
  --namespace orkiva-system -f customer-values.yaml

helm upgrade --install orkiva ./charts/orkiva \
  --namespace orkiva-system --create-namespace \
  -f customer-values.yaml

Inspect the rendered workload, volume, Secret references and ingress before installing. After installation, check pod readiness and the serving endpoint. Complete first-run setup only after the intended persistent storage and secrets are attached.

Validate the installation#

Open the HTTPS URL from a client that will use the console. Confirm the expected certificate and hostname.
Complete setup and connect a non-production cluster first.
Test resource listing, one permitted operation, and a denied operation with a restricted account.
Test the logs/terminal WebSocket path if those features are enabled.
Restart the application through your deployment system and confirm that configuration and connected clusters persist.
Perform a backup/restore rehearsal before relying on the installation for production work.

Check readiness after Helm installation#

Use the same Kubernetes context and namespace used for installation. These read-only commands show the release state, pods, storage claims and recent namespace events:

helm status orkiva --namespace orkiva-system
kubectl get pods,pvc --namespace orkiva-system
kubectl get events --namespace orkiva-system --sort-by=.metadata.creationTimestamp

A deployed Helm release does not by itself prove that its pods are ready. Confirm that the application pod is Ready, required claims are Bound, and the HTTPS endpoint works. The chart uses /readyz for readiness and /healthz for liveness; an ingress response alone does not prove database or Kubernetes access.

Resolve common installation failures#

Symptom	Check next
Helm rendering rejects the image	Set the supplied image repository and exact `image.digest`. The chart requires a SHA-256 digest; a tag alone is insufficient.
Pod remains Pending	Inspect scheduling events and any unbound persistent volume claims. Check the selected storage class and available node capacity.
ImagePullBackOff	Check the package image reference, registry reachability and image-pull credentials. Do not replace the pinned image with an unrelated latest tag.
Pod starts but does not become Ready	Inspect startup logs and readiness events. Check database connectivity, required Secret references and configuration validation errors.
Login works but logs disconnect	Check whether the reverse proxy supports WebSocket upgrades and whether the user has log access. See runtime configuration and TLS.

Review logs before sending them to support and remove credentials. Keep the release version, failed check and relevant error text so the issue can be reproduced.

Finish the first operational rehearsal#

After the console is reachable, follow first login, connect a non-production cluster and test a restricted account using access control. Confirm persistence after an operator-managed restart, then rehearse backup and restore. For GitOps, continue with your first Delivery project.