> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kubernetes Prerequisites

> Cluster requirements for self-hosting Runlayer on EKS or GKE — you provision the cluster

Runlayer does **not** provision or operate your Kubernetes cluster. You create EKS or GKE to your own security, networking, and IaC standards. This page is the **cluster contract** the [Runlayer Operator](https://docs.runlayer.com/deployment/runlayer-operator.md) expects.

For Postgres, Redis, buckets, and streams, see [External dependencies](https://docs.runlayer.com/deployment/external-dependencies.md). For IRSA / Workload Identity, see [Workload identity](https://docs.runlayer.com/deployment/workload-identity.md).

## Supported platforms

| | EKS | GKE |
| - | - | - |
| **Kubernetes** | **1.29+** (recommend current EKS stable) | **1.29+** (recommend current GKE stable) |
| **Helm** | 3.8+ | 3.8+ |
| **CNI + NetworkPolicy** | VPC CNI + policy engine (Calico/Cilium/etc.) | Dataplane with NetworkPolicy support |
| **Workload identity** | OIDC provider + **IRSA** | **Workload Identity** enabled |
| **Ingress** | AWS Load Balancer Controller (`alb`) typical | GKE Ingress (`gce` / `gce-internal`) or nginx |
| **Image pull** | Node role or pull secret for Customer Distribution ECR `088332244652` (or your mirror) | Same — usually a GAR / private mirror |

## Capacity (baseline)

Size for your HA targets. Operator defaults (override per component) roughly need:

| Workload | Default CPU request | Default memory |
| - | - | - |
| backend | 4000m | 8192Mi (+ ephemeral storage for audit spool) |
| frontend | 250m | 512Mi |
| worker | 1000m | 4096Mi |

Plan node pools that can schedule at least two backend replicas for production. Metrics Server is required if you enable HPA (`spec.autoscaling`).

## Storage and encryption

| Requirement | Why | EKS | GKE |
| - | - | - | - |
| **Encrypted node volumes** | Audit-log spool briefly holds pre-redaction payloads on node disk | Enable encrypted EBS for node groups | Google-managed encryption by default; CMEK optional |
| Storage class for platform pods | Core platform pods are stateless (`emptyDir` spool) | EBS CSI only if you add stateful add-ons | Same |

## Networking

| Requirement | Notes |
| - | - |
| Pods → Postgres / Redis | Private connectivity (VPC, peering, Private Service Connect) |
| Outbound HTTPS | WorkOS, hosted MCP Catalog (`mcp-catalog.prod.runlayer.com`), optional Sentry, upstream MCP SaaS — see [Egress requirements](https://docs.runlayer.com/deployment/egress-requirements.md) |
| DNS | CoreDNS; resolve private DB/Redis hostnames |
| Ingress → backend:8000 / frontend:80 | ALB target groups or GKE BackendConfig health checks |

## Identity

| Cloud | Requirement |
| - | - |
| **EKS** | Cluster OIDC issuer; IAM roles trust `system:serviceaccount:<platform-ns>:<instance>-<workload>` |
| **GKE** | Workload Identity pool; bind GSA ↔ KSA for each operator-created ServiceAccount |

Exact SA names and permission matrix: [Workload identity](https://docs.runlayer.com/deployment/workload-identity.md).

## Optional cluster features

| Feature | When | Cluster need |
| - | - | - |
| **ToolGuard GPU** | `components.toolguard` with `gpu.enabled: true` | GPU node pool + NVIDIA device plugin / drivers; scheduling labels/tolerations |
| **ToolGuard CPU-only** | `gpu.enabled: false` | No GPU pool |
| **Runlayer Deploy** | `spec.deploy.enabled: true` | Capacity for MCP pods; optional dedicated node pool via operator values |
| **Agent sandbox `k8s`** | `spec.agents.sandboxMode: k8s` | Agent Sandbox controller + gVisor/Kata — advanced; prefer AgentCore on AWS |
| **OTEL / MCP telemetry** | Sidecars / proxy enabled | Reachable OTLP endpoints from pods; NetworkPolicy egress |

## What you do **not** get from Runlayer

* Terraform to create the EKS/GKE control plane
* Managed node-group / Autopilot sizing for your org
* Shared cluster multi-tenancy beyond what you configure with `RunlayerInstance`

Deprecated: [EKS + Terraform](https://docs.runlayer.com/deployment/eks-terraform) (do not use for new installs).

## Next

1. [External dependencies](https://docs.runlayer.com/deployment/external-dependencies.md)
2. [Workload identity](https://docs.runlayer.com/deployment/workload-identity.md)
3. [Runlayer Operator](https://docs.runlayer.com/deployment/runlayer-operator.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.