Installation - Odigos

You can install Odigos Central using the CLI or Helm chart.

CLI
Helm

Use the odigos pro central install command with --set flags:

odigos pro central install --set onPremToken=<token>

This installs:

central-backend
central-ui
redis (for state)
keycloak (as identity provider)

CLI Flags

Flag	Default	Description
`--set onPremToken`	(required)	Your Odigos Enterprise license token
`--set auth.externalUrl`	`http://localhost:8081`	Browser-accessible URL of the Central Backend for SSO redirect flows
`--set auth.externalUIUrl`	(derived from `auth.externalUrl`)	Browser-accessible URL of the Central UI for OAuth `redirect_uri` (`/signin`). When empty, defaults to `auth.externalUrl`, except for local port-forward (`http://localhost:8081`) where the UI is on port 3000
`--set auth.adminPassword`	(auto-generated)	Keycloak master admin password for backend API access. If not provided, a random password is generated. Not used for Central UI login. See Troubleshooting
`--set auth.adminUsername`	`admin`	Keycloak master admin username
`--set auth.persistence.enabled`	`false`	Persist Keycloak data on a PVC. Recommended for production. See Keycloak persistence
`--set cloudConnectors.enabled`	`false`	Enable Cloud Connectors (controller, Postgres, CRD)
`--namespace`, `-n`	`odigos-central`	Target namespace for installation
`--version`	(current)	Specify a specific version to install

Example with all options:

odigos pro central install \
  --set onPremToken=<token> \
  --namespace odigos-central \
  --version v1.0.0

Add the Odigos Helm repository and install:

helm repo add odigos https://odigos-io.github.io/odigos/
helm repo update
helm upgrade --install odigos-central odigos/odigos-central \
  --namespace odigos-central \
  --create-namespace \
  --set onPremToken=<token>

For production deployments, consider using a values.yaml file:

onPremToken: "<your-token>"

auth:
  externalUrl: "https://central.example.com"  # Browser-accessible URL for SSO redirects
  adminUsername: admin
  adminPassword: "<your-password>"
  persistence:
    enabled: true
    size: 2Gi
    storageClassName: "gp3"

centralBackend:
  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 10
  resources:
    requests:
      cpu: 200m
      memory: 256Mi
    limits:
      cpu: 1000m
      memory: 1Gi

centralUI:
  resources:
    requests:
      cpu: 100m
      memory: 128Mi
    limits:
      cpu: 500m
      memory: 512Mi

Then install with:

helm upgrade --install odigos-central odigos/odigos-central \
  --namespace odigos-central \
  --create-namespace \
  -f values.yaml

centralProxy.centralBackendURL is not a Central install flag. Set it when you install the odigos chart on each remote cluster so the Central Proxy can reach this backend. See Connecting Remote Clusters.

Keycloak image

Odigos Central deploys Keycloak from the image in auth.image (see the odigos-central Helm values file). That image is based on official Keycloak with health and metrics enabled at build time, which is required for start --optimized. The chart starts Keycloak with start --optimized --http-enabled=true and probes /health/live and /health/ready. Those endpoints are not available on a stock official image in optimized mode.

Do not replace auth.image in the helm chart with quay.io/keycloak/keycloak (or another unmodified official tag) unless you also change the container args and probes. An official image can appear Ready while central-backend stays on “Waiting for Keycloak to become ready” and /readyz never succeeds. See Troubleshooting.

When mirroring images to a private registry, also pull the Keycloak image from auth.image in the Helm values file. See Custom Docker Registry.

Custom Docker Registry

Odigos Central images are hosted at registry.odigos.io. To install from a private registry, mirror at least:

Image	Notes
`registry.odigos.io/odigos-enterprise-central-backend:$VERSION`	Central Backend. Tag matches the Odigos Central version.
`registry.odigos.io/odigos-enterprise-central-ui:$VERSION`	Central UI. Tag matches the Odigos Central version.
Keycloak (`auth.image`)	Bundled Keycloak. Tag is not the Odigos version. Do not substitute the official Keycloak image.
Redis (`redis.image`)	Bundled Redis.

The Keycloak and Redis image versions are defined in the odigos-central Helm values file (auth.image and redis.image). Use those values as the source of truth when mirroring; do not rely on tags copied from this page. If Cloud Connectors are enabled, also mirror odigos-enterprise-connector-runtime, odigos-enterprise-connector-aws, odigos-enterprise-connector-gcp, odigos-enterprise-connector-azure, and odigos-enterprise-connector-postgres. Keycloak is set with auth.image, not imagePrefix. After you push the mirrored Keycloak image, set auth.image to that full URL. Copy auth.image from the Helm values file first:

# Example: registry.odigos.io/keycloak:<tag> from helm/odigos-central/values.yaml
export KEYCLOAK_IMAGE=<auth.image from values.yaml>
export KEYCLOAK_TAG=<tag from auth.image>

docker pull --platform $PLATFORM $KEYCLOAK_IMAGE
docker tag $KEYCLOAK_IMAGE $CUSTOM_DOCKER_REGISTRY/keycloak:$KEYCLOAK_TAG
docker push $CUSTOM_DOCKER_REGISTRY/keycloak:$KEYCLOAK_TAG

helm upgrade --install odigos-central odigos/odigos-central \
  --namespace odigos-central \
  --create-namespace \
  --set onPremToken=$ODIGOS_TOKEN \
  --set imagePrefix=$CUSTOM_DOCKER_REGISTRY \
  --set image.tag=$VERSION \
  --set auth.image=$CUSTOM_DOCKER_REGISTRY/keycloak:$KEYCLOAK_TAG

For mirroring K8s agent images (odigos chart), see Custom Docker Registry.

Keycloak persistence

Persistence is disabled by default. Without a PVC, Keycloak stores data in the container filesystem. Restarting or recreating the Keycloak pod wipes SSO configuration and users stored in Keycloak. For production, enable a PVC:

auth:
  persistence:
    enabled: true
    size: 2Gi
    storageClassName: "gp3"  # omit to use the cluster default

After resetting Keycloak, restart central-backend if login does not recover. With persistence enabled, a bad identity-provider config in the database can leave pods Ready while OAuth still fails until the PVC is recreated. See Troubleshooting.

auth.adminUsername / auth.adminPassword are the Keycloak master admin used by central-backend, not Central UI login credentials. On upgrade, Helm reuses the existing keycloak-admin-credentials secret and ignores a new auth.adminPassword value.

Optional: Cloud Connectors

Cloud Connectors are disabled by default. To discover and instrument cloud workloads (AWS, GCP, and more) from Central, enable the feature at install or upgrade time:

CLI
Helm

odigos pro central install \
  --set onPremToken=<token> \
  --set cloudConnectors.enabled=true \
  --set cloudConnectors.postgres.password=<strong-password> \
  --set cloudConnectors.postgres.persistence.enabled=true \
  --set cloudConnectors.postgres.persistence.size=20Gi \
  --set cloudConnectors.postgres.persistence.storageClassName=

On an existing install:

odigos pro central upgrade \
  --set cloudConnectors.enabled=true \
  --set cloudConnectors.postgres.password=<strong-password> \
  --set cloudConnectors.postgres.persistence.enabled=true \
  --set cloudConnectors.postgres.persistence.size=20Gi \
  --set cloudConnectors.postgres.persistence.storageClassName=

helm upgrade --install odigos-central odigos/odigos-central \
  --namespace odigos-central \
  --reuse-values \
  --set cloudConnectors.enabled=true \
  --set cloudConnectors.postgres.password=<strong-password> \
  --set cloudConnectors.postgres.persistence.enabled=true \
  --set cloudConnectors.postgres.persistence.size=20Gi \
  --set cloudConnectors.postgres.persistence.storageClassName=

See Enable Cloud Connectors for PostgreSQL settings, verification steps, and full values.

​CLI Flags

​Keycloak image

​Custom Docker Registry

​Keycloak persistence

​Optional: Cloud Connectors

CLI Flags

Keycloak image

Custom Docker Registry

Keycloak persistence

Optional: Cloud Connectors