Deploying Genesis - Kuberenetes on AWS

This guide walks you through deploying the Genesis container to an existing AWS EKS (Elastic Kubernetes Service) cluster.

Genesis will provide you with the container image URL. Replace <container-registry-url> throughout this document with the URL provided by Genesis.

Prerequisites

AWS EKS Cluster Requirements

EKS Cluster

Kubernetes version 1.23 or higher

kubectl

Configured to access your EKS cluster

Helm 3.8+

For deploying the Genesis Helm chart

AWS CLI

Configured with appropriate credentials

Verify cluster access:

aws eks update-kubeconfig --name <cluster-name> --region <region>
kubectl get nodes  # Verify access

Verify Helm installation:

helm version

Additional Requirements

EBS CSI Driver: Required for persistent storage (see EBS CSI Driver Setup)
Ingress Controller: For external access (see Ingress Controller Setup)

Network Access

Requirement	Purpose
Outbound Internet	Cluster nodes must pull container images from the registry URL provided by Genesis
DNS Resolution	For accessing external APIs (OpenAI, Databricks, etc.) if using those LLM providers

IAM Permissions

The EKS cluster node group IAM role needs the following permissions:

AmazonEKSWorkerNodePolicy
AmazonEKS_CNI_Policy
AmazonEC2ContainerRegistryReadOnly

If using AWS Bedrock as the LLM provider, the node group role also needs AmazonBedrockFullAccess (or appropriate scoped permissions).

EBS CSI Driver Setup

Genesis requires persistent storage for its database, git repositories, and uploaded files. The Amazon EBS CSI driver must be installed in your cluster to provision EBS volumes.

The EBS CSI driver is not automatically installed by default on standard EKS clusters (even for Kubernetes 1.23+). You must install it manually. However, if you’re using EKS Auto Mode, the EBS CSI driver is automatically included and no installation is needed.

Check if installed:

kubectl get pods -n kube-system | grep ebs-csi

Installation Instructions

Refer to the Amazon EKS User Guide for detailed EBS CSI driver installation steps, including IAM role setup and add-on installation.

Ingress Controller Setup

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

AWS Load Balancer Controller (Recommended)
NGINX Ingress Controller

The AWS Load Balancer Controller creates Application Load Balancers (ALB) or Network Load Balancers (NLB) for ingress resources.Install AWS Load Balancer Controller:

# Add the EKS chart repository
helm repo add eks https://aws.github.io/eks-charts
helm repo update

# Install the controller
helm install aws-load-balancer-controller eks/aws-load-balancer-controller \
  -n kube-system \
  --set clusterName=<cluster-name> \
  --set serviceAccount.create=false \
  --set serviceAccount.name=aws-load-balancer-controller

Verify installation:

kubectl get deployment -n kube-system aws-load-balancer-controller

Install NGINX Ingress:

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/cloud/deploy.yaml

# Wait for it to be ready
kubectl wait --namespace ingress-nginx \
  --for=condition=ready pod \
  --selector=app.kubernetes.io/component=controller \
  --timeout=90s

Genesis Container Configuration

Container Image

Setting	Description
Repository	Genesis will provide the container image URL (e.g., `<container-registry-url>/genesis`)
Tags	Genesis will specify the appropriate tag to use (typically `latest` or a specific version)
Registry Access	Genesis will provide details about authentication requirements, if any

Image Pull Secrets (If Required)

If the container registry requires authentication, Genesis will provide the necessary credentials. Create a Kubernetes secret:

# Create namespace first if it doesn't exist
kubectl create namespace genesis

# Create Docker registry secret (if credentials provided by Genesis)
kubectl create secret docker-registry genesis-registry-credentials \
  --docker-server=<container-registry-url> \
  --docker-username=<username> \
  --docker-password=<password> \
  --docker-email=<email> \
  -n genesis

Then reference it in your Helm values file:

imagePullSecrets:
  - name: genesis-registry-credentials

Exposed Ports

Port	Service	Description
8080	FastAPI	Primary application with React GUI and modern APIs
8082	Flask	UDF proxy, OAuth, external integrations
8501	Streamlit	Legacy Streamlit interface

Persistent Storage Requirements

Genesis requires persistent storage for:

Path	Purpose
`/app/.genesis/db/genesis.db`	SQLite database
`/app/bot_git`	Cloned git repositories
`/app/bot_storage`	Uploaded files and bot storage
`/app/tmp`	Runtime temp files

Recommended Storage Size: 50Gi minimum (adjust based on expected usage)Storage Class: Uses cluster default (typically gp2 or gp3 on EKS)

Environment Variables

Required Configuration

Variable	Default	Description
`SQLITE_DB_PATH`	`/app/.genesis/db/genesis.db`	Path to SQLite database
`DATABASE_URL`	`sqlite:///app/.genesis/db/genesis.db`	SQLite connection string

AWS Bedrock Configuration

BOT_OS_DEFAULT_LLM_ENGINE: "litellm"  # Optional: helps with initial Bedrock setup
LITELLM_MODEL: "bedrock/<model-id>"
AWS_REGION: "<aws-region>"
AWS_DEFAULT_REGION: "<aws-region>"
# Note: Uses IAM role credentials from node group, no API key needed

Authentication (Optional)

Variable	Value	Description
`AUTH_ENABLED`	`"true"`	Enable authentication
`AUTH_PROVIDER`	`"proxy"`	For ingress-based auth

Logging

Variable	Options	Description
`LOG_LEVEL`	`DEBUG`, `INFO`, `WARNING`, `ERROR`	Log verbosity
`LOGS_FORMAT`	`json`, `text`	Log output format

Deployment Steps

Prepare Helm Chart

Genesis will provide you with the Helm chart as an archive file. Extract it:

# Extract the Helm chart archive provided by Genesis
tar -xzf genesis-<version>.tgz

# Navigate to the chart directory
cd genesis

Create Values File

Create a genesis-values.yaml file with your configuration:

# Genesis EKS Deployment Values

# Container image (Genesis will provide the repository URL)
image:
  repository: <container-registry-url>/genesis  # Replace with URL provided by Genesis
  tag: latest  # Use the tag specified by Genesis
  pullPolicy: IfNotPresent

# Image pull secrets (if the container registry requires authentication)
# Genesis will provide instructions if credentials are needed
# imagePullSecrets:
#   - name: genesis-registry-credentials

# Secrets - REQUIRED: Configure at least one LLM provider
secrets:
  # Master encryption key (auto-generated if not provided)
  genesisMasterKey: ""  # Optional: python -c "import secrets; print(secrets.token_hex(32))"
  
  # OpenAI configuration
  openaiApiKey: "sk-your-key-here"  # Required if using OpenAI
  
  # Databricks configuration (alternative to OpenAI)
  # databricksApiKey: ""
  # databricksBaseUrl: ""
  # databricksModelName: "databricks-claude-3-7-sonnet"

# Non-sensitive configuration
config:
  sqliteDbPath: "/app/.genesis/db/genesis.db"
  logLevel: "INFO"
  logsFormat: "json"
  authEnabled: "true"
  authProvider: "proxy"  # For ingress-based authentication
  
  # AWS Bedrock configuration (if using Bedrock)
  extraEnv:
    BOT_OS_DEFAULT_LLM_ENGINE: "litellm"  # Optional: helps with initial Bedrock setup
    LITELLM_MODEL: "bedrock/us.anthropic.claude-sonnet-4-5-20250929-v1:0"
    AWS_REGION: "us-east-1"
    AWS_DEFAULT_REGION: "us-east-1"

# Resource requests
resources:
  requests:
    cpu: "2000m"
    memory: "6Gi"
  limits: {}  # No limits by default

# Persistent storage
persistence:
  storageClassName: ""  # Uses cluster default (gp2/gp3)
  size: 50Gi  # Kubernetes uses binary units (Gi = Gibibytes)
  accessMode: ReadWriteOnce

# Service configuration
service:
  type: ClusterIP
  ports:
    fastapi: 8080
    flask: 8082
    streamlit: 8501

