mirror of https://github.com/istio/istio.io.git
Initial inplace ambient upgrade guide (#14491)
* Initial attempt at an inplace ambient upgrade guide Signed-off-by: Benjamin Leggett <benjamin.leggett@solo.io> * Update content/en/docs/ops/ambient/upgrade/helm-upgrade/index.md Co-authored-by: Faseela K <k.faseela@gmail.com> * Update content/en/docs/ops/ambient/upgrade/helm-upgrade/index.md Co-authored-by: Faseela K <k.faseela@gmail.com> * Update content/en/docs/ops/ambient/upgrade/helm-upgrade/index.md Co-authored-by: Faseela K <k.faseela@gmail.com> * Update content/en/docs/ops/ambient/upgrade/helm-upgrade/index.md Co-authored-by: Faseela K <k.faseela@gmail.com> * Update content/en/docs/ops/ambient/upgrade/helm-upgrade/index.md Co-authored-by: Faseela K <k.faseela@gmail.com> * Update content/en/docs/ops/ambient/upgrade/helm-upgrade/index.md Co-authored-by: Faseela K <k.faseela@gmail.com> * Update content/en/docs/ops/ambient/upgrade/helm-upgrade/index.md Co-authored-by: Faseela K <k.faseela@gmail.com> * Fix typo Signed-off-by: Benjamin Leggett <benjamin.leggett@solo.io> * Update content/en/docs/ops/ambient/upgrade/helm-upgrade/index.md Co-authored-by: John Howard <howardjohn@google.com> * Reword the warning a bit to contrast with sidecars Signed-off-by: Benjamin Leggett <benjamin.leggett@solo.io> --------- Signed-off-by: Benjamin Leggett <benjamin.leggett@solo.io> Co-authored-by: Lin Sun <lin.sun@solo.io> Co-authored-by: Faseela K <k.faseela@gmail.com> Co-authored-by: John Howard <howardjohn@google.com>
This commit is contained in:
Ben Leggett
GitHub
parent
e7c1d0e373
commit
678d523f1b
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
title: Ambient Mesh Architecture
|
||||
description: Deep dive into ambient mesh architecture.
|
||||
weight: 3
|
||||
weight: 20
|
||||
owner: istio/wg-networking-maintainers
|
||||
test: n/a
|
||||
---
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
title: Installation Guide
|
||||
description: Installation guide for Istio Ambient mesh.
|
||||
weight: 2
|
||||
weight: 5
|
||||
owner: istio/wg-environment-maintainers
|
||||
test: n/a
|
||||
---
|
||||
|
|
|
|||
|
|
@ -65,9 +65,22 @@ The `ztunnel` chart installs the ztunnel DaemonSet, which is the node-proxy comp
|
|||
$ helm install ztunnel istio/ztunnel -n istio-system
|
||||
{{< /text >}}
|
||||
|
||||
### (Optional) Install an ingress gateway
|
||||
|
||||
{{< warning >}}
|
||||
The namespace the gateway is deployed in must not have a `istio-injection=disabled` label.
|
||||
See [Controlling the injection policy](/docs/setup/additional-setup/sidecar-injection/#controlling-the-injection-policy) for more info.
|
||||
{{< /warning >}}
|
||||
|
||||
{{< text syntax=bash snip_id=install_ingress >}}
|
||||
$ helm install istio-ingress istio/gateway -n istio-ingress --wait --create-namespace
|
||||
{{< /text >}}
|
||||
|
||||
See [Installing Gateways](/docs/setup/additional-setup/gateway/) for in-depth documentation on gateway installation.
|
||||
|
||||
## Configuration
|
||||
|
||||
To view support configuration options and documentation, run:
|
||||
To view supported configuration options and documentation, run:
|
||||
|
||||
{{< text syntax=bash >}}
|
||||
$ helm show values istio/istiod
|
||||
|
|
@ -112,7 +125,7 @@ installed above.
|
|||
|
||||
1. (Optional) Delete any Istio gateway chart installations:
|
||||
|
||||
{{< text syntax=bash >}}
|
||||
{{< text syntax=bash snip_id=delete_ingress >}}
|
||||
$ helm delete istio-ingress -n istio-ingress
|
||||
$ kubectl delete namespace istio-ingress
|
||||
{{< /text >}}
|
||||
|
|
@ -152,7 +165,7 @@ installed above.
|
|||
This will delete all created Istio resources.
|
||||
{{< /warning >}}
|
||||
|
||||
{{< text syntax=bash >}}
|
||||
{{< text syntax=bash snip_id=delete_crds >}}
|
||||
$ kubectl get crd -oname | grep --color=never 'istio.io' | xargs kubectl delete
|
||||
{{< /text >}}
|
||||
|
||||
|
|
|
|||
|
|
@ -41,6 +41,10 @@ snip_install_ztunnel() {
|
|||
helm install ztunnel istio/ztunnel -n istio-system
|
||||
}
|
||||
|
||||
snip_install_ingress() {
|
||||
helm install istio-ingress istio/gateway -n istio-ingress --wait --create-namespace
|
||||
}
|
||||
|
||||
snip_configuration_1() {
|
||||
helm show values istio/istiod
|
||||
}
|
||||
|
|
@ -63,7 +67,7 @@ istio-base istio-system 1 ... ... ... ... deployed base-1.0.0 1.0.0
|
|||
istiod istio-system 1 ... ... ... ... deployed istiod-1.0.0 1.0.0
|
||||
ENDSNIP
|
||||
|
||||
snip_uninstall_2() {
|
||||
snip_delete_ingress() {
|
||||
helm delete istio-ingress -n istio-ingress
|
||||
kubectl delete namespace istio-ingress
|
||||
}
|
||||
|
|
@ -84,7 +88,7 @@ snip_delete_base() {
|
|||
helm delete istio-base -n istio-system
|
||||
}
|
||||
|
||||
snip_uninstall_7() {
|
||||
snip_delete_crds() {
|
||||
kubectl get crd -oname | grep --color=never 'istio.io' | xargs kubectl delete
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -32,6 +32,9 @@ _wait_for_daemonset istio-system istio-cni-node
|
|||
_rewrite_helm_repo snip_install_ztunnel
|
||||
_wait_for_daemonset istio-system ztunnel
|
||||
|
||||
_rewrite_helm_repo snip_install_ingress
|
||||
_wait_for_deployment istio-ingress istio-ingress
|
||||
|
||||
# shellcheck disable=SC2154
|
||||
_verify_contains snip_check_pods "istiod"
|
||||
_verify_contains snip_check_pods "istio-cni-node"
|
||||
|
|
@ -43,3 +46,4 @@ snip_delete_ztunnel
|
|||
snip_delete_discovery
|
||||
snip_delete_base
|
||||
snip_delete_system_namespace
|
||||
snip_delete_ingress
|
||||
|
|
|
|||
|
|
@ -0,0 +1,7 @@
|
|||
---
|
||||
title: Upgrade Guide
|
||||
description: Upgrade guide for Istio Ambient mesh.
|
||||
weight: 10
|
||||
owner: istio/wg-environment-maintainers
|
||||
test: n/a
|
||||
---
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
#!/usr/bin/env bash
|
||||
# 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.
|
||||
source "content/en/docs/ops/ambient/install/helm-installation/snips.sh"
|
||||
|
||||
_install_istio_ambient_helm() {
|
||||
snip_configure_helm
|
||||
_rewrite_helm_repo snip_install_base
|
||||
_rewrite_helm_repo snip_install_discovery
|
||||
_wait_for_deployment istio-system istiod
|
||||
_rewrite_helm_repo snip_install_cni
|
||||
_wait_for_daemonset istio-system istio-cni-node
|
||||
_rewrite_helm_repo snip_install_ztunnel
|
||||
_wait_for_daemonset istio-system ztunnel
|
||||
_rewrite_helm_repo snip_install_ingress
|
||||
_wait_for_deployment istio-ingress istio-ingress
|
||||
}
|
||||
|
||||
_remove_istio_ambient_helm() {
|
||||
snip_delete_cni
|
||||
snip_delete_ztunnel
|
||||
snip_delete_discovery
|
||||
snip_delete_base
|
||||
snip_delete_system_namespace
|
||||
snip_delete_ingress
|
||||
snip_delete_crds
|
||||
}
|
||||
|
|
@ -0,0 +1,132 @@
|
|||
---
|
||||
title: Upgrade with Helm
|
||||
description: How to upgrade Ambient Mesh with Helm.
|
||||
weight: 5
|
||||
owner: istio/wg-environments-maintainers
|
||||
test: yes
|
||||
status: Experimental
|
||||
---
|
||||
|
||||
Follow this guide to upgrade and configure ambient mesh using
|
||||
[Helm](https://helm.sh/docs/). This guide assumes you have already performed an ambient mesh
|
||||
[installation with Helm](/docs/ops/ambient/install/helm-installation/) with a previous minor or patch version of Istio.
|
||||
|
||||
{{< boilerplate ambient-alpha-warning >}}
|
||||
|
||||
{{< warning >}}
|
||||
In contrast to sidecar mode, `Ambient` supports moving application pods to an upgraded data plane without a mandatory restart or reschedule of running application pods. However, upgrading the data plane **will** briefly disrupt all workload traffic on the upgraded node, and ambient does not currently support canary upgrades of the data plane.
|
||||
|
||||
Node cordoning and blue/green node pools are recommended to control blast radius of application pod traffic disruption during production upgrades. See your Kubernetes provider documentation for details.
|
||||
{{< /warning >}}
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. Install ambient mesh with Helm by following [Install with Helm](/docs/ops/ambient/install/helm-installation/) and meeting all prerequisites in that guide.
|
||||
|
||||
1. Update the Helm repository:
|
||||
|
||||
{{< text syntax=bash snip_id=update_helm >}}
|
||||
$ helm repo update istio
|
||||
{{< /text >}}
|
||||
|
||||
## In-place upgrade
|
||||
|
||||
You can perform an in place upgrade of Istio in your cluster using the Helm
|
||||
upgrade workflow.
|
||||
|
||||
Before upgrading Istio, it is recommended to run the `istioctl x precheck` command to make sure the upgrade is compatible with your environment.
|
||||
|
||||
{{< text syntax=bash snip_id=istioctl_precheck >}}
|
||||
$ istioctl x precheck
|
||||
✔ No issues found when checking the cluster. Istio is safe to install or upgrade!
|
||||
To get started, check out <https://istio.io/latest/docs/setup/getting-started/>
|
||||
{{< /text >}}
|
||||
|
||||
{{< warning >}}
|
||||
[Helm does not upgrade or delete CRDs](https://helm.sh/docs/chart_best_practices/custom_resource_definitions/#some-caveats-and-explanations) when performing an upgrade. Because of this restriction, an additional step is required when upgrading Istio with Helm.
|
||||
{{< /warning >}}
|
||||
|
||||
### Manually upgrade the CRDs and Istio base chart
|
||||
|
||||
1. Upgrade the Kubernetes custom resource definitions ({{< gloss >}}CRDs{{</ gloss >}}):
|
||||
|
||||
{{< text syntax=bash snip_id=manual_crd_upgrade >}}
|
||||
$ kubectl apply -f manifests/charts/base/crds
|
||||
{{< /text >}}
|
||||
|
||||
1. Upgrade the Istio base chart:
|
||||
|
||||
{{< text syntax=bash snip_id=upgrade_base >}}
|
||||
$ helm upgrade istio-base manifests/charts/base -n istio-system --skip-crds
|
||||
{{< /text >}}
|
||||
|
||||
### Upgrade the Istio discovery Component
|
||||
|
||||
Istiod is the control plane component that manages and configures the proxies to route traffic within the ambient mesh.
|
||||
|
||||
{{< text syntax=bash snip_id=upgrade_istiod >}}
|
||||
$ helm upgrade istiod istio/istiod -n istio-system
|
||||
{{< /text >}}
|
||||
|
||||
### Upgrade the ztunnel component
|
||||
|
||||
The ztunnel DaemonSet is the L4 node-proxy component of ambient.
|
||||
|
||||
{{< 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.
|
||||
{{< /warning >}}
|
||||
|
||||
{{< text syntax=bash snip_id=upgrade_ztunnel >}}
|
||||
$ helm upgrade ztunnel istio/ztunnel -n istio-system
|
||||
{{< /text >}}
|
||||
|
||||
### Upgrade the CNI Component
|
||||
|
||||
The Istio CNI agent is responsible for detecting the pods that belong to the ambient mesh, and configuring the traffic redirection between pods and the ztunnel DaemonSet. It is not part of the data plane or control plane.
|
||||
|
||||
The Istio CNI agent at version 1.x is compatible with control plane at version 1.x-1, 1.x, and 1.x+1, which means the Istio CNI agent and the Istio control plane can be upgraded independently and in any order, as long as their version difference is within one minor version.
|
||||
|
||||
{{< warning >}}
|
||||
Upgrading the Istio CNI agent will reconfigure networking on the node, and as such will momentarily disrupt node traffic. To manage blast radius to application pods during Istio CNI agent upgrade, node cordons are recommended.
|
||||
{{< /warning >}}
|
||||
|
||||
{{< text syntax=bash snip_id=upgrade_cni >}}
|
||||
$ helm upgrade istio-cni istio/cni -n istio-system
|
||||
{{< /text >}}
|
||||
|
||||
### (Optional) Upgrade the Gateway component
|
||||
|
||||
Gateway components manage east-west and north-south dataplane traffic between ambient mesh boundaries, as well as some aspects of the L7 dataplane.
|
||||
|
||||
{{< text syntax=bash snip_id=upgrade_gateway >}}
|
||||
$ helm upgrade istio-ingress istio/gateway -n istio-ingress
|
||||
{{< /text >}}
|
||||
|
||||
## Configuration
|
||||
|
||||
To view supported configuration options and documentation, run:
|
||||
|
||||
{{< text syntax=bash snip_id=show_istiod_values >}}
|
||||
$ helm show values istio/istiod
|
||||
{{< /text >}}
|
||||
|
||||
## Verify the Installation
|
||||
|
||||
### Verify the workload status
|
||||
|
||||
After installing all the components, you can check the Helm deployment status with:
|
||||
|
||||
{{< text syntax=bash snip_id=show_components >}}
|
||||
$ helm list -n istio-system
|
||||
{{< /text >}}
|
||||
|
||||
You can check the status of the deployed Istio pods with:
|
||||
|
||||
{{< text syntax=bash snip_id=check_pods >}}
|
||||
$ kubectl get pods -n istio-system
|
||||
{{< /text >}}
|
||||
|
||||
## Uninstall
|
||||
|
||||
Please refer to the uninstall section in our [Helm ambient install guide](/docs/ops/ambient/install/helm-installation/#uninstall).
|
||||
|
|
@ -0,0 +1,70 @@
|
|||
#!/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/ops/ambient/upgrade/helm-upgrade/index.md
|
||||
####################################################################################################
|
||||
|
||||
snip_update_helm() {
|
||||
helm repo update istio
|
||||
}
|
||||
|
||||
snip_istioctl_precheck() {
|
||||
istioctl x precheck
|
||||
}
|
||||
|
||||
! read -r -d '' snip_istioctl_precheck_out <<\ENDSNIP
|
||||
✔ No issues found when checking the cluster. Istio is safe to install or upgrade!
|
||||
To get started, check out <https://istio.io/latest/docs/setup/getting-started/>
|
||||
ENDSNIP
|
||||
|
||||
snip_manual_crd_upgrade() {
|
||||
kubectl apply -f manifests/charts/base/crds
|
||||
}
|
||||
|
||||
snip_upgrade_base() {
|
||||
helm upgrade istio-base manifests/charts/base -n istio-system --skip-crds
|
||||
}
|
||||
|
||||
snip_upgrade_istiod() {
|
||||
helm upgrade istiod istio/istiod -n istio-system
|
||||
}
|
||||
|
||||
snip_upgrade_ztunnel() {
|
||||
helm upgrade ztunnel istio/ztunnel -n istio-system
|
||||
}
|
||||
|
||||
snip_upgrade_cni() {
|
||||
helm upgrade istio-cni istio/cni -n istio-system
|
||||
}
|
||||
|
||||
snip_upgrade_gateway() {
|
||||
helm upgrade istio-ingress istio/gateway -n istio-ingress
|
||||
}
|
||||
|
||||
snip_show_istiod_values() {
|
||||
helm show values istio/istiod
|
||||
}
|
||||
|
||||
snip_show_components() {
|
||||
helm list -n istio-system
|
||||
}
|
||||
|
||||
snip_check_pods() {
|
||||
kubectl get pods -n istio-system
|
||||
}
|
||||
|
|
@ -0,0 +1,42 @@
|
|||
#!/usr/bin/env bash
|
||||
# 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
|
||||
|
||||
source "content/en/docs/ops/ambient/upgrade/helm-upgrade/common.sh"
|
||||
|
||||
# @setup profile=none
|
||||
_install_istio_ambient_helm
|
||||
|
||||
snip_update_helm
|
||||
snip_istioctl_precheck
|
||||
snip_manual_crd_upgrade
|
||||
|
||||
_rewrite_helm_repo snip_upgrade_base
|
||||
_rewrite_helm_repo snip_upgrade_istiod
|
||||
_wait_for_deployment istio-system istiod
|
||||
_rewrite_helm_repo snip_upgrade_ztunnel
|
||||
_wait_for_daemonset istio-system ztunnel
|
||||
_rewrite_helm_repo snip_upgrade_cni
|
||||
_wait_for_daemonset istio-system istio-cni-node
|
||||
_rewrite_helm_repo snip_upgrade_gateway
|
||||
_wait_for_deployment istio-ingress istio-ingress
|
||||
|
||||
|
||||
# @cleanup
|
||||
_remove_istio_ambient_helm
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
title: Ambient Mesh User Guides
|
||||
description: How to use ambient mesh.
|
||||
weight: 2
|
||||
weight: 15
|
||||
owner: istio/wg-networking-maintainers
|
||||
test: n/a
|
||||
---
|
||||
|
|
|
|||
|
|
@ -6,11 +6,7 @@ owner: istio/wg-networking-maintainers
|
|||
test: no
|
||||
---
|
||||
|
||||
{{< warning >}}
|
||||
`Ambient` is currently in [alpha status](/docs/releases/feature-stages/#feature-phase-definitions).
|
||||
|
||||
Please **do not run ambient in production** and be sure to thoroughly review the [feature phase definitions](/docs/releases/feature-stages/#feature-phase-definitions) before use. In particular, there are known performance, stability, and security issues in the `alpha` release. There are also functional caveats some of which are listed in the [Caveats section](#caveats) of this guide. There are also planned breaking changes, including some that will prevent upgrades. These are all limitations that will be addressed before graduation to `beta`. The current version of this guide is meant to assist early deployments and testing of the alpha version of ambient. This guide will be updated as ambient itself evolves from alpha to beta status and beyond.
|
||||
{{< /warning >}}
|
||||
{{< boilerplate ambient-alpha-warning >}}
|
||||
|
||||
## Introduction {#introsection}
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue