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
Additional Requirements
- Azure Disk CSI Driver: Required for persistent storage (see Azure Disk CSI Driver Setup)
- Ingress Controller: For external access (see Ingress Controller Setup)
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.
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:- Application Gateway (Recommended)
- NGINX Ingress Controller
The Application Gateway Ingress Controller (AGIC) integrates Azure Application Gateway with AKS for ingress management.Install Application Gateway Ingress Controller:Verify installation:
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: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
Required Configuration
Required Configuration
LLM Provider Configuration
LLM Provider Configuration
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.Authentication (Optional)
Authentication (Optional)
Git repository runtime
Git repository runtime
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.Logging
Logging
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.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
- Via Ingress (Recommended)
- Port Forward (For Testing)
For Application Gateway Ingress Controller: Get the Application Gateway public IP:Access via: Access via:
http://<public-ip> or https://genesis.yourdomain.comFor NGINX Ingress: Get the external IP:http://<external-ip> or http://genesis.yourdomain.com (if DNS configured)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/healthon port 8080 - Period: 10 seconds
- Timeout: 5 seconds
- Failure threshold: 60 (up to ~10 minutes boot grace)
- Gates liveness and readiness until startup completes (
503with progress, then200)
Liveness Probe
- Endpoint:
GET /api/health/liveon port 8080 - Period: 30 seconds
- Timeout: 5 seconds
- Failure threshold: 3
- Always
200while the process is alive — does not require Genesis to be fully ready
Readiness Probe
- Endpoint:
GET /api/healthon port 8080 - Period: 10 seconds
- Timeout: 5 seconds
- Failure threshold: 3
- Returns
503while booting;200when ready to serve traffic
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
Pod Not Starting
Pod Not Starting
- 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
Persistent Volume Issues
Persistent Volume Issues
Ingress Not Working
Ingress Not Working
For Application Gateway Ingress Controller:For NGINX Ingress:
Database Issues
Database Issues
Viewing Logs
Viewing Logs
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.Uninstalling
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