# Ingress configuration
ingress:
  enabled: true
  className: "alb"  # For AWS Load Balancer Controller, or "nginx" for NGINX
  
  # For AWS Load Balancer Controller
  annotations:
    alb.ingress.kubernetes.io/scheme: internet-facing
    alb.ingress.kubernetes.io/target-type: ip
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}, {"HTTPS": 443}]'
    alb.ingress.kubernetes.io/ssl-redirect: "443"
    alb.ingress.kubernetes.io/healthcheck-path: "/api/health"
    alb.ingress.kubernetes.io/healthcheck-protocol: "HTTP"
    alb.ingress.kubernetes.io/healthcheck-port: "8080"
    # For HTTPS, add certificate ARN:
    # alb.ingress.kubernetes.io/certificate-arn: "arn:aws:acm:region:account:certificate/cert-id"
  
  hosts:
    - host: genesis.yourdomain.com  # Replace with your domain
      paths:
        - path: /
          pathType: Prefix
          port: 8080
  
  # TLS configuration (if using HTTPS)
  tls: []

For NGINX Ingress Controller, use these annotations instead:

annotations:
  nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
  nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
  nginx.ingress.kubernetes.io/proxy-body-size: "100m"

Deploy Genesis

# Install using Helm
helm install genesis ./genesis -f genesis-values.yaml

# Or if deploying from chart directory
helm install genesis . -f genesis-values.yaml

Verify Deployment

# Check namespace
kubectl get namespace genesis

# Check StatefulSet
kubectl get statefulset -n genesis

# Check pod status
kubectl get pods -n genesis -w

# Check persistent volume claim
kubectl get pvc -n genesis

# Check service
kubectl get svc -n genesis

# Check ingress
kubectl get ingress -n genesis

# View pod logs
kubectl logs -n genesis genesis-0 --follow

Access Genesis

Via Ingress (Recommended)
Port Forward (For Testing)

For AWS Load Balancer Controller: Get the ALB address:

kubectl get ingress -n genesis genesis -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'

Access via: http://<alb-hostname> or https://genesis.yourdomain.comFor NGINX Ingress: Get the external IP:

kubectl get svc -n ingress-nginx ingress-nginx-controller

Access via: http://<external-ip> or http://genesis.yourdomain.com (if DNS configured)

# Forward port 8080
kubectl port-forward -n genesis svc/genesis 8080:8080

# Access at http://localhost:8080

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:

Property	Value
Name	`genesis-data-genesis-0`
Storage Class	Uses cluster default (typically `gp2` or `gp3`)
Access Mode	`ReadWriteOnce` (single pod access)
Retention	PVC is retained when StatefulSet is deleted (data preservation)

Volume Mounts

The Genesis container mounts the persistent volume at multiple paths:

Mount Path	Purpose
`/app/.genesis/db`	Database files
`/app/bot_git`	Git repositories
`/app/bot_storage`	File storage and uploads
`/app/tmp`	Temporary files

Health Checks

Genesis includes liveness and readiness probes:

Liveness Probe

Endpoint: GET /api/health on port 8080
Initial delay: 60 seconds
Period: 30 seconds
Timeout: 5 seconds
Failure threshold: 3

Readiness Probe

Endpoint: GET /api/health on port 8080
Initial delay: 30 seconds
Period: 10 seconds
Timeout: 5 seconds
Failure threshold: 3

Resource Requirements

Default resource requests:

Resource	Request
CPU	2000m (2 cores)
Memory	6Gi

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

AWS-Specific Considerations

IAM Roles for Service Accounts (IRSA)

If using AWS Bedrock, you can configure IRSA to allow the Genesis pod to access Bedrock without storing credentials:

Create IAM Role with Bedrock permissions
Create Service Account with role annotation:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: genesis
  namespace: genesis
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::<account-id>:role/genesis-bedrock-role

Configure StatefulSet to use the service account (modify Helm values or StatefulSet directly)

EBS Volume Encryption

EBS volumes created by the EBS CSI driver on EKS are encrypted by default if your cluster has encryption enabled. Verify:

kubectl get storageclass -o yaml

VPC Configuration

Ensure your EKS cluster nodes have:

Requirement	Purpose
Outbound Internet Access	For pulling images from the container registry provided by Genesis
DNS Resolution	For external API calls (OpenAI, Databricks, etc.)
Security Group Rules	Allow ingress on ports 80/443 if using ALB, or node port if using NodePort service

Troubleshooting

Pod Not Starting

# Check pod status
kubectl describe pod -n genesis genesis-0

# Check events
kubectl get events -n genesis --sort-by='.lastTimestamp'

Common issues:

Image pull errors: Check network connectivity to the container registry provided by Genesis
PVC issues: Verify EBS CSI driver is installed and storage class exists
Resource constraints: Check node resources

Persistent Volume Issues

# Check PVC status
kubectl get pvc -n genesis
kubectl describe pvc genesis-data-genesis-0 -n genesis

# Check PV
kubectl get pv
kubectl describe pv <pv-name>

# Check EBS CSI driver logs
kubectl logs -n kube-system -l app=ebs-csi-controller

Ingress Not Working

For AWS Load Balancer Controller:

# Check controller logs
kubectl logs -n kube-system -l app.kubernetes.io/name=aws-load-balancer-controller

# Check ingress status
kubectl describe ingress -n genesis genesis

# Verify ALB was created
aws elbv2 describe-load-balancers --region <region>

For NGINX Ingress:

# Check controller pods
kubectl get pods -n ingress-nginx

# Check controller logs
kubectl logs -n ingress-nginx -l app.kubernetes.io/component=controller

Database Issues

# Access pod shell
kubectl exec -it -n genesis genesis-0 -- /bin/bash

# Check database file
ls -lh /app/.genesis/db/

# Check database integrity (if SQLite tools available)
sqlite3 /app/.genesis/db/genesis.db "PRAGMA integrity_check;"

Viewing Logs

# View current logs
kubectl logs -n genesis genesis-0

# Follow logs
kubectl logs -n genesis genesis-0 --follow

# View previous container logs (if pod restarted)
kubectl logs -n genesis genesis-0 --previous

Upgrading Genesis

When a new Genesis version is released:

# Update image tag in values file or override
helm upgrade genesis ./genesis -f genesis-values.yaml --set image.tag=v1.3.2

# Or update values.yaml and upgrade
helm upgrade genesis ./genesis -f genesis-values.yaml

# Verify upgrade
kubectl get pods -n genesis -o jsonpath='{.items[0].spec.containers[0].image}'
kubectl get pods -n genesis

The StatefulSet will perform a rolling update, and the persistent volume will be reattached to the new pod.

Uninstalling

# Uninstall Helm release
helm uninstall genesis

# Note: PVC is retained by default to preserve data
# To delete PVC and all data:
kubectl delete pvc genesis-data-genesis-0 -n genesis

# Delete namespace
kubectl delete namespace genesis

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

Additional Resources

AWS EKS Documentation

Official Amazon EKS documentation

EBS CSI Driver

EBS CSI Driver setup guide

AWS Load Balancer Controller

AWS Load Balancer Controller documentation

Getting Started

Creating A Mission

Blueprint

Genesis Data Agents

Genesis Agent Security Controls

Genesis Data Agent's Toolkit

Setup

Slack and Teams

Data Connections

Deployment Options

​Prerequisites

​AWS EKS Cluster Requirements

EKS Cluster

kubectl

Helm 3.8+

AWS CLI

​Additional Requirements

​Network Access

​IAM Permissions

​EBS CSI Driver Setup

Installation Instructions

​Ingress Controller Setup

​Genesis Container Configuration

​Container Image

​Image Pull Secrets (If Required)

​Exposed Ports

​Persistent Storage Requirements

​Environment Variables

​Deployment Steps

​Kubernetes-Specific Configuration

​StatefulSet

​Persistent Volume Claim

​Volume Mounts

​Health Checks

Liveness Probe

Readiness Probe

​Resource Requirements

​AWS-Specific Considerations

​IAM Roles for Service Accounts (IRSA)

​EBS Volume Encryption

​VPC Configuration

​Troubleshooting

​Upgrading Genesis

​Uninstalling

​Additional Resources

AWS EKS Documentation

EBS CSI Driver

AWS Load Balancer Controller

Prerequisites

AWS EKS Cluster Requirements

Additional Requirements

Network Access

IAM Permissions

EBS CSI Driver Setup

Ingress Controller Setup

Genesis Container Configuration

Container Image

Image Pull Secrets (If Required)

Exposed Ports

Persistent Storage Requirements

Environment Variables

Deployment Steps

Kubernetes-Specific Configuration

StatefulSet

Persistent Volume Claim

Volume Mounts

Health Checks

Resource Requirements

AWS-Specific Considerations

IAM Roles for Service Accounts (IRSA)

EBS Volume Encryption

VPC Configuration

Troubleshooting

Upgrading Genesis

Uninstalling

Additional Resources