> ## 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

> Infrastructure, networking, database, and access requirements for deploying CRAFT on Kubernetes.

# Prerequisites

Before deploying EM-Runtime, ensure your environment meets the infrastructure, database, networking, and access requirements listed below.

## Kubernetes Cluster

<CardGroup cols={2}>
  <Card title="Kubernetes Version" icon="dharmachakra">
    **1.28+** required for Gateway API v1 support.
  </Card>

  <Card title="Minimum Nodes" icon="server">
    **3 nodes** for HA pod distribution across failure domains.
  </Card>

  <Card title="Node Sizing (Minimum)" icon="microchip">
    **4 vCPU, 16 GB RAM** per node.
  </Card>

  <Card title="Node Sizing (Recommended)" icon="microchip">
    **8 vCPU, 32 GB RAM** per node for HPA burst headroom.
  </Card>
</CardGroup>

| 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     |

<Note>
  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.
</Note>

## Infrastructure Overview

```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': {'lineColor': '#555555', 'fontFamily': 'sans-serif', 'edgeLabelBackground': '#ffffff'}}}%%
graph TB
    subgraph Cluster["Kubernetes Cluster (3+ nodes, 4vCPU/16GB each)"]
        GW["Gateway API v1\n(HTTPRoute + TLS)"]
        subgraph Services["Platform Services"]
            KC["Keycloak 26\n(2 replicas)"]
            OF["OpenFGA 1.11\n(2–10 replicas)"]
            GV["Governance\n(2–10 replicas)"]
            AS["Assets\n(2–10 replicas)"]
            UT["Utils\n(2–10 replicas)"]
        end
    end
    subgraph Data["Data Layer"]
        PG[("PostgreSQL 18+\n9 databases\n2vCPU / 4GB / 100GB SSD")]
        RD[("Redis 8.4.2\n5GB / noeviction")]
    end
    OBJ[("Object Storage\n(S3-compatible, private)")]
    CERT["cert-manager\n(TLS certificates)"]

    GW --> Services
    Services --> PG & RD
    Services --> OBJ
    CERT --> GW

    classDef cluster fill:#56B4E9,stroke:#555555,color:#000
    classDef svc fill:#E69F00,stroke:#555555,color:#000
    classDef data fill:#0072B2,stroke:#555555,color:#fff
    classDef ext fill:#009E73,stroke:#555555,color:#000
    class GW cluster
    class KC,OF,GV,AS,UT svc
    class PG,RD data
    class OBJ,CERT ext
```

## 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/*` |

## Required Tools

| Tool      | Version | Purpose                                |
| --------- | ------- | -------------------------------------- |
| `kubectl` | Latest  | Kubernetes cluster management          |
| `helm`    | 3.x     | Helm chart installation                |
| `gh`      | Latest  | GitHub CLI for registry authentication |

```bash theme={null}
# Authenticate GitHub CLI with required scopes
gh auth login --scopes read:packages,repo,workflow
```

## Pre-Deployment Checklist

<Steps>
  <Step title="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
  </Step>

  <Step title="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)
  </Step>

  <Step title="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
  </Step>

  <Step title="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
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Helm Configuration" icon="gear" href="/deployment/helm/configuration">
    Configure the Helm chart for your environment.
  </Card>
</CardGroup>