From 4bc4815bd75eb336d3cd5f1ff3f82e1c612d6e67 Mon Sep 17 00:00:00 2001 From: Parv Agarwal Date: Sun, 13 Jul 2025 20:11:57 +0530 Subject: [PATCH 01/10] docs: update GKE ambient guide to remove manual ResourceQuota step (Fix istio/istio#56376) Signed-off-by: Parv Agarwal --- .../ambient/install/platform-prerequisites/index.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/content/en/docs/ambient/install/platform-prerequisites/index.md b/content/en/docs/ambient/install/platform-prerequisites/index.md index 9c2c0d721291..6dfd072a9c31 100644 --- a/content/en/docs/ambient/install/platform-prerequisites/index.md +++ b/content/en/docs/ambient/install/platform-prerequisites/index.md @@ -19,10 +19,14 @@ Certain Kubernetes environments require you to set various Istio configuration o #### Namespace restrictions -On GKE, any pods with the [system-node-critical](https://kubernetes.io/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods/) `priorityClassName` can only be installed in namespaces that have a [ResourceQuota](https://kubernetes.io/docs/concepts/policy/resource-quotas/) defined. By default in GKE, only `kube-system` has a defined ResourceQuota for the `node-critical` class. The Istio CNI node agent and `ztunnel` both require the `node-critical` class, and so in GKE, both components must either: +On GKE, any pods with the [system-node-critical](https://kubernetes.io/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods/) `priorityClassName` can only be installed in namespaces that have a [ResourceQuota](https://kubernetes.io/docs/concepts/policy/resource-quotas/) defined. By default in GKE, only `kube-system` has a defined ResourceQuota for the `node-critical` class. -- Be installed into `kube-system` (_not_ `istio-system`) -- Be installed into another namespace (such as `istio-system`) in which a ResourceQuota has been manually created, for example: +The Istio CNI node agent and `ztunnel` both require the `node-critical` class. Starting with **Istio 1.26**, the installer (`istioctl install --set profile=ambient`) automatically creates the required ResourceQuota in the `istio-system` namespace. No manual steps are needed. + +--- + +⚠️ **For Istio versions earlier than 1.26:** +You must manually create a ResourceQuota in the namespace (such as `istio-system`), for example: {{< text syntax=yaml >}} apiVersion: v1 From 26baa005e5becfcb100b8335c416b84109965457 Mon Sep 17 00:00:00 2001 From: Parv Agarwal <142515806+parv18050212@users.noreply.github.com> Date: Mon, 14 Jul 2025 08:44:39 +0530 Subject: [PATCH 02/10] Update content/en/docs/ambient/install/platform-prerequisites/index.md Co-authored-by: Craig Box --- .../en/docs/ambient/install/platform-prerequisites/index.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/content/en/docs/ambient/install/platform-prerequisites/index.md b/content/en/docs/ambient/install/platform-prerequisites/index.md index 6dfd072a9c31..5a0ba855d340 100644 --- a/content/en/docs/ambient/install/platform-prerequisites/index.md +++ b/content/en/docs/ambient/install/platform-prerequisites/index.md @@ -21,12 +21,6 @@ Certain Kubernetes environments require you to set various Istio configuration o On GKE, any pods with the [system-node-critical](https://kubernetes.io/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods/) `priorityClassName` can only be installed in namespaces that have a [ResourceQuota](https://kubernetes.io/docs/concepts/policy/resource-quotas/) defined. By default in GKE, only `kube-system` has a defined ResourceQuota for the `node-critical` class. -The Istio CNI node agent and `ztunnel` both require the `node-critical` class. Starting with **Istio 1.26**, the installer (`istioctl install --set profile=ambient`) automatically creates the required ResourceQuota in the `istio-system` namespace. No manual steps are needed. - ---- - -⚠️ **For Istio versions earlier than 1.26:** -You must manually create a ResourceQuota in the namespace (such as `istio-system`), for example: {{< text syntax=yaml >}} apiVersion: v1 From bd30dacc7361336f2e468f609a5b9953ca135c57 Mon Sep 17 00:00:00 2001 From: Parv Agarwal <142515806+parv18050212@users.noreply.github.com> Date: Mon, 14 Jul 2025 08:44:52 +0530 Subject: [PATCH 03/10] Update content/en/docs/ambient/install/platform-prerequisites/index.md Co-authored-by: Craig Box --- .../en/docs/ambient/install/platform-prerequisites/index.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/content/en/docs/ambient/install/platform-prerequisites/index.md b/content/en/docs/ambient/install/platform-prerequisites/index.md index 5a0ba855d340..d4d7e42af044 100644 --- a/content/en/docs/ambient/install/platform-prerequisites/index.md +++ b/content/en/docs/ambient/install/platform-prerequisites/index.md @@ -19,7 +19,11 @@ Certain Kubernetes environments require you to set various Istio configuration o #### Namespace restrictions -On GKE, any pods with the [system-node-critical](https://kubernetes.io/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods/) `priorityClassName` can only be installed in namespaces that have a [ResourceQuota](https://kubernetes.io/docs/concepts/policy/resource-quotas/) defined. By default in GKE, only `kube-system` has a defined ResourceQuota for the `node-critical` class. +On GKE, any pods with the [system-node-critical](https://kubernetes.io/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods/) `priorityClassName` can only be installed in namespaces that have a [ResourceQuota](https://kubernetes.io/docs/concepts/policy/resource-quotas/) defined. The Istio CNI node agent and `ztunnel` both require the `node-critical` class. + +By default in GKE, only `kube-system` has a defined ResourceQuota for the `node-critical` class. Installing Istio with the `ambient` profile creates a ResourceQuota in the `istio-system` namespace. + +To install Istio in any other namespace, you must manually create a ResourceQuota: {{< text syntax=yaml >}} From 65bd2df33cadf8af0b0df6e1a1bb54b85d6b6bed Mon Sep 17 00:00:00 2001 From: Parv Agarwal <142515806+parv18050212@users.noreply.github.com> Date: Mon, 14 Jul 2025 15:28:48 +0530 Subject: [PATCH 04/10] Update content/en/docs/ambient/install/platform-prerequisites/index.md Co-authored-by: Craig Box --- content/en/docs/ambient/install/platform-prerequisites/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/en/docs/ambient/install/platform-prerequisites/index.md b/content/en/docs/ambient/install/platform-prerequisites/index.md index d4d7e42af044..686fd23e3b88 100644 --- a/content/en/docs/ambient/install/platform-prerequisites/index.md +++ b/content/en/docs/ambient/install/platform-prerequisites/index.md @@ -25,7 +25,6 @@ By default in GKE, only `kube-system` has a defined ResourceQuota for the `node- To install Istio in any other namespace, you must manually create a ResourceQuota: - {{< text syntax=yaml >}} apiVersion: v1 kind: ResourceQuota From 911fa089bda87e962519bf7cdacdc3dd0350cf92 Mon Sep 17 00:00:00 2001 From: Parv Agarwal <142515806+parv18050212@users.noreply.github.com> Date: Mon, 14 Jul 2025 15:52:42 +0530 Subject: [PATCH 05/10] docs: move GKE Namespace restrictions below Platform profile --- .../install/platform-prerequisites/index.md | 51 ++++++++++--------- 1 file changed, 26 insertions(+), 25 deletions(-) diff --git a/content/en/docs/ambient/install/platform-prerequisites/index.md b/content/en/docs/ambient/install/platform-prerequisites/index.md index 686fd23e3b88..2afd25ab8806 100644 --- a/content/en/docs/ambient/install/platform-prerequisites/index.md +++ b/content/en/docs/ambient/install/platform-prerequisites/index.md @@ -17,31 +17,6 @@ Certain Kubernetes environments require you to set various Istio configuration o ### Google Kubernetes Engine (GKE) -#### Namespace restrictions - -On GKE, any pods with the [system-node-critical](https://kubernetes.io/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods/) `priorityClassName` can only be installed in namespaces that have a [ResourceQuota](https://kubernetes.io/docs/concepts/policy/resource-quotas/) defined. The Istio CNI node agent and `ztunnel` both require the `node-critical` class. - -By default in GKE, only `kube-system` has a defined ResourceQuota for the `node-critical` class. Installing Istio with the `ambient` profile creates a ResourceQuota in the `istio-system` namespace. - -To install Istio in any other namespace, you must manually create a ResourceQuota: - -{{< text syntax=yaml >}} -apiVersion: v1 -kind: ResourceQuota -metadata: - name: gcp-critical-pods - namespace: istio-system -spec: - hard: - pods: 1000 - scopeSelector: - matchExpressions: - - operator: In - scopeName: PriorityClass - values: - - system-node-critical -{{< /text >}} - #### Platform profile When using GKE you must append the correct `platform` value to your installation commands, as GKE uses nonstandard locations for CNI binaries which requires Helm overrides. @@ -66,6 +41,32 @@ When using GKE you must append the correct `platform` value to your installation {{< /tabset >}} +#### Namespace restrictions + +On GKE, any pods with the [system-node-critical](https://kubernetes.io/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods/) `priorityClassName` can only be installed in namespaces that have a [ResourceQuota](https://kubernetes.io/docs/concepts/policy/resource-quotas/) defined. By default in GKE, only `kube-system` has a defined ResourceQuota for the `node-critical` class. + +The Istio CNI node agent and `ztunnel` both require the `node-critical` class. Starting with **Istio 1.26**, the installer (`istioctl install --set profile=ambient`) automatically creates the required ResourceQuota in the `istio-system` namespace. No manual steps are needed. +--- +⚠️ **For Istio versions earlier than 1.26:** +You must manually create a ResourceQuota in the namespace (such as `istio-system`), for example: + +{{< text syntax=yaml >}} +apiVersion: v1 +kind: ResourceQuota +metadata: + name: gcp-critical-pods + namespace: istio-system +spec: + hard: + pods: 1000 + scopeSelector: + matchExpressions: + - operator: In + scopeName: PriorityClass + values: + - system-node-critical +{{< /text >}} + ### Amazon Elastic Kubernetes Service (EKS) If you are using EKS: From 12cedb24bf0a7071d7aa872afe2e5bb9dc8483c9 Mon Sep 17 00:00:00 2001 From: Parv Agarwal <142515806+parv18050212@users.noreply.github.com> Date: Mon, 14 Jul 2025 16:46:05 +0530 Subject: [PATCH 06/10] final updated --- .../install/platform-prerequisites/index.md | 33 ++++++++----------- 1 file changed, 14 insertions(+), 19 deletions(-) diff --git a/content/en/docs/ambient/install/platform-prerequisites/index.md b/content/en/docs/ambient/install/platform-prerequisites/index.md index 2afd25ab8806..730f59881d0b 100644 --- a/content/en/docs/ambient/install/platform-prerequisites/index.md +++ b/content/en/docs/ambient/install/platform-prerequisites/index.md @@ -21,36 +21,31 @@ Certain Kubernetes environments require you to set various Istio configuration o When using GKE you must append the correct `platform` value to your installation commands, as GKE uses nonstandard locations for CNI binaries which requires Helm overrides. -{{< tabset category-name="install-method" >}} - -{{< tab name="Helm" category-value="helm" >}} - - {{< text syntax=bash >}} - $ helm install istio-cni istio/cni -n istio-system --set profile=ambient --set global.platform=gke --wait - {{< /text >}} +{{< tabset category="Ambient install" >}} +{{< tab name="istioctl ambient" >}} +```bash +istioctl install --set profile=ambient --set values.cni.platform=gke +``` {{< /tab >}} -{{< tab name="istioctl" category-value="istioctl" >}} - - {{< text syntax=bash >}} - $ istioctl install --set profile=ambient --set values.global.platform=gke - {{< /text >}} - +{{< tab name="Helm ambient" >}} +```bash +helm install istio-cni charts/cni --set profile=ambient --set values.cni.platform=gke +``` {{< /tab >}} {{< /tabset >}} #### Namespace restrictions -On GKE, any pods with the [system-node-critical](https://kubernetes.io/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods/) `priorityClassName` can only be installed in namespaces that have a [ResourceQuota](https://kubernetes.io/docs/concepts/policy/resource-quotas/) defined. By default in GKE, only `kube-system` has a defined ResourceQuota for the `node-critical` class. +On GKE, any pods with the [system-node-critical](https://kubernetes.io/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods/) `priorityClassName` can only be installed in namespaces that have a [ResourceQuota](https://kubernetes.io/docs/concepts/policy/resource-quotas/) defined. The Istio CNI node agent and `ztunnel` both require the `node-critical` class. -The Istio CNI node agent and `ztunnel` both require the `node-critical` class. Starting with **Istio 1.26**, the installer (`istioctl install --set profile=ambient`) automatically creates the required ResourceQuota in the `istio-system` namespace. No manual steps are needed. ---- -⚠️ **For Istio versions earlier than 1.26:** -You must manually create a ResourceQuota in the namespace (such as `istio-system`), for example: +By default in GKE, only `kube-system` has a defined ResourceQuota for the `node-critical` class. Installing Istio with the `ambient` profile creates a ResourceQuota in the `istio-system` namespace. + +To install Istio in any other namespace, you must manually create a ResourceQuota: -{{< text syntax=yaml >}} +{{< text syntax="yaml" >}} apiVersion: v1 kind: ResourceQuota metadata: From 7cb276fd38a0b427b33f6e679e07cd2471734ea0 Mon Sep 17 00:00:00 2001 From: Parv Agarwal <142515806+parv18050212@users.noreply.github.com> Date: Mon, 14 Jul 2025 17:15:27 +0530 Subject: [PATCH 07/10] fixed lint error --- .../install/platform-prerequisites/index.md | 211 +++++++----------- 1 file changed, 79 insertions(+), 132 deletions(-) diff --git a/content/en/docs/ambient/install/platform-prerequisites/index.md b/content/en/docs/ambient/install/platform-prerequisites/index.md index 730f59881d0b..0c8fde399b81 100644 --- a/content/en/docs/ambient/install/platform-prerequisites/index.md +++ b/content/en/docs/ambient/install/platform-prerequisites/index.md @@ -21,21 +21,17 @@ Certain Kubernetes environments require you to set various Istio configuration o When using GKE you must append the correct `platform` value to your installation commands, as GKE uses nonstandard locations for CNI binaries which requires Helm overrides. -{{< tabset category="Ambient install" >}} +#### istioctl ambient -{{< tab name="istioctl ambient" >}} ```bash istioctl install --set profile=ambient --set values.cni.platform=gke ``` -{{< /tab >}} -{{< tab name="Helm ambient" >}} +#### Helm ambient + ```bash helm install istio-cni charts/cni --set profile=ambient --set values.cni.platform=gke ``` -{{< /tab >}} - -{{< /tabset >}} #### Namespace restrictions @@ -45,7 +41,7 @@ By default in GKE, only `kube-system` has a defined ResourceQuota for the `node- To install Istio in any other namespace, you must manually create a ResourceQuota: -{{< text syntax="yaml" >}} +```yaml apiVersion: v1 kind: ResourceQuota metadata: @@ -60,7 +56,7 @@ spec: scopeName: PriorityClass values: - system-node-critical -{{< /text >}} +``` ### Amazon Elastic Kubernetes Service (EKS) @@ -76,21 +72,21 @@ There is an [open issue on the VPC CNI component](https://github.com/aws/amazon- You can check if you have pod ENI trunking enabled by running the following command: -{{< text syntax=bash >}} -$ kubectl set env daemonset aws-node -n kube-system --list | grep ENABLE_POD_ENI -{{< /text >}} +```bash +kubectl set env daemonset aws-node -n kube-system --list | grep ENABLE_POD_ENI +``` You can check if you have any pod-attached security groups in your cluster by running the following command: -{{< text syntax=bash >}} -$ kubectl get securitygrouppolicies.vpcresources.k8s.aws -{{< /text >}} +```bash +kubectl get securitygrouppolicies.vpcresources.k8s.aws +``` You can set `POD_SECURITY_GROUP_ENFORCING_MODE=standard` by running the following command, and recycling affected pods: -{{< text syntax=bash >}} -$ kubectl set env daemonset aws-node -n kube-system POD_SECURITY_GROUP_ENFORCING_MODE=standard -{{< /text >}} +```bash +kubectl set env daemonset aws-node -n kube-system POD_SECURITY_GROUP_ENFORCING_MODE=standard +``` ### k3d @@ -98,102 +94,69 @@ When using [k3d](https://k3d.io/) with the default Flannel CNI, you must append 1. Create a cluster with Traefik disabled so it doesn't conflict with Istio's ingress gateways: - {{< text bash >}} - $ k3d cluster create --api-port 6550 -p '9080:80@loadbalancer' -p '9443:443@loadbalancer' --agents 2 --k3s-arg '--disable=traefik@server:*' - {{< /text >}} - -1. Set `global.platform=k3d` when installing Istio charts. For example: - - {{< tabset category-name="install-method" >}} + ```bash + k3d cluster create --api-port 6550 -p '9080:80@loadbalancer' -p '9443:443@loadbalancer' --agents 2 --k3s-arg '--disable=traefik@server:*' + ``` - {{< tab name="Helm" category-value="helm" >}} +2. Set `global.platform=k3d` when installing Istio charts. For example: - {{< text syntax=bash >}} - $ helm install istio-cni istio/cni -n istio-system --set profile=ambient --set global.platform=k3d --wait - {{< /text >}} + #### Helm - {{< /tab >}} + ```bash + helm install istio-cni istio/cni -n istio-system --set profile=ambient --set global.platform=k3d --wait + ``` - {{< tab name="istioctl" category-value="istioctl" >}} + #### istioctl - {{< text syntax=bash >}} - $ istioctl install --set profile=ambient --set values.global.platform=k3d - {{< /text >}} - - {{< /tab >}} - - {{< /tabset >}} + ```bash + istioctl install --set profile=ambient --set values.global.platform=k3d + ``` ### K3s When using [K3s](https://k3s.io/) and one of its bundled CNIs, you must append the correct `platform` value to your installation commands, as K3s uses nonstandard locations for CNI configuration and binaries which requires some Helm overrides. For the default K3s paths, Istio provides built-in overrides based on the `global.platform` value. -{{< tabset category-name="install-method" >}} - -{{< tab name="Helm" category-value="helm" >}} +#### Helm - {{< text syntax=bash >}} - $ helm install istio-cni istio/cni -n istio-system --set profile=ambient --set global.platform=k3s --wait - {{< /text >}} - -{{< /tab >}} - -{{< tab name="istioctl" category-value="istioctl" >}} - - {{< text syntax=bash >}} - $ istioctl install --set profile=ambient --set values.global.platform=k3s - {{< /text >}} +```bash +helm install istio-cni istio/cni -n istio-system --set profile=ambient --set global.platform=k3s --wait +``` -{{< /tab >}} +#### istioctl -{{< /tabset >}} +```bash +istioctl install --set profile=ambient --set values.global.platform=k3s +``` However, these locations may be overridden in K3s, [according to K3s documentation](https://docs.k3s.io/cli/server#k3s-server-cli-help). If you are using K3s with a custom, non-bundled CNI, you must manually specify the correct paths for those CNIs, e.g. `/etc/cni/net.d` - [see the K3s docs for details](https://docs.k3s.io/networking/basic-network-options#custom-cni). For example: -{{< tabset category-name="install-method" >}} +#### Helm -{{< tab name="Helm" category-value="helm" >}} - - {{< text syntax=bash >}} - $ helm install istio-cni istio/cni -n istio-system --set profile=ambient --wait --set cniConfDir=/var/lib/rancher/k3s/agent/etc/cni/net.d --set cniBinDir=/var/lib/rancher/k3s/data/current/bin/ - {{< /text >}} - -{{< /tab >}} - -{{< tab name="istioctl" category-value="istioctl" >}} - - {{< text syntax=bash >}} - $ istioctl install --set profile=ambient --set values.cni.cniConfDir=/var/lib/rancher/k3s/agent/etc/cni/net.d --set values.cni.cniBinDir=/var/lib/rancher/k3s/data/current/bin/ - {{< /text >}} +```bash +helm install istio-cni istio/cni -n istio-system --set profile=ambient --wait --set cniConfDir=/var/lib/rancher/k3s/agent/etc/cni/net.d --set cniBinDir=/var/lib/rancher/k3s/data/current/bin/ +``` -{{< /tab >}} +#### istioctl -{{< /tabset >}} +```bash +istioctl install --set profile=ambient --set values.cni.cniConfDir=/var/lib/rancher/k3s/agent/etc/cni/net.d --set values.cni.cniBinDir=/var/lib/rancher/k3s/data/current/bin/ +``` ### MicroK8s If you are installing Istio on [MicroK8s](https://microk8s.io/), you must append the correct `platform` value to your installation commands, as MicroK8s [uses non-standard locations for CNI configuration and binaries](https://microk8s.io/docs/change-cidr). For example: -{{< tabset category-name="install-method" >}} - -{{< tab name="Helm" category-value="helm" >}} - - {{< text syntax=bash >}} - $ helm install istio-cni istio/cni -n istio-system --set profile=ambient --set global.platform=microk8s --wait - - {{< /text >}} +#### Helm -{{< /tab >}} - -{{< tab name="istioctl" category-value="istioctl" >}} - - {{< text syntax=bash >}} - $ istioctl install --set profile=ambient --set values.global.platform=microk8s - {{< /text >}} +```bash +helm install istio-cni istio/cni -n istio-system --set profile=ambient --set global.platform=microk8s --wait +``` -{{< /tab >}} +#### istioctl -{{< /tabset >}} +```bash +istioctl install --set profile=ambient --set values.global.platform=microk8s +``` ### minikube @@ -201,74 +164,58 @@ If you are using [minikube](https://kubernetes.io/docs/tasks/tools/install-minik you must append the correct `platform` value to your installation commands, as minikube with Docker uses a nonstandard bind mount path for containers. For example: -{{< tabset category-name="install-method" >}} - -{{< tab name="Helm" category-value="helm" >}} - - {{< text syntax=bash >}} - $ helm install istio-cni istio/cni -n istio-system --set profile=ambient --set global.platform=minikube --wait" - {{< /text >}} - -{{< /tab >}} - -{{< tab name="istioctl" category-value="istioctl" >}} +#### Helm - {{< text syntax=bash >}} - $ istioctl install --set profile=ambient --set values.global.platform=minikube" - {{< /text >}} +```bash +helm install istio-cni istio/cni -n istio-system --set profile=ambient --set global.platform=minikube --wait +``` -{{< /tab >}} +#### istioctl -{{< /tabset >}} +```bash +istioctl install --set profile=ambient --set values.global.platform=minikube +``` ### Red Hat OpenShift OpenShift requires that `ztunnel` and `istio-cni` components are installed in the `kube-system` namespace, and that you set `global.platform=openshift` for all charts. -{{< tabset category-name="install-method" >}} - -{{< tab name="Helm" category-value="helm" >}} - - You must `--set global.platform=openshift` for **every** chart you install, for example with the `istiod` chart: - - {{< text syntax=bash >}} - $ helm install istiod istio/istiod -n istio-system --set profile=ambient --set global.platform=openshift --wait - {{< /text >}} +#### Helm - In addition, you must install `istio-cni` and `ztunnel` in the `kube-system` namespace, for example: +You must `--set global.platform=openshift` for **every** chart you install, for example with the `istiod` chart: - {{< text syntax=bash >}} - $ helm install istio-cni istio/cni -n kube-system --set profile=ambient --set global.platform=openshift --wait - $ helm install ztunnel istio/ztunnel -n kube-system --set profile=ambient --set global.platform=openshift --wait - {{< /text >}} - -{{< /tab >}} +```bash +helm install istiod istio/istiod -n istio-system --set profile=ambient --set global.platform=openshift --wait +``` -{{< tab name="istioctl" category-value="istioctl" >}} +In addition, you must install `istio-cni` and `ztunnel` in the `kube-system` namespace, for example: - {{< text syntax=bash >}} - $ istioctl install --set profile=openshift-ambient --skip-confirmation - {{< /text >}} +```bash +helm install istio-cni istio/cni -n kube-system --set profile=ambient --set global.platform=openshift --wait +helm install ztunnel istio/ztunnel -n kube-system --set profile=ambient --set global.platform=openshift --wait +``` -{{< /tab >}} +#### istioctl -{{< /tabset >}} +```bash +istioctl install --set profile=openshift-ambient --skip-confirmation +``` ## CNI plugins -The following configurations apply to all platforms, when certain {{< gloss "CNI" >}}CNI plugins{{< /gloss >}} are used: +The following configurations apply to all platforms, when certain CNI plugins are used: ### Cilium 1. Cilium currently defaults to proactively deleting other CNI plugins and their config, and must be configured with -`cni.exclusive = false` to properly support chaining. See [the Cilium documentation](https://docs.cilium.io/en/stable/helm-reference/) for more details. -1. Cilium's BPF masquerading is currently disabled by default, and has issues with Istio's use of link-local IPs for Kubernetes health checking. Enabling BPF masquerading via `bpf.masquerade=true` is not currently supported, and results in non-functional pod health checks in Istio ambient. Cilium's default iptables masquerading implementation should continue to function correctly. -1. Due to how Cilium manages node identity and internally allow-lists node-level health probes to pods, -applying any default-DENY `NetworkPolicy` in a Cilium CNI install underlying Istio in ambient mode will cause `kubelet` health probes (which are by-default silently exempted from all policy enforcement by Cilium) to be blocked. This is because Istio uses a link-local SNAT address for kubelet health probes, which Cilium is not aware of, and Cilium does not have an option to exempt link-local addresses from policy enforcement. + `cni.exclusive = false` to properly support chaining. See [the Cilium documentation](https://docs.cilium.io/en/stable/helm-reference/) for more details. +2. Cilium's BPF masquerading is currently disabled by default, and has issues with Istio's use of link-local IPs for Kubernetes health checking. Enabling BPF masquerading via `bpf.masquerade=true` is not currently supported, and results in non-functional pod health checks in Istio ambient. Cilium's default iptables masquerading implementation should continue to function correctly. +3. Due to how Cilium manages node identity and internally allow-lists node-level health probes to pods, + applying any default-DENY `NetworkPolicy` in a Cilium CNI install underlying Istio in ambient mode will cause `kubelet` health probes (which are by-default silently exempted from all policy enforcement by Cilium) to be blocked. This is because Istio uses a link-local SNAT address for kubelet health probes, which Cilium is not aware of, and Cilium does not have an option to exempt link-local addresses from policy enforcement. This can be resolved by applying the following `CiliumClusterWideNetworkPolicy`: - {{< text syntax=yaml >}} + ```yaml apiVersion: "cilium.io/v2" kind: CiliumClusterwideNetworkPolicy metadata: @@ -282,7 +229,7 @@ applying any default-DENY `NetworkPolicy` in a Cilium CNI install underlying Ist ingress: - fromCIDR: - "169.254.7.127/32" - {{< /text >}} + ``` This policy override is *not* required unless you already have other default-deny `NetworkPolicies` or `CiliumNetworkPolicies` applied in your cluster. From 8dd2737ea6157b9031141b30062b2fd5dd444d1c Mon Sep 17 00:00:00 2001 From: Parv Agarwal <142515806+parv18050212@users.noreply.github.com> Date: Wed, 16 Jul 2025 16:22:29 +0530 Subject: [PATCH 08/10] docs: corrected lint issues --- .../install/platform-prerequisites/index.md | 203 +++++++++++------- 1 file changed, 127 insertions(+), 76 deletions(-) diff --git a/content/en/docs/ambient/install/platform-prerequisites/index.md b/content/en/docs/ambient/install/platform-prerequisites/index.md index 0c8fde399b81..de611b9821fe 100644 --- a/content/en/docs/ambient/install/platform-prerequisites/index.md +++ b/content/en/docs/ambient/install/platform-prerequisites/index.md @@ -41,7 +41,7 @@ By default in GKE, only `kube-system` has a defined ResourceQuota for the `node- To install Istio in any other namespace, you must manually create a ResourceQuota: -```yaml +{{< text syntax=yaml >}} apiVersion: v1 kind: ResourceQuota metadata: @@ -56,7 +56,7 @@ spec: scopeName: PriorityClass values: - system-node-critical -``` +{{< /text >}} ### Amazon Elastic Kubernetes Service (EKS) @@ -72,21 +72,21 @@ There is an [open issue on the VPC CNI component](https://github.com/aws/amazon- You can check if you have pod ENI trunking enabled by running the following command: -```bash -kubectl set env daemonset aws-node -n kube-system --list | grep ENABLE_POD_ENI -``` +{{< text syntax=bash >}} +$ kubectl set env daemonset aws-node -n kube-system --list | grep ENABLE_POD_ENI +{{< /text >}} You can check if you have any pod-attached security groups in your cluster by running the following command: -```bash -kubectl get securitygrouppolicies.vpcresources.k8s.aws -``` +{{< text syntax=bash >}} +$ kubectl get securitygrouppolicies.vpcresources.k8s.aws +{{< /text >}} You can set `POD_SECURITY_GROUP_ENFORCING_MODE=standard` by running the following command, and recycling affected pods: -```bash -kubectl set env daemonset aws-node -n kube-system POD_SECURITY_GROUP_ENFORCING_MODE=standard -``` +{{< text syntax=bash >}} +$ kubectl set env daemonset aws-node -n kube-system POD_SECURITY_GROUP_ENFORCING_MODE=standard +{{< /text >}} ### k3d @@ -94,69 +94,102 @@ When using [k3d](https://k3d.io/) with the default Flannel CNI, you must append 1. Create a cluster with Traefik disabled so it doesn't conflict with Istio's ingress gateways: - ```bash - k3d cluster create --api-port 6550 -p '9080:80@loadbalancer' -p '9443:443@loadbalancer' --agents 2 --k3s-arg '--disable=traefik@server:*' - ``` + {{< text bash >}} + $ k3d cluster create --api-port 6550 -p '9080:80@loadbalancer' -p '9443:443@loadbalancer' --agents 2 --k3s-arg '--disable=traefik@server:*' + {{< /text >}} -2. Set `global.platform=k3d` when installing Istio charts. For example: +1. Set `global.platform=k3d` when installing Istio charts. For example: - #### Helm + {{< tabset category-name="install-method" >}} - ```bash - helm install istio-cni istio/cni -n istio-system --set profile=ambient --set global.platform=k3d --wait - ``` + {{< tab name="Helm" category-value="helm" >}} - #### istioctl + {{< text syntax=bash >}} + $ helm install istio-cni istio/cni -n istio-system --set profile=ambient --set global.platform=k3d --wait + {{< /text >}} - ```bash - istioctl install --set profile=ambient --set values.global.platform=k3d - ``` + {{< /tab >}} + + {{< tab name="istioctl" category-value="istioctl" >}} + + {{< text syntax=bash >}} + $ istioctl install --set profile=ambient --set values.global.platform=k3d + {{< /text >}} + + {{< /tab >}} + + {{< /tabset >}} ### K3s When using [K3s](https://k3s.io/) and one of its bundled CNIs, you must append the correct `platform` value to your installation commands, as K3s uses nonstandard locations for CNI configuration and binaries which requires some Helm overrides. For the default K3s paths, Istio provides built-in overrides based on the `global.platform` value. -#### Helm +{{< tabset category-name="install-method" >}} -```bash -helm install istio-cni istio/cni -n istio-system --set profile=ambient --set global.platform=k3s --wait -``` +{{< tab name="Helm" category-value="helm" >}} -#### istioctl + {{< text syntax=bash >}} + $ helm install istio-cni istio/cni -n istio-system --set profile=ambient --set global.platform=k3s --wait + {{< /text >}} -```bash -istioctl install --set profile=ambient --set values.global.platform=k3s -``` +{{< /tab >}} + +{{< tab name="istioctl" category-value="istioctl" >}} + + {{< text syntax=bash >}} + $ istioctl install --set profile=ambient --set values.global.platform=k3s + {{< /text >}} + +{{< /tab >}} + +{{< /tabset >}} However, these locations may be overridden in K3s, [according to K3s documentation](https://docs.k3s.io/cli/server#k3s-server-cli-help). If you are using K3s with a custom, non-bundled CNI, you must manually specify the correct paths for those CNIs, e.g. `/etc/cni/net.d` - [see the K3s docs for details](https://docs.k3s.io/networking/basic-network-options#custom-cni). For example: -#### Helm +{{< tabset category-name="install-method" >}} -```bash -helm install istio-cni istio/cni -n istio-system --set profile=ambient --wait --set cniConfDir=/var/lib/rancher/k3s/agent/etc/cni/net.d --set cniBinDir=/var/lib/rancher/k3s/data/current/bin/ -``` +{{< tab name="Helm" category-value="helm" >}} -#### istioctl + {{< text syntax=bash >}} + $ helm install istio-cni istio/cni -n istio-system --set profile=ambient --wait --set cniConfDir=/var/lib/rancher/k3s/agent/etc/cni/net.d --set cniBinDir=/var/lib/rancher/k3s/data/current/bin/ + {{< /text >}} -```bash -istioctl install --set profile=ambient --set values.cni.cniConfDir=/var/lib/rancher/k3s/agent/etc/cni/net.d --set values.cni.cniBinDir=/var/lib/rancher/k3s/data/current/bin/ -``` +{{< /tab >}} + +{{< tab name="istioctl" category-value="istioctl" >}} + + {{< text syntax=bash >}} + $ istioctl install --set profile=ambient --set values.cni.cniConfDir=/var/lib/rancher/k3s/agent/etc/cni/net.d --set values.cni.cniBinDir=/var/lib/rancher/k3s/data/current/bin/ + {{< /text >}} + +{{< /tab >}} + +{{< /tabset >}} ### MicroK8s If you are installing Istio on [MicroK8s](https://microk8s.io/), you must append the correct `platform` value to your installation commands, as MicroK8s [uses non-standard locations for CNI configuration and binaries](https://microk8s.io/docs/change-cidr). For example: -#### Helm +{{< tabset category-name="install-method" >}} -```bash -helm install istio-cni istio/cni -n istio-system --set profile=ambient --set global.platform=microk8s --wait -``` +{{< tab name="Helm" category-value="helm" >}} -#### istioctl + {{< text syntax=bash >}} + $ helm install istio-cni istio/cni -n istio-system --set profile=ambient --set global.platform=microk8s --wait -```bash -istioctl install --set profile=ambient --set values.global.platform=microk8s -``` + {{< /text >}} + +{{< /tab >}} + +{{< tab name="istioctl" category-value="istioctl" >}} + + {{< text syntax=bash >}} + $ istioctl install --set profile=ambient --set values.global.platform=microk8s + {{< /text >}} + +{{< /tab >}} + +{{< /tabset >}} ### minikube @@ -164,58 +197,76 @@ If you are using [minikube](https://kubernetes.io/docs/tasks/tools/install-minik you must append the correct `platform` value to your installation commands, as minikube with Docker uses a nonstandard bind mount path for containers. For example: -#### Helm +{{< tabset category-name="install-method" >}} -```bash -helm install istio-cni istio/cni -n istio-system --set profile=ambient --set global.platform=minikube --wait -``` +{{< tab name="Helm" category-value="helm" >}} -#### istioctl + {{< text syntax=bash >}} + $ helm install istio-cni istio/cni -n istio-system --set profile=ambient --set global.platform=minikube --wait" + {{< /text >}} -```bash -istioctl install --set profile=ambient --set values.global.platform=minikube -``` +{{< /tab >}} + +{{< tab name="istioctl" category-value="istioctl" >}} + + {{< text syntax=bash >}} + $ istioctl install --set profile=ambient --set values.global.platform=minikube" + {{< /text >}} + +{{< /tab >}} + +{{< /tabset >}} ### Red Hat OpenShift OpenShift requires that `ztunnel` and `istio-cni` components are installed in the `kube-system` namespace, and that you set `global.platform=openshift` for all charts. -#### Helm +{{< tabset category-name="install-method" >}} -You must `--set global.platform=openshift` for **every** chart you install, for example with the `istiod` chart: +{{< tab name="Helm" category-value="helm" >}} -```bash -helm install istiod istio/istiod -n istio-system --set profile=ambient --set global.platform=openshift --wait -``` + You must `--set global.platform=openshift` for **every** chart you install, for example with the `istiod` chart: -In addition, you must install `istio-cni` and `ztunnel` in the `kube-system` namespace, for example: + {{< text syntax=bash >}} + $ helm install istiod istio/istiod -n istio-system --set profile=ambient --set global.platform=openshift --wait + {{< /text >}} -```bash -helm install istio-cni istio/cni -n kube-system --set profile=ambient --set global.platform=openshift --wait -helm install ztunnel istio/ztunnel -n kube-system --set profile=ambient --set global.platform=openshift --wait -``` + In addition, you must install `istio-cni` and `ztunnel` in the `kube-system` namespace, for example: -#### istioctl + {{< text syntax=bash >}} + $ helm install istio-cni istio/cni -n kube-system --set profile=ambient --set global.platform=openshift --wait + $ helm install ztunnel istio/ztunnel -n kube-system --set profile=ambient --set global.platform=openshift --wait + {{< /text >}} -```bash -istioctl install --set profile=openshift-ambient --skip-confirmation -``` +{{< /tab >}} + +{{< tab name="istioctl" category-value="istioctl" >}} + + {{< text syntax=bash >}} + $ istioctl install --set profile=openshift-ambient --skip-confirmation + {{< /text >}} + +{{< /tab >}} + +{{< /tabset >}} ## CNI plugins -The following configurations apply to all platforms, when certain CNI plugins are used: +The following configurations apply to all platforms, when certain {{< gloss "CNI" >}}CNI plugins{{< /gloss >}} are used: ### Cilium 1. Cilium currently defaults to proactively deleting other CNI plugins and their config, and must be configured with - `cni.exclusive = false` to properly support chaining. See [the Cilium documentation](https://docs.cilium.io/en/stable/helm-reference/) for more details. -2. Cilium's BPF masquerading is currently disabled by default, and has issues with Istio's use of link-local IPs for Kubernetes health checking. Enabling BPF masquerading via `bpf.masquerade=true` is not currently supported, and results in non-functional pod health checks in Istio ambient. Cilium's default iptables masquerading implementation should continue to function correctly. -3. Due to how Cilium manages node identity and internally allow-lists node-level health probes to pods, - applying any default-DENY `NetworkPolicy` in a Cilium CNI install underlying Istio in ambient mode will cause `kubelet` health probes (which are by-default silently exempted from all policy enforcement by Cilium) to be blocked. This is because Istio uses a link-local SNAT address for kubelet health probes, which Cilium is not aware of, and Cilium does not have an option to exempt link-local addresses from policy enforcement. +`cni.exclusive = false` to properly support chaining. See [the Cilium documentation](https://docs.cilium.io/en/stable/helm-reference/) for more details. + +1. Cilium's BPF masquerading is currently disabled by default, and has issues with Istio's use of link-local IPs for Kubernetes health checking. Enabling BPF masquerading via `bpf.masquerade=true` is not currently supported, and results in non-functional pod health checks in Istio ambient. Cilium's default iptables masquerading implementation should continue to function correctly. + +1. Due to how Cilium manages node identity and internally allow-lists node-level health probes to pods, +applying any default-DENY `NetworkPolicy` in a Cilium CNI install underlying Istio in ambient mode will cause `kubelet` health probes (which are by-default silently exempted from all policy enforcement by Cilium) to be blocked. This is because Istio uses a link-local SNAT address for kubelet health probes, which Cilium is not aware of, and Cilium does not have an option to exempt link-local addresses from policy enforcement. This can be resolved by applying the following `CiliumClusterWideNetworkPolicy`: - ```yaml + {{< text syntax=yaml >}} apiVersion: "cilium.io/v2" kind: CiliumClusterwideNetworkPolicy metadata: @@ -229,7 +280,7 @@ The following configurations apply to all platforms, when certain CNI plugins ar ingress: - fromCIDR: - "169.254.7.127/32" - ``` + {{< /text >}} This policy override is *not* required unless you already have other default-deny `NetworkPolicies` or `CiliumNetworkPolicies` applied in your cluster. From cbf32dcf6a62e60ce526c2092843493229f6e8c6 Mon Sep 17 00:00:00 2001 From: Parv Agarwal <142515806+parv18050212@users.noreply.github.com> Date: Wed, 16 Jul 2025 16:37:44 +0530 Subject: [PATCH 09/10] docs: fix code block formatting for lint compliance in GKE section --- .../docs/ambient/install/platform-prerequisites/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/en/docs/ambient/install/platform-prerequisites/index.md b/content/en/docs/ambient/install/platform-prerequisites/index.md index de611b9821fe..c36fac0dabcd 100644 --- a/content/en/docs/ambient/install/platform-prerequisites/index.md +++ b/content/en/docs/ambient/install/platform-prerequisites/index.md @@ -23,15 +23,15 @@ When using GKE you must append the correct `platform` value to your installation #### istioctl ambient -```bash +{{< text syntax=bash >}} istioctl install --set profile=ambient --set values.cni.platform=gke -``` +{{< /text >}} #### Helm ambient -```bash +{{< text syntax=bash >}} helm install istio-cni charts/cni --set profile=ambient --set values.cni.platform=gke -``` +{{< /text >}} #### Namespace restrictions From cb82172e2150640c93877adeb7996343797dd17f Mon Sep 17 00:00:00 2001 From: Parv Agarwal <142515806+parv18050212@users.noreply.github.com> Date: Wed, 16 Jul 2025 16:41:38 +0530 Subject: [PATCH 10/10] docs: prepend $ to bash code blocks to fix Hugo lint errors --- .../en/docs/ambient/install/platform-prerequisites/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/ambient/install/platform-prerequisites/index.md b/content/en/docs/ambient/install/platform-prerequisites/index.md index c36fac0dabcd..2b39a6f3dd3e 100644 --- a/content/en/docs/ambient/install/platform-prerequisites/index.md +++ b/content/en/docs/ambient/install/platform-prerequisites/index.md @@ -24,13 +24,13 @@ When using GKE you must append the correct `platform` value to your installation #### istioctl ambient {{< text syntax=bash >}} -istioctl install --set profile=ambient --set values.cni.platform=gke +$ istioctl install --set profile=ambient --set values.cni.platform=gke {{< /text >}} #### Helm ambient {{< text syntax=bash >}} -helm install istio-cni charts/cni --set profile=ambient --set values.cni.platform=gke +$ helm install istio-cni charts/cni --set profile=ambient --set values.cni.platform=gke {{< /text >}} #### Namespace restrictions