OSSM-4815: Document HA for a mesh #96010
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,14 @@ | ||
| // This module is used in the following assemblies: | ||
| // * service-mesh-docs-main/install/ossm-installing-service-mesh.adoc | ||
|
|
||
| :_mod-docs-content-type: CONCEPT | ||
| [id="ossm-about-istio-high-availability_{context}"] | ||
| = About Istio High Availability | ||
|
|
||
| Running the {istio} control plane in High Availability (HA) mode prevents single points of failure, and ensures continuous mesh operation even if an `istiod` pod fails. By using HA, if one `istiod` pod becomes unavailable, another one continues to manage and configure the {istio} data plane, preventing service outages or disruptions. HA provides scalability by distributing the control plane workload, enables graceful upgrades, supports disaster recovery operations, and protects against zone-wide mesh outages. | ||
|
|
||
| There are two ways for a system administrator to configure HA for the {istio} deployment: | ||
|
|
||
| * Defining a static replica count: This approach involves setting a fixed number of `istiod` pods, providing a consistent level of redundancy. | ||
|
|
||
| * Using autoscaling: This approach dynamically adjusts the number of `istiod` pods based on resource utilization or custom metrics, providing more efficient resource consumption for fluctuating workloads. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,30 @@ | ||||||
| // This module is used in the following assemblies: | ||||||
| // * service-mesh-docs-main/install/ossm-installing-service-mesh.adoc | ||||||
|
|
||||||
| :_mod-docs-content-type: REFERENCE | ||||||
| [id="ossm-api-settings-mesh-ha-autoscaling_{context}"] | ||||||
| = API settings for Service Mesh HA autoscaling mode | ||||||
|
|
||||||
| Use the following `istio` custom resource definition (CRD) parameters when you configure a service mesh for High Availability (HA) by using autoscaling. | ||||||
|
|
||||||
| .HA API parameters | ||||||
| [cols="1,1"] | ||||||
| |=== | ||||||
| |Parameter |Description | ||||||
|
|
||||||
| |`autoScaleMin` | Defines the minimum number of `istiod` pods for an istio deployment. Each pod contains one instance of the {istio} control plane. | ||||||
|
|
||||||
| {ocp-short-name} only uses this parameter when the Horizontal Pod Autoscaler (HPA) is enabled for the {istio} deployment. This is the default behavior. | ||||||
| |`autoScaleMax` | Defines the maximum number of `istiod` pods for an {istio} deployment. Each pod contains one instance of the {istio} control plane. | ||||||
|
|
||||||
| For {ocp-short-name} to automatically scale the number of `istiod` pods based on load, you must set this parameter to a value that is greater than the value that you defined for the `autoScaleMin` parameter. | ||||||
|
|
||||||
| You must also configure metrics for autoscaling to work properly. If no metrics are configured, the autoscaler does not scale up or down. | ||||||
|
|
||||||
| {ocp-short-name} only uses this parameter when Horizontal Pod Autoscaler (HPA) is enabled for the {istio} deployment. This is the default behavior. | ||||||
| |`cpu.targetAverageUtilization` | Defines the target CPU utilization for the `istiod` pod. If the average CPU usage exceeds the threshold that this parameter defines, the HPA automatically increases the number of replica pods. | ||||||
| |`memory.targetAverageUtilization` | Defines the target memory utilization for the `istiod` pod. If the average memory usage exceeds the threshold that this parameter defines, the HPA automatically increases the number of replica pods. | ||||||
| |`behavior` | You can use the `behavior` field to define additional policies that {ocp-short-name} uses to scale {istio} resources up or down. | ||||||
|
|
||||||
| For more information, see link:https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/#configurable-scaling-behavior[Configurable Scaling Behavior]. | ||||||
|
There was a problem hiding this comment.
Suggested change
Just a suggestion to provide the link in the "Additional resources" section rather than the module. I will update the suggestion in the assembly file as well. |
||||||
| |=== | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,20 @@ | ||||||
| // This module is used in the following assemblies: | ||||||
| // * service-mesh-docs-main/install/ossm-installing-service-mesh.adoc | ||||||
|
|
||||||
| :_mod-docs-content-type: REFERENCE | ||||||
| [id="ossm-api-settings-mesh-ha-replicacount_{context}"] | ||||||
| = API settings for Service Mesh HA replica count mode | ||||||
|
|
||||||
| Use the following `istio` custom resource definition (CRD) parameters when you configure a service mesh for High Availability (HA) by using replica count. | ||||||
|
|
||||||
| .HA API parameters | ||||||
| [cols="1,1"] | ||||||
| |=== | ||||||
| |Parameter |Description | ||||||
|
|
||||||
| |`replicaCount` | Defines the number of `istiod` pods for an istio deployment. Each pod contains one instance of the `istio` control plane. The default setting is `1`. | ||||||
|
There was a problem hiding this comment.
Suggested change
I have a confusion regarding the usage of the following:
I will leave it up to you to decide. My only suggestion is to make it consistent throughout and also the usage of {istio} attribute. |
||||||
|
|
||||||
| You must set `replicaCount` to a value of `2` or greater to support HA. | ||||||
|
|
||||||
| {ocp-short-name} only uses this parameter when the `istio` deployment does not use the Horizontal Pod Autoscaler (HPA) configuration. | ||||||
| |=== | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,72 @@ | ||
| // This procedure is used in the following assembly: | ||
| // * service-mesh-docs-main/install/ossm-installing-service-mesh.adoc | ||
|
|
||
| :_mod-docs-content-type: PROCEDURE | ||
| [id="ossm-configuring-istio-ha-autoscaling_{context}"] | ||
| = Configuring Istio HA by using autoscaling | ||
|
|
||
| Configure the {istio} control plane in High Availability (HA) mode to prevent a single point of failure, and ensure continuous mesh operation even if one of the `istiod` pods fails. Autoscaling defines the minimum and maximum number of {istio} control plane pods that can operate. {ocp-product-title} uses these values to scale the number of control planes in operation based on resource utilization, such as CPU or memory, to efficiently respond to the varying number of workloads and overall traffic patterns within the mesh. | ||
|
|
||
| .Prerequisites | ||
|
|
||
| * You are logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role. | ||
|
|
||
| * You have installed the {SMProductName} Operator. | ||
|
|
||
| * You have deployed the {istio} resource. | ||
|
|
||
| .Procedure | ||
|
|
||
| . In the {ocp-product-title} web console, click *Installed Operators*. | ||
|
|
||
| . Click {SMProductName} 3 Operator. | ||
|
|
||
| . Click *Istio*. | ||
|
|
||
| . Click the name of the {istio} installation. For example, `default`. | ||
|
|
||
| . Click *YAML*. | ||
|
|
||
| . Modify the `{istio}` custom resource (CR) similar to the following example: | ||
| + | ||
| .Example configuration | ||
| [source,yaml,subs="attributes,verbatim"] | ||
| ---- | ||
| apiVersion: sailoperator.io/v1 | ||
| kind: Istio | ||
| metadata: | ||
| name: default | ||
| spec: | ||
| namespace: istio-system | ||
| values: | ||
| pilot: | ||
| autoscaleMin: 2 # <1> | ||
| autoscaleMax: 5 # <2> | ||
| cpu: | ||
| targetAverageUtilization: 80 # <3> | ||
| memory: | ||
| targetAverageUtilization: 80 # <4> | ||
| ---- | ||
| <1> Specifies the minimum number of {istio} control plane replicas that always run. | ||
| <2> Specifies the maximum number of {istio} control plane replicas, allowing for scaling based on load. To support HA, there must be at least two replicas. | ||
| <3> Specifies the target CPU utilization for autoscaling to 80%. If the average CPU usage exceeds this threshold, the Horizontal Pod Autoscaler (HPA) automatically increases the number of replicas. | ||
| <4> Specifies the target memory utilization for autoscaling to 80%. If the average memory usage exceeds this threshold, the HPA automatically increases the number of replicas. | ||
|
|
||
| .Verification | ||
|
|
||
| * Verify the status of the {istio} control pods by running the following command: | ||
| + | ||
| [source,terminal] | ||
| ---- | ||
| $ oc get pods -n istio-system -l app=istiod | ||
| ---- | ||
| + | ||
| .Example output | ||
| [source,terminal] | ||
| ---- | ||
| NAME READY STATUS RESTARTS AGE | ||
| istiod-7c7b6564c9-nwhsg 1/1 Running 0 70s | ||
| istiod-7c7b6564c9-xkmsl 1/1 Running 0 85s | ||
| ---- | ||
| + | ||
| Two `istiod` pods are running. Two pods, the minimum requirement for an HA {istio} control plane, indicates that a basic HA setup is in place. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,68 @@ | ||||||
| // This procedure is used in the following assembly: | ||||||
| // * service-mesh-docs-main/install/ossm-installing-service-mesh.adoc | ||||||
|
|
||||||
| :_mod-docs-content-type: PROCEDURE | ||||||
| [id="ossm-configuring-istio-ha-replicacount_{context}"] | ||||||
| = Configuring Istio HA by using replica count | ||||||
|
|
||||||
| Configure the {istio} control plane in High Availability (HA) mode to prevent a single point of failure, and ensure continuous mesh operation even if one of the `istiod` pods fails. The replica count defines a fixed number of {istio} control plane pods that can operate. Use replica count for mesh environments where the control plane workload is relatively stable or predictable, or when you prefer to manually scale the `istiod` pod. | ||||||
|
|
||||||
| .Prerequisites | ||||||
|
|
||||||
| * You are logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role. | ||||||
|
|
||||||
| * You have installed the {SMProductName} Operator. | ||||||
|
|
||||||
| * You have deployed the {istio} resource. | ||||||
|
|
||||||
| .Procedure | ||||||
|
|
||||||
| . Obtain the name of the `{istio}` resource by running the following command: | ||||||
| + | ||||||
| [source,terminal] | ||||||
| ---- | ||||||
| $ oc get istio -n istio-sytem | ||||||
| ---- | ||||||
| + | ||||||
| .Example output | ||||||
| [source,terminal] | ||||||
| ---- | ||||||
| NAME REVISIONS READY IN USE ACTIVE REVISION STATUS VERSION AGE | ||||||
| default 1 1 0 default Healthy v1.24.6 24m | ||||||
| ---- | ||||||
| + | ||||||
| The name of the `{istio}` resource is `default`. | ||||||
|
|
||||||
| . Update the `{istio}` custom resource (CR) by adding the `autoscaleEnabled` and `replicaCount` parameters by running the following command: | ||||||
| + | ||||||
| [source,terminal] | ||||||
| ---- | ||||||
| $ oc patch istio default -n istio-system --type merge -p ' | ||||||
| spec: | ||||||
| values: | ||||||
| pilot: | ||||||
| autoscaleEnabled: false <1> | ||||||
| replicaCount: 2 <2> | ||||||
| ' | ||||||
| ---- | ||||||
| <1> Specifies a setting that disables autoscaling and ensures that the number of replicas remains fixed. | ||||||
| <2> Specifies the number of {istio} control plane replicas. To support HA, there must be at least two replicas. | ||||||
|
|
||||||
| .Verification | ||||||
|
|
||||||
| . Verify the status of the {Istio} control pods by running the following command: | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| + | ||||||
| [source,terminal] | ||||||
| ---- | ||||||
| $ oc get pods -n istio-system -l app=istiod | ||||||
| ---- | ||||||
| + | ||||||
| .Example output | ||||||
| [source,terminal] | ||||||
| ---- | ||||||
| NAME READY STATUS RESTARTS AGE | ||||||
| istiod-7c7b6564c9-nwhsg 1/1 Running 0 70s | ||||||
| istiod-7c7b6564c9-xkmsl 1/1 Running 0 85s | ||||||
| ---- | ||||||
| + | ||||||
| Two `istiod` pods are running, which is the minimum requirement for an HA {istio} control plane and indicates that a basic HA setup is in place. | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"By using HA, if one
istiodpod becomes unavailable, another one continues..."@rh-tokeefe does this make sense or it should be rephrased?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@FilipB "By using" conforms to the style guide.
All I'm trying to say here is "When using HA, if one
istiodpod becomes unavailable, another one continues to manage and configure the {istio} data plane, preventing service outages or disruptions."There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We can sync and chat if you'd like.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It's fine I was just not sure if it is good English grammar.