Customer onboarding¶

Runbook for onboarding a brand-new customer onto AKKO. The starting point is helm/examples/values-customer-template.yaml — an empty-by- default values file that carries zero AKKO demo identity (no alice/bob/carol/dave/eve personas, no akko-admin defaults, no demo dataset references).

This page is the operational counterpart of ADR-039 — no hardcoded identities and the Sprint 56 zero-hardcoding refactor.

Prerequisites the customer brings¶

#	Item	Why
1	Kubernetes 1.28+ cluster with a default `StorageClass`	AKKO sub-charts target k3s/EKS/AKS/GKE/OpenShift/OVH/Outscale (see ADR-036)
2	DNS entry `*.<CUSTOMER_DOMAIN>` pointing at the Ingress entrypoint	TLS wildcard cert + 18 functional FQDN
3	cert-manager installed OR a pre-issued wildcard cert	Sprint 47 V2 / ADR-035
4	An OIDC IdP with the AKKO confidential client created (Keycloak / Auth0 / Okta / Azure AD)	Single-sign-on for cockpit + ADEN + every sub-app
5	An S3-compatible object storage endpoint + credentials	Iceberg lake, RAG document store, Spark warehouse
6	Postgres credentials (or accept the bundled akko-postgres)	Application metadata, audit log, DPIA inventory store

Step 1 — Copy the template¶

cd akko
cp helm/examples/values-customer-template.yaml \
   helm/examples/values-<CUSTOMER>.yaml

Replace every <CUSTOMER_*> placeholder with the actual value :

Placeholder	Example	Source
`<CUSTOMER_DOMAIN>`	`analytics.bigcorp.com`	DNS
`<CUSTOMER_SLUG>`	`bigcorp`	annotations + chart labels
`<CUSTOMER_IDP_URL>`	`https://idp.bigcorp.com/realms/bigcorp`	their Keycloak
`<CUSTOMER_S3_ENDPOINT>`	`https://s3.eu-west-1.amazonaws.com`	their object storage
`<CUSTOMER_REGION>`	`eu-west-1`	their object storage
`<CUSTOMER_BUCKET>`	`bigcorp-akko-lake`	their object storage
`<CUSTOMER_OPS_CONTACT>`	`ops@bigcorp.com`	Let's Encrypt notifications

Step 2 — Provide secrets¶

Create helm/examples/values-<CUSTOMER>-secrets.yaml (gitignored) :

global:
  oidc:
    clientSecret: "<from the customer's IdP>"
  storage:
    accessKey: "<S3 access key>"
    secretKey: "<S3 secret key>"
  auth:
    # Postgres + Keycloak admin + Trino + Airflow + Superset secrets ;
    # generate via : bash helm/scripts/generate-dev-secrets.sh
    keycloakAdminPassword: "<random>"
    postgresPassword: "<random>"
    # … see helm/scripts/generate-dev-secrets.sh for the full list

Step 3 — Map the customer's AD groups to AKKO platform roles¶

Edit the global.groupRoleMapping section of values-<CUSTOMER>.yaml to bridge the customer's existing AD/LDAP group names with AKKO's 5 platform roles :

global:
  groupRoleMapping:
    # Each line maps the customer's AD group name → an AKKO role
    "CN=DataAdmins,OU=IT,DC=corp":     "akko-admin"
    "CN=DataEng,OU=Teams,DC=corp":     "akko-engineer"
    "CN=Analysts,OU=Teams,DC=corp":    "akko-analyst"
    "CN=DPO,OU=Compliance,DC=corp":    "akko-steward"
    "CN=Viewers,OU=Teams,DC=corp":     "akko-viewer"

Empty list = no AKKO-side opinion on which groups exist (ADR-039). The cockpit JS, OPA Rego and ai-service all read this mapping at runtime.

Step 4 — Generate the realm + domain values¶

bash helm/scripts/generate-domain-values.sh <CUSTOMER_DOMAIN>

Produces :

helm/examples/values-<CUSTOMER>-domain.yaml — every Ingress host
helm/examples/realm-<CUSTOMER>.json — Keycloak realm template (only consumed if the customer doesn't already have a Keycloak)

Step 5 — Pre-flight check¶

# Run the 7-level testing cascade up to level 4 (pre-deployment)
bash helm/scripts/akko-test-all.sh --pre-deploy

Levels 1+2+4 must all pass before proceeding. The audit script also runs as part of the pre-commit hook :

python3 helm/scripts/audit-hardcoded-identities.py --ratchet 121

Step 6 — Helm install¶

helm install akko helm/akko/ -n akko --create-namespace \
  -f helm/examples/values-<CUSTOMER>.yaml \
  -f helm/examples/values-<CUSTOMER>-domain.yaml \
  -f helm/examples/values-<CUSTOMER>-secrets.yaml \
  --set-file akko-keycloak.realm.data=helm/examples/realm-<CUSTOMER>.json

(If the customer brings their own Keycloak, drop the --set-file line and set akko-keycloak.enabled: false in their values file.)

Step 7 — Configure Keycloak User Federation¶

If the customer is using their own Keycloak :

Admin Console → User Federation → Add LDAP / Add Active Directory
Read-only sync, point at the customer's AD / OpenLDAP / 389-DS
Map memberOf to a groups claim
Test : a real customer matricule logs in → JWT carries their AD group names → AKKO resolves via groupRoleMapping → cockpit, Trino, Superset all gate access accordingly.

Step 8 — Post-deploy smoke¶

bash helm/scripts/akko-test-all.sh --post-deploy

Validates : - All pods Ready - 12 functional FQDN return HTTP 2xx-3xx - 4 OIDC clients reachable - Helm release status = deployed - Cluster post-upgrade hooks all Completed

Step 9 — Activate optional sub-charts¶

Sub-chart	When to enable	Prerequisites
`akko-cockpit-backend` (ADR-040)	Once Sprint 57.5 D5 lands	Customer creates a Keycloak `akko-cockpit-backend` confidential client + 2 k8s Secrets (client_credentials + audit-log PG password)
`akko-mtls` (Linkerd, ADR-037)	Production only	Linkerd CRDs installed cluster-wide. Then phased per-service rollout via `global.serviceMesh.linkerdInject.<service>` — see mTLS rollout runbook.
`akko-milvus` (ADR-042/043)	When you want ADEN's vector semantic catalog	+1.5 GiB memory ; turn on `akko-init.adenCatalogIndexer.enabled=true` in the same upgrade so the catalog gets populated within an hour
`global.security.cosignVerify` (Sprint 52 P1)	After every image has been signed at least once by the Sprint 46 A1 pipeline	Kyverno installed cluster-wide. Start with `cosignVerifyAction: audit`, monitor PolicyReports for one sprint, then flip to `enforce`
`akko-bootstrap.banking/healthcare/retail/climascore`	Never at customer	These are demo datasets ; flip via `akko-demo.enabled=true` only on a sandbox

Verification checklist¶

[ ] python3 helm/scripts/audit-hardcoded-identities.py reports 0 (or whatever the current ratchet floor is)
[ ] No alice/bob/carol/dave/eve in any Secret, ConfigMap, Job, Ingress, Deployment of the live cluster
[ ] Customer's first user logs in via their AD → cockpit shows the right role badge
[ ] DPIA inventory (docs/admin/dpia-inventory.md) updated with the customer's data classifications
[ ] DR drill executed within 90 days of go-live (dr-drill-log.md)
[ ] Pentest scope shared with the customer's security team (pentest-scope.md)

Day-2 operations¶

Task	Frequency	Tool
Onboard a new user	When their AD enrolls them	Nothing — JWT propagation is automatic
Add a new role	Rare, mapping change	Edit `global.groupRoleMapping` + helm upgrade
Rotate Postgres password	Quarterly	Secret rotation runbook
Rotate object storage credentials	Quarterly	Secret rotation runbook
Audit log review	Monthly	`akko_audit.cockpit_events` table queries
Compliance refresh	Annually	DPIA / DR drill / pentest scope updates