From e09da17b08b5dc1a86afc3a7eaab30520a7baf86 Mon Sep 17 00:00:00 2001 From: Francisco H Date: Mon, 2 Jun 2025 16:24:49 +0000 Subject: [PATCH 1/3] Docs: adding HA istiod documentations Signed-off-by: Francisco H Adding missing file from mage gen Signed-off-by: Francisco H Fix spelling Signed-off-by: Francisco H Apply suggestions from code review Co-authored-by: Nick Fox <6226732+nrfox@users.noreply.github.com> Signed-off-by: Francisco H Update from review Signed-off-by: Francisco H Addin doc test for HA, improve from review Signed-off-by: Francisco H Fix istiod ha doc test Signed-off-by: Francisco H Fix istiod ha doc test Signed-off-by: Francisco H --- docs/README.md | 7 + docs/general/istiod-ha.md | 127 +++++++++++++++++++ tests/documentation_tests/README-runme.md | 7 + tests/documentation_tests/istiod-ha-runme.md | 127 +++++++++++++++++++ 4 files changed, 268 insertions(+) create mode 100644 docs/general/istiod-ha.md create mode 100644 tests/documentation_tests/istiod-ha-runme.md diff --git a/docs/README.md b/docs/README.md index 59ab184705..88f7953b9e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,6 +6,9 @@ - [User Documentation](#user-documentation) - [Concepts](#concepts) - [Istio resource](#istio-resource) + - [Istiod in HA mode](general/istiod-ha.md#Running–Istiod-in-HA-mode) + - [Setting up Istiod in HA mode: using fixed replicas](general/istiod-ha.md#Setting-up-Istiod-in-HA-mode:-increasing-replicaCount) + - [Setting up Istiod in HA mode: using autoscaling](general/istiod-ha.md#Setting-up-Istiod-in-HA-mode:-using-autoscaling) - [IstioRevision resource](#istiorevision-resource) - [IstioRevisionTag resource](#istiorevisiontag-resource) - [IstioCNI resource](#istiocni-resource) @@ -23,6 +26,7 @@ - [Update Strategy](#update-strategy) - [InPlace](#inplace) - [Example using the InPlace strategy](#example-using-the-inplace-strategy) + - [Recommendations for InPlace strategy](#recommendations-for-inplace-strategy) - [RevisionBased](#revisionbased) - [Example using the RevisionBased strategy](#example-using-the-revisionbased-strategy) - [Example using the RevisionBased strategy and an IstioRevisionTag](#example-using-the-revisionbased-strategy-and-an-istiorevisiontag) @@ -547,6 +551,9 @@ Steps: with_retries pods_istio_version_match "bookinfo" "1.26.0" ``` --> +#### Recommendations for InPlace Strategy +During `InPlace` updates, the control plane pods are restarted, which may cause temporary service disruptions. To minimize downtime during updates, we recommend configuring the `istiod` deployment with high availability (HA). For more information, please refer to this [guide](general/istiod-ha.md). + ### RevisionBased When the `RevisionBased` strategy is used, a new Istio control plane instance is created for every change to the `Istio.spec.version` field. The old control plane remains in place until all workloads have been moved to the new control plane instance. This needs to be done by the user by updating the namespace label and restarting all the pods. The old control plane will be deleted after the grace period specified in the `Istio` resource field `spec.updateStrategy.inactiveRevisionDeletionGracePeriodSeconds`. diff --git a/docs/general/istiod-ha.md b/docs/general/istiod-ha.md new file mode 100644 index 0000000000..82ba4c2750 --- /dev/null +++ b/docs/general/istiod-ha.md @@ -0,0 +1,127 @@ +# Running Istiod in HA mode +Please follow this guide to run Istiod in HA mode. By default, istiod is deployed with replica count set to 1, to be able to run it in HA mode, you can achieve it in two different ways: +* Setting `replicaCount` to 2 or more in Istio resource and disabling autoscale (by default enabled). +* Setting `autoscaleMin` to 2 or more in Istio resource and keeping `autoscaleMax` to 2 or more. + +Pros and Cons of each approach: +- **Setting `replicaCount` to 2 or more**: + - Pros: Simplicity, easy to understand and manage. Since this approach disables Pod Disruption Budget (PDB), it is recommended for cluster with single node cluster or clusters with only one worker node. + - Cons: Fixed number of replicas, no autoscaling based on load. +- **Setting `autoscaleMin` to 2 or more**: + - Pros: Autoscaling based on load, can handle increased traffic without manual intervention, more efficient resource usage. + - Cons: Requires monitoring to ensure proper scaling. + +Now, let's see how to achieve this in Sail. + +# Prerequisites +- Sail Operator installed and running in your cluster. +- kubernetes client configured to access your cluster. + +## Setting up Istiod in HA mode: increasing replicaCount +To set up Istiod in HA mode by increasing the `replicaCount`, you can create/modify the Istio resource: +```yaml +apiVersion: sailoperator.io/v1 +kind: Istio +metadata: + name: default +spec: + namespace: istio-system + values: + global: + defaultPodDisruptionBudget: + enabled: false # <-- disable default PDB + pilot: + autoscaleEnabled: false # <-- disable autoscaling + replicaCount: 2 # <-- number of desired replicas +``` + + +After applying this configuration, you can check the status of the Istiod pods: +```bash +kubectl get pods -n istio-system -l app=istiod +``` +You should see two pods running, indicating that Istiod is now in HA mode. +```console +NAME READY STATUS RESTARTS AGE +istiod-7c5947b8d7-88z7m 1/1 Running 0 14m +istiod-7c5947b8d7-ssnmt 1/1 Running 0 54m +``` + + +Let's break down the configuration: +- `spec.values.pilot.replicaCount: 2`: This sets the number of Istiod replicas to 2 (or the desired value), enabling HA mode. +- `spec.values.pilot.autoscaleEnabled: false`: This disables autoscaling, ensuring that the number of replicas remains fixed at 2 (or the desired value). +- `spec.global.defaultPodDisruptionBudget.enabled: false`: This disables the default Pod Disruption Budget, which can cause issues with scaling in HA mode. + +## Setting up Istiod in HA mode: using autoscaling +To set up Istiod in HA mode using autoscaling, you can create/modify the Istio resource as follows: +```yaml +apiVersion: sailoperator.io/v1 +kind: Istio +metadata: + name: default +spec: + namespace: istio-system + values: + pilot: + autoscaleMin: 2 # <-- number of desired min replicas + autoscaleMax: 5 # <-- number of desired max replicas +``` + + +After applying this configuration, you can check the status of the Istiod pods: +```bash +kubectl get pods -n istio-system -l app=istiod +``` +You should see at least two pods running, indicating that Istiod is now in HA mode. +```console +NAME READY STATUS RESTARTS AGE +istiod-7c7b6564c9-nwhsg 1/1 Running 0 70s +istiod-7c7b6564c9-xkmsl 1/1 Running 0 85s +``` + +Let's break down the configuration: +- `spec.values.pilot.autoscaleMin: 2`: This sets the minimum number of Istiod replicas to 2, ensuring that there are always at least 2 replicas running. +- `spec.values.pilot.autoscaleMax: 5`: This sets the maximum number of Istiod replicas to 5, allowing for scaling based on load. + diff --git a/tests/documentation_tests/README-runme.md b/tests/documentation_tests/README-runme.md index 7f1eb98130..7e4cc2e8a7 100644 --- a/tests/documentation_tests/README-runme.md +++ b/tests/documentation_tests/README-runme.md @@ -6,6 +6,9 @@ - [User Documentation](#user-documentation) - [Concepts](#concepts) - [Istio resource](#istio-resource) + - [Istiod in HA mode](general/istiod-ha.md#Running–Istiod-in-HA-mode) + - [Setting up Istiod in HA mode: using fixed replicas](general/istiod-ha.md#Setting-up-Istiod-in-HA-mode:-increasing-replicaCount) + - [Setting up Istiod in HA mode: using autoscaling](general/istiod-ha.md#Setting-up-Istiod-in-HA-mode:-using-autoscaling) - [IstioRevision resource](#istiorevision-resource) - [IstioRevisionTag resource](#istiorevisiontag-resource) - [IstioCNI resource](#istiocni-resource) @@ -23,6 +26,7 @@ - [Update Strategy](#update-strategy) - [InPlace](#inplace) - [Example using the InPlace strategy](#example-using-the-inplace-strategy) + - [Recommendations for InPlace strategy](#recommendations-for-inplace-strategy) - [RevisionBased](#revisionbased) - [Example using the RevisionBased strategy](#example-using-the-revisionbased-strategy) - [Example using the RevisionBased strategy and an IstioRevisionTag](#example-using-the-revisionbased-strategy-and-an-istiorevisiontag) @@ -547,6 +551,9 @@ Steps: with_retries pods_istio_version_match "bookinfo" "1.26.0" ``` +#### Recommendations for InPlace Strategy +During `InPlace` updates, the control plane pods are restarted, which may cause temporary service disruptions. To minimize downtime during updates, we recommend configuring the `istiod` deployment with high availability (HA). For more information, please refer to this [guide](general/istiod-ha.md). + ### RevisionBased When the `RevisionBased` strategy is used, a new Istio control plane instance is created for every change to the `Istio.spec.version` field. The old control plane remains in place until all workloads have been moved to the new control plane instance. This needs to be done by the user by updating the namespace label and restarting all the pods. The old control plane will be deleted after the grace period specified in the `Istio` resource field `spec.updateStrategy.inactiveRevisionDeletionGracePeriodSeconds`. diff --git a/tests/documentation_tests/istiod-ha-runme.md b/tests/documentation_tests/istiod-ha-runme.md new file mode 100644 index 0000000000..7bdfe24237 --- /dev/null +++ b/tests/documentation_tests/istiod-ha-runme.md @@ -0,0 +1,127 @@ +# Running Istiod in HA mode +Please follow this guide to run Istiod in HA mode. By default, istiod is deployed with replica count set to 1, to be able to run it in HA mode, you can achieve it in two different ways: +* Setting `replicaCount` to 2 or more in Istio resource and disabling autoscale (by default enabled). +* Setting `autoscaleMin` to 2 or more in Istio resource and keeping `autoscaleMax` to 2 or more. + +Pros and Cons of each approach: +- **Setting `replicaCount` to 2 or more**: + - Pros: Simplicity, easy to understand and manage. Since this approach disables Pod Disruption Budget (PDB), it is recommended for cluster with single node cluster or clusters with only one worker node. + - Cons: Fixed number of replicas, no autoscaling based on load. +- **Setting `autoscaleMin` to 2 or more**: + - Pros: Autoscaling based on load, can handle increased traffic without manual intervention, more efficient resource usage. + - Cons: Requires monitoring to ensure proper scaling. + +Now, let's see how to achieve this in Sail. + +# Prerequisites +- Sail Operator installed and running in your cluster. +- kubernetes client configured to access your cluster. + +## Setting up Istiod in HA mode: increasing replicaCount +To set up Istiod in HA mode by increasing the `replicaCount`, you can create/modify the Istio resource: +```yaml +apiVersion: sailoperator.io/v1 +kind: Istio +metadata: + name: default +spec: + namespace: istio-system + values: + global: + defaultPodDisruptionBudget: + enabled: false # <-- disable default PDB + pilot: + autoscaleEnabled: false # <-- disable autoscaling + replicaCount: 2 # <-- number of desired replicas +``` +```bash { name=validation-istio-expected-version tag=istio-ha-replicacount } +kubectl create ns istio-system +cat < Date: Wed, 4 Jun 2025 08:56:30 +0000 Subject: [PATCH 2/3] Update from review Signed-off-by: Francisco H --- docs/general/istiod-ha.md | 30 ++++++++++++-------- tests/documentation_tests/istiod-ha-runme.md | 30 ++++++++++++-------- 2 files changed, 36 insertions(+), 24 deletions(-) diff --git a/docs/general/istiod-ha.md b/docs/general/istiod-ha.md index 82ba4c2750..62158ab039 100644 --- a/docs/general/istiod-ha.md +++ b/docs/general/istiod-ha.md @@ -1,12 +1,12 @@ # Running Istiod in HA mode -Please follow this guide to run Istiod in HA mode. By default, istiod is deployed with replica count set to 1, to be able to run it in HA mode, you can achieve it in two different ways: +By default, istiod is deployed with replica count set to 1, to be able to run it in HA mode, you can achieve it in two different ways: * Setting `replicaCount` to 2 or more in Istio resource and disabling autoscale (by default enabled). * Setting `autoscaleMin` to 2 or more in Istio resource and keeping `autoscaleMax` to 2 or more. Pros and Cons of each approach: - **Setting `replicaCount` to 2 or more**: - - Pros: Simplicity, easy to understand and manage. Since this approach disables Pod Disruption Budget (PDB), it is recommended for cluster with single node cluster or clusters with only one worker node. - - Cons: Fixed number of replicas, no autoscaling based on load. + - Pros: Simplicity, easy to understand and manage. + - Cons: Fixed number of replicas, no autoscaling based on load. For single-node clusters, you may need to disable the default Pod Disruption Budget (PDB) as outlined in the [Considerations for Single-Node Clusters ](#considerations-for-single-node-clusters) section. - **Setting `autoscaleMin` to 2 or more**: - Pros: Autoscaling based on load, can handle increased traffic without manual intervention, more efficient resource usage. - Cons: Requires monitoring to ensure proper scaling. @@ -26,10 +26,6 @@ metadata: name: default spec: namespace: istio-system - values: - global: - defaultPodDisruptionBudget: - enabled: false # <-- disable default PDB pilot: autoscaleEnabled: false # <-- disable autoscaling replicaCount: 2 # <-- number of desired replicas @@ -43,10 +39,6 @@ metadata: name: default spec: namespace: istio-system - values: - global: - defaultPodDisruptionBudget: - enabled: false # <-- disable default PDB pilot: autoscaleEnabled: false # <-- disable autoscaling replicaCount: 2 # <-- number of desired replicas @@ -73,7 +65,6 @@ istiod-7c5947b8d7-ssnmt 1/1 Running 0 54m Let's break down the configuration: - `spec.values.pilot.replicaCount: 2`: This sets the number of Istiod replicas to 2 (or the desired value), enabling HA mode. - `spec.values.pilot.autoscaleEnabled: false`: This disables autoscaling, ensuring that the number of replicas remains fixed at 2 (or the desired value). -- `spec.global.defaultPodDisruptionBudget.enabled: false`: This disables the default Pod Disruption Budget, which can cause issues with scaling in HA mode. ## Setting up Istiod in HA mode: using autoscaling To set up Istiod in HA mode using autoscaling, you can create/modify the Istio resource as follows: @@ -125,3 +116,18 @@ Let's break down the configuration: - `spec.values.pilot.autoscaleMin: 2`: This sets the minimum number of Istiod replicas to 2, ensuring that there are always at least 2 replicas running. - `spec.values.pilot.autoscaleMax: 5`: This sets the maximum number of Istiod replicas to 5, allowing for scaling based on load. +## Considerations for Single-Node Clusters +For single-node clusters, it is crucial to disable the default Pod Disruption Budget (PDB) to prevent issues during node operations (e.g., draining) or scaling in HA mode. You can do this by adding the following configuration to your Istio resource: +```yaml +apiVersion: sailoperator.io/v1 +kind: Istio +metadata: + name: default +spec: + namespace: istio-system + global: + defaultPodDisruptionBudget: + enabled: false # <-- disable default Pod Disruption Budget +``` + +`spec.global.defaultPodDisruptionBudget.enabled: false` disables the default Pod Disruption Budget for Istiod. In single-node clusters, a PDB can block operations such as node drains or pod evictions, as it prevents the number of available Istiod replicas from falling below the PDB's minimum desired count. Disabling it ensures smooth operations in this specific topology. diff --git a/tests/documentation_tests/istiod-ha-runme.md b/tests/documentation_tests/istiod-ha-runme.md index 7bdfe24237..ecf7ef3760 100644 --- a/tests/documentation_tests/istiod-ha-runme.md +++ b/tests/documentation_tests/istiod-ha-runme.md @@ -1,12 +1,12 @@ # Running Istiod in HA mode -Please follow this guide to run Istiod in HA mode. By default, istiod is deployed with replica count set to 1, to be able to run it in HA mode, you can achieve it in two different ways: +By default, istiod is deployed with replica count set to 1, to be able to run it in HA mode, you can achieve it in two different ways: * Setting `replicaCount` to 2 or more in Istio resource and disabling autoscale (by default enabled). * Setting `autoscaleMin` to 2 or more in Istio resource and keeping `autoscaleMax` to 2 or more. Pros and Cons of each approach: - **Setting `replicaCount` to 2 or more**: - - Pros: Simplicity, easy to understand and manage. Since this approach disables Pod Disruption Budget (PDB), it is recommended for cluster with single node cluster or clusters with only one worker node. - - Cons: Fixed number of replicas, no autoscaling based on load. + - Pros: Simplicity, easy to understand and manage. + - Cons: Fixed number of replicas, no autoscaling based on load. For single-node clusters, you may need to disable the default Pod Disruption Budget (PDB) as outlined in the [Considerations for Single-Node Clusters ](#considerations-for-single-node-clusters) section. - **Setting `autoscaleMin` to 2 or more**: - Pros: Autoscaling based on load, can handle increased traffic without manual intervention, more efficient resource usage. - Cons: Requires monitoring to ensure proper scaling. @@ -26,10 +26,6 @@ metadata: name: default spec: namespace: istio-system - values: - global: - defaultPodDisruptionBudget: - enabled: false # <-- disable default PDB pilot: autoscaleEnabled: false # <-- disable autoscaling replicaCount: 2 # <-- number of desired replicas @@ -43,10 +39,6 @@ metadata: name: default spec: namespace: istio-system - values: - global: - defaultPodDisruptionBudget: - enabled: false # <-- disable default PDB pilot: autoscaleEnabled: false # <-- disable autoscaling replicaCount: 2 # <-- number of desired replicas @@ -73,7 +65,6 @@ istiod-7c5947b8d7-ssnmt 1/1 Running 0 54m Let's break down the configuration: - `spec.values.pilot.replicaCount: 2`: This sets the number of Istiod replicas to 2 (or the desired value), enabling HA mode. - `spec.values.pilot.autoscaleEnabled: false`: This disables autoscaling, ensuring that the number of replicas remains fixed at 2 (or the desired value). -- `spec.global.defaultPodDisruptionBudget.enabled: false`: This disables the default Pod Disruption Budget, which can cause issues with scaling in HA mode. ## Setting up Istiod in HA mode: using autoscaling To set up Istiod in HA mode using autoscaling, you can create/modify the Istio resource as follows: @@ -125,3 +116,18 @@ Let's break down the configuration: - `spec.values.pilot.autoscaleMin: 2`: This sets the minimum number of Istiod replicas to 2, ensuring that there are always at least 2 replicas running. - `spec.values.pilot.autoscaleMax: 5`: This sets the maximum number of Istiod replicas to 5, allowing for scaling based on load. +## Considerations for Single-Node Clusters +For single-node clusters, it is crucial to disable the default Pod Disruption Budget (PDB) to prevent issues during node operations (e.g., draining) or scaling in HA mode. You can do this by adding the following configuration to your Istio resource: +```yaml +apiVersion: sailoperator.io/v1 +kind: Istio +metadata: + name: default +spec: + namespace: istio-system + global: + defaultPodDisruptionBudget: + enabled: false # <-- disable default Pod Disruption Budget +``` + +`spec.global.defaultPodDisruptionBudget.enabled: false` disables the default Pod Disruption Budget for Istiod. In single-node clusters, a PDB can block operations such as node drains or pod evictions, as it prevents the number of available Istiod replicas from falling below the PDB's minimum desired count. Disabling it ensures smooth operations in this specific topology. From 5aa722b2c844374e580d710b835ee3cf010a8be9 Mon Sep 17 00:00:00 2001 From: Francisco H Date: Wed, 4 Jun 2025 09:27:32 +0000 Subject: [PATCH 3/3] Fix doc test error Signed-off-by: Francisco H --- docs/general/istiod-ha.md | 2 ++ tests/documentation_tests/istiod-ha-runme.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/docs/general/istiod-ha.md b/docs/general/istiod-ha.md index 62158ab039..af597d17fb 100644 --- a/docs/general/istiod-ha.md +++ b/docs/general/istiod-ha.md @@ -26,6 +26,7 @@ metadata: name: default spec: namespace: istio-system + values: pilot: autoscaleEnabled: false # <-- disable autoscaling replicaCount: 2 # <-- number of desired replicas @@ -39,6 +40,7 @@ metadata: name: default spec: namespace: istio-system + values: pilot: autoscaleEnabled: false # <-- disable autoscaling replicaCount: 2 # <-- number of desired replicas diff --git a/tests/documentation_tests/istiod-ha-runme.md b/tests/documentation_tests/istiod-ha-runme.md index ecf7ef3760..04d4e0d34b 100644 --- a/tests/documentation_tests/istiod-ha-runme.md +++ b/tests/documentation_tests/istiod-ha-runme.md @@ -26,6 +26,7 @@ metadata: name: default spec: namespace: istio-system + values: pilot: autoscaleEnabled: false # <-- disable autoscaling replicaCount: 2 # <-- number of desired replicas @@ -39,6 +40,7 @@ metadata: name: default spec: namespace: istio-system + values: pilot: autoscaleEnabled: false # <-- disable autoscaling replicaCount: 2 # <-- number of desired replicas