Merging to release-5.12: DX-2363: docs: Add container support guide (Podman, containerd, CRI-O) (#1872)

buger · sharadregoti · claude · web-flow · commit 4595d7f7b6d7 · 2026-04-16T08:42:36.000Z
DX-2363: docs: Add container support guide (Podman, containerd, CRI-O) (#1872) * docs: add container support guide (Podman, containerd, CRI-O) * docs(DX-2363): restructure container runtimes guide and add cross-references - Rewrite containers.mdx as a proper Tyk docs page: clean frontmatter, active voice, no numbered headings, FAQ as AccordionGroup, no em dashes - Move page from tyk-self-managed/install/containers to deployment-and-operations/container-runtimes - Update docs.json: remove old nav entry, add new entry under Configuration group after planning-for-production - Add Container Runtimes cross-reference Note (after Prerequisites) to 7 install pages: tyk-self-managed docker/k8s, portal docker/k8s, ai-studio docker/k8s, tyk-governance installation Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Leonid Bugaev <leonsbox@gmail.com> Co-authored-by: Sharad Regoti <sharadregoti15@gmail.com> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
diff --git a/ai-management/ai-studio/deployment-k8s.mdx b/ai-management/ai-studio/deployment-k8s.mdx
@@ -25,6 +25,10 @@ This guide explains how to deploy Tyk AI Studio (control plane), an Edge Gateway
 - A Tyk AI License key (contact support@tyk.io or your account manager to obtain)
 - For production with TLS: cert-manager installed in your cluster
 
+<Note>
+Running on Podman, containerd, or another container runtime? See [Container Runtimes](/deployment-and-operations/container-runtimes).
+</Note>
+
 ## Generate Secrets
 
 Before installing, generate three secret keys to secure communication and encrypt data:
diff --git a/ai-management/ai-studio/quickstart.mdx b/ai-management/ai-studio/quickstart.mdx
@@ -25,6 +25,10 @@ This guide covers deploying Tyk AI Studio with a Edge Gateway using Docker Compo
 - At least 4 GB RAM available
 - A Tyk AI License key (contact support@tyk.io or your account manager to obtain)
 
+<Note>
+Running on Podman, containerd, or another container runtime? See [Container Runtimes](/deployment-and-operations/container-runtimes).
+</Note>
+
 ## Generate Secrets
 
 Before starting, generate the required secret keys. These will be used in the configuration files to secure communication and encrypt data:
diff --git a/deployment-and-operations/container-runtimes.mdx b/deployment-and-operations/container-runtimes.mdx
@@ -0,0 +1,137 @@
+---
+title: "Container Runtimes"
+description: "Tyk runs as OCI-compatible containers and works with Docker, containerd, CRI-O, and Podman. Learn which runtimes are supported and how to configure each for local and Kubernetes deployments."
+sidebarTitle: "Container Runtimes"
+keywords: ["container runtime", "docker", "podman", "containerd", "CRI-O", "RHEL 8", "kubernetes", "OCI", "helm", "OpenShift"]
+---
+
+| Edition   | Deployment Type |
+| :------------- | :---------------------- |
+| Enterprise | Self-Managed, Hybrid |
+
+Tyk distributes all components as OCI-compatible container images, which means they run unchanged on any OCI-compliant runtime: Docker Engine, containerd, CRI-O, or Podman. You do not need to rebuild images when moving between runtimes or cloud providers.
+
+Since Kubernetes v1.24 removed the dockershim compatibility layer, managed Kubernetes services (EKS, GKE, AKS, OpenShift) use containerd or CRI-O directly. Docker is no longer required or present by default on Kubernetes nodes. Tyk's Helm-based installations work on all of these out of the box.
+
+## Supported runtimes
+
+The table below shows the default container runtime for each major provider.
+
+| Provider | Default runtime | Notes |
+| :--- | :--- | :--- |
+| **AWS EKS** | containerd | Default since dockershim removal; all Linux and Windows node groups |
+| **Google GKE** | containerd | Default since GKE 1.19; Docker deprecated by 1.24 |
+| **Azure AKS** | containerd | Linux nodes ≥ 1.19; Windows nodes ≥ 1.23 (only option) |
+| **Red Hat OpenShift** | CRI-O | Includes ROSA; uses CRI-O with runc/crun |
+| **Rancher (RKE2/K3s)** | containerd | Default for all cluster types |
+| **VMware Tanzu** | containerd | Default for all cluster types |
+| **DigitalOcean Kubernetes** | containerd | Default since Kubernetes 1.20 |
+| **IBM Cloud Kubernetes Service** | containerd | Default on all managed node pools |
+
+To check the container runtime on your cluster nodes:
+
+```bash
+kubectl get node -o jsonpath='{range .items[*]}{.metadata.name}{"  "}{.status.nodeInfo.containerRuntimeVersion}{"\n"}{end}'
+```
+
+## Running Tyk locally
+
+### Docker
+
+Docker is the fastest way to try Tyk on a laptop or VM. Tyk's quick starts and demo repositories use Docker Compose by default. See the [Docker installation guide](/tyk-self-managed/install/docker) for step-by-step instructions.
+
+### Podman (RHEL 8+)
+
+RHEL 8 ships Podman instead of Docker. Podman is daemonless, rootless-friendly, and uses the same CLI syntax as Docker. Tyk images run on Podman without modification.
+
+**Running Tyk Gateway with Podman (rootless):**
+
+```bash
+podman run -d --name tyk-gateway \
+  -p 8080:8080 \
+  -v $PWD/tyk.standalone.conf:/opt/tyk-gateway/tyk.conf:Z \
+  tykio/tyk-gateway:latest
+```
+
+The `:Z` suffix is required on SELinux-enabled systems (RHEL, Fedora) to relabel the bind-mounted volume so the container can access it.
+
+**Alias Podman as Docker (optional):**
+
+If your scripts call `docker`, you can alias Podman:
+
+```bash
+alias docker=podman
+```
+
+### Docker Compose and Podman Compose
+
+Tyk's demo repositories use standard `compose.yaml` files that work with both Docker Compose and Podman Compose.
+
+```yaml
+# Minimal example: Gateway + Redis
+services:
+  redis:
+    image: redis:7-alpine
+  gateway:
+    image: tykio/tyk-gateway:latest
+    ports: ["8080:8080"]
+    volumes:
+      - ./tyk.standalone.conf:/opt/tyk-gateway/tyk.conf:ro
+    depends_on: [redis]
+```
+
+```bash
+# Docker
+docker compose up -d
+
+# Podman
+podman compose up -d
+```
+
+## Running Tyk in Kubernetes
+
+Use Tyk's Helm charts for production Kubernetes deployments. The charts work across EKS, GKE, AKS, OpenShift (CRI-O), Rancher, and VMware Tanzu without modification.
+
+```bash
+helm repo add tyk-helm https://helm.tyk.io/public/helm/charts/
+helm repo update
+helm install tyk tyk-helm/tyk-stack -n tyk --create-namespace -f values.yaml
+```
+
+For full installation instructions, see the [Tyk Self-Managed Kubernetes guide](/tyk-self-managed/install/kubernetes) or the [Tyk Stack Helm Chart reference](/product-stack/tyk-charts/tyk-stack-chart).
+
+## Building images
+
+Both `docker build` and `podman build` produce OCI-compliant images that run on containerd, CRI-O, or Docker Engine without modification.
+
+```bash
+# Build with Docker
+docker build -t your-registry/tyk-gateway:TAG .
+
+# Build with Podman (RHEL 8+)
+podman build -t your-registry/tyk-gateway:TAG .
+```
+
+OCI images are supported by all major registries (ECR, ACR, Google Artifact Registry, Docker Hub). For production, pin images by digest rather than by tag for reproducible deployments.
+
+## FAQ
+
+<AccordionGroup>
+
+<Accordion title="Do I need to rebuild Tyk images when moving from Docker to containerd or CRI-O?">
+No. Docker-built images are OCI images and run unchanged on containerd and CRI-O.
+</Accordion>
+
+<Accordion title="Does Podman change how Tyk runs?">
+Functionally, no. Images are identical. On RHEL, apply SELinux volume labels (`:Z` / `:z`) to bind mounts and be aware of rootless defaults.
+</Accordion>
+
+<Accordion title="Can I use Docker Compose files with Podman?">
+Yes. Use `podman compose` or point Docker Compose at Podman's Docker-compatible socket. See the [Podman documentation](https://docs.podman.io/en/latest/markdown/podman-compose.1.html) for details.
+</Accordion>
+
+<Accordion title="How do I check which runtime my cluster uses?">
+Run the `kubectl` one-liner in the [Supported runtimes](#supported-runtimes) section above.
+</Accordion>
+
+</AccordionGroup>
diff --git a/docs.json b/docs.json
@@ -156,7 +156,8 @@
                       "tyk-configuration-reference/kv-store",
                       "planning-for-production/monitoring/tyk-components",
                       "tyk-configuration-reference/redis-cluster-sentinel",
-                      "planning-for-production/ensure-high-availability/graceful-shutdown"
+                      "planning-for-production/ensure-high-availability/graceful-shutdown",
+                      "deployment-and-operations/container-runtimes"
                     ]
                   },
                   "deployment-and-operations/tyk-self-managed/tyk-demos-and-pocs/overview"
diff --git a/portal/install/docker.mdx b/portal/install/docker.mdx
@@ -9,12 +9,15 @@ sidebarTitle: "Docker"
 | :------------- | :---------------------- |
 | Enterprise | Self-Managed, Hybrid, Cloud |
 
-
 ## Prerequisites
 
 - [Docker](https://docs.docker.com/get-docker/)
 - [Enterprise Edition License](/portal/overview/intro#getting-access)
 
+<Note>
+Running on Podman, containerd, or another container runtime? See [Container Runtimes](/deployment-and-operations/container-runtimes).
+</Note>
+
 ## Docker
 
 This section explains how to install Tyk Developer Portal in a container using Docker.
diff --git a/portal/install/kubernetes.mdx b/portal/install/kubernetes.mdx
@@ -19,6 +19,10 @@ sidebarTitle: "Kubernetes"
 - [Helm 3+](https://helm.sh/docs/intro/install/)
 - [Enterprise Edition License](/portal/overview/intro#getting-access)
 
+<Note>
+Running on Podman, containerd, or another container runtime? See [Container Runtimes](/deployment-and-operations/container-runtimes).
+</Note>
+
 ## Tyk Stack (New Helm Chart)
 
 There are two ways to install the portal on Kubernetes:
diff --git a/tyk-governance/installation.mdx b/tyk-governance/installation.mdx
@@ -43,6 +43,10 @@ Before beginning the installation and setup process for Tyk Governance, ensure y
 - Outbound HTTPS (port 443) access to the Tyk Governance Hub
 - If API Provider gateways run on different networks, network routes must allow the agent to communicate with those networks
 
+<Note>
+Running on Podman, containerd, or another container runtime? See [Container Runtimes](/deployment-and-operations/container-runtimes).
+</Note>
+
 ## System Architecture
 
 Tyk Governance follows a cloud-hosted service model with customer-deployed agents, creating a secure and flexible architecture that respects your network boundaries while providing centralized governance.
diff --git a/tyk-self-managed/install/docker.mdx b/tyk-self-managed/install/docker.mdx
@@ -8,14 +8,17 @@ sidebarTitle: "Docker"
 | :------------- | :---------------------- |
 | Enterprise | Self-Managed, Hybrid |
 
-
 ## Prerequisites
 
 - [Docker](https://docs.docker.com/get-docker/)
 - [Enterprise Edition License](/apim#licensing)
 
 This guide spins up a full Tyk Self Managed stack; however, if you are interested in learning Tyk Stack, there's an option for [Tyk Demo](/deployment-and-operations/tyk-self-managed/tyk-demos-and-pocs/overview), which is a project that spins up a full Tyk stack that includes pre-populated API definitions of all kinds, with various middleware options, and can also spin up supporting tools such as Prometheus, Keycloak (IDP), etc.
 
+<Note>
+Running on Podman, containerd, or another container runtime? See [Container Runtimes](/deployment-and-operations/container-runtimes).
+</Note>
+
 ## What's included?
 
 This installation will run Tyk Self-Managed on your machine, which contains 5 containers: Tyk Gateway, Tyk Dashboard, Tyk Pump, Redis and MongoDB.
diff --git a/tyk-self-managed/install/kubernetes.mdx b/tyk-self-managed/install/kubernetes.mdx
@@ -18,6 +18,10 @@ sidebarTitle: "Kubernetes"
 - [Helm 3+](https://helm.sh/docs/intro/install/)
 - [Enterprise Edition License](/apim#licensing)
 
+<Note>
+Running on Podman, containerd, or another container runtime? See [Container Runtimes](/deployment-and-operations/container-runtimes).
+</Note>
+
 ## Tyk Stack (PostgreSQL)
 
 The following section provide instructions to install Redis, PostgreSQL, and Tyk stack with default configurations. It is intended for quick start only. For production, you should install and configure Redis and PostgreSQL separately.
