Install with Helm

Install Omnia’s CRDs and operator with Helm.

Prerequisites

• A Kubernetes cluster (1.26 or later) and kubectl configured to reach it
• Helm v3

Steps

1. Install the CRDs as their own release. The app chart refuses to install without them, and helm upgrade of the app chart never updates them.

   helm install omnia-crds oci://ghcr.io/altairalabs/charts/omnia-crds \
     --devel \
     --namespace omnia-system --create-namespace

   This installs every kind, the Enterprise ones (Arena, ToolPolicy, RolloutAnalysis, SessionPrivacyPolicy, PromptPackSource) included, so turning Enterprise on later needs no CRD step. If you want a Core-only cluster, add --set enterprise.enabled=false to leave the Enterprise kinds out.

2. Install the app chart. dashboard.auth.mode has no default: set it to oauth, builtin, proxy or anonymous. The example uses builtin.

   helm install omnia oci://ghcr.io/altairalabs/charts/omnia \
     --devel \
     --namespace omnia-system \
     --create-namespace \
     --set dashboard.auth.mode=builtin \
     -f values.yaml

   values.yaml is your own file. See Configure Helm for common scenarios for starting points and the Helm Values Reference for every field.

   Every mode but anonymous needs a Redis for sessions in values.yaml (redis.default), and builtin also a PostgreSQL database for management-api (managementApi.database.existingSecret). The chart fails to render without them. Configure builtin authentication shows both.

Verify

kubectl get pods -n omnia-system
helm list -n omnia-system

The operator pod reaches Running, and helm list shows three releases deployed: omnia-crds, omnia, and omnia-resources.

The operator installs omnia-resources itself, a few seconds after it starts. It holds the custom resources the chart’s values ask for: the starter Workspace, the default privacy and retention policies, the compliance presets, the sandbox classes and registries, and the consolidation pack. The app chart renders none of these, because some installers cannot create a custom resource in the same step as its CRD. It hands their values to the operator in the omnia-resources-values ConfigMap instead, and every helm upgrade of the app chart rolls them forward.

Uninstall

helm uninstall omnia -n omnia-system
helm uninstall omnia-resources -n omnia-system

The second command removes what the operator installed. Run it because the operator is removed by the first and usually cannot do it itself. The starter Workspace and its namespace stay either way, with their data, and so do the CRDs and every custom resource of those kinds.

Troubleshooting

The install fails with “Omnia CRDs are not installed”

Install the omnia-crds release first (step 1). If the cluster has Omnia CRDs from before they became a separate chart, run hack/adopt-crds.sh --release-namespace omnia-system from the Omnia repository, then install omnia-crds.

The install fails with “omnia-crds is at … older than this chart”

Upgrade the CRD release to the app chart’s version, then retry:

helm upgrade omnia-crds oci://ghcr.io/altairalabs/charts/omnia-crds \
  --devel --namespace omnia-system

The install fails because the app chart enables Enterprise and the Enterprise kinds are missing

Upgrade omnia-crds with --set enterprise.enabled=true.

The default policies, sandbox classes or starter workspace never appear

The operator reports why on the values ConfigMap:

kubectl get events -n omnia-system \
  --field-selector involvedObject.name=omnia-resources-values
helm history omnia-resources -n omnia-system

A namespace that does not exist yet (for example sandbox.toolRegistry.namespace) fails the release, and the operator retries with backoff until it exists.

The install fails on a kube-system Forbidden error

The CRD preflight reads the kube-system namespace. If the installing identity cannot get namespaces, add --set crdPreflight.enabled=false to the app chart install.

Related pages

• Configure Helm for common scenarios
• Helm Values Reference
• Installing a License