Skip to content

Deploy AKKO on OpenShift

OpenShift 4.14+ is a supported AKKO target. The values-openshift.yaml overlay handles the three OpenShift-specific concerns: Security Context Constraints (SCC), Routes vs Ingress, and Image Registry pull policies.

Prerequisites

Requirement Version
OpenShift 4.14+ (tested on OKD, ROSA, ARO)
Helm ≥ 3.14
oc CLI matching cluster version
Project pre-created, admin role on it
cert-manager for Let's Encrypt Routes (optional)

One-command install

oc new-project akko

AKKO_DOMAIN=apps.customer.example \
AKKO_VERSION=2026.04 \
AKKO_NAMESPACE=akko \
AKKO_VALUES_EXTRA=helm/examples/values-openshift.yaml \
  bash deploy-from-harbor.sh

The overlay enables Routes (HAProxy) and disables Traefik. It sets the right SCC (anyuid is not required — AKKO v2026.04 runs non-root everywhere except the in-migration directory service/Dashboards components that are being replaced by ADR-020 Apache 2.0 alternatives).

OpenShift-specific notes

Security Context Constraints

AKKO 2026.04 runs under the default restricted-v2 SCC everywhere except:

  • akko-lldap — requires anyuid (historical runAsUser: 0). Disabled by default in values-openshift.yaml; use Keycloak external IDP federation instead. Full replacement (389-DS) lands Sprint 39.5.
  • kube-prometheus-stack[grafana] — requires anyuid. Disabled by default; migrate to VictoriaMetrics + vmui (Apache 2.0, ADR-020).

If you must enable those legacy components on OpenShift, grant anyuid to their service accounts:

oc adm policy add-scc-to-user anyuid -z akko-akko-lldap -n akko
oc adm policy add-scc-to-user anyuid -z akko-grafana -n akko

Routes vs Ingress

The overlay exposes services through OpenShift Route objects managed by HAProxy (native) rather than an external ingress controller. TLS passthrough or edge termination is configurable per service.

Image Pull

Harbor harbor.akko-ai.com is public for the AKKO project, so no pull secret is required. If you mirror to an internal Quay / ImageStreams:

oc create secret docker-registry akko-pull \
  --docker-server=quay.internal.example \
  --docker-username=<user> \
  --docker-password=<token> \
  -n akko
oc secrets link default akko-pull --for=pull

Then override global.image.registry to point at your mirror.

Machine Config (if using Node tuning)

Some heavy workloads (OpenMetadata, Spark Connect) benefit from kernel tuning. AKKO does not ship a MachineConfig — apply your cluster's standard tuning profile. Start with 4 vCPU / 16 GiB worker nodes.

Verify installation

oc -n akko get pods
oc -n akko get routes
oc -n akko exec svc/akko-trino -c trino -- trino --execute "SHOW CATALOGS"

Post-install

  • Harbor pull works out of the box for the public AKKO project
  • Configure Keycloak LDAP federation for your corporate AD
  • Onboard the first customer data source through Admin → Data Catalogs

Troubleshooting

Symptom Cause Fix
Pod CrashLoopBackOff with runAsNonRoot error Chart requires non-root but image defaults to root Check the podSecurityContext in the relevant sub-chart — 2026.04 fixes this for all first-party images
Route returns 503 Backend service not ready oc describe pod for the corresponding service
TLS certificate errors cert-manager not installed or DNS not resolved Check oc describe certificate -n akko + confirm the *.apps.customer.example DNS is correct
PVC stuck Pending Default SC does not support RWX AKKO 2026.04 reconciles all PVCs to RWO — verify with oc get pvc