Documentation Index
Fetch the complete documentation index at: https://docs.emergence.ai/llms.txt
Use this file to discover all available pages before exploring further.
Prerequisites
Before deploying EM-Runtime, ensure your environment meets the infrastructure, database, networking, and access requirements listed below.
Kubernetes Cluster
Kubernetes Version
1.28+ required for Gateway API v1 support.
Minimum Nodes
3 nodes for HA pod distribution across failure domains.
Node Sizing (Minimum)
4 vCPU, 16 GB RAM per node.
Node Sizing (Recommended)
8 vCPU, 32 GB RAM per node for HPA burst headroom.
| Requirement | Specification |
|---|
| Cluster type | Managed (GKE, EKS, AKS) or self-managed (RKE2, k3s, OpenShift) |
| CNI plugin | Calico, Cilium, or cloud-native CNI |
| Gateway API | Gateway API v1 controller (NGINX Gateway Fabric, Envoy Gateway, or cloud-native) |
| cert-manager | v1.x for TLS certificate lifecycle |
| external-dns | Optional, for automatic DNS record creation |
| Image registry access | Pull access to ghcr.io/emergenceai/* (private) |
IP Address Planning
Allocate three non-overlapping CIDR ranges:
| Range | Purpose | Recommended Size |
|---|
| Node CIDR | Kubernetes node IPs | /20 (4,096 addresses) |
| Pod CIDR | Pod network | /19 (8,192 addresses) |
| Service CIDR | ClusterIP services | /22 (1,024 addresses) |
Compute Resources
Per-Component Resource Allocation
The table shows Helm chart defaults (suitable for dev/staging) and production overrides (used in GCP deployments).
| Component | Min Replicas | CPU Request (Default / Prod) | CPU Limit | Memory Request (Default / Prod) | Memory Limit | |
|---|
| Keycloak | 2 | 1000m / 1000m | 2000m | 1280Mi / 1536Mi | 2Gi | |
| OpenFGA | 2 (HPA: 2-10) | 100m / 200m | 500m | 256Mi / 256Mi | 512Mi | |
| Infisical | 2 | 350m / 500m | 1000m | 512Mi / 512Mi | 1Gi | (if using Infisical backend; omit for ESO) |
| em-runtime-governance | 2 (HPA: 2-10) | 250m / 500m | 1000m | 512Mi / 512Mi | 1Gi | |
| em-runtime-assets | 2 (HPA: 2-10) | 250m / 500m | 1000m | 512Mi / 512Mi | 1Gi | |
| em-runtime-utils | 2 (HPA: 2-10) | 100m / 250m | 500m | 256Mi / 256Mi | 512Mi | |
Aggregate Totals (Core Only, Helm Defaults)
| Scenario | CPU Request | CPU Limit | Memory Request | Memory Limit |
|---|
| Minimum (all at min replicas) | 4.1 vCPU | 12.0 vCPU | 6.5 GiB | 12.0 GiB |
| Maximum (HPA services at max 10) | 9.7 vCPU | 36.0 vCPU | 18.5 GiB | 36.0 GiB |
Add 10-20% overhead for system pods (kube-system, cert-manager, external-dns, gateway controller, monitoring agents). Companion solution services (Data Insights, Data Governance) add additional resources.
Infrastructure Overview
Database Requirements
PostgreSQL
| Parameter | Specification |
|---|
| Version | PostgreSQL 18 |
| Instance sizing | 2 vCPU, 4 GB RAM (minimum) |
| High availability | Multi-AZ / regional replication |
| Initial disk | 100 GB SSD |
| Maximum disk | 1,000 GB (auto-resize) |
| Backup retention | 7 days minimum |
| Required extensions | pg_cron (on utils database) |
Databases (9 total, single shared instance)
| Database | Used By |
|---|
keycloak | Keycloak IAM |
openfga | OpenFGA authorization |
infisical | Infisical secrets management (provisioned by default; unused if using ESO backend) |
governance | Platform Governance service |
assets | Platform Assets service |
utils | Platform Utilities service (+ pg_cron) |
prefect | Prefect workflow orchestration (Data Governance) |
datareadiness | Data quality and metadata (Data Governance) |
talk2data | Natural language query engine (Data Insights) |
Redis
| Parameter | Specification |
|---|
| Version | Redis 8.4.2 (self-managed) / Redis 7.0+ (managed services) |
| Memory | 5 GB |
| High availability | Multi-AZ replica (STANDARD_HA) |
| Authentication | Password-protected (AUTH required) |
| TLS | Supported (rediss:// scheme) |
| Eviction policy | noeviction (reject writes when full) |
Object Storage (S3-Compatible)
| Parameter | Specification |
|---|
| Protocol | S3-compatible API (AWS S3, GCS HMAC, MinIO) |
| Access control | Private (no public access) |
| Authentication | Access key + secret key (HMAC) |
| Bucket name | Configurable (default: em-runtime) |
| Max file upload | 1,000 MB (configurable) |
Networking
Service Ports (Internal)
| Service | Port | Protocol | |
|---|
| em-runtime-governance | 8000 | HTTP | |
| em-runtime-assets | 8000 | HTTP | |
| em-runtime-utils | 8000 | HTTP | |
| Keycloak | 8080 | HTTP | |
| OpenFGA | 8080 | HTTP + gRPC (health: 8081) | |
| Infisical | 8080 | HTTP | (if using Infisical backend) |
| PostgreSQL | 5432 | TCP | |
| Redis | 6379 | TCP | |
External Ingress (HTTPRoute Rules)
| Path | Backend | Port | Notes |
|---|
/keycloak | keycloak | 8080 | Pass-through (no rewrite) |
/api/governance | em-runtime-governance | 8000 | Rewrite to /governance |
/api/assets | em-runtime-assets | 8000 | Rewrite to /assets |
/api/utils | em-runtime-utils | 8000 | Rewrite to /utils |
TLS Requirements
| Boundary | Requirement |
|---|
| Client to load balancer | TLS 1.2+ (certificate required) |
| Load balancer to pods | HTTP (in-cluster; TLS optional) |
| Services to PostgreSQL | SSL recommended (private network) |
| Services to Redis | TLS supported (rediss:// scheme) |
Firewall Rules
Ensure the following traffic is allowed:
- Inbound: HTTPS (443)
- From cluster: PostgreSQL (5432), Redis (6379), S3 (443)
- LLM API egress: OpenAI, Anthropic, Vertex AI endpoints (for Data Insights and Data Governance)
Required Secrets
Create these credentials before deployment:
| Secret | Description |
|---|
POSTGRES_PASSWORD | PostgreSQL superuser password |
POSTGRES_HOST | PostgreSQL hostname or IP |
REDIS_PASSWORD | Redis AUTH password |
REDIS_HOST | Redis hostname or IP |
S3_ACCESS_KEY_ID | Object storage access key |
S3_SECRET_ACCESS_KEY | Object storage secret key |
S3_ENDPOINT_URL | Object storage endpoint |
S3_BUCKET_NAME | Bucket name |
| OCI registry credentials | Pull secret for ghcr.io/emergenceai/* |
| Tool | Version | Purpose |
|---|
kubectl | Latest | Kubernetes cluster management |
helm | 3.x | Helm chart installation |
gh | Latest | GitHub CLI for registry authentication |
# Authenticate GitHub CLI with required scopes
gh auth login --scopes read:packages,repo,workflow
Pre-Deployment Checklist
Infrastructure
- Kubernetes cluster provisioned (1.28+, 3+ nodes, 4+ vCPU / 16+ GB RAM each)
- Gateway API controller installed and operational
- cert-manager installed
- kubectl access configured with cluster-admin or equivalent
Databases
- PostgreSQL 18 instance provisioned with multi-AZ
- 9 databases created
pg_cron extension installed on utils database- Redis instance provisioned (5 GB, AUTH enabled,
noeviction policy)
Storage and Networking
- S3-compatible bucket created (private access)
- HMAC access key and secret key provisioned
- DNS record planned for platform hostname
- TLS certificate available
Secrets and Access
- All database and storage credentials available
- Container registry credentials for
ghcr.io/emergenceai/*
- Helm 3.x and
gh CLI installed and authenticated
- Access to
oci://ghcr.io/emergenceai/charts verified
Next Steps
Helm Configuration
Configure the Helm chart for your environment.
