diff --git a/_attributes/common-attributes.adoc b/_attributes/common-attributes.adoc index 2998c668844c..6dbe49dfabc0 100644 --- a/_attributes/common-attributes.adoc +++ b/_attributes/common-attributes.adoc @@ -17,14 +17,14 @@ :SMProductName: Red{nbsp}Hat OpenShift Service Mesh :SMProduct: OpenShift Service Mesh :SMProductShortName: Service Mesh -:SMProductVersion: 3.1.2 +:SMProductVersion: 3.2.0 //service mesh v2 //Update when there is a new 2.6.z release :SMv2Version: 2.6.10 //SMv2Version must be updated with each 2.x release because users can only migrate from the latest 2.x.z version. Update 02/24/2025 for service-mesh-docs-3.0 //Istio :istio: Istio -:istio-latest: 1.26.4 +:istio-latest: 1.27.3 //update istio-latest as necessary //Kiali Operator :KialiProduct: Kiali Operator provided by Red{nbsp}Hat diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 383be24b0fe6..889e842e586c 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -91,8 +91,14 @@ Name: Updating Dir: update Distros: openshift-service-mesh Topics: +- Name: About updating OpenShift Service Mesh + File: ossm-about-updating-openshift-service-mesh - Name: Updating OpenShift Service Mesh File: ossm-updating-openshift-service-mesh +- Name: Updating OpenShift Service Mesh in ambient mode + File: ossm-updating-openshift-service-mesh-in-ambient-mode +- Name: Updating the Istio CNI + File: ossm-updating-istio-cni --- Name: Gateways Dir: gateways diff --git a/modules/ossm-about-istio-cni-update-process.adoc b/modules/ossm-about-istio-cni-update-process.adoc index 2e27da03be96..98d4be1607bb 100644 --- a/modules/ossm-about-istio-cni-update-process.adoc +++ b/modules/ossm-about-istio-cni-update-process.adoc @@ -6,10 +6,20 @@ [id="ossm-about-istio-cni-update-process_{context}"] = About the Istio CNI update process -The {istio} Container Network Interface (CNI) update process uses in-place updates. When the `IstioCNI` resource changes, the daemonset automatically replaces the existing `istio-cni-node` pods with the specified version of the CNI plugin. +[role="_abstract"] +The {istio} Container Network Interface (CNI) update process uses `Inplace` updates. When the `IstioCNI` resource changes, the daemonset automatically replaces the existing `istio-cni-node` pods with the specified version of the CNI plugin. You can use the following field to manage version updates: -`spec.version`:: defines the CNI plugin version to install. Specify the value in the format `vX.Y.Z`, where `X.Y.Z` represents the desired version. For example, use `v1.24.4` to install the CNI plugin version `1.24.4`. +`spec.version`:: defines the CNI plugin version to install. Specify the value in the format `vX.Y.Z`, where `X.Y.Z` represents the required version. For example, use `v{istio-latest}` to install the CNI plugin version `{istio-latest}`. -To update the CNI plugin, modify the `spec.version` field with the target version. The `IstioCNI` resource also includes a `values` field that exposes configuration options from the `istio-cni` chart. \ No newline at end of file +To update the CNI plugin, change the `spec.version` field with the target version. The `IstioCNI` resource also includes a `values` field that exposes configuration options from the `istio-cni` chart. + +In ambient mode, the {istio} CNI component manages traffic redirection. During `RevisionBased` upgrades, the component remains compatible with the control plane's old version and continues to manage traffic redirection for both the old and the new control planes throughout the migration. + +[NOTE] +==== +The {istio} CNI is compatible with a control plane running the same minor version or one minor version higher. +==== + +After you update the {istio} control plane, update the {istio} CNI component. The {SMProduct} Operator deploys a new version of the CNI plugin, replacing the existing one. The `istio-cni-node` DaemonSet pods update using a rolling update strategy, ensuring that traffic redirection rules remain active during the entire update process. \ No newline at end of file diff --git a/modules/ossm-about-istio-control-plane-update-strategies.adoc b/modules/ossm-about-istio-control-plane-update-strategies.adoc index 713a8213e208..47cd12d886eb 100644 --- a/modules/ossm-about-istio-control-plane-update-strategies.adoc +++ b/modules/ossm-about-istio-control-plane-update-strategies.adoc @@ -5,10 +5,18 @@ [id="ossm-about-istio-control-plane-update-strategies_{context}"] = About Istio control plane update strategies +[role="_abstract"] The update strategy affects how the update process is performed. The `spec.updateStrategy` field in the `{istio}` resource configuration determines how the {SMProduct} Operator updates the {istio} control plane. When the Operator detects a change in the `spec.version` field or identifies a new minor release with a configured `vX.Y-latest` alias, it initiates an upgrade procedure. For each mesh, you select one of two strategies: * `InPlace` * `RevisionBased` -`InPlace` is the default strategy for updating {SMProduct}. +`InPlace` is the default strategy for updating {SMProduct}. Both the update strategies apply to sidecar and ambient modes. + +If you use ambient mode, you must update the {istio} Container Network Interface (CNI) and `ZTunnel` components in addition to the standard control plane update procedures. + +[IMPORTANT] +==== +The `InPlace` update strategy is recommended for ambient mode. Using `RevisionBased` updates with ambient mode has limitations and requires manual intervention. +==== diff --git a/modules/ossm-understanding-versioning.adoc b/modules/ossm-understanding-versioning.adoc index c9de6d961c65..f7104f89eb5f 100644 --- a/modules/ossm-understanding-versioning.adoc +++ b/modules/ossm-understanding-versioning.adoc @@ -6,11 +6,11 @@ [id="ossm-understanding-versioning_{context}"] = Understanding versioning +[role="_abstract"] {product-title} follows Semantic Versioning for all product releases. Semantic Versioning uses a three-part version number in the format `X.Y.Z` to communicate the nature of changes in each release. -X (Major version):: indicates significant updates that might include breaking changes, such as architectural shifts, API changes, or schema modifications. +X (Major version):: Indicates significant updates that might include breaking changes, such as architectural shifts, API changes, or schema modifications. -Y (Minor version):: introduces new features and enhancements while maintaining backward compatibility. - -Z (Patch version or z-stream release):: delivers critical bug fixes and security updates, such as Common Vulnerabilities and Exposures (CVEs) resolutions. Patch versions do not include new features. +Y (Minor version):: Introduces new features and enhancements while maintaining backward compatibility. +Z (Patch version or z-stream release):: Delivers critical bug fixes and security updates, such as Common Vulnerabilities and Exposures (CVEs) resolutions. Patch versions do not include new features. \ No newline at end of file diff --git a/modules/ossm-updating-cross-namespace-waypoint.adoc b/modules/ossm-updating-cross-namespace-waypoint.adoc new file mode 100644 index 000000000000..e1a39b110391 --- /dev/null +++ b/modules/ossm-updating-cross-namespace-waypoint.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// update/ossm-updating-openshift-service-mesh-in-ambient-mode.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ossm-updating-cross-namespace-waypoint_{context}"] += Updating cross-namespace waypoint + +[role="_abstract"] +If you are using cross-namespace waypoints, verify that the `istio.io/use-waypoint-namespace` and `istio.io/use-waypoint` labels are correctly applied to the relevant namespaces before updating. + +. Verify the namespace with any of the waypoint labels by running the following command: ++ +[source,terminal] +---- +$ oc get ns bookinfo --show-labels | grep waypoint +---- + +. If there is no namespace with the label or if the label is wrong, re-apply the labels: + +.. Apply the `istio.io/use-waypoint-namespace` by running the following command: ++ +[source,terminal] +---- +$ oc label ns bookinfo istio.io/use-waypoint-namespace=foo --overwrite +---- + +.. Apply the `istio.io/use-waypoint` by running the following command: ++ +[source,terminal] +---- +$ oc label ns bookinfo istio.io/use-waypoint=waypoint-foo --overwrite +---- \ No newline at end of file diff --git a/modules/ossm-updating-istio-cni-resource-version.adoc b/modules/ossm-updating-istio-cni-resource-version.adoc index 761e0cdd37eb..20605b7ba5f6 100644 --- a/modules/ossm-updating-istio-cni-resource-version.adoc +++ b/modules/ossm-updating-istio-cni-resource-version.adoc @@ -6,21 +6,29 @@ [id="ossm-updating-istio-cni-resource-version_{context}"] = Updating the Istio CNI resource version -You can update the Istio CNI resource version by changing the version in the resource. Then, the {SMProductShortName} Operator deploys a new version of the CNI plugin that replaces the old version of the CNI plugin. The `istio-cni-node` pods automatically reconnect to the new CNI plugin. +You can update the {istio} Container Network Interface (CNI) resource version by changing the version in the resource. Then, the {SMProductShortName} Operator deploys a new version of the CNI plugin that replaces the old version of the CNI plugin. The `istio-cni-node` pods automatically reconnect to the new CNI plugin. .Prerequisites * You are logged in to {ocp-product-title} as a user with the `cluster-admin` role. -* You installed the {SMProductName} Operator and deployed {istio}. -* You installed the {istio} CNI plugin with the desired version. In the following example, the `IstioCNI` resource named `default` is deployed in the `istio-cni` namespace. +* You have installed the {SMProductName} Operator and deployed {istio}. +* You have installed the {istio} CNI plugin with the required version. In the following example, the `IstioCNI` resource named `default` is deployed in the `istio-cni` namespace. +* You have either updated the {istio} control plane to the required version (for `Inplace` strategy) or created a new control plane revision (for `RevisionBased` strategy). .Procedure -. Change the version in the `{istio}` resource. For example, to update to {istio} `1.24.4`, set the `spec.version` field to `v1.24.4` by running the following command: +. Change the version in the `{istio}` resource. For example, to update to {istio} `{istio-latest}`, set the `spec.version` field to `{istio-latest}` by running the following command: ++ +[source,terminal,subs="+attributes"] +---- +$ oc patch istiocni default -n istio-cni --type='merge' -p '{"spec":{"version":"v{istio-latest}"}}' +---- + +. Wait for the `IstioCNI` DaemonSet to reach the `Ready` status after the update by running the following command: + [source,terminal] ---- -$ oc patch istiocni default -n istio-cni --type='merge' -p '{"spec":{"version":"v1.24.4"}}' +$ oc wait --for=condition=Ready istiocnis/default --timeout=5m ---- . Confirm that the new version of the CNI plugin is ready by running the following command: @@ -30,10 +38,32 @@ $ oc patch istiocni default -n istio-cni --type='merge' -p '{"spec":{"version":" $ oc get istiocni default ---- + -.Example Output +You should see an output similar to the following example: + [source,terminal] ---- NAME READY STATUS VERSION AGE -default True Healthy v1.24.4 91m ----- \ No newline at end of file +default True Healthy v{istio-latest} 7d1h +---- + +. Check the status of the pods by running the following command: ++ +[source,terminal] +---- +$ oc get pods -n istio-cni +---- ++ +You should see an output similar to the following example: ++ +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +istio-cni-node-abc12 1/1 Running 0 3m +istio-cni-node-def34 1/1 Running 0 3m +istio-cni-node-ghi56 1/1 Running 0 3m +---- + +[NOTE] +==== +When you use the `RevisionBased` strategy, the {istio} CNI component remains compatible with many control plane versions. It continues to manage traffic redirection for both the old and the new control planes throughout the migration. The {istio} CNI is compatible with a control plane running the same minor version or one minor version higher. +==== \ No newline at end of file diff --git a/modules/ossm-updating-waypoint-proxies-with-inplace-strategy.adoc b/modules/ossm-updating-waypoint-proxies-with-inplace-strategy.adoc new file mode 100644 index 000000000000..df563875a0e5 --- /dev/null +++ b/modules/ossm-updating-waypoint-proxies-with-inplace-strategy.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// update/ossm-updating-openshift-service-mesh-in-ambient-mode.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ossm-updating-waypoint-proxies-with-inplace-strategy_{context}"] += Updating waypoint proxies with InPlace strategy in ambient mode + +[role="_abstract"] +During an `InPlace` update in ambient mode, waypoint proxies are going to be updated to the latest control plane version without restarting application workloads because they are deployed and managed as separate Gateway API resources that scale and upgrade independently. + +.Prerequisites + +* You have updated the {istio} control plane with `InPlace` update strategy. + +.Procedure + +* Confirm that the waypoint proxy was updated proxy version by running the following command: ++ +[source,terminal] +---- +$ istioctl proxy-status | grep waypoint +---- ++ +You should see an output similar to the following example: ++ +[source,terminal,subs="+attributes"] +---- +waypoint-5d9c8b7f9-abc12.bookinfo SYNCED SYNCED SYNCED SYNCED istiod-6cf8d4f9cb-wm7x6.istio-system {istio-latest} +---- ++ +You can run the command to query the {istio} control plane and verify that the waypoint proxy connects and synchronizes. The output lists the waypoint proxy name and namespace, the synchronization status for each configuration type, the connected `istiod` pod, and the {istio} version of the running proxy. Columns showing `SYNCED` confirm that the waypoint proxy is successfully receiving configuration from the control plane. diff --git a/modules/ossm-updating-waypoint-proxies-with-revisionbased-strategy.adoc b/modules/ossm-updating-waypoint-proxies-with-revisionbased-strategy.adoc new file mode 100644 index 000000000000..d2b523a897a9 --- /dev/null +++ b/modules/ossm-updating-waypoint-proxies-with-revisionbased-strategy.adoc @@ -0,0 +1,51 @@ +// Module included in the following assemblies: +// update/ossm-updating-openshift-service-mesh-in-ambient-mode.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ossm-updating-waypoint-proxies-with-revisionbased-strategy_{context}"] += Updating waypoint proxies with RevisionBased strategy in ambient mode + +[role="_abstract"] +In ambient mode, you can update waypoint proxies by using the `RevisionBased` update strategy. During the migration period, the proxies remain compatible with many control plane versions and automatically connect to the active control plane revision. + +[NOTE] +==== +Keep waypoint proxies within one minor version of the control plane (same version or `n–1`). This recommendation aligns with the support policy of {istio}, which states that data plane components must not run ahead of the control plane version. Apply the same versioning guidance to {istio} Container Network Interface (CNI) and `Ztunnel` components. For more details, see the "{istio} Supported Releases" documentation. +==== + +.Prerequisites + +* You have updated the {istio} control plane with `RevisionBased` update strategy. + +.Procedure + +. After the new {istio} control plane revision is ready, verify waypoint proxy pods are running by entering the following command: ++ +[source,terminal] +---- +$ oc get pods -n bookinfo -l gateway.networking.k8s.io/gateway-name=waypoint +---- ++ +You should see an output similar to the following example: ++ +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +waypoint-5d9c8b7f9-abc12 1/1 Running 0 5m +---- + +. Confirm that the waypoint proxy is updated to the latest version by running the following command: ++ +[source,terminal] +---- +$ istioctl proxy-status | grep waypoint +---- ++ +You should see an output similar to the following example: ++ +[source,terminal,subs="+attributes"] +---- +waypoint-5d9c8b7f9-abc12.bookinfo SYNCED SYNCED SYNCED SYNCED istiod-1-27-3-7b9f8c5d6-xyz78.istio-system {istio-latest} +---- ++ +You can run the command to query the {istio} control plane and verify that the waypoint proxy is connected to the new revision. The output lists the revision-specific `istiod` pod (for example, `istiod-1-27-3`) and shows that the waypoint proxy is running the updated version, {istio-latest}. The revision-specific name in the `ISTIOD` column confirms that the waypoint proxy has successfully migrated to the new control plane revision. \ No newline at end of file diff --git a/modules/ossm-verifying-l7-features-with-authorization-policies.adoc b/modules/ossm-verifying-l7-features-with-authorization-policies.adoc new file mode 100644 index 000000000000..6b28de497bdd --- /dev/null +++ b/modules/ossm-verifying-l7-features-with-authorization-policies.adoc @@ -0,0 +1,80 @@ +// Module included in the following assemblies: +// update/ossm-updating-openshift-service-mesh-in-ambient-mode.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ossm-verifying-l7-features-with-authorization-policies_{context}"] += Verifying Layer 7 (L7) features with authorization policies + +[role="_abstract"] +After updating the waypoint proxies, verify that the Layer 7 (L7) authorization policies are enforced correctly. In this example, the `AuthorizationPolicy` resource named `productpage-waypoint` allows only requests from the `default/sa/curl` service account to send `GET` requests to the `productpage` service. + +.Prerequisites + +* You have updated the waypoint proxies. + +* You have created an application pod using the described service account in the `AuthorizationPolicy` resource. + +* You have created an `AuthorizationPolicy` resource. + +.Procedure + +. Optional: Create the `AuthorizationPolicy` resource if it does not already exist by running the following command: ++ +[source,terminal] +---- +$ oc apply -f - <.*" +---- ++ +The request will succeed because the `curl` service meets the authorization policy rules. It uses the `cluster.local/ns/default/sa/curl` principal and performs a `GET` operation, both allowed by the policy. The successful response containing the page title confirms that the waypoint proxy correctly enforces L7 authorization rules and allows valid traffic. \ No newline at end of file diff --git a/modules/ossm-verifying-l7-features-with-traffic-routing.adoc b/modules/ossm-verifying-l7-features-with-traffic-routing.adoc new file mode 100644 index 000000000000..fb644525fead --- /dev/null +++ b/modules/ossm-verifying-l7-features-with-traffic-routing.adoc @@ -0,0 +1,66 @@ +// Module included in the following assemblies: +// update/ossm-updating-openshift-service-mesh-in-ambient-mode.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ossm-verifying-l7-features-with-traffic-routing_{context}"] += Verifying Layer 7 (L7) features with traffic routing + +[role="_abstract"] +After updating the waypoint proxies, verify that Layer 7 (L7) features function as expected. +If you use traffic routing rules such as `HTTPRoute`, confirm that they continue to enforce the intended behavior. + +.Prerequisites + +* You have updated the waypoint proxies. + +* You have deployed the `bookinfo` application. + +* You have created an `HTTPRoute` resource. + +.Procedure + +. Optional: Create the `HTTPRoute` resource if it does not already exist by running the following command: ++ +[source,terminal] +---- +$ oc apply -f - <