diff --git a/.spelling b/.spelling index 7daf5a5741b8..7faa80b453f1 100644 --- a/.spelling +++ b/.spelling @@ -1163,6 +1163,7 @@ topologySpreadConstraints touchpoints tradeoff tradeoffs +Traefik TrafficPolicy Trendyol Trivedi diff --git a/content/en/docs/ambient/install/_index.md b/content/en/docs/ambient/install/_index.md index 8c212e3ba330..bf75507d2973 100644 --- a/content/en/docs/ambient/install/_index.md +++ b/content/en/docs/ambient/install/_index.md @@ -1,10 +1,18 @@ --- title: Install -description: Installation guide for Istio ambient mode. +description: Installation guides for Istio in ambient mode. weight: 5 aliases: - /docs/ops/ambient/install - /latest/docs/ops/ambient/install owner: istio/wg-environment-maintainers test: n/a +list_below: yes --- + +{{< tip >}} +Want to quickly try out Istio in ambient mode? [Read our Getting Started guide](/docs/ambient/getting-started/)! +{{< /tip >}} + +There are two different options for installing Istio. Which one you should choose will depend on your production requirements, and how you install other software. If you need help choosing, refer to our +[which Istio installation method should I use?](/about/faq/#install-method-selection) FAQ page. diff --git a/content/en/docs/ambient/install/helm-installation/index.md b/content/en/docs/ambient/install/helm/index.md similarity index 71% rename from content/en/docs/ambient/install/helm-installation/index.md rename to content/en/docs/ambient/install/helm/index.md index b9d73308dc3e..54b28a501d3a 100644 --- a/content/en/docs/ambient/install/helm-installation/index.md +++ b/content/en/docs/ambient/install/helm/index.md @@ -1,17 +1,23 @@ --- title: Install with Helm -description: Install Istio in Ambient mode with Helm. +description: Install Istio with support for ambient mode with Helm. weight: 4 aliases: - /docs/ops/ambient/install/helm-installation - /latest/docs/ops/ambient/install/helm-installation + - /docs/ambient/install/helm-installation + - /latest/docs/ambient/install/helm-installation owner: istio/wg-environments-maintainers test: yes --- -This guide shows you how to install Istio in ambient mode with Helm. -Aside from following the demo in [Getting Started with Ambient Mode](/docs/ambient/getting-started/), -we encourage the use of Helm to install Istio for use in ambient mode. Helm helps you manage components separately, and you can easily upgrade the components to the latest version. +{{< tip >}} +Follow this guide to install and configure an Istio mesh with support for ambient mode. +If you are new to Istio, and just want to try it out, follow the +[quick start instructions](/docs/ambient/getting-started) instead. +{{< /tip >}} + +We encourage the use of Helm to install Istio for production use in ambient mode. To allow controlled upgrades, the control plane and data plane components are packaged and installed separately. (Because the ambient data plane is split across [two components](/docs/ambient/architecture/data-plane), the ztunnel and waypoints, upgrades involve separate steps for these components.) ## Prerequisites @@ -26,11 +32,19 @@ we encourage the use of Helm to install Istio for use in ambient mode. Helm help $ helm repo update {{< /text >}} -*See [helm repo](https://helm.sh/docs/helm/helm_repo/) for command documentation.* +## Install the control plane + +Default configuration values can be changed using one or more `--set =` arguments. Alternatively, you can specify several parameters in a custom values file using the `--values ` argument. + +{{< tip >}} +You can display the default values of configuration parameters using the `helm show values ` command or refer to Artifact Hub chart documentation for the [base](https://artifacthub.io/packages/helm/istio-official/base?modal=values), [istiod](https://artifacthub.io/packages/helm/istio-official/istiod?modal=values), [CNI](https://artifacthub.io/packages/helm/istio-official/cni?modal=values), [ztunnel](https://artifacthub.io/packages/helm/istio-official/ztunnel?modal=values) and [Gateway](https://artifacthub.io/packages/helm/istio-official/gateway?modal=values) chart configuration parameters. +{{< /tip >}} + +Full details on how to use and customize Helm installations are available in [the sidecar installation documentation](/docs/setup/install/helm/). -## Install the components +Unlike [istioctl](/docs/ambient/install/istioctl/) profiles, which group together components to be installed or removed, Helm profiles simply set groups of configuration values. -### Install the base component +### Base components The `base` chart contains the basic CRDs and cluster roles required to set up Istio. This should be installed prior to any other Istio component. @@ -39,24 +53,26 @@ This should be installed prior to any other Istio component. $ helm install istio-base istio/base -n istio-system --create-namespace --wait {{< /text >}} -### Install the CNI component +### istiod control plane -The `cni` chart installs the Istio CNI plugin. It is responsible for detecting the pods that belong to the ambient mesh, and configuring the traffic redirection between pods and the ztunnel node proxy (which will be installed later). +The `istiod` chart installs a revision of Istiod. Istiod is the control plane component that manages and +configures the proxies to route traffic within the mesh. -{{< text syntax=bash snip_id=install_cni >}} -$ helm install istio-cni istio/cni -n istio-system --set profile=ambient --wait +{{< text syntax=bash snip_id=install_istiod >}} +$ helm install istiod istio/istiod --namespace istio-system --set profile=ambient --wait {{< /text >}} -### Install the Istiod component +### CNI node agent -The `istiod` chart installs a revision of Istiod. Istiod is the control plane component that manages and -configures the proxies to route traffic within the mesh. +The `cni` chart installs the Istio CNI node agent. It is responsible for detecting the pods that belong to the ambient mesh, and configuring the traffic redirection between pods and the ztunnel node proxy (which will be installed later). -{{< text syntax=bash snip_id=install_discovery >}} -$ helm install istiod istio/istiod --namespace istio-system --set profile=ambient --wait +{{< text syntax=bash snip_id=install_cni >}} +$ helm install istio-cni istio/cni -n istio-system --set profile=ambient --wait {{< /text >}} -### Install the ztunnel component +## Install the data plane + +### ztunnel DaemonSet The `ztunnel` chart installs the ztunnel DaemonSet, which is the node proxy component of Istio's ambient mode. @@ -64,7 +80,7 @@ The `ztunnel` chart installs the ztunnel DaemonSet, which is the node proxy comp $ helm install ztunnel istio/ztunnel -n istio-system --wait {{< /text >}} -### Install an ingress gateway (optional) +### Ingress gateway (optional) To install an ingress gateway, run the command below: @@ -135,21 +151,21 @@ installed above. $ kubectl delete namespace istio-ingress {{< /text >}} -1. Delete the Istio CNI chart: +1. Delete the ztunnel chart: - {{< text syntax=bash snip_id=delete_cni >}} - $ helm delete istio-cni -n istio-system + {{< text syntax=bash snip_id=delete_ztunnel >}} + $ helm delete ztunnel -n istio-system {{< /text >}} -1. Delete the Istio ztunnel chart: +1. Delete the Istio CNI chart: - {{< text syntax=bash snip_id=delete_ztunnel >}} - $ helm delete ztunnel -n istio-system + {{< text syntax=bash snip_id=delete_cni >}} + $ helm delete istio-cni -n istio-system {{< /text >}} -1. Delete the Istio discovery chart: +1. Delete the istiod control plane chart: - {{< text syntax=bash snip_id=delete_discovery >}} + {{< text syntax=bash snip_id=delete_istiod >}} $ helm delete istiod -n istio-system {{< /text >}} diff --git a/content/en/docs/ambient/install/helm-installation/snips.sh b/content/en/docs/ambient/install/helm/snips.sh similarity index 97% rename from content/en/docs/ambient/install/helm-installation/snips.sh rename to content/en/docs/ambient/install/helm/snips.sh index aa90abeaf8e4..6683ad1df913 100644 --- a/content/en/docs/ambient/install/helm-installation/snips.sh +++ b/content/en/docs/ambient/install/helm/snips.sh @@ -17,7 +17,7 @@ #################################################################################################### # WARNING: THIS IS AN AUTO-GENERATED FILE, DO NOT EDIT. PLEASE MODIFY THE ORIGINAL MARKDOWN FILE: -# docs/ambient/install/helm-installation/index.md +# docs/ambient/install/helm/index.md #################################################################################################### snip_configure_helm() { @@ -29,12 +29,12 @@ snip_install_base() { helm install istio-base istio/base -n istio-system --create-namespace --wait } -snip_install_cni() { -helm install istio-cni istio/cni -n istio-system --set profile=ambient --wait +snip_install_istiod() { +helm install istiod istio/istiod --namespace istio-system --set profile=ambient --wait } -snip_install_discovery() { -helm install istiod istio/istiod --namespace istio-system --set profile=ambient --wait +snip_install_cni() { +helm install istio-cni istio/cni -n istio-system --set profile=ambient --wait } snip_install_ztunnel() { @@ -89,15 +89,15 @@ helm delete istio-ingress -n istio-ingress kubectl delete namespace istio-ingress } -snip_delete_cni() { -helm delete istio-cni -n istio-system -} - snip_delete_ztunnel() { helm delete ztunnel -n istio-system } -snip_delete_discovery() { +snip_delete_cni() { +helm delete istio-cni -n istio-system +} + +snip_delete_istiod() { helm delete istiod -n istio-system } diff --git a/content/en/docs/ambient/install/helm-installation/test.sh b/content/en/docs/ambient/install/helm/test.sh similarity index 95% rename from content/en/docs/ambient/install/helm-installation/test.sh rename to content/en/docs/ambient/install/helm/test.sh index 5adbbabca513..15d3eed9dd50 100644 --- a/content/en/docs/ambient/install/helm-installation/test.sh +++ b/content/en/docs/ambient/install/helm/test.sh @@ -25,7 +25,7 @@ set -o pipefail snip_configure_helm _rewrite_helm_repo snip_install_base -_rewrite_helm_repo snip_install_discovery +_rewrite_helm_repo snip_install_istiod _wait_for_deployment istio-system istiod _rewrite_helm_repo snip_install_cni @@ -41,9 +41,9 @@ _verify_like snip_show_components "$snip_show_components_out" _verify_like snip_check_pods "$snip_check_pods_out" # @cleanup -snip_delete_cni +snip_delete_ingress snip_delete_ztunnel -snip_delete_discovery +snip_delete_cni +snip_delete_istiod snip_delete_base snip_delete_system_namespace -snip_delete_ingress diff --git a/content/en/docs/ambient/install/istioctl/index.md b/content/en/docs/ambient/install/istioctl/index.md new file mode 100644 index 000000000000..c7ac42a89dff --- /dev/null +++ b/content/en/docs/ambient/install/istioctl/index.md @@ -0,0 +1,83 @@ +--- +title: Install with istioctl +description: Install Istio with support for ambient mode using the istioctl command line tool. +weight: 10 +keywords: [istioctl,ambient] +owner: istio/wg-environments-maintainers +test: yes +--- + +{{< tip >}} +Follow this guide to install and configure an Istio mesh with support for ambient mode. +If you are new to Istio, and just want to try it out, follow the +[quick start instructions](/docs/ambient/getting-started) instead. +{{< /tip >}} + +This installation guide uses the [istioctl](/docs/reference/commands/istioctl/) command-line +tool. `istioctl`, like other installation methods, exposes many customization options. Additionally, +it offers has user input validation to help prevent installation errors, and includes many +post-installation analysis and configuration tools. + +Using these instructions, you can select any one of Istio's built-in +[configuration profiles](/docs/setup/additional-setup/config-profiles/) +and then further customize the configuration for your specific needs. + +The `istioctl` command supports the full [`IstioOperator` API](/docs/reference/config/istio.operator.v1alpha1/) +via command-line options for individual settings, or passing a YAML file containing an `IstioOperator` +{{}}custom resource{{}}. + +## Prerequisites + +Before you begin, check the following prerequisites: + +1. [Download the Istio release](/docs/setup/additional-setup/download-istio-release/). +1. Perform any necessary [platform-specific setup](/docs/ambient/install/platform-prerequisites/). + +## Install or upgrade the Kubernetes Gateway API CRDs + +{{< boilerplate gateway-api-install-crds >}} + +## Install Istio using the ambient profile + +`istioctl` supports a number of [configuration profiles](/docs/setup/additional-setup/config-profiles/) that include different default options, +and can be customized for your production needs. Support for ambient mode is included in the `ambient` profile. Install Istio with the +following command: + +{{< text syntax=bash snip_id=install_ambient >}} +$ istioctl install --set profile=ambient --skip-confirmation +{{< /text >}} + +This command installs the `ambient` profile on the cluster defined by your +Kubernetes configuration. + +## Configure and modify profiles + +Istio's installation API is documented in the [`IstioOperator` API reference](/docs/reference/config/istio.operator.v1alpha1/). You +can use the `--set` option to `istioctl install` to modify individual installation parameters, or specify your own configuration file with `-f`. + +Full details on how to use and customize `istioctl` installations are available in [the sidecar installation documentation](/docs/setup/install/istioctl/). + +## Uninstall Istio + +To completely uninstall Istio from a cluster, run the following command: + +{{< text syntax=bash snip_id=uninstall >}} +$ istioctl uninstall --purge -y +{{< /text >}} + +{{< warning >}} +The optional `--purge` flag will remove all Istio resources, including cluster-scoped resources that may be shared with other Istio control planes. +{{< /warning >}} + +Alternatively, to remove only a specific Istio control plane, run the following command: + +{{< text syntax=bash snip_id=none >}} +$ istioctl uninstall +{{< /text >}} + +The control plane namespace (e.g., `istio-system`) is not removed by default. +If no longer needed, use the following command to remove it: + +{{< text syntax=bash snip_id=remove_namespace >}} +$ kubectl delete namespace istio-system +{{< /text >}} diff --git a/content/en/docs/ambient/install/istioctl/snips.sh b/content/en/docs/ambient/install/istioctl/snips.sh new file mode 100644 index 000000000000..fede58baa59e --- /dev/null +++ b/content/en/docs/ambient/install/istioctl/snips.sh @@ -0,0 +1,34 @@ +#!/bin/bash +# shellcheck disable=SC2034,SC2153,SC2155,SC2164 + +# Copyright Istio Authors. All Rights Reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +#################################################################################################### +# WARNING: THIS IS AN AUTO-GENERATED FILE, DO NOT EDIT. PLEASE MODIFY THE ORIGINAL MARKDOWN FILE: +# docs/ambient/install/istioctl/index.md +#################################################################################################### +source "content/en/boilerplates/snips/gateway-api-install-crds.sh" + +snip_install_ambient() { +istioctl install --set values.pilot.env.PILOT_ENABLE_CONFIG_DISTRIBUTION_TRACKING=true --set profile=ambient --skip-confirmation +} + +snip_uninstall() { +istioctl uninstall --purge -y +} + +snip_remove_namespace() { +kubectl delete namespace istio-system +} diff --git a/content/en/docs/ambient/install/istioctl/test.sh b/content/en/docs/ambient/install/istioctl/test.sh new file mode 100644 index 000000000000..e353b06a5550 --- /dev/null +++ b/content/en/docs/ambient/install/istioctl/test.sh @@ -0,0 +1,33 @@ +#!/usr/bin/env bash +# shellcheck disable=SC2154 + +# Copyright Istio Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +set -e +set -u + +set -o pipefail + +# @setup profile=none + +snip_install_ambient + +_wait_for_deployment istio-system istiod +_wait_for_daemonset istio-system istio-cni-node +_wait_for_daemonset istio-system ztunnel + +# @cleanup +snip_uninstall +snip_remove_namespace \ No newline at end of file diff --git a/content/en/docs/ambient/install/platform-prerequisites/index.md b/content/en/docs/ambient/install/platform-prerequisites/index.md index 0ba892b3552c..dfef98074fe8 100644 --- a/content/en/docs/ambient/install/platform-prerequisites/index.md +++ b/content/en/docs/ambient/install/platform-prerequisites/index.md @@ -1,7 +1,7 @@ --- title: Platform-Specific Prerequisites description: Platform-specific prerequisites for installing Istio in ambient mode. -weight: 4 +weight: 2 aliases: - /docs/ops/ambient/install/platform-prerequisites - /latest/docs/ops/ambient/install/platform-prerequisites @@ -9,65 +9,170 @@ owner: istio/wg-environments-maintainers test: no --- -This document covers any platform or environment specific prerequisites for installing Istio in ambient mode. +This document covers any platform- or environment-specific prerequisites for installing Istio in ambient mode. ## Platform +Certain Kubernetes environments require you to set various Istio configuration options to support them. + ### Google Kubernetes Engine (GKE) -1. On GKE, Istio components 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. `istio-cni` and `ztunnel` both require the `node-critical` class, and so in GKE, both components must either: - - - 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: - - {{< text syntax=yaml snip_id=none >}} - 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 >}} - -### Minikube - -1. If you are using [Minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/) with the [Docker driver](https://minikube.sigs.k8s.io/docs/drivers/docker/), -you must append `--set cni.cniNetnsDir="/var/run/docker/netns"` to the `helm install` command so that the `istio-cni` node agent can correctly manage -and capture pods on the node. +On GKE, Istio components 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: -### MicroK8s +- 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: -1. If you are using [MicroK8s](https://microk8s.io/), you must append `--set values.cni.cniConfDir=/var/snap/microk8s/current/args/cni-network --set values.cni.cniBinDir=/var/snap/microk8s/current/opt/cni/bin` to the `helm install` command, as MicroK8s [uses nonstandard locations for CNI configuration and binaries](https://microk8s.io/docs/change-cidr). +{{< 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 >}} -### K3D +### k3d -1. If you are using [k3d](https://k3d.io/) with the default flannel CNI, you must append `--set values.cni.cniConfDir=/var/lib/rancher/k3s/agent/etc/cni/net.d --set values.cni.cniBinDir=/bin/` to your `istioctl install` or `helm install` command to install Istio with the `ambient` profile. +If you are using [k3d](https://k3d.io/) with the default Flannel CNI, you must append some values to your installation command, as k3d uses nonstandard locations for CNI configuration and binaries. -1. Create a cluster and disable `Traefik` so it doesn't conflict with Istio's ingress gateways: +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. Install Istio with the `ambient` profile using `istioctl`: +1. Set the `cniConfDir` and `cniBinDir` values when installing Istio. 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 --wait --set cniConfDir=/var/lib/rancher/k3s/agent/etc/cni/net.d --set cniBinDir=/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=/bin + {{< /text >}} + + {{< /tab >}} + + {{< /tabset >}} + +### K3s + +When using [K3s](https://k3s.io/) and one of its bundled CNIs, you must append some values to your installation command, as K3S uses nonstandard locations for CNI configuration and binaries. These nonstandard locations may be overridden as well, [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 use 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" >}} + +{{< 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 >}} + +{{< /tab >}} + +{{< /tabset >}} + +### MicroK8s + +If you are installing Istio on [MicroK8s](https://microk8s.io/), you must append a value to your installation command, 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 --wait --set cniConfDir=/var/snap/microk8s/current/args/cni-network --set cniBinDir=/var/snap/microk8s/current/opt/cni/bin - {{< text bash >}} - $ istioctl install --set profile=ambient --skip-confirmation --set values.cni.cniConfDir=/var/lib/rancher/k3s/agent/etc/cni/net.d --set values.cni.cniBinDir=/bin {{< /text >}} -### K3S +{{< /tab >}} + +{{< tab name="istioctl" category-value="istioctl" >}} + + {{< text syntax=bash >}} + $ istioctl install --set profile=ambient --set values.cni.cniConfDir=/var/snap/microk8s/current/args/cni-network --set values.cni.cniBinDir=/var/snap/microk8s/current/opt/cni/bin + {{< /text >}} + +{{< /tab >}} + +{{< /tabset >}} + +### minikube + +If you are using [minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/) with the [Docker driver](https://minikube.sigs.k8s.io/docs/drivers/docker/), +you must append some values to your installation command so that the Istio CNI node agent can correctly manage +and capture pods on the node. 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 --wait --set cniNetnsDir="/var/run/docker/netns" + {{< /text >}} + +{{< /tab >}} + +{{< tab name="istioctl" category-value="istioctl" >}} + + {{< text syntax=bash >}} + $ istioctl install --set profile=ambient --set cni.cniNetnsDir="/var/run/docker/netns" + {{< /text >}} + +{{< /tab >}} + +{{< /tabset >}} + +### Red Hat OpenShift + +OpenShift requires that `ztunnel` and `istio-cni` components are installed in the `kube-system` namespace. An `openshift-ambient` installation profile is provided which will make this change for you. Replace instances of `profile=ambient` with `profile=openshift-ambient` in the installation commands. 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=openshift-ambient --wait + {{< /text >}} + +{{< /tab >}} + +{{< tab name="istioctl" category-value="istioctl" >}} + + {{< text syntax=bash >}} + $ istioctl install --set profile=openshift-ambient --skip-confirmation + {{< /text >}} + +{{< /tab >}} + +{{< /tabset >}} -1. If you are using [K3S](https://k3s.io/) and one of its bundled CNIs, you must append `--set values.cni.cniConfDir=/var/lib/rancher/k3s/agent/etc/cni/net.d --set values.cni.cniBinDir=/var/lib/rancher/k3s/data/current/bin/` to your `istioctl install` or `helm install` command to install Istio ambient, as K3S uses nonstandard locations for CNI configuration and binaries. These nonstandard locations may be overridden as well [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 use the correct paths for those CNIs, e.g. `/etc/cni/net.d` - [see K3S docs for details](https://docs.k3s.io/networking/basic-network-options#custom-cni). +## CNI plugins -## CNI +The following configurations apply to all platforms, when certain {{< gloss "CNI" >}}CNI plugins{{< /gloss >}} are used: ### Cilium @@ -79,7 +184,7 @@ applying default-DENY `NetworkPolicy` in a Cilium CNI install underlying Istio i This can be resolved by applying the following `CiliumClusterWideNetworkPolicy`: - {{< text syntax=yaml snip_id=none >}} + {{< text syntax=yaml >}} apiVersion: "cilium.io/v2" kind: CiliumClusterwideNetworkPolicy metadata: diff --git a/content/en/docs/ambient/upgrade/_index.md b/content/en/docs/ambient/upgrade/_index.md index 765f8c4776ca..cb85363d79e4 100644 --- a/content/en/docs/ambient/upgrade/_index.md +++ b/content/en/docs/ambient/upgrade/_index.md @@ -1,6 +1,6 @@ --- title: Upgrade -description: Upgrade guide for Istio ambient mode. +description: Upgrade guides for Istio in ambient mode. weight: 10 aliases: - /docs/ops/ambient/upgrade diff --git a/content/en/docs/ambient/upgrade/helm-upgrade/common.sh b/content/en/docs/ambient/upgrade/helm/common.sh similarity index 89% rename from content/en/docs/ambient/upgrade/helm-upgrade/common.sh rename to content/en/docs/ambient/upgrade/helm/common.sh index 741fe6998995..24b9a0d88b82 100644 --- a/content/en/docs/ambient/upgrade/helm-upgrade/common.sh +++ b/content/en/docs/ambient/upgrade/helm/common.sh @@ -12,12 +12,12 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -source "content/en/docs/ambient/install/helm-installation/snips.sh" +source "content/en/docs/ambient/install/helm/snips.sh" _install_istio_ambient_helm() { snip_configure_helm _rewrite_helm_repo snip_install_base - _rewrite_helm_repo snip_install_discovery + _rewrite_helm_repo snip_install_istiod _wait_for_deployment istio-system istiod _rewrite_helm_repo snip_install_cni _wait_for_daemonset istio-system istio-cni-node @@ -30,7 +30,7 @@ _install_istio_ambient_helm() { _remove_istio_ambient_helm() { snip_delete_cni snip_delete_ztunnel - snip_delete_discovery + snip_delete_istiod snip_delete_base snip_delete_system_namespace snip_delete_ingress diff --git a/content/en/docs/ambient/upgrade/helm-upgrade/index.md b/content/en/docs/ambient/upgrade/helm/index.md similarity index 78% rename from content/en/docs/ambient/upgrade/helm-upgrade/index.md rename to content/en/docs/ambient/upgrade/helm/index.md index f74b3a472b1e..611917c0b4f6 100644 --- a/content/en/docs/ambient/upgrade/helm-upgrade/index.md +++ b/content/en/docs/ambient/upgrade/helm/index.md @@ -5,13 +5,14 @@ weight: 5 aliases: - /docs/ops/ambient/upgrade/helm-upgrade - /latest/docs/ops/ambient/upgrade/helm-upgrade + - /docs/ambient/upgrade/helm + - /latest/docs/ambient/upgrade/helm owner: istio/wg-environments-maintainers test: yes -status: Experimental --- Follow this guide to upgrade and configure an ambient mode installation using -[Helm](https://helm.sh/docs/). This guide assumes you have already performed an [ambient mode installation with Helm](/docs/ambient/install/helm-installation/) with a previous version of Istio. +[Helm](https://helm.sh/docs/). This guide assumes you have already performed an [ambient mode installation with Helm](/docs/ambient/install/helm/) with a previous version of Istio. {{< warning >}} In contrast to sidecar mode, ambient mode supports moving application pods to an upgraded ztunnel proxy without a mandatory restart or reschedule of running application pods. However, upgrading ztunnel **will** cause all long-lived TCP connections on the upgraded node to reset, and Istio does not currently support canary upgrades of ztunnel. @@ -19,11 +20,11 @@ In contrast to sidecar mode, ambient mode supports moving application pods to an Node cordoning and blue/green node pools are recommended to limit the blast radius of resets on application traffic during production upgrades. See your Kubernetes provider documentation for details. {{< /warning >}} -## Understanding ambient upgrades +## Understanding ambient mode upgrades -All Istio upgrades involve upgrading the control plane, data plane, and Istio CRDs. Because the ambient data plane is split across [two components](/docs/ambient/architecture/data-plane), the ztunnel and waypoints, upgrades involve separate steps for these components. Upgrading the control plane and CRDs is covered here in brief, but is essentially identical to [the process for upgrading these components in sidecar mode](docs/setup/upgrade/canary/). +All Istio upgrades involve upgrading the control plane, data plane, and Istio CRDs. Because the ambient data plane is split across [two components](/docs/ambient/architecture/data-plane), the ztunnel and waypoints, upgrades involve separate steps for these components. Upgrading the control plane and CRDs is covered here in brief, but is essentially identical to [the process for upgrading these components in sidecar mode](/docs/setup/upgrade/canary/). -Like sidecar mode, gateways can make use of [revision tags](docs/setup/upgrade/canary/#stable-revision-labels) to allow fine-grained control over ({{< gloss >}}gateway{{}}) upgrades, including waypoints, with simple controls for rolling back at any point. However, unlike sidecar mode, the ztunnel runs as a DaemonSet — a per-node proxy — meaning that ztunnel upgrades affect, at minimum, an entire node at a time. While this may be acceptable in many cases, applications with long-lived TCP connections may be disrupted. In such cases, we recommend using node cordoning and draining before upgrading the ztunnel for a given node. For the sake of simplicity, this document will demonstrate in-place upgrades of the ztunnel, which may involve a short downtime. +Like sidecar mode, gateways can make use of [revision tags](/docs/setup/upgrade/canary/#stable-revision-labels) to allow fine-grained control over ({{< gloss >}}gateway{{}}) upgrades, including waypoints, with simple controls for rolling back at any point. However, unlike sidecar mode, the ztunnel runs as a DaemonSet — a per-node proxy — meaning that ztunnel upgrades affect, at minimum, an entire node at a time. While this may be acceptable in many cases, applications with long-lived TCP connections may be disrupted. In such cases, we recommend using node cordoning and draining before upgrading the ztunnel for a given node. For the sake of simplicity, this document will demonstrate in-place upgrades of the ztunnel, which may involve a short downtime. ## Prerequisites @@ -62,7 +63,9 @@ $ export REVISION=istio-1-22-1 $ export OLD_REVISION=istio-1-21-2 {{< /text >}} -## Upgrade the Istio CRDs +## Upgrade the control plane + +### Base components The cluster-wide Custom Resource Definitions (CRDs) must be upgraded prior to the deployment of a new version of the control plane: @@ -70,7 +73,7 @@ The cluster-wide Custom Resource Definitions (CRDs) must be upgraded prior to th $ kubectl apply -f manifests/charts/base/crds {{< /text >}} -## Install the new control plane +### istiod control plane The [Istiod](/docs/ops/deployment/architecture/#istiod) control plane manages and configures the proxies that route traffic within the mesh. The following command will install a new instance of the control plane alongside the current, but will not introduce any new proxies, or take over control of existing proxies. @@ -80,34 +83,37 @@ If you have customized your istiod installation, you can reuse the `values.yaml` $ helm install istiod-"$REVISION" istio/istiod -n istio-system --set revision="$REVISION" --set profile=ambient --wait {{< /text >}} -## Upgrade the ztunnel DaemonSet +### CNI node agent -The {{< gloss >}}ztunnel{{< /gloss >}} DaemonSet is the node proxy component. The ztunnel at version 1.x is compatible with the control plane at version 1.x+1 and 1.x. This means the control plane must be upgraded before ztunnel, as long as their version difference is within one minor version. If you have previously customized your ztunnel installation, you can reuse the `values.yaml` file from previous upgrades or installs to keep your {{< gloss >}}data plane{{< /gloss >}} consistent. +The Istio CNI node agent is responsible for detecting pods added to the ambient mesh, informing ztunnel that proxy ports should be established within added pods, and configuring traffic redirection within the pod network namespace. It is not part of the data plane or control plane. + +The CNI at version 1.x is compatible with the control plane at version 1.x+1 and 1.x. This means the control plane must be upgraded before Istio CNI, as long as their version difference is within one minor version. {{< warning >}} -Upgrading ztunnel in-place will briefly disrupt all ambient mesh traffic on the node. -Node cordoning and blue/green node pools are recommended to mitigate blast radius risk during production upgrades. See your Kubernetes provider documentation for details. +Upgrading the Istio CNI node agent to a compatible version in-place will not disrupt networking for running pods already successfully added to an ambient mesh, but no ambient-captured pods will be successfully scheduled (or rescheduled) on the node until the upgrade is complete and the upgraded Istio CNI agent on the node passes readiness checks. If this is a significant disruption concern, or stricter blast radius controls are desired for CNI upgrades, node taints and/or node cordons are recommended. {{< /warning >}} -{{< text syntax=bash snip_id=upgrade_ztunnel >}} -$ helm upgrade ztunnel istio/ztunnel -n istio-system --set revision="$REVISION" --wait +{{< text syntax=bash snip_id=upgrade_cni >}} +$ helm upgrade istio-cni istio/cni -n istio-system {{< /text >}} -## Upgrade the CNI DaemonSet +## Upgrade the data plane -The Istio CNI agent is responsible for detecting pods added to the ambient mesh, informing ztunnel that proxy ports should be established within added pods, and configuring traffic redirection within the pod network namespace. It is not part of the data plane or control plane. +### ztunnel DaemonSet -The CNI at version 1.x is compatible with the control plane at version 1.x+1 and 1.x. This means the control plane must be upgraded before Istio CNI, as long as their version difference is within one minor version. +The {{< gloss >}}ztunnel{{< /gloss >}} DaemonSet is the node proxy component. The ztunnel at version 1.x is compatible with the control plane at version 1.x+1 and 1.x. This means the control plane must be upgraded before ztunnel, as long as their version difference is within one minor version. If you have previously customized your ztunnel installation, you can reuse the `values.yaml` file from previous upgrades or installs to keep your {{< gloss >}}data plane{{< /gloss >}} consistent. {{< warning >}} -Upgrading the Istio CNI agent to a compatible version in-place will not disrupt networking for running pods already successfully added to an ambient mesh, but no ambient-captured pods will be successfully scheduled (or rescheduled) on the node until the upgrade is complete and the upgraded Istio CNI agent on the node passes readiness checks. If this is a significant disruption concern, or stricter blast radius controls are desired for CNI upgrades, node taints and/or node cordons are recommended. +Upgrading ztunnel in-place will briefly disrupt all ambient mesh traffic on the node, regardless of the use of revisions. In practice the disruption period is a very small window, primarily affecting long-running connections. + +Node cordoning and blue/green node pools are recommended to mitigate blast radius risk during production upgrades. See your Kubernetes provider documentation for details. {{< /warning >}} -{{< text syntax=bash snip_id=upgrade_cni >}} -$ helm upgrade istio-cni istio/cni -n istio-system +{{< text syntax=bash snip_id=upgrade_ztunnel >}} +$ helm upgrade ztunnel istio/ztunnel -n istio-system --set revision="$REVISION" --wait {{< /text >}} -## Upgrade waypoints and gateways using tags +### Upgrade waypoints and gateways using tags If you have followed best practices, all of your gateways, workloads, and namespaces use either the default revision (effectively, a tag named `default`), or the `istio.io/rev` label with the value set to a tag name. You can now upgrade all of these to the new version of the Istio data plane by moving their tags to point to the new version, one at a time. To list all tags in your cluster, run: diff --git a/content/en/docs/ambient/upgrade/helm-upgrade/snips.sh b/content/en/docs/ambient/upgrade/helm/snips.sh similarity index 96% rename from content/en/docs/ambient/upgrade/helm-upgrade/snips.sh rename to content/en/docs/ambient/upgrade/helm/snips.sh index 001d5f756739..12ef51272767 100644 --- a/content/en/docs/ambient/upgrade/helm-upgrade/snips.sh +++ b/content/en/docs/ambient/upgrade/helm/snips.sh @@ -17,7 +17,7 @@ #################################################################################################### # WARNING: THIS IS AN AUTO-GENERATED FILE, DO NOT EDIT. PLEASE MODIFY THE ORIGINAL MARKDOWN FILE: -# docs/ambient/upgrade/helm-upgrade/index.md +# docs/ambient/upgrade/helm/index.md #################################################################################################### snip_istioctl_precheck() { @@ -40,7 +40,7 @@ export REVISION=istio-1-22-1 export OLD_REVISION=istio-1-21-2 } -snip_upgrade_the_istio_crds_1() { +snip_base_components_1() { kubectl apply -f manifests/charts/base/crds } @@ -48,14 +48,14 @@ snip_upgrade_istiod() { helm install istiod-"$REVISION" istio/istiod -n istio-system --set revision="$REVISION" --set profile=ambient --wait } -snip_upgrade_ztunnel() { -helm upgrade ztunnel istio/ztunnel -n istio-system --set revision="$REVISION" --wait -} - snip_upgrade_cni() { helm upgrade istio-cni istio/cni -n istio-system } +snip_upgrade_ztunnel() { +helm upgrade ztunnel istio/ztunnel -n istio-system --set revision="$REVISION" --wait +} + snip_list_tags() { kubectl get mutatingwebhookconfigurations -l 'istio.io/tag' -L istio\.io/tag,istio\.io/rev } diff --git a/content/en/docs/ambient/upgrade/helm-upgrade/test.sh b/content/en/docs/ambient/upgrade/helm/test.sh similarity index 94% rename from content/en/docs/ambient/upgrade/helm-upgrade/test.sh rename to content/en/docs/ambient/upgrade/helm/test.sh index 189d008285ad..598a3126b4da 100755 --- a/content/en/docs/ambient/upgrade/helm-upgrade/test.sh +++ b/content/en/docs/ambient/upgrade/helm/test.sh @@ -18,7 +18,7 @@ set -u set -o pipefail -source "content/en/docs/ambient/upgrade/helm-upgrade/common.sh" +source "content/en/docs/ambient/upgrade/helm/common.sh" # @setup profile=none _install_istio_ambient_helm @@ -28,7 +28,7 @@ export MYTAG=tagname snip_list_revisions snip_update_helm snip_istioctl_precheck -snip_upgrade_the_istio_crds_1 +snip_base_components_1 _rewrite_helm_repo snip_upgrade_istiod diff --git a/content/en/docs/tasks/traffic-management/egress/egress-gateway-tls-origination/snips.sh b/content/en/docs/tasks/traffic-management/egress/egress-gateway-tls-origination/snips.sh index ef8f67878c01..30fb0a51652a 100644 --- a/content/en/docs/tasks/traffic-management/egress/egress-gateway-tls-origination/snips.sh +++ b/content/en/docs/tasks/traffic-management/egress/egress-gateway-tls-origination/snips.sh @@ -277,7 +277,7 @@ kubectl delete destinationrule egressgateway-for-cnn snip_cleanup_the_tls_origination_example_2() { kubectl delete serviceentry cnn -kubectl delete gtw cnn-egress-gateway +kubectl delete gtw --cascade=foreground cnn-egress-gateway kubectl delete httproute direct-cnn-to-egress-gateway kubectl delete httproute forward-cnn-from-egress-gateway kubectl delete destinationrule egressgateway-for-cnn @@ -709,7 +709,7 @@ kubectl delete destinationrule egressgateway-for-nginx snip_cleanup_the_mutual_tls_origination_example_3() { kubectl delete secret client-credential -kubectl delete gtw nginx-egressgateway +kubectl delete gtw --cascade=foreground nginx-egressgateway kubectl delete role nginx-egressgateway-istio-sds kubectl delete rolebinding nginx-egressgateway-istio-sds kubectl delete virtualservice direct-nginx-to-egress-gateway diff --git a/content/en/docs/tasks/traffic-management/egress/egress-gateway/snips.sh b/content/en/docs/tasks/traffic-management/egress/egress-gateway/snips.sh index 8d5f2ba5857d..d355c6321ea9 100644 --- a/content/en/docs/tasks/traffic-management/egress/egress-gateway/snips.sh +++ b/content/en/docs/tasks/traffic-management/egress/egress-gateway/snips.sh @@ -260,7 +260,7 @@ kubectl delete destinationrule egressgateway-for-cnn snip_cleanup_http_gateway_2() { kubectl delete serviceentry cnn -kubectl delete gtw cnn-egress-gateway +kubectl delete gtw --cascade=foreground cnn-egress-gateway kubectl delete httproute direct-cnn-to-egress-gateway kubectl delete httproute forward-cnn-from-egress-gateway } @@ -448,7 +448,7 @@ kubectl delete destinationrule egressgateway-for-cnn snip_cleanup_https_gateway_2() { kubectl delete serviceentry cnn -kubectl delete gtw cnn-egress-gateway +kubectl delete gtw --cascade=foreground cnn-egress-gateway kubectl delete tlsroute direct-cnn-to-egress-gateway kubectl delete tlsroute forward-cnn-from-egress-gateway } diff --git a/content/en/docs/tasks/traffic-management/egress/wildcard-egress-hosts/snips.sh b/content/en/docs/tasks/traffic-management/egress/wildcard-egress-hosts/snips.sh index 46dbafd9d781..ef8b4aae7165 100644 --- a/content/en/docs/tasks/traffic-management/egress/wildcard-egress-hosts/snips.sh +++ b/content/en/docs/tasks/traffic-management/egress/wildcard-egress-hosts/snips.sh @@ -257,7 +257,7 @@ kubectl delete destinationrule egressgateway-for-wikipedia snip_cleanup_egress_gateway_traffic_to_a_wildcard_host_2() { kubectl delete se wikipedia kubectl delete se www-wikipedia -kubectl delete gtw wikipedia-egress-gateway +kubectl delete gtw --cascade=foreground wikipedia-egress-gateway kubectl delete tlsroute direct-wikipedia-to-egress-gateway kubectl delete tlsroute forward-wikipedia-from-egress-gateway } diff --git a/content/en/docs/tasks/traffic-management/ingress/ingress-control/index.md b/content/en/docs/tasks/traffic-management/ingress/ingress-control/index.md index c365b8487177..fd5d0f2e0af5 100644 --- a/content/en/docs/tasks/traffic-management/ingress/ingress-control/index.md +++ b/content/en/docs/tasks/traffic-management/ingress/ingress-control/index.md @@ -536,8 +536,8 @@ $ kubectl delete --ignore-not-found=true -f @samples/httpbin/httpbin.yaml@ Delete the `Gateway` and `HTTPRoute` configuration, and shutdown the [httpbin]({{< github_tree >}}/samples/httpbin) service: {{< text bash >}} -$ kubectl delete gtw httpbin-gateway $ kubectl delete httproute httpbin +$ kubectl delete gtw httpbin-gateway $ kubectl delete --ignore-not-found=true -f @samples/httpbin/httpbin.yaml@ {{< /text >}} diff --git a/content/en/docs/tasks/traffic-management/ingress/ingress-control/snips.sh b/content/en/docs/tasks/traffic-management/ingress/ingress-control/snips.sh index a24474dedb5f..c78d930c1680 100644 --- a/content/en/docs/tasks/traffic-management/ingress/ingress-control/snips.sh +++ b/content/en/docs/tasks/traffic-management/ingress/ingress-control/snips.sh @@ -307,7 +307,7 @@ kubectl delete --ignore-not-found=true -f samples/httpbin/httpbin.yaml } snip_cleanup_2() { -kubectl delete gtw httpbin-gateway kubectl delete httproute httpbin +kubectl delete gtw --cascade=foreground httpbin-gateway kubectl delete --ignore-not-found=true -f samples/httpbin/httpbin.yaml } diff --git a/content/en/docs/tasks/traffic-management/ingress/ingress-sni-passthrough/snips.sh b/content/en/docs/tasks/traffic-management/ingress/ingress-sni-passthrough/snips.sh index 53f73679c26b..651129a9455b 100644 --- a/content/en/docs/tasks/traffic-management/ingress/ingress-sni-passthrough/snips.sh +++ b/content/en/docs/tasks/traffic-management/ingress/ingress-sni-passthrough/snips.sh @@ -265,7 +265,7 @@ kubectl delete virtualservice nginx } snip_cleanup_2() { -kubectl delete gtw mygateway +kubectl delete gtw --cascade=foreground mygateway kubectl delete tlsroute nginx } diff --git a/scripts/snip.py b/scripts/snip.py index 42c682b038ec..651ff8573615 100644 --- a/scripts/snip.py +++ b/scripts/snip.py @@ -105,6 +105,7 @@ github_url = "https://raw.githubusercontent.com/istio/istio/" + source_branch_name line = line.replace("{{< github_file >}}", github_url) line = line.replace("istioctl install", "istioctl install --set values.pilot.env.PILOT_ENABLE_CONFIG_DISTRIBUTION_TRACKING=true") + line = line.replace("kubectl delete gtw", "kubectl delete gtw --cascade=foreground") match = sectionhead.match(line) if match: diff --git a/tests/util/samples.sh b/tests/util/samples.sh index 6d19b269b7dc..3f06e5dc750e 100644 --- a/tests/util/samples.sh +++ b/tests/util/samples.sh @@ -39,7 +39,7 @@ cleanup_bookinfo_sample() { if [ "$GATEWAY_API" == "true" ]; then kubectl delete -f samples/bookinfo/platform/kube/bookinfo-versions.yaml || true - kubectl delete -f samples/bookinfo/gateway-api/bookinfo-gateway.yaml || true + kubectl delete -f --cascade=foreground samples/bookinfo/gateway-api/bookinfo-gateway.yaml || true else kubectl delete -f samples/bookinfo/networking/destination-rule-all.yaml || true kubectl delete -f samples/bookinfo/networking/bookinfo-gateway.yaml || true