Install with a License

This guide covers installing Omnia with an Enterprise license to unlock advanced features like Git sources, load testing, and distributed workers.

For feature comparison between Open Core and Enterprise, see Licensing & Features.

---

Prerequisites

• A Kubernetes cluster (v1.25+)
• Helm 3.x installed
• An Omnia license key (contact sales@altairalabs.ai or request a free trial)

Install with License Key

The simplest way to install with a license is to pass it directly to Helm:

helm install omnia oci://ghcr.io/altairalabs/charts/omnia \
  --devel \
  --namespace omnia-system \
  --create-namespace \
  --set dashboard.auth.mode=builtin \
  --set dashboard.auth.sessionSecret="$(openssl rand -base64 32)" \
  --set license.key="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

This creates the arena-license Secret automatically.

Install with Existing Secret

If you prefer to manage the license Secret separately (recommended for GitOps):

1. Create the Secret. The name must be arena-license, in the operator’s namespace, with the JWT under the license key — the operator looks the Secret up by that fixed name, so a different name will not be found:

kubectl create secret generic arena-license \
  --namespace omnia-system \
  --from-literal=license="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

2. Tell Helm not to create its own Secret:

values.yaml

license:
  existingSecret: "arena-license"

license.existingSecret only suppresses the chart-managed Secret; it does not rename the Secret the operator reads. Any non-empty value skips creation, but the Secret you provide must still be named arena-license.

3. Install Omnia:

helm install omnia oci://ghcr.io/altairalabs/charts/omnia \
  --devel \
  --namespace omnia-system \
  --create-namespace \
  --set dashboard.auth.mode=builtin \
  --set dashboard.auth.sessionSecret="$(openssl rand -base64 32)" \
  -f values.yaml

Verify License Status

Check that your license is active:

# View license status in the dashboard
kubectl port-forward svc/omnia-dashboard 3000:3000 -n omnia-system
# Open http://localhost:3000/settings and check the License section

# Or check operator logs
kubectl logs -l app.kubernetes.io/name=omnia -n omnia-system | grep -i license

Update an Existing License

To update your license key:

If using license.key:

helm upgrade omnia oci://ghcr.io/altairalabs/charts/omnia \
  --namespace omnia-system \
  --set license.key="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.NEW_KEY..."

If using license.existingSecret:

kubectl create secret generic arena-license \
  --namespace omnia-system \
  --from-literal=license="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.NEW_KEY..." \
  --dry-run=client -o yaml | kubectl apply -f -

The operator will detect the new license within 5 minutes (or restart it for immediate effect).

Upload via Dashboard

You can also install a license through the dashboard without touching kubectl or Helm:

1. Open the Omnia dashboard as a user with the admin role (the upload requires the settings:edit permission).
2. Navigate to Settings → License.
3. Click Upload License.
4. Drag your license file onto the drop zone, or click Browse Files and select it. The file just needs to contain the JWT (a .jwt, .txt, .license, or .pem file all work).

The dashboard writes the JWT into the arena-license Secret for you. As with a Helm-managed license, the operator re-reads the Secret on its 5-minute refresh cycle, so the License panel can take up to 5 minutes to reflect the new key. A confirmation (or a specific error) is shown beneath the Upload License button.

How the License Is Validated

Omnia validates the license offline. The key is a cryptographically signed RS256 JWT; the operator verifies it against an embedded public key and re-reads the Secret every 5 minutes. No internet connection is needed to install, validate, or run Enterprise features.

Enforcement is honour-system. Each Enterprise component logs a one-time startup reminder when it runs without a valid license, but the features keep working. The license genuinely gates only dashboard white-labelling and Arena Fleet source/job/limit checks — see License enforcement.

License Activation (Optional)

For enterprise-tier licenses, the operator can register the cluster with the Altaira Labs license server to count activations for the sales relationship:

• Each license has a maximum number of cluster activations
• On install the operator activates once and heartbeats every 24 hours
• You can view and manage activations in Settings → License → Activations

Activation is telemetry, not a gate: if the phone-home fails or the activation limit is exceeded, Omnia records a Kubernetes warning event but does not disable any feature.

Deactivate a Cluster

If you want to free an activation slot when moving a license to a new cluster:

1. Open Settings → License → Activations
2. Find the cluster you want to deactivate
3. Click Deactivate

The activation slot is now available for a new cluster.

Offline/Air-Gapped Installations

No special license is required for air-gapped clusters — validation is fully offline. The optional activation phone-home simply logs a warning event when it cannot reach the license server, and Enterprise features continue to run.

Troubleshooting

License Not Recognized

Enterprise features run on the enterprise.enabled flag, so they are not “locked” by a missing license — but white-labelling and Arena Fleet limits are license-gated. If the dashboard still shows the default theme or Arena rejects Git/OCI sources after installing a license:

1. Check the Secret exists:

   kubectl get secret arena-license -n omnia-system

2. Verify the Secret has the correct key:

   kubectl get secret arena-license -n omnia-system -o jsonpath='{.data.license}' | base64 -d | head -c 50

   Should show the start of your JWT: eyJhbGciOiJSUzI1NiI...

3. Check operator logs for validation errors:

   kubectl logs -l app.kubernetes.io/name=omnia -n omnia-system | grep -i "license\|validation"

Enterprise CRDs missing after enabling on an existing install

Omnia’s Enterprise CRDs (Arena, RolloutAnalysis, SessionPrivacyPolicy, ToolPolicy) ship in a subchart that only installs when enterprise.enabled=true. Helm applies CRDs on helm install but never on helm upgrade, so switching an existing community release to Enterprise with helm upgrade --set enterprise.enabled=true can fail while Helm builds the release:

Error: unable to build kubernetes objects from release manifest:
  resource mapping not found for name: "..." ...
  no matches for kind "SessionPrivacyPolicy" ... ensure CRDs are installed first

Apply the Enterprise CRDs once, then upgrade:

# Pull and unpack the chart to get the Enterprise CRDs
helm pull oci://ghcr.io/altairalabs/charts/omnia --devel --untar

# Apply them server-side (they embed large schemas that exceed the
# client-side apply annotation limit)
kubectl apply --server-side --force-conflicts \
  -f omnia/charts/omnia-ee-crds/crds/

# Now enable Enterprise
helm upgrade omnia oci://ghcr.io/altairalabs/charts/omnia --devel \
  --namespace omnia-system \
  --reuse-values \
  --set enterprise.enabled=true

A fresh helm install with enterprise.enabled=true needs none of this — Helm applies the subchart’s CRDs before the rest of the release. Likewise, helm uninstall never deletes these CRDs, so your Enterprise custom resources survive an uninstall/reinstall.

License Expired

If your license has expired:

1. Your agents and the enterprise memory/privacy/policy services keep running; a startup license reminder is logged
2. Dashboard white-labelling reverts to the Omnia default theme, and Arena admission webhooks reject new enterprise-tier ArenaSource / ArenaJob resources
3. A warning banner appears in the dashboard
4. Contact support to renew your license

Activation Failed

Activation is optional telemetry (see License Activation), so a failed activation does not disable any feature — Omnia just records a Kubernetes warning event. If you want activation tracking to succeed:

1. Check network connectivity to https://license.altairalabs.ai
2. Verify activation slots are available (check dashboard)
3. Deactivate unused clusters if at the activation limit

Air-gapped clusters need no offline activation — validation is fully offline and features run regardless of the phone-home.

Next Steps

• Licensing & Features - Compare Open Core vs Enterprise features
• Configure Arena S3 Storage - Set up artifact storage (Enterprise)
• Setup Scheduled Jobs - Configure job scheduling (Enterprise)