Skip to main content
This guide walks you through deploying the Genesis container to an existing Azure AKS (Azure Kubernetes Service) cluster.
For everything after the install — upgrade, rollback, backup and restore, secrets, user offboarding, scaling, teardown, and the failure-mode catalogue — see the Genesis Operations Runbook. It is cloud-agnostic, with a per-cloud section for the AKS-specific substrate. Snapshot options stay in Backup and Snapshot Options.
Genesis will provide you with the container image URL. Replace <container-registry-url> throughout this document with the URL provided by Genesis. Helm charts are published as private OCI artifacts on Docker Hub (oci://registry-1.docker.io/genesiscomputingai/genesis), ECR (oci://<account>.dkr.ecr.<region>.amazonaws.com/charts/genesis), and GHCR (oci://ghcr.io/genesis-computing-ai/charts/genesis). Docker Hub and ECR credentials are provided during onboarding; GHCR access uses a GitHub PAT with read:packages. If you use the bundled azure-aks/ helper scripts, set ECR_REGISTRY in azure-aks/aks-config.env and ensure the environment can run aws ecr get-login-password for that registry. Pin image.tag in your values file, and set GENESIS_IMAGE_TAG in azure-aks/aks-config.env only when you want a one-off override for a deploy.

Prerequisites

Azure AKS Cluster Requirements

AKS Cluster

Kubernetes version 1.23 or higher

kubectl

Configured to access your AKS cluster

Helm 3.8+

For deploying the Genesis Helm chart

Azure CLI

Configured with appropriate credentials
Verify cluster access:
Verify Helm installation:

Additional Requirements

Network Access

Azure Permissions

The AKS cluster’s managed identity or service principal needs appropriate permissions for:
  • Azure Disk operations (for persistent volumes)
  • Azure Container Registry access (if using ACR)
  • Azure Key Vault access (if storing secrets in Key Vault)

Azure Disk CSI Driver Setup

Genesis requires persistent storage for its database, git repositories, and uploaded files. The Azure Disk CSI driver must be installed in your cluster to provision Azure managed disks.
The Azure Disk CSI driver is automatically installed by default on AKS clusters. However, verify it’s running and properly configured.
Check if installed:

Installation Instructions

If not installed, refer to the Azure Kubernetes Service documentation for detailed Azure Disk CSI driver installation steps.

Ingress Controller Setup

Genesis requires an ingress controller for external access. Choose one based on your requirements:

Genesis Container Configuration

Container Image

Current Genesis container images include ripgrep (rg) out of the box for in-container file-content searches. After kubectl exec, you can use it to inspect mounted files under /app/bot_storage or /app/bot_git without installing extra packages. The same images also bundle the in-repo genesis_sdk package under /app/genesis_sdk (for execute_python_code local execution — not installable from PyPI) and the llm_wiki package under /app/llm_wiki, so the SDK, wiki APIs, and tools shipped with Genesis are available without extra image customization.

Image Pull Secrets (If Required)

If the container registry requires authentication, Genesis will provide the necessary credentials. Create a Kubernetes secret:
Then reference it in your Helm values file:

Exposed Ports

Persistent Storage Requirements

Genesis requires persistent storage for:
Recommended Storage Size: 50Gi minimum (adjust based on expected usage)Storage Class: Uses cluster default (typically managed-csi or managed-premium on AKS)For CSI volume snapshots, Azure Backup for AKS, Velero, and logical export options, see Backup and Snapshot Options.

Environment Variables

There is no LLM provider environment variable to set on the container. The provider, its credential and its model assignments are configured after the pod is running, from Config -> AI Providers or through the config API — see the worked example in Deployment Steps below. The Azure Terraform deployment also seeds AZURE_OPENAI_ENABLED=true; see the legacy-image compatibility note under AWS Bedrock Configuration.
Genesis prepares GIT_PATH on startup and ensures repos/, worktrees/, and .genesis_runtime/ exist before shared Git-backed workflows use the mount. The shared group-write repair starts in the background so slow recursive permission fixes do not block container startup.

Deployment Steps

1

Prepare Helm Chart

Genesis publishes the Helm chart to private OCI registries. After authenticating with the registry Genesis assigned to your deployment, pull and unpack the chart locally. If Genesis provided a .tgz archive instead, extract it and continue with the same chart directory layout:
Chart releases are published from main. On each GA release, Genesis updates appVersion in Chart.yaml to the promoted container version and patch-bumps the chart version automatically. To find the chart version for a specific GA release, query the GA_HELM_MAP repo variable: gh variable get GA_HELM_MAP -R genesis-computing-ai/genesis-agents | jq -r '.["vX.Y.Z"]'.
2

Create Values File

Create a genesis-values.yaml file with your configuration:
For IaC-managed deployments, keep AKS and ingress settings in genesis-values.yaml and copy the chart’s genesis-config-example.yaml to a separate genesis-config.yaml for providers, llm, embedding, auth, oauth_providers, and related app settings (including LiteLLM Proxy OAuth). Deploy with --set-file genesisConfig.content=genesis-config.yaml, or set genesisConfig.existingConfigMap when the file already exists as a ConfigMap. Genesis mounts the file at /app/.genesis/config/genesis-config.yaml, and explicit environment variables still take precedence over file-backed values.For Helm-driven RBAC on OIDC deployments, you can also pass --set-file groupRoleMapping.content=group-role-mapping.yaml and --set-file rbacSeedPolicy.content=rbac-policies.csv. See Deploying Genesis - Azure AKS with OIDC Authentication.
extraManifests defaults to []. Add complete Kubernetes resources here when you want Helm to deploy objects such as PodDisruptionBudget, NetworkPolicy, or PodMonitor alongside Genesis without forking the chart. Each list item is rendered as its own YAML document.
For NGINX Ingress Controller, use these annotations instead:
If you deploy with the bundled azure-aks/deploy-aks-*.sh helpers, pin image.tag in the corresponding values-aks-*.yaml file. The script passes ecr.enabled, ecr.registry, a fresh ecr.token, and image.pullPolicy=Always, runs kubectl rollout restart statefulset, and only passes --set image.tag when GENESIS_IMAGE_TAG is set in azure-aks/aks-config.env.
3

Deploy Genesis

4

Verify Deployment

5

Access Genesis

6

Configure the LLM Provider

Genesis starts without a provider and reports No suitable LLM found until one is configured. Configure it against the running pod, either from Config -> AI Providers in the UI or through the config API. Keep credentials in a request-body file — process arguments are visible to every process on the host and land in shell history.
Read each response before running the next call: these routes also answer 200 with success: false (for example when the provider already exists — repeat that call as a PUT). For the full endpoint reference and the other providers, see Configuring a provider through the config API.
Some schema fields carry a default_env_var binding that seeds them from the environment while nothing is stored, so an image can come up pre-seeded. That is bootstrap only — it is not the way to configure a provider, and anything saved through the UI or the config API outranks it.

Kubernetes-Specific Configuration

StatefulSet

Genesis is deployed as a StatefulSet (not Deployment) to ensure:
  • Stable network identity (pod name: genesis-0)
  • Ordered, graceful deployment and scaling
  • Stable persistent storage (PVC name: genesis-data-genesis-0)

Persistent Volume Claim

The StatefulSet creates a PersistentVolumeClaim with:

Volume Mounts

The Genesis container mounts the persistent volume at multiple paths:

Health Checks

Genesis uses three Kubernetes probes so slow startups do not trigger liveness restarts before the app is ready:

Startup Probe

  • Endpoint: GET /api/health on port 8080
  • Period: 10 seconds
  • Timeout: 5 seconds
  • Failure threshold: 60 (up to ~10 minutes boot grace)
  • Gates liveness and readiness until startup completes (503 with progress, then 200)

Liveness Probe

  • Endpoint: GET /api/health/live on port 8080
  • Period: 30 seconds
  • Timeout: 5 seconds
  • Failure threshold: 3
  • Always 200 while the process is alive — does not require Genesis to be fully ready

Readiness Probe

  • Endpoint: GET /api/health on port 8080
  • Period: 10 seconds
  • Timeout: 5 seconds
  • Failure threshold: 3
  • Returns 503 while booting; 200 when ready to serve traffic
When Genesis sits behind OAuth2 Proxy (authProvider: "proxy"), configure the proxy so GET health probes and the dashboard healthcheck endpoint bypass authentication. The bundled azure-aks/oauth2-proxy-values.yaml example (also generated by azure-aks/setup-azure-ad-auth.sh) includes:
cookie_secure = true is correct when HTTPS terminates at the ingress controller or external load balancer, even if the OAuth2 Proxy chart ingress has tls: []. Routes are GET-scoped and anchored so other /api/health/* paths (errors, threads, slots, and so on) remain authenticated. cookie_csrf_per_request isolates concurrent login flows and prevents invalid-CSRF 403 responses. For Azure AD refresh-token, CSRF-cookie, and nginx auth_request caveats, see Deploying Genesis - Azure AKS with OIDC Authentication. For native OIDC without OAuth2 Proxy, see Deploying Genesis - Azure AKS with OIDC Authentication.

Graceful shutdown (podLifecycle)

The chart sets a preStop sleep and a pod-level termination grace period so ingress load balancers can drain in-flight requests before Genesis receives SIGTERM.

Extension containers (extraContainers, extraInitContainers)

Pass additional Kubernetes container specs through the chart without forking templates. See Genesis on AWS for YAML examples (log shipper, wait-for-dependency init container).

Resource Requirements

Default resource requests:
No resource limits are set by default to avoid OOM kills. Adjust based on your workload.

Azure-Specific Considerations

Managed Identity for Azure OpenAI

If using Azure OpenAI, you can configure a managed identity to access Azure OpenAI without storing API keys in Kubernetes secrets:
1

Create Managed Identity

If not using cluster’s managed identity:
2

Grant Permissions

3

Configure Pod Identity

For Workload Identity:
  • Create a service account with the managed identity annotation
  • Configure the StatefulSet to use the service account
4

Retrieve API Key (Optional)

Using managed identity in an init container or startup script:

Azure Disk Encryption

Azure managed disks created by the Azure Disk CSI driver on AKS are encrypted by default. Verify:

Virtual Network Configuration

Ensure your AKS cluster nodes have:

Troubleshooting

Common issues:
  • Image pull errors: Check network connectivity to the container registry provided by Genesis
  • PVC issues: Verify Azure Disk CSI driver is installed and storage class exists
  • Resource constraints: Check node resources
For Application Gateway Ingress Controller:
For NGINX Ingress:

Upgrading Genesis

When a new Genesis version is released:
The StatefulSet will perform a rolling update, and the persistent volume will be reattached to the new pod.
For values-driven upgrades with the AKS helper scripts, update image.tag in the relevant values-aks-*.yaml file and rerun the matching azure-aks/deploy-aks-*.sh helper. If you use azure-aks/update-aks-images.sh, GA stacks default to v1.18.2 and edge stacks default to edge when you do not pass an explicit override.
Purely numeric image.tag values (for example ECR build IDs) are coerced to strings automatically in chart 0.3.55 and later. On older charts, quote the tag in YAML or use --set-string image.tag=... instead of --set.

Uninstalling

Deleting the PVC will permanently remove all Genesis data including the database, git repositories, and uploaded files.

Additional Resources

Azure AKS Documentation

Official Azure Kubernetes Service documentation

Azure Disk CSI Driver

Azure Disk CSI Driver setup guide

Application Gateway Ingress

Application Gateway Ingress Controller documentation