Skip to content

docs: align Kubernetes version requirements across doc versions #814

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Mirage20 merged 2 commits into from
Aug 10, 2026
Merged

docs: align Kubernetes version requirements across doc versions #814

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
210b57a
docs: align Kubernetes version requirements across doc versions
Mirage20 Aug 10, 2026
ab6cb44
docs: state the Kubernetes version as a minimum, not a recommendation
Mirage20 Aug 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/getting-started/try-it-out/on-k3d-locally.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ By the end you'll have a working installation on localhost: a web app you can op
| -------------------------------------------------- | ---------------------- | ------------------------- |
| [Docker](https://docs.docker.com/get-docker/) | v26+ (8 GB RAM, 4 CPU) | Container runtime |
| [k3d](https://k3d.io/stable/#installation) | v5.8+ | Local Kubernetes clusters |
| [kubectl](https://kubernetes.io/docs/tasks/tools/) | v1.33+ | Kubernetes CLI |
| [kubectl](https://kubernetes.io/docs/tasks/tools/) | v1.34+ | Kubernetes CLI |
| [Helm](https://helm.sh/docs/intro/install/) | v3.12+ | Package manager |

Verify everything is installed:
Expand Down
16 changes: 2 additions & 14 deletions docs/getting-started/try-it-out/on-your-environment.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,22 +29,10 @@ By the end you'll have OpenChoreo running on your cluster over HTTPS, reachable

| Tool | Version | Purpose |
| -------------------------------------------------- | ------- | --------------- |
| [kubectl](https://kubernetes.io/docs/tasks/tools/) | v1.33+ | Kubernetes CLI |
| [kubectl](https://kubernetes.io/docs/tasks/tools/) | v1.34+ | Kubernetes CLI |
| [Helm](https://helm.sh/docs/intro/install/) | v3.12+ | Package manager |

Recommended cluster baseline: Kubernetes 1.33+, LoadBalancer support, and a default StorageClass.

:::warning User namespaces required
OpenChoreo's default build workflows run Argo Workflow pods that opt in to Kubernetes [user namespaces](https://kubernetes.io/docs/concepts/workloads/pods/user-namespaces/) by setting `hostUsers: false`. Use **Kubernetes 1.33 or newer**; Kubernetes 1.33 enables user namespaces by default when the node stack supports them.

Every Linux node that can run Workflow Plane build pods must also provide:

- **Linux kernel 6.3 or newer**
- **containerd 2.0 or newer** or **CRI-O 1.25 or newer**
- **runc 1.2 or newer** or **crun 1.9 or newer**

See the [Kubernetes user namespaces guide](https://kubernetes.io/docs/concepts/workloads/pods/user-namespaces/) for details.
:::
Minimum supported Kubernetes version: 1.34+. The cluster also needs LoadBalancer support and a default StorageClass.

Verify everything is installed:

Expand Down
4 changes: 2 additions & 2 deletions docs/platform-engineer-guide/deployment-topology.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Before deploying OpenChoreo to production, ensure your environment meets the fol

| Requirement | Specification |
| ------------------ | ------------------------------------------------------------ |
| Kubernetes Version | 1.32 or later |
| Kubernetes Version | 1.34 or later |
| Node Count | Minimum 3 nodes (for high availability) |
| Node Resources | 4 CPU cores, 8 GB RAM per node (minimum) |
| RBAC | Enabled |
Expand All @@ -33,7 +33,7 @@ Install the following tools on your workstation:

| Tool | Version | Notes |
| ---------------------------------------------------------- | ------- | ------------------------------------------------------------- |
| [kubectl](https://kubernetes.io/docs/tasks/tools/) | 1.32+ | Kubernetes CLI |
| [kubectl](https://kubernetes.io/docs/tasks/tools/) | 1.34+ | Kubernetes CLI |
| [Helm](https://helm.sh/docs/intro/install/) | 3.12+ | Package manager |
| [cert-manager](https://cert-manager.io/docs/installation/) | 1.12+ | Required on all clusters where OpenChoreo planes are deployed |

Expand Down
4 changes: 2 additions & 2 deletions docs/reference/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,8 @@ OpenChoreo focuses on:

### What are the prerequisites for OpenChoreo?

- **Kubernetes Cluster**: Version 1.32 or later
- **kubectl**: v1.32+ configured to access your cluster
- **Kubernetes Cluster**: Version 1.34 or later
- **kubectl**: v1.34+ configured to access your cluster
- **Helm**: Version 3.x (for installation)
- **Container Registry**: For storing application images (required for CI workflows)

Expand Down
4 changes: 4 additions & 0 deletions versioned_docs/version-v1.0.x/getting-started/try-it-out/on-k3d-locally.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,10 @@ By the end you will have all four running in a single k3d cluster.
| [kubectl](https://kubernetes.io/docs/tasks/tools/) | v1.32+ | Kubernetes CLI |
| [Helm](https://helm.sh/docs/intro/install/) | v3.12+ | Package manager |

:::note Kubernetes version in this setup
The local k3d cluster created by the quick start runs Kubernetes 1.32. The default build workflows set `hostUsers: false`, but [Kubernetes user namespaces](https://kubernetes.io/docs/concepts/workloads/pods/user-namespaces/) only take effect on Kubernetes 1.33 or later, so the setting is ignored here. This setup is intended for local development.
:::

Verify everything is installed:

```bash
Expand Down
6 changes: 5 additions & 1 deletion versioned_docs/version-v1.0.x/getting-started/try-it-out/on-your-environment.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,11 @@ OpenChoreo has four planes:
| [kubectl](https://kubernetes.io/docs/tasks/tools/) | v1.32+ | Kubernetes CLI |
| [Helm](https://helm.sh/docs/intro/install/) | v3.12+ | Package manager |

Recommended cluster baseline: Kubernetes 1.32+, LoadBalancer support, and a default StorageClass.
Minimum supported Kubernetes version: 1.32+, or 1.33+ for the default build workflows. The cluster also needs LoadBalancer support and a default StorageClass.

:::note Kubernetes version for the default build workflows
The default build workflows rely on [Kubernetes user namespaces](https://kubernetes.io/docs/concepts/workloads/pods/user-namespaces/) by setting `hostUsers: false`. This takes effect only on Kubernetes 1.33 or later, so use 1.33 or later if you plan to run them. On earlier versions the setting is ignored.
:::

Verify everything is installed:

Expand Down
6 changes: 5 additions & 1 deletion versioned_docs/version-v1.0.x/platform-engineer-guide/deployment-topology.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Before deploying OpenChoreo to production, ensure your environment meets the fol

| Requirement | Specification |
| ------------------ | ------------------------------------------------------------ |
| Kubernetes Version | 1.32 or later |
| Kubernetes Version | 1.32 or later (1.33 or later for the default build workflows) |
| Node Count | Minimum 3 nodes (for high availability) |
| Node Resources | 4 CPU cores, 8 GB RAM per node (minimum) |
| RBAC | Enabled |
Expand All @@ -27,6 +27,10 @@ Before deploying OpenChoreo to production, ensure your environment meets the fol
For development or testing, a single-node cluster with 8 GB RAM and 4 CPU cores is sufficient. Production deployments should use a multi-node cluster with appropriate resource allocation.
:::

:::note Kubernetes version for the default build workflows
The default build workflows rely on [Kubernetes user namespaces](https://kubernetes.io/docs/concepts/workloads/pods/user-namespaces/) by setting `hostUsers: false`. This takes effect only on Kubernetes 1.33 or later, so use 1.33 or later if you plan to run them. On earlier versions the setting is ignored.
:::

### Required Tools

Install the following tools on your workstation:
Expand Down
2 changes: 1 addition & 1 deletion versioned_docs/version-v1.0.x/reference/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ OpenChoreo focuses on:

### What are the prerequisites for OpenChoreo?

- **Kubernetes Cluster**: Version 1.32 or later
- **Kubernetes Cluster**: Version 1.32 or later. Use 1.33 or later if you plan to run the default build workflows, as these rely on [Kubernetes user namespaces](https://kubernetes.io/docs/concepts/workloads/pods/user-namespaces/) that are ignored on earlier versions.
- **kubectl**: v1.32+ configured to access your cluster
- **Helm**: Version 3.x (for installation)
- **Container Registry**: For storing application images (required for CI workflows)
Expand Down
4 changes: 4 additions & 0 deletions versioned_docs/version-v1.1.x/getting-started/try-it-out/on-k3d-locally.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,10 @@ By the end you will have all four running in a single k3d cluster.
| [kubectl](https://kubernetes.io/docs/tasks/tools/) | v1.32+ | Kubernetes CLI |
| [Helm](https://helm.sh/docs/intro/install/) | v3.12+ | Package manager |

:::note Kubernetes version in this setup
The local k3d cluster created by the quick start runs Kubernetes 1.32. The default build workflows set `hostUsers: false`, but [Kubernetes user namespaces](https://kubernetes.io/docs/concepts/workloads/pods/user-namespaces/) only take effect on Kubernetes 1.33 or later, so the setting is ignored here. This setup is intended for local development.
:::

Verify everything is installed:

```bash
Expand Down
6 changes: 5 additions & 1 deletion versioned_docs/version-v1.1.x/getting-started/try-it-out/on-your-environment.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,11 @@ OpenChoreo has four planes:
| [kubectl](https://kubernetes.io/docs/tasks/tools/) | v1.32+ | Kubernetes CLI |
| [Helm](https://helm.sh/docs/intro/install/) | v3.12+ | Package manager |

Recommended cluster baseline: Kubernetes 1.32+, LoadBalancer support, and a default StorageClass.
Minimum supported Kubernetes version: 1.32+, or 1.33+ for the default build workflows. The cluster also needs LoadBalancer support and a default StorageClass.

:::note Kubernetes version for the default build workflows
The default build workflows rely on [Kubernetes user namespaces](https://kubernetes.io/docs/concepts/workloads/pods/user-namespaces/) by setting `hostUsers: false`. This takes effect only on Kubernetes 1.33 or later, so use 1.33 or later if you plan to run them. On earlier versions the setting is ignored.
:::

Verify everything is installed:

Expand Down
6 changes: 5 additions & 1 deletion versioned_docs/version-v1.1.x/platform-engineer-guide/deployment-topology.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Before deploying OpenChoreo to production, ensure your environment meets the fol

| Requirement | Specification |
| ------------------ | ------------------------------------------------------------ |
| Kubernetes Version | 1.32 or later |
| Kubernetes Version | 1.32 or later (1.33 or later for the default build workflows) |
| Node Count | Minimum 3 nodes (for high availability) |
| Node Resources | 4 CPU cores, 8 GB RAM per node (minimum) |
| RBAC | Enabled |
Expand All @@ -27,6 +27,10 @@ Before deploying OpenChoreo to production, ensure your environment meets the fol
For development or testing, a single-node cluster with 8 GB RAM and 4 CPU cores is sufficient. Production deployments should use a multi-node cluster with appropriate resource allocation.
:::

:::note Kubernetes version for the default build workflows
The default build workflows rely on [Kubernetes user namespaces](https://kubernetes.io/docs/concepts/workloads/pods/user-namespaces/) by setting `hostUsers: false`. This takes effect only on Kubernetes 1.33 or later, so use 1.33 or later if you plan to run them. On earlier versions the setting is ignored.
:::

### Required Tools

Install the following tools on your workstation:
Expand Down
2 changes: 1 addition & 1 deletion versioned_docs/version-v1.1.x/reference/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ OpenChoreo focuses on:

### What are the prerequisites for OpenChoreo?

- **Kubernetes Cluster**: Version 1.32 or later
- **Kubernetes Cluster**: Version 1.32 or later. Use 1.33 or later if you plan to run the default build workflows, as these rely on [Kubernetes user namespaces](https://kubernetes.io/docs/concepts/workloads/pods/user-namespaces/) that are ignored on earlier versions.
- **kubectl**: v1.32+ configured to access your cluster
- **Helm**: Version 3.x (for installation)
- **Container Registry**: For storing application images (required for CI workflows)
Expand Down
2 changes: 1 addition & 1 deletion versioned_docs/version-v1.2.x/getting-started/try-it-out/on-k3d-locally.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ By the end you'll have a working installation on localhost: a web app you can op
| -------------------------------------------------- | ---------------------- | ------------------------- |
| [Docker](https://docs.docker.com/get-docker/) | v26+ (8 GB RAM, 4 CPU) | Container runtime |
| [k3d](https://k3d.io/stable/#installation) | v5.8+ | Local Kubernetes clusters |
| [kubectl](https://kubernetes.io/docs/tasks/tools/) | v1.33+ | Kubernetes CLI |
| [kubectl](https://kubernetes.io/docs/tasks/tools/) | v1.34+ | Kubernetes CLI |
| [Helm](https://helm.sh/docs/intro/install/) | v3.12+ | Package manager |

Verify everything is installed:
Expand Down
16 changes: 2 additions & 14 deletions versioned_docs/version-v1.2.x/getting-started/try-it-out/on-your-environment.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,22 +29,10 @@ By the end you'll have OpenChoreo running on your cluster over HTTPS, reachable

| Tool | Version | Purpose |
| -------------------------------------------------- | ------- | --------------- |
| [kubectl](https://kubernetes.io/docs/tasks/tools/) | v1.33+ | Kubernetes CLI |
| [kubectl](https://kubernetes.io/docs/tasks/tools/) | v1.34+ | Kubernetes CLI |
| [Helm](https://helm.sh/docs/intro/install/) | v3.12+ | Package manager |

Recommended cluster baseline: Kubernetes 1.33+, LoadBalancer support, and a default StorageClass.

:::warning User namespaces required
OpenChoreo's default build workflows run Argo Workflow pods that opt in to Kubernetes [user namespaces](https://kubernetes.io/docs/concepts/workloads/pods/user-namespaces/) by setting `hostUsers: false`. Use **Kubernetes 1.33 or newer**; Kubernetes 1.33 enables user namespaces by default when the node stack supports them.

Every Linux node that can run Workflow Plane build pods must also provide:

- **Linux kernel 6.3 or newer**
- **containerd 2.0 or newer** or **CRI-O 1.25 or newer**
- **runc 1.2 or newer** or **crun 1.9 or newer**

See the [Kubernetes user namespaces guide](https://kubernetes.io/docs/concepts/workloads/pods/user-namespaces/) for details.
:::
Minimum supported Kubernetes version: 1.34+. The cluster also needs LoadBalancer support and a default StorageClass.

Verify everything is installed:

Expand Down
4 changes: 2 additions & 2 deletions versioned_docs/version-v1.2.x/platform-engineer-guide/deployment-topology.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Before deploying OpenChoreo to production, ensure your environment meets the fol

| Requirement | Specification |
| ------------------ | ------------------------------------------------------------ |
| Kubernetes Version | 1.32 or later |
| Kubernetes Version | 1.34 or later |
| Node Count | Minimum 3 nodes (for high availability) |
| Node Resources | 4 CPU cores, 8 GB RAM per node (minimum) |
| RBAC | Enabled |
Expand All @@ -33,7 +33,7 @@ Install the following tools on your workstation:

| Tool | Version | Notes |
| ---------------------------------------------------------- | ------- | ------------------------------------------------------------- |
| [kubectl](https://kubernetes.io/docs/tasks/tools/) | 1.32+ | Kubernetes CLI |
| [kubectl](https://kubernetes.io/docs/tasks/tools/) | 1.34+ | Kubernetes CLI |
| [Helm](https://helm.sh/docs/intro/install/) | 3.12+ | Package manager |
| [cert-manager](https://cert-manager.io/docs/installation/) | 1.12+ | Required on all clusters where OpenChoreo planes are deployed |

Expand Down
4 changes: 2 additions & 2 deletions versioned_docs/version-v1.2.x/reference/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,8 @@ OpenChoreo focuses on:

### What are the prerequisites for OpenChoreo?

- **Kubernetes Cluster**: Version 1.32 or later
- **kubectl**: v1.32+ configured to access your cluster
- **Kubernetes Cluster**: Version 1.34 or later
- **kubectl**: v1.34+ configured to access your cluster
- **Helm**: Version 3.x (for installation)
- **Container Registry**: For storing application images (required for CI workflows)

Expand Down