From f7a6d53d01e6ef301fa4c2de5bad1d44b10f704e Mon Sep 17 00:00:00 2001 From: BigEars Date: Wed, 26 Aug 2026 16:03:30 -0400 Subject: [PATCH] [OSSM] Service Mesh JTBD work for Configure, Observe, Secure, and other categories --- about/ossm-planning.adoc | 2 - .../ossm-getting-traffic-into-a-mesh.adoc | 8 +- install/ossm-SPIRE.adoc | 3 +- install/ossm-cert-manager.adoc | 13 +- install/ossm-enabling-mtls.adoc | 4 +- ...sm-supported-platforms-configurations.adoc | 12 ++ modules/ossm-about-cert-manager.adoc | 13 +- ...g-a-gateway-to-accept-ingress-traffic.adoc | 7 +- modules/ossm-about-console-plugin.adoc | 4 +- ...about-control-plane-update-strategies.adoc | 29 +++-- ...ing-istio-using-service-mesh-operator.adoc | 6 +- ...out-deploying-multiple-control-planes.adoc | 2 +- ...iscovery-selectors-istio-ambient-mode.adoc | 4 +- modules/ossm-about-discoveryselectors.adoc | 2 +- ...-distributed-tracing-and-service-mesh.adoc | 4 +- ...about-external-control-plane-topology.adoc | 5 +- modules/ossm-about-inplace-strategy.adoc | 2 +- .../ossm-about-installing-console-plugin.adoc | 2 +- .../ossm-about-istio-cni-update-process.adoc | 2 +- ...istio-control-plane-update-strategies.adoc | 2 +- modules/ossm-about-istio-deployment.adoc | 2 +- .../ossm-about-istio-high-availability.adoc | 6 +- modules/ossm-about-istio-update-process.adoc | 2 +- .../ossm-about-metrics-and-observability.adoc | 22 ++-- modules/ossm-about-metrics.adoc | 19 ++- modules/ossm-about-mtls-planning.adoc | 13 +- modules/ossm-about-mtls.adoc | 6 +- ...m-about-multi-cluster-mesh-topologies.adoc | 2 +- ...ossm-about-observability-service-mesh.adoc | 2 +- modules/ossm-about-pqc-service-mesh.adoc | 11 +- .../ossm-about-revisionbased-strategy.adoc | 2 +- modules/ossm-about-sidecar-injection.adoc | 2 +- modules/ossm-about-sidecar-proxies.adoc | 6 +- ...ssm-about-uninstalling-console-plugin.adoc | 2 +- ...out-update-strategies-in-ambient-mode.adoc | 9 +- modules/ossm-adding-authorization-policy.adoc | 12 +- ...tificates-to-a-multi-cluster-topology.adoc | 2 +- modules/ossm-cert-manager-planning.adoc | 3 - modules/ossm-config-dt-ambient-mode.adoc | 2 +- ...fig-openshift-monitoring-ambient-mode.adoc | 8 +- ...ssm-config-openshift-monitoring-kiali.adoc | 10 +- ...ossm-config-openshift-monitoring-only.adoc | 8 +- modules/ossm-config-otel-kiali.adoc | 4 +- modules/ossm-config-otel.adoc | 2 +- modules/ossm-configure-traffic-routing.adoc | 6 +- ...ssm-configuring-istio-ha-replicacount.adoc | 2 +- modules/ossm-configuring-sm-pqc-ambient.adoc | 2 +- modules/ossm-configuring-sm-pqc-gateways.adoc | 2 +- .../ossm-configuring-sm-pqc-mesh-wide.adoc | 2 +- ...ossm-configuring-ztunnel-grace-period.adoc | 6 +- ...ificates-for-a-multi-cluster-topology.adoc | 2 +- .../ossm-customizing-istio-configuration.adoc | 2 +- modules/ossm-decide-if-service-mesh-fits.adoc | 7 +- modules/ossm-deploy-in-ambient-mode.adoc | 2 +- .../ossm-deploying-first-control-plane.adoc | 4 +- .../ossm-deploying-second-control-plane.adoc | 4 +- modules/ossm-edge-traffic-planning.adoc | 1 - modules/ossm-enable-pqc.adoc | 11 ++ modules/ossm-generating-tls-certificates.adoc | 4 +- .../ossm-install-console-plugin-ocp-cli.adoc | 2 +- ...nstall-console-plugin-ocp-web-console.adoc | 10 +- modules/ossm-install-kiali-operator.adoc | 4 +- modules/ossm-installing-cert-manager.adoc | 2 +- ...ssm-installing-external-control-plane.adoc | 14 +-- ...nstalling-istio-with-inplace-strategy.adoc | 2 +- ...visionbased-strategy-istiorevisiontag.adoc | 2 +- ...ing-istio-with-revisionbased-strategy.adoc | 2 +- ...m-installing-kiali-multi-cluster-mesh.adoc | 2 +- ...ing-kiali-operator-on-remote-clusters.adoc | 2 +- ...ti-primary-multi-network-mesh-ambient.adoc | 14 +-- ...ling-multi-primary-multi-network-mesh.adoc | 12 +- modules/ossm-installing-operator.adoc | 2 +- ...ing-primary-remote-multi-network-mesh.adoc | 2 +- .../ossm-installing-the-istioctl-tool.adoc | 2 +- modules/ossm-integrating-kiali-otel.adoc | 2 +- ...ssm-isolate-workloads-multiple-meshes.adoc | 11 ++ modules/ossm-istioctl-tool-concept.adoc | 11 ++ modules/ossm-kiali-about.adoc | 6 +- modules/ossm-kiali-ambient-mode.adoc | 2 +- modules/ossm-kiali-planning.adoc | 14 ++- modules/ossm-mixed-data-plane-modes.adoc | 6 + .../ossm-plan-upgrade-release-alignment.adoc | 11 ++ modules/ossm-plan-upgrade-strategy.adoc | 4 +- modules/ossm-pqc-gateways.adoc | 11 ++ modules/ossm-pqc-mesh-internal.adoc | 11 ++ modules/ossm-release-notes-3-4-1.adoc | 20 +++ .../ossm-release-notes-3-4-fixed-issues.adoc | 21 ++++ ...e-notes-3-4-new-features-enhancements.adoc | 117 ++++++++++++++++++ ...notes-3-4-technology-preview-features.adoc | 46 +++++++ modules/ossm-release-notes-concept.adoc | 11 ++ ...allation-from-development-environment.adoc | 2 +- ...-routing-traffic-using-virtualservice.adoc | 2 +- ...outing-traffic-using-waypoint-proxies.adoc | 2 +- ...-service-mesh-with-discoveryselectors.adoc | 14 +-- ...iscovery-selectors-istio-ambient-mode.adoc | 2 +- modules/ossm-selecting-inplace-strategy.adoc | 4 +- ...ossm-selecting-revisionbased-strategy.adoc | 2 +- ...ssm-service-mesh-deployment-resources.adoc | 14 +-- modules/ossm-setup-observability-console.adoc | 2 +- modules/ossm-support-for-istioctl.adoc | 2 +- modules/ossm-tls-gateways.adoc | 2 +- ...tanding-operator-updates-and-channels.adoc | 2 +- .../ossm-understanding-sm-istio-versions.adoc | 2 +- ...ossm-uninstall-console-plugin-ocp-cli.adoc | 2 +- ...nstall-console-plugin-ocp-web-console.adoc | 2 +- modules/ossm-uninstalling-cert-manager.adoc | 2 +- modules/ossm-update-istio-cni-plugin.adoc | 11 ++ .../ossm-updating-control-plane-inplace.adoc | 15 +++ ...-updating-control-plane-revisionbased.adoc | 15 +++ ...ssm-updating-cross-namespace-waypoint.adoc | 2 +- ...m-updating-istio-cni-resource-version.adoc | 2 +- ...e-with-revisionbased-istiorevisiontag.adoc | 2 +- ...stio-control-plane-with-revisionbased.adoc | 2 +- ...aypoint-proxies-with-inplace-strategy.adoc | 2 +- ...t-proxies-with-revisionbased-strategy.adoc | 2 +- ...m-updating-ztunnel-with-node-draining.adoc | 10 +- ...-upgrade-core-platform-infrastructure.adoc | 11 ++ ...ade-node-level-infrastructure-ambient.adoc | 11 ++ ...discoveryselectors-scope-service-mesh.adoc | 2 +- .../ossm-verifying-cert-manager-ambient.adoc | 2 +- modules/ossm-verifying-cert-manager.adoc | 2 +- ...-features-with-authorization-policies.adoc | 2 +- ...ying-l7-features-with-traffic-routing.adoc | 2 +- .../ossm-verifying-metrics-ambient-mode.adoc | 4 +- ...ifying-multi-cluster-topology-ambient.adoc | 2 +- ...ossm-verifying-multi-cluster-topology.adoc | 2 +- ...ssm-verifying-multiple-control-planes.adoc | 2 +- .../ossm-verifying-traces-ambient-mode.adoc | 6 +- modules/ossm-ztunnel-update-lifecycle.adoc | 12 +- 129 files changed, 627 insertions(+), 272 deletions(-) create mode 100644 modules/ossm-enable-pqc.adoc create mode 100644 modules/ossm-isolate-workloads-multiple-meshes.adoc create mode 100644 modules/ossm-istioctl-tool-concept.adoc create mode 100644 modules/ossm-mixed-data-plane-modes.adoc create mode 100644 modules/ossm-plan-upgrade-release-alignment.adoc create mode 100644 modules/ossm-pqc-gateways.adoc create mode 100644 modules/ossm-pqc-mesh-internal.adoc create mode 100644 modules/ossm-release-notes-3-4-1.adoc create mode 100644 modules/ossm-release-notes-3-4-fixed-issues.adoc create mode 100644 modules/ossm-release-notes-3-4-new-features-enhancements.adoc create mode 100644 modules/ossm-release-notes-3-4-technology-preview-features.adoc create mode 100644 modules/ossm-release-notes-concept.adoc create mode 100644 modules/ossm-update-istio-cni-plugin.adoc create mode 100644 modules/ossm-updating-control-plane-inplace.adoc create mode 100644 modules/ossm-updating-control-plane-revisionbased.adoc create mode 100644 modules/ossm-upgrade-core-platform-infrastructure.adoc create mode 100644 modules/ossm-upgrade-node-level-infrastructure-ambient.adoc diff --git a/about/ossm-planning.adoc b/about/ossm-planning.adoc index 6b5be62b2e8..61ad1d03c7a 100644 --- a/about/ossm-planning.adoc +++ b/about/ossm-planning.adoc @@ -16,8 +16,6 @@ include::modules/ossm-choose-data-plane-mode.adoc[leveloffset=+1] include::modules/ossm-about-sidecar-proxies.adoc[leveloffset=+2] -include::modules/ossm-about-istio-ambient-mode.adoc[leveloffset=+2] - include::modules/ossm-mesh-security-planning.adoc[leveloffset=+1] include::modules/ossm-about-mtls-planning.adoc[leveloffset=+2] diff --git a/gateways/ossm-getting-traffic-into-a-mesh.adoc b/gateways/ossm-getting-traffic-into-a-mesh.adoc index 9fe320c86d0..9812b546bc4 100644 --- a/gateways/ossm-getting-traffic-into-a-mesh.adoc +++ b/gateways/ossm-getting-traffic-into-a-mesh.adoc @@ -1,10 +1,10 @@ :_mod-docs-content-type: ASSEMBLY [id="ossm-getting-traffic-into-a-mesh"] -= Getting traffic into a mesh += Route ingress traffic and expose mesh services include::_attributes/common-attributes.adoc[] -:context: ossm-getting-traffic-into-a-mesh +:context: ossm-getting-traffic-into-a-mesh -toc::[] +toc::[] [role="_abstract"] @@ -28,8 +28,6 @@ include::modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api-in- [id="additional-resources_{context}"] == Additional resources -* xref:../gateways/ossm-about-gateways.adoc#ossm-about-gateway-injection_ossm-about-gateways[About gateway injection] - * link:https://istio.io/latest/docs/reference/config/networking/gateway/#Gateway[Istio Gateway resource API reference (Istio documentation)] * link:https://istio.io/latest/docs/reference/config/networking/virtual-service/#VirtualService[VirtualService API reference (Istio documentation)] diff --git a/install/ossm-SPIRE.adoc b/install/ossm-SPIRE.adoc index 2a8ef814b20..5812e87649e 100644 --- a/install/ossm-SPIRE.adoc +++ b/install/ossm-SPIRE.adoc @@ -7,7 +7,8 @@ include::_attributes/common-attributes.adoc[] toc::[] [role="_abstract"] -The SPIFFE Runtime Environment (SPIRE), supported by the OpenShift Zero Trust Workload Identity Manager, provides cryptographic identity management for your service mesh. SPIRE validates platform and runtime attributes to securely authenticate workloads across hybrid infrastructure. + +The SPIFFE Runtime Environment (SPIRE), supported by the OpenShift Zero Trust Workload Identity Manager, provides attested workload identity for your service mesh. include::snippets/technology-preview-SPIRE.adoc[] diff --git a/install/ossm-cert-manager.adoc b/install/ossm-cert-manager.adoc index d2f298eece7..28793bc0969 100644 --- a/install/ossm-cert-manager.adoc +++ b/install/ossm-cert-manager.adoc @@ -1,6 +1,6 @@ :_mod-docs-content-type: ASSEMBLY [id="ossm-cert-manager"] -= OpenShift Service Mesh and cert-manager += Configure automated certificate lifecycle management include::_attributes/common-attributes.adoc[] :context: ossm-cert-manager @@ -8,7 +8,7 @@ toc::[] [role="_abstract"] -The cert-manager tool provides a unified API to manage X.509 certificates for applications in a {k8s} environment. You can use cert-manager to integrate with public or private key infrastructures (PKI) and automate certificate renewal. +To centralize certificate lifecycle management for your mesh, replace the built-in {istio} certificate authority (CA) with the {cert-manager-operator}. This integration lets you connect {SMProductShortName} to your organization's preferred CA provider and automate certificate issuing, renewal, and rotation. include::modules/ossm-about-cert-manager.adoc[leveloffset=+1] @@ -19,12 +19,3 @@ include::modules/ossm-verifying-cert-manager.adoc[leveloffset=+2] include::modules/ossm-verifying-cert-manager-ambient.adoc[leveloffset=+2] include::modules/ossm-uninstalling-cert-manager.adoc[leveloffset=+2] - - -[role="_additional-resources"] -[id="additional-resources_{context}"] -== Additional resources - -* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/security_and_compliance/cert-manager-operator-for-red-hat-openshift#cert-manager-operator-install[Installing the {cert-manager-operator}] - -* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/security_and_compliance/cert-manager-operator-for-red-hat-openshift#cert-manager-operator-integrating-istio[Integrating the {cert-manager-operator} with Istio-CSR] \ No newline at end of file diff --git a/install/ossm-enabling-mtls.adoc b/install/ossm-enabling-mtls.adoc index 2c03c7bb9b2..6ac76ae9fbd 100644 --- a/install/ossm-enabling-mtls.adoc +++ b/install/ossm-enabling-mtls.adoc @@ -1,6 +1,6 @@ :_mod-docs-content-type: ASSEMBLY [id="ossm-enabling-mtls"] -= Enabling mutual Transport Layer Security += Encrypt communication for mesh traffic include::_attributes/common-attributes.adoc[] :context: ossm-enabling-mtls @@ -8,7 +8,7 @@ toc::[] [role="_abstract"] -You can use {SMProductName} for your application to customize the communication security between the complex array of microservices. Mutual Transport Layer Security (mTLS) is a protocol that enables two parties to authenticate each other. +You can use {SMProductName} for your application to customize the communication security between the complex array of microservices. Mutual Transport Layer Security (mTLS) is a protocol that enables two parties to authenticate each other. include::modules/ossm-about-mtls.adoc[leveloffset=+1] diff --git a/install/ossm-supported-platforms-configurations.adoc b/install/ossm-supported-platforms-configurations.adoc index e82ec046140..13e8c34b2fd 100644 --- a/install/ossm-supported-platforms-configurations.adoc +++ b/install/ossm-supported-platforms-configurations.adoc @@ -10,6 +10,18 @@ toc::[] Before you install {SMProductName}, verify that your environment meets the platform, configuration, and network requirements. +Confirming compatibility early prevents installation failures and ensures that all {SMProductShortName} components operate as expected in your cluster. + +Verify the following areas before installing {SMProductShortName}: + +Supported platforms:: Your {ocp-product-title} version and managed platform type are compatible with {SMProductShortName}. + +Supported configurations:: Your cluster architecture and deployment topology meet {SMProductShortName} requirements. + +Supported network configurations:: Your cluster's Container Network Interface (CNI) plugin is validated for {SMProductShortName}. + +Supported Kiali configurations:: Your web browser and authentication strategy are compatible with the Kiali console. + include::modules/ossm-supported-platforms.adoc[leveloffset=+1] include::modules/ossm-supported-configurations-sm.adoc[leveloffset=+1] diff --git a/modules/ossm-about-cert-manager.adoc b/modules/ossm-about-cert-manager.adoc index d96f2fa54e5..fd31332efe1 100644 --- a/modules/ossm-about-cert-manager.adoc +++ b/modules/ossm-about-cert-manager.adoc @@ -4,15 +4,14 @@ :_mod-docs-content-type: CONCEPT [id="ossm-cert-manager-integration-istio_{context}"] -= About the cert-manager Operator istio-csr agent += The cert-manager Operator [role="_abstract"] -The {cert-manager-operator} enhances certificate management for securing workloads and control plane components in {SMProductName} and {istio}. It supports issuing, delivering, and renewing certificates used for mutual Transport Layer Security (mTLS) through cert-manager issuers. +The {cert-manager-operator} manages the `istio-csr` agent, which handles certificate signing requests from mesh proxies. You must install the Operator and deploy the agent before you create your `{istio}` resource. For Operator installation instructions, see the {ocp-product-title} documentation. -By integrating {istio} with the `istio-csr` agent, which the cert-manager Operator manages, you enable {istio} to request and manage the certificates directly. The integration simplifies security configuration and centralizes certificate management within the cluster. +[role="_additional-resources"] +[id="additional-resources_{context}"] +== Additional resources -[NOTE] -==== -You must install the {cert-manager-operator} before you create and install your `{istio}` resource. -==== \ No newline at end of file +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/security_and_compliance/cert-manager-operator-for-red-hat-openshift#cert-manager-operator-install[Installing the {cert-manager-operator}] diff --git a/modules/ossm-about-configuring-a-gateway-to-accept-ingress-traffic.adoc b/modules/ossm-about-configuring-a-gateway-to-accept-ingress-traffic.adoc index 032bb03f66a..4bd6ab846f3 100644 --- a/modules/ossm-about-configuring-a-gateway-to-accept-ingress-traffic.adoc +++ b/modules/ossm-about-configuring-a-gateway-to-accept-ingress-traffic.adoc @@ -19,4 +19,9 @@ Ingress routing with {k8s} Gateway API:: The {k8s} Gateway API provides a standardized approach for configuring ingress traffic routing using native {k8s} resources. With this approach, you use `Gateway` and `HTTPRoute` (or `GRPCRoute`) resources to configure how traffic enters the mesh and routes to services. -While {istio} `Gateway` and `VirtualService` resources support certain ingress use cases in ambient mode, the recommended approach is to use the {k8s} Gateway API, which provides full support and integration with ambient. You can also use the Gateway API with sidecar-based deployments. \ No newline at end of file +While {istio} `Gateway` and `VirtualService` resources support certain ingress use cases in ambient mode, the recommended approach is to use the {k8s} Gateway API, which provides full support and integration with ambient. You can also use the Gateway API with sidecar-based deployments. + +[NOTE] +==== +After configuring ingress routing with one of these approaches, you must expose the gateway to external traffic using either a LoadBalancer service or an {ocp-short-name} route. +==== diff --git a/modules/ossm-about-console-plugin.adoc b/modules/ossm-about-console-plugin.adoc index 23f64060608..b6b49be92fb 100644 --- a/modules/ossm-about-console-plugin.adoc +++ b/modules/ossm-about-console-plugin.adoc @@ -4,11 +4,11 @@ :_mod-docs-content-type: CONCEPT [id="ossm-about-console-plugin_{context}"] -= About {sm-plugin-full} += OpenShift Service Mesh Console plugin [role="_abstract"] -The {SMPlugin} is an extension to {ocp-product-title} web console that provides visibility into your {SMProductShortName}. +The {SMPlugin} is an extension to the {ocp-product-title} web console that surfaces Kiali observability features directly in the console. [WARNING] ==== diff --git a/modules/ossm-about-control-plane-update-strategies.adoc b/modules/ossm-about-control-plane-update-strategies.adoc index 1393715c331..ba779d43642 100644 --- a/modules/ossm-about-control-plane-update-strategies.adoc +++ b/modules/ossm-about-control-plane-update-strategies.adoc @@ -8,21 +8,26 @@ [role="_abstract"] -The `spec.updateStrategy` field in the `Istio` resource determines how the Operator updates the Istio control plane when a new version becomes available. You set this field when you create the `Istio` resource during installation. +The `spec.updateStrategy` field in the `Istio` resource determines how the Operator updates the Istio control plane when a new version becomes available. +You set this field when you create the `Istio` resource during installation. InPlace:: -The Operator updates the existing control plane in place. There is only one control plane revision at a time. +The Operator updates the existing control plane in place. +There is only one control plane revision at a time. +You trigger the update by setting the `spec.version` field in the `Istio` resource, or you can use a `vX.Y-latest` version alias so the Operator applies new patch versions automatically as they become available. +This is the simpler approach, but workloads might experience brief interruption during the transition. + +RevisionBased:: +The Operator deploys a new control plane alongside the existing one. +You trigger the new revision by setting the `spec.version` field, but the process does not end there. +You must then migrate workloads gradually from the old revision to the new one, validate that they are working correctly, and remove the old revision. +This approach is more complex but allows canary-style validation before committing. +The Operator bundles multiple Istio versions specifically to support this dual-revision workflow. -You trigger the update by setting the `spec.version` field in the `Istio` resource, or you can use a `vX.Y-latest` version alias so the Operator applies new patch versions automatically as they become available. This is the simpler approach, but workloads might experience brief interruption during the transition. - -`RevisionBased`:: -The Operator deploys a new control plane alongside the existing one. You trigger the new revision by setting the `spec.version` field, but the process does not end there. You must then migrate workloads gradually from the old revision to the new one, validate that they are working correctly, and remove the old revision. - -This approach is more complex but allows canary-style validation before committing. The Operator bundles multiple Istio versions specifically to support this dual-revision workflow. - -[id="how-channels-and-strategies-work-together_{context}"] == How channels and strategies work together -The channel and approval strategy control *when* a new Istio version becomes available to the Operator. The update strategy controls *how* the Operator transitions the control plane to that version. +The channel and approval strategy control *when* a new Istio version becomes available to the Operator. +The update strategy controls *how* the Operator transitions the control plane to that version. -For example, you might use a versioned channel with manual approval to control exactly when new patches arrive, and then use the `InPlace` strategy to apply them quickly. Or you might use the stable channel with automatic approval to stay current, and then use the `RevisionBased` strategy to migrate workloads gradually after each update. +For example, you might use a versioned channel with manual approval to control exactly when new patches arrive, and then use the `InPlace` strategy to apply them quickly. +Or you might use the stable channel with automatic approval to stay current, and then use the `RevisionBased` strategy to migrate workloads gradually after each update. diff --git a/modules/ossm-about-deploying-istio-using-service-mesh-operator.adoc b/modules/ossm-about-deploying-istio-using-service-mesh-operator.adoc index 92489cb6e10..501d7cd7867 100644 --- a/modules/ossm-about-deploying-istio-using-service-mesh-operator.adoc +++ b/modules/ossm-about-deploying-istio-using-service-mesh-operator.adoc @@ -4,10 +4,8 @@ :_mod-docs-content-type: CONCEPT [id="ossm-about-deploying-istio-using-service-mesh-operator_{context}"] -= The {SMProductName} Operator += About deploying {istio} using the {SMProductName} Operator [role="_abstract"] -The {SMProductName} Operator installs the custom resource definitions (CRDs) you need to deploy and configure {istio} control planes. Once the Operator is installed, you create custom resources such as `Istio` and `IstioCNI` to deploy the control plane, and the Operator manages their lifecycle. - -The control plane runs as `istiod`, which handles service discovery, configuration distribution, and certificate management for the mesh. +The {SMProductName} Operator installs the custom resource definitions (CRDs) you need to deploy and configure {istio} control planes. Once the Operator is installed, you create custom resources such as `Istio` and `IstioCNI` to deploy the control plane, and the Operator manages their lifecycle. diff --git a/modules/ossm-about-deploying-multiple-control-planes.adoc b/modules/ossm-about-deploying-multiple-control-planes.adoc index 7980b6e27cc..d1f6bac374c 100644 --- a/modules/ossm-about-deploying-multiple-control-planes.adoc +++ b/modules/ossm-about-deploying-multiple-control-planes.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: CONCEPT [id="ossm-about-deploying-multiple-control-planes_{context}"] -= About deploying multiple control planes += Requirements for multiple control planes [role="_abstract"] diff --git a/modules/ossm-about-discovery-selectors-istio-ambient-mode.adoc b/modules/ossm-about-discovery-selectors-istio-ambient-mode.adoc index 3860ebfe98e..472ae07a95c 100644 --- a/modules/ossm-about-discovery-selectors-istio-ambient-mode.adoc +++ b/modules/ossm-about-discovery-selectors-istio-ambient-mode.adoc @@ -4,12 +4,10 @@ :_mod-docs-content-type: CONCEPT [id="ossm-about-discovery-selectors-istio-ambient-mode_{context}"] -= About discovery selectors and Istio ambient mode += Discovery selectors in ambient mode [role="_abstract"] {istio} ambient mode includes workloads when the control plane discovers each workload and the appropriate label enables traffic redirection through the Ztunnel proxy. By default, the control plane discovers workloads in all namespaces across the cluster. As a result, each proxy receives configuration for every namespace, including workloads that are not enrolled in the mesh. In shared or multitenant clusters, limiting mesh participation to specific namespaces helps reduce configuration costs and supports many service meshes within the same cluster. - -For more information about discovery selectors, see "Scoping the Service Mesh with discovery selectors". \ No newline at end of file diff --git a/modules/ossm-about-discoveryselectors.adoc b/modules/ossm-about-discoveryselectors.adoc index 63bab3b9641..0a657b4cea8 100644 --- a/modules/ossm-about-discoveryselectors.adoc +++ b/modules/ossm-about-discoveryselectors.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: CONCEPT [id="ossm-about-discoveryselectors_{context}"] -= About discovery selectors += How discovery selectors work [role="_abstract"] diff --git a/modules/ossm-about-distributed-tracing-and-service-mesh.adoc b/modules/ossm-about-distributed-tracing-and-service-mesh.adoc index 4181a8b9727..c69839e977b 100644 --- a/modules/ossm-about-distributed-tracing-and-service-mesh.adoc +++ b/modules/ossm-about-distributed-tracing-and-service-mesh.adoc @@ -4,11 +4,11 @@ :_mod-docs-content-type: CONCEPT [id="ossm-about-distributed-tracing-and-service-mesh_{context}"] -= About {DTProductName} and {SMProductName} += Trace requests across services [role="_abstract"] -Two parts integrate {DTProductName} with {SMProductName}: {TempoName} and {OTELName}. +Integrate {DTProductName} with {SMProductName} by using {TempoName} for trace storage and {OTELName} for standardized telemetry data collection and processing. {TempoName}:: Provides {DTShortName} to monitor and troubleshoot transactions in complex distributed systems. Tempo derives its core functionality from the open source Grafana Tempo project. + diff --git a/modules/ossm-about-external-control-plane-topology.adoc b/modules/ossm-about-external-control-plane-topology.adoc index 74cf0f027d7..87a44d0413e 100644 --- a/modules/ossm-about-external-control-plane-topology.adoc +++ b/modules/ossm-about-external-control-plane-topology.adoc @@ -4,8 +4,9 @@ :_mod-docs-content-type: CONCEPT [id="ossm-about-external-control-plane-topology_{context}"] -= About external control plane topology += Host the control plane externally for better security [role="_abstract"] +An external control plane topology places the control plane on a dedicated cluster, separate from the clusters that run your application workloads. This isolation prevents a compromised application workload from reaching the control plane that manages certificates, policies, and mesh configuration. -The external control plane topology improves security and offers the ability to host the Service Mesh as a service. In this configuration, one cluster hosts and manages the {istio} control plane, while other clusters host the applications. \ No newline at end of file +Platform teams can restrict access to the control plane cluster independently from the clusters where developers deploy applications. This separation also lets you host and manage the service mesh as a shared service across many application clusters. diff --git a/modules/ossm-about-inplace-strategy.adoc b/modules/ossm-about-inplace-strategy.adoc index 9122483d8af..296cbeacec1 100644 --- a/modules/ossm-about-inplace-strategy.adoc +++ b/modules/ossm-about-inplace-strategy.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: CONCEPT [id="about-inplace-strategy_{context}"] -= About InPlace strategy += InPlace update strategy [role="_abstract"] diff --git a/modules/ossm-about-installing-console-plugin.adoc b/modules/ossm-about-installing-console-plugin.adoc index c3cb4a1547a..4a1964425a3 100644 --- a/modules/ossm-about-installing-console-plugin.adoc +++ b/modules/ossm-about-installing-console-plugin.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: CONCEPT [id="ossm-about-installing-console-plugin_{context}"] -= About installing {sm-plugin-full} += Console plugin installation requirements [role="_abstract"] diff --git a/modules/ossm-about-istio-cni-update-process.adoc b/modules/ossm-about-istio-cni-update-process.adoc index 0e3e458e0b5..8c470f267f5 100644 --- a/modules/ossm-about-istio-cni-update-process.adoc +++ b/modules/ossm-about-istio-cni-update-process.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: CONCEPT [id="ossm-about-istio-cni-update-process_{context}"] -= About the Istio CNI update process += How the Istio CNI update process works [role="_abstract"] diff --git a/modules/ossm-about-istio-control-plane-update-strategies.adoc b/modules/ossm-about-istio-control-plane-update-strategies.adoc index 2303f775db0..e960475e967 100644 --- a/modules/ossm-about-istio-control-plane-update-strategies.adoc +++ b/modules/ossm-about-istio-control-plane-update-strategies.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: CONCEPT [id="ossm-about-istio-control-plane-update-strategies_{context}"] -= About Istio control plane update strategies += Choose a rollout strategy: InPlace or RevisionBased [role="_abstract"] diff --git a/modules/ossm-about-istio-deployment.adoc b/modules/ossm-about-istio-deployment.adoc index 18e34c17f2a..e1a39a98796 100644 --- a/modules/ossm-about-istio-deployment.adoc +++ b/modules/ossm-about-istio-deployment.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: CONCEPT [id="about-istio-deployment_{context}"] -= Deploy a mesh in sidecar mode += Deploy in sidecar mode [role="_abstract"] diff --git a/modules/ossm-about-istio-high-availability.adoc b/modules/ossm-about-istio-high-availability.adoc index e0c558c7fa6..93e25f45b89 100644 --- a/modules/ossm-about-istio-high-availability.adoc +++ b/modules/ossm-about-istio-high-availability.adoc @@ -4,13 +4,13 @@ :_mod-docs-content-type: CONCEPT [id="ossm-about-istio-high-availability_{context}"] -= About {istio} High Availability += {istio} High Availability (HA) mode [role="_abstract"] -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. +Running the {istio} control plane in High Availability (HA) mode 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. +In HA mode, 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: diff --git a/modules/ossm-about-istio-update-process.adoc b/modules/ossm-about-istio-update-process.adoc index 962a260167a..02c25793f87 100644 --- a/modules/ossm-about-istio-update-process.adoc +++ b/modules/ossm-about-istio-update-process.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: CONCEPT [id="ossm-about-istio-update-process_{context}"] -= About Istio update process += Control plane update process [role="_abstract"] diff --git a/modules/ossm-about-metrics-and-observability.adoc b/modules/ossm-about-metrics-and-observability.adoc index 29f36c25178..eb3f689aa56 100644 --- a/modules/ossm-about-metrics-and-observability.adoc +++ b/modules/ossm-about-metrics-and-observability.adoc @@ -3,26 +3,22 @@ // * TBD :_mod-docs-content-type: CONCEPT -[id="ossm-about-metrics-and-observability_{context}"] -= Metrics and observability +[id="ossm-observability-planning_{context}"] += Metrics and observability in {SMProductShortName} [role="_abstract"] -{SMProductShortName} proxies generate metrics as they handle traffic between services. +You can use mesh telemetry data to monitor service health, track performance, and diagnose problems. -[id="how-metrics-are-collected_{context}"] == How metrics are collected -Every {ocp-product-title} cluster includes the Cluster Monitoring Operator, which provides Prometheus for scraping and storing metrics. -To collect metrics from your mesh proxies, you configure {SMProductShortName} to integrate with user-workload monitoring. -This integration exposes the proxy metrics so that Prometheus can scrape and store them alongside other cluster metrics. +The mesh proxies generate metrics as they handle traffic between services. +In sidecar mode, each pod's sidecar proxy produces metrics for its own traffic. +In ambient mode, the ztunnel proxy produces Layer 4 (L4) metrics such as TCP connections, and waypoint proxies produce Layer 7 (L7) metrics such as HTTP request rates and response codes. -The type of metrics collected depends on your deployment mode: +The {ocp-product-title} monitoring stack collects these metrics automatically. +Every {ocp-product-title} cluster includes a monitoring stack with Prometheus, which scrapes and stores metrics from the mesh proxies alongside other cluster metrics. -* In sidecar mode, each pod's sidecar proxy produces metrics for its own traffic. -* In ambient mode, the ztunnel proxy produces Layer 4 (L4) metrics such as TCP connections, and waypoint proxies produce Layer 7 (L7) metrics such as HTTP request rates and response codes. - -[id="tools-for-viewing-mesh-metrics_{context}"] == Tools for viewing mesh metrics The following tools surface the metrics that the mesh generates: @@ -34,7 +30,7 @@ You can monitor CPU and memory usage, network connectivity, and request performa Kiali:: The observability console for {SMProductShortName}. Kiali visualizes service-to-service traffic, displays the health of your mesh, and shows the structure of your service topology. -It also integrates with Perses or Grafana for detailed metric dashboards and with the {TempoName} for distributed tracing. +It also integrates with Grafana for detailed metric dashboards and with the {TempoName} for distributed tracing. Distributed tracing:: Follows individual requests as they travel across multiple services, helping you identify where latency or failures occur. diff --git a/modules/ossm-about-metrics.adoc b/modules/ossm-about-metrics.adoc index 209329f819d..061fe999e95 100644 --- a/modules/ossm-about-metrics.adoc +++ b/modules/ossm-about-metrics.adoc @@ -4,16 +4,27 @@ :_mod-docs-content-type: CONCEPT [id="ossm-about-metrics_{context}"] -= About metrics += Collect mesh metrics for service health and dashboards [role="_abstract"] -You can monitor service mesh application health and performance by using the platform monitoring stack to track Layer 4 (L4) and Layer 7 (L7) metrics across sidecar, ztunnel, and waypoint proxies. +To monitor the health and performance of your applications, you can use the platform monitoring stack to track Layer 4 (L4) and Layer 7 (L7) metrics across sidecar, ztunnel, and waypoint proxies. + +[id="monitoring-stack_{context}"] +== Monitoring stack Every {ocp-product-title} installation deploys monitoring stack components by default, and the Cluster Monitoring Operator (CMO) manages them. These components include Prometheus, Alertmanager, Thanos Querier, and others. The CMO also deploys the Telemeter Client, which sends a subset of data from platform Prometheus instances to Red{nbsp}Hat to ease Remote Health Monitoring for clusters. -When you have added your application to the mesh, you can monitor the in-cluster health and performance of your applications running on {ocp-product-title} with metrics and customized alerts for CPU and memory usage, network connectivity, and other resource usage. +By default, the monitoring stack only collects metrics from platform components. To collect metrics from your mesh control plane and proxies, you must enable user-workload monitoring, which extends the monitoring stack to scrape metrics from user-defined namespaces. + +[id="sidecar-mode-metrics_{context}"] +== Sidecar mode metrics + +In sidecar mode, the Envoy sidecar proxy on each workload exposes both L4 and L7 metrics directly, so you can collect TCP and HTTP traffic metrics from a single source. + +[id="ambient-mode-metrics_{context}"] +== Ambient mode metrics -When you have added your application to the mesh in ambient mode, you can monitor the {istio} standard metrics of your application from the `ztunnel` resource and the waypoint proxies. The ztunnel also exposes a variety of DNS and debugging metrics. +In ambient mode, you can monitor the {istio} standard metrics of your application from the `ztunnel` resource and the waypoint proxies. The ztunnel also exposes a variety of DNS and debugging metrics. Ambient mode uses two proxy layers, which results in two types of metrics for each application service. You can collect L4 TCP metrics from both the ztunnel and the waypoint proxies. You can collect L7 metrics, such as HTTP traffic metrics, from the waypoint proxies. \ No newline at end of file diff --git a/modules/ossm-about-mtls-planning.adoc b/modules/ossm-about-mtls-planning.adoc index 59aebf9ea1d..39770ab3a6e 100644 --- a/modules/ossm-about-mtls-planning.adoc +++ b/modules/ossm-about-mtls-planning.adoc @@ -8,22 +8,23 @@ [role="_abstract"] -Mutual Transport Layer Security (mTLS) provides both identity verification and encryption for communication between services in the mesh. It is the foundation that other mesh security features build on. +Mutual Transport Layer Security (mTLS) provides both identity verification and encryption for communication between services in the mesh. +It is the foundation that other mesh security features build on. -[id="what-mutual-tls-is_{context}"] == What mutual TLS is -In standard TLS, only the server proves its identity to the client. Mutual TLS requires both sides of a connection to present certificates and verify each other's identity. This ensures that a service can trust who is sending a request, not just that the connection is encrypted. +In standard TLS, only the server proves its identity to the client. +Mutual TLS requires both sides of a connection to present certificates and verify each other's identity. +This ensures that a service can trust who is sending a request, not just that the connection is encrypted. -When mTLS is active, every connection between services is both authenticated and encrypted. A service that cannot present a valid certificate is rejected, which prevents unauthorized workloads from communicating inside the mesh. +When mTLS is active, every connection between services is both authenticated and encrypted. +A service that cannot present a valid certificate is rejected, which prevents unauthorized workloads from communicating inside the mesh. -[id="how-mutual-tls-works-in-a-service-mesh_{context}"] == How mutual TLS works in a service mesh In a service mesh, application code does not need to change to use mTLS. The control plane issues a certificate to each workload, and the mesh proxies use those certificates to authenticate and encrypt connections automatically. How the proxy handles mTLS depends on the data plane mode: in sidecar mode, each pod has its own proxy that manages mTLS for that pod; in ambient mode, a shared ztunnel proxy on each node manages mTLS for all workloads on that node. -[id="mesh-security-features-that-build-on-mutual-tls_{context}"] == Mesh security features that build on mutual TLS The identity and encryption that mTLS provides are the foundation for other mesh security features, including authorization policies, certificate management with cert-manager, attested workload identity with SPIRE, and post-quantum cryptography. diff --git a/modules/ossm-about-mtls.adoc b/modules/ossm-about-mtls.adoc index c5bb99fb1f6..0695454adcd 100644 --- a/modules/ossm-about-mtls.adoc +++ b/modules/ossm-about-mtls.adoc @@ -4,14 +4,10 @@ :_mod-docs-content-type: CONCEPT [id="ossm-about-mtls_{context}"] -= About mutual Transport Layer Security (mTLS) += Mutual TLS in {SMProductName} [role="_abstract"] -In {SMProduct} 3, you use the `{istio}` resource instead of the `ServiceMeshControlPlane` resource to configure mTLS settings. - -In {SMProduct} 3, you configure `STRICT` mTLS mode by using the `PeerAuthentication` and `DestinationRule` resources. You set TLS protocol versions through {istio} Workload Minimum TLS Version Configuration. - Review the following `{istio}` resources and concepts to configure mTLS settings properly: `PeerAuthentication`:: defines the type of mTLS traffic a sidecar accepts. `PERMISSIVE` mode allows both plain text and mTLS traffic. `STRICT` mode requires mTLS for all incoming traffic.. diff --git a/modules/ossm-about-multi-cluster-mesh-topologies.adoc b/modules/ossm-about-multi-cluster-mesh-topologies.adoc index 91d7f65b3c0..6a9d5838daf 100644 --- a/modules/ossm-about-multi-cluster-mesh-topologies.adoc +++ b/modules/ossm-about-multi-cluster-mesh-topologies.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: CONCEPT [id="ossm-about-multi-cluster-mesh-topologies_{context}"] -= About multi-cluster mesh topologies += Extend your mesh across multiple clusters [role="_abstract"] diff --git a/modules/ossm-about-observability-service-mesh.adoc b/modules/ossm-about-observability-service-mesh.adoc index 296dc2bebec..8b85fcc55ff 100644 --- a/modules/ossm-about-observability-service-mesh.adoc +++ b/modules/ossm-about-observability-service-mesh.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: CONCEPT [id="ossm-about-observability-service-mesh_{context}"] -= About Observability and Service Mesh += Observability and Service Mesh [role="_abstract"] diff --git a/modules/ossm-about-pqc-service-mesh.adoc b/modules/ossm-about-pqc-service-mesh.adoc index 57c9a70860f..c9cab6d33ab 100644 --- a/modules/ossm-about-pqc-service-mesh.adoc +++ b/modules/ossm-about-pqc-service-mesh.adoc @@ -4,17 +4,18 @@ :_mod-docs-content-type: CONCEPT [id="ossm-about-pqc-service-mesh_{context}"] -= {pqc-short} in a service mesh += {pqc} ({pqc-short}) in {SMProductName} [role="_abstract"] -{pqc}, also known as quantum-resistant cryptography, uses encryption algorithms designed to resist attacks from quantum computers. +Standard encryption algorithms that protect your mesh traffic today are vulnerable to future quantum computing attacks. An adversary with access to a large-scale quantum computer could break widely used key exchange mechanisms, exposing service-to-service communication and gateway traffic. -Quantum computers use principles of quantum mechanics to perform certain calculations significantly faster than classical computers, compromising widely used cryptographic algorithms. +{pqc} addresses this threat by introducing quantum-resistant key exchange algorithms. You can enable {pqc-short} in {SMProductName} to protect: -Most current encryption methods rely on mathematical problems that classical computers cannot solve in a practical time. Large-scale quantum computers could solve some of these problems more efficiently, which would weaken the security of existing cryptographic systems. +* *Mesh-internal traffic* — mTLS communication between workloads, in both sidecar and ambient modes +* *Gateway traffic* — TLS connections at ingress and egress gateways -In {SMProductName}, cryptographic algorithms protect control plane and data plane communications, including mutual TLS (mTLS) between workloads. Enabling {pqc-short} strengthens these communications by introducing quantum-resistant key exchange mechanisms while maintaining compatibility with existing infrastructure. +These protections are independent — you can enable {pqc-short} for mesh traffic, gateway traffic, or both, depending on your security requirements. [NOTE] ==== diff --git a/modules/ossm-about-revisionbased-strategy.adoc b/modules/ossm-about-revisionbased-strategy.adoc index d5476d7303c..685e5eecd17 100644 --- a/modules/ossm-about-revisionbased-strategy.adoc +++ b/modules/ossm-about-revisionbased-strategy.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: CONCEPT [id="about-revisionbased-strategy_{context}"] -= About RevisionBased strategy += RevisionBased update strategy [role="_abstract"] diff --git a/modules/ossm-about-sidecar-injection.adoc b/modules/ossm-about-sidecar-injection.adoc index e5fcfd2b867..6273caa1566 100644 --- a/modules/ossm-about-sidecar-injection.adoc +++ b/modules/ossm-about-sidecar-injection.adoc @@ -16,4 +16,4 @@ Namespace labels:: Apply an injection label to a namespace to inject sidecars in Pod labels:: Apply an injection label to individual pod templates to control which specific workloads receive a sidecar. Use this approach when you need fine-grained control over which workloads are in the mesh. -Namespace labels and an `IstioRevisionTag` resource:: Create an `IstioRevisionTag` resource to provide a stable alias for a control plane revision, and then use namespace labels to inject sidecars. This approach simplifies workload management during revision-based upgrades. +Namespace labels and an IstioRevisionTag resource:: Create an `IstioRevisionTag` resource to provide a stable alias for a control plane revision, and then use namespace labels to inject sidecars. This approach simplifies workload management during revision-based upgrades. diff --git a/modules/ossm-about-sidecar-proxies.adoc b/modules/ossm-about-sidecar-proxies.adoc index 14c03832610..1d1cbcc7400 100644 --- a/modules/ossm-about-sidecar-proxies.adoc +++ b/modules/ossm-about-sidecar-proxies.adoc @@ -16,7 +16,7 @@ Sidecar proxy:: A per-pod proxy that intercepts all inbound and outbound TCP tra Sidecar injection:: The process by which the control plane automatically adds a proxy container to application pods at creation time. An admission controller watches for pods with valid injection labels and injects the proxy before the pod starts. You can enable injection at the namespace level or on individual pods. -Traffic interception:: The mechanism that transparently redirects network traffic through the sidecar proxy. The {istio} Container Network Interface (CNI) plugin configures traffic redirection rules within the pod network namespace so that the application sends and receives traffic normally while the proxy processes it transparently. +Traffic interception:: The mechanism that transparently redirects network traffic through the sidecar proxy. The {istio} CNI plugin configures traffic redirection rules within the pod network namespace so that the application sends and receives traffic normally while the proxy processes it transparently. Sidecar mode offers the following benefits: @@ -24,11 +24,11 @@ Sidecar mode offers the following benefits: * *Full L4 and L7 capability* in every pod, enabling traffic routing, retries, circuit breaking, fault injection, authorization policies, and detailed telemetry without deploying additional components. -* *Mature ecosystem* with broad community support, extensive documentation, and compatibility with the full range of traffic management resources such as `VirtualService`, `DestinationRule`, and `AuthorizationPolicy`. +* *Mature ecosystem* with broad community support, extensive documentation, and compatibility with the full range of traffic management resources such as VirtualService, DestinationRule, and AuthorizationPolicy. Sidecar mode has the following operational considerations: -* *Resource consumption* because each pod runs its own proxy container, which consumes additional CPU and memory. For large deployments with many pods, this resource usage can be significant. +* *Resource overhead* because each pod runs its own proxy container, which consumes additional CPU and memory. For large deployments with many pods, this overhead can be significant. * *Pod restarts required for proxy updates* because the proxy runs as a container within the pod. When the control plane is updated, workloads must be restarted to receive the updated proxy version. diff --git a/modules/ossm-about-uninstalling-console-plugin.adoc b/modules/ossm-about-uninstalling-console-plugin.adoc index b57243e8d39..bc5e3705b7d 100644 --- a/modules/ossm-about-uninstalling-console-plugin.adoc +++ b/modules/ossm-about-uninstalling-console-plugin.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: CONCEPT [id="ossm-about-uninstalling-console-plugin_{context}"] -= About uninstalling {sm-plugin-full} += Requirements for uninstalling the OSSMC plugin [role="_abstract"] diff --git a/modules/ossm-about-update-strategies-in-ambient-mode.adoc b/modules/ossm-about-update-strategies-in-ambient-mode.adoc index 9c1eafe0b1f..15e37641faf 100644 --- a/modules/ossm-about-update-strategies-in-ambient-mode.adoc +++ b/modules/ossm-about-update-strategies-in-ambient-mode.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: CONCEPT [id="ossm-about-update-strategies-in-ambient-mode_{context}"] -= About the update strategies in ambient mode += Ambient mode upgrade sequence and strategy [role="_abstract"] @@ -16,4 +16,9 @@ Update sequence:: To update in ambient mode, use the following sequence: .. {istio} CNI: Update to the same patch version as the control plane. -.. ZTunnel: Update to the same patch version as the control plane. \ No newline at end of file +.. ztunnel: Update to the same patch version as the control plane. + +[NOTE] +==== +If your cluster includes {op-system-base-full} 10 nodes, you must enable `nftables` support by setting `spec.values.global.nativeNftables` to `true` in both the `{istio}` and `IstioCNI` resources. Existing nodes that were previously configured with `iptables` may need to be rebooted to complete the migration to the `nftables` backend. +==== \ No newline at end of file diff --git a/modules/ossm-adding-authorization-policy.adoc b/modules/ossm-adding-authorization-policy.adoc index 6b454161a0b..eb6c25ed9a4 100644 --- a/modules/ossm-adding-authorization-policy.adoc +++ b/modules/ossm-adding-authorization-policy.adoc @@ -4,11 +4,19 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-adding-authorization-policy_{context}"] -= Adding authorization policy += Add an authorization policy for a service [role="_abstract"] -Use an Layer 7 (L7) authorization policy to explicitly allow the `curl` service to send `GET` requests to the `productpage` service while blocking all other operations. +Use a Layer 7 (L7) authorization policy to explicitly allow the `curl` service to send `GET` requests to the Bookinfo `productpage` service while blocking all other operations. This example uses ambient mode with a waypoint proxy to enforce the policy. + +.Prerequisites + +* You have deployed {istio} in ambient mode. + +* You have deployed a waypoint proxy for the `bookinfo` namespace. + +* You have deployed the Bookinfo sample application in the `bookinfo` namespace. .Procedure diff --git a/modules/ossm-applying-certificates-to-a-multi-cluster-topology.adoc b/modules/ossm-applying-certificates-to-a-multi-cluster-topology.adoc index 7428d7a8570..f162ba35e02 100644 --- a/modules/ossm-applying-certificates-to-a-multi-cluster-topology.adoc +++ b/modules/ossm-applying-certificates-to-a-multi-cluster-topology.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-applying-certificates-to-a-multi-cluster-topology_{context}"] -= Applying certificates to a multi-cluster topology += Apply certificates to a multi-cluster topology [role="_abstract"] diff --git a/modules/ossm-cert-manager-planning.adoc b/modules/ossm-cert-manager-planning.adoc index 278516bd4af..ed5a09980d3 100644 --- a/modules/ossm-cert-manager-planning.adoc +++ b/modules/ossm-cert-manager-planning.adoc @@ -11,7 +11,6 @@ By default, {SMProductShortName} uses a built-in certificate authority (CA) to issue the certificates that workloads use for mutual TLS (mTLS). The cert-manager tool provides an alternative that integrates with external public key infrastructure (PKI) for organizations that need more control over certificate lifecycle management. -[id="what-cert-manager-does_{context}"] == What cert-manager does The cert-manager tool automates the issuance, renewal, and rotation of X.509 certificates in a {k8s} environment. @@ -20,7 +19,6 @@ It connects to certificate authorities through a unified API, so you can use a s When integrated with {SMProductShortName}, cert-manager replaces the built-in CA and manages the certificates that workloads use for mTLS. An agent called `istio-csr` handles certificate signing requests from the mesh proxies and delegates signing to cert-manager, which forwards requests to the configured CA. -[id="when-to-use-cert-manager_{context}"] == When to use cert-manager The built-in CA is sufficient for many deployments. @@ -31,7 +29,6 @@ Consider using cert-manager when your organization has any of the following requ * You need consistent certificate management across multiple clusters, because each cluster's built-in CA issues its own independent certificates. * You want automated certificate rotation with configurable renewal windows. -[id="compatibility_{context}"] == Compatibility The cert-manager integration works with both sidecar and ambient data plane modes. diff --git a/modules/ossm-config-dt-ambient-mode.adoc b/modules/ossm-config-dt-ambient-mode.adoc index 63b9a7b4127..d6d03775f8e 100644 --- a/modules/ossm-config-dt-ambient-mode.adoc +++ b/modules/ossm-config-dt-ambient-mode.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-config-dt-ambient-mode_{context}"] -= Configuring {TempoName} with Service Mesh ambient mode += Configure {TempoName} with Service Mesh ambient mode [role="_abstract"] diff --git a/modules/ossm-config-openshift-monitoring-ambient-mode.adoc b/modules/ossm-config-openshift-monitoring-ambient-mode.adoc index ac800df2b3f..7cb6efd332b 100644 --- a/modules/ossm-config-openshift-monitoring-ambient-mode.adoc +++ b/modules/ossm-config-openshift-monitoring-ambient-mode.adoc @@ -4,21 +4,21 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-config-openshift-monitoring-ambient-mode_{context}"] -= Configuring OpenShift Monitoring with Service Mesh ambient mode += Configure OpenShift Monitoring with Service Mesh ambient mode [role="_abstract"] -You can integrate {SMProductName} with user-workload monitoring to enable observability in your service mesh ambient mode. User-workload monitoring provides access to essential built-in tools. Kiali requires this feature to run the dedicated console for {istio}. +Integrate {SMProductName} ambient mode with user-workload monitoring, a feature of the Monitoring stack for Red{nbsp}Hat OpenShift. Kiali requires this feature to run the dedicated console for {istio}. .Prerequisites * You have installed the {SMProductName} Operator. -* You have enabled the user-workload monitoring. +* You have enabled user-workload monitoring. + [NOTE] ==== -You can enable user workload monitoring by applying the `ConfigMap` change for metrics integration. For more information, see "Configuring user workload monitoring". +You can enable user-workload monitoring by applying the `ConfigMap` change for metrics integration. For more information, see "Configuring user workload monitoring" in the Monitoring stack for Red{nbsp}Hat OpenShift documentation. ==== .Procedure diff --git a/modules/ossm-config-openshift-monitoring-kiali.adoc b/modules/ossm-config-openshift-monitoring-kiali.adoc index bbbce98c6f4..aba134d124c 100644 --- a/modules/ossm-config-openshift-monitoring-kiali.adoc +++ b/modules/ossm-config-openshift-monitoring-kiali.adoc @@ -4,21 +4,21 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-config-openshift-monitoring-kiali_{context}"] -= Configuring OpenShift Monitoring with Kiali += Configure OpenShift Monitoring with Kiali [role="_abstract"] -The following steps show how to integrate the {KialiProduct} with user-workload monitoring. +Connect Kiali to user-workload monitoring so that Kiali can query mesh metrics from the platform monitoring stack and display traffic topology, health, and performance data. .Prerequisites * You have installed {SMProductName}. -* You have enabled user-workload monitoring. See "Enabling monitoring for user-defined projects". +* You have enabled user-workload monitoring. See "Enabling monitoring for user-defined projects" in Monitoring stack for Red Hat OpenShift documentation. -* You have configured OpenShift Monitoring with {SMProductShortName}. See "Configuring OpenShift Monitoring with Service Mesh". +* You have configured OpenShift Monitoring with {SMProductShortName}. -* You have {KialiProduct} 2.4 installed. +* You have {KialiProduct} 2.4 or a later version installed. .Procedure diff --git a/modules/ossm-config-openshift-monitoring-only.adoc b/modules/ossm-config-openshift-monitoring-only.adoc index 0291b0ce1ab..62797ab4338 100644 --- a/modules/ossm-config-openshift-monitoring-only.adoc +++ b/modules/ossm-config-openshift-monitoring-only.adoc @@ -4,21 +4,21 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-config-openshift-monitoring-only_{context}"] -= Configuring OpenShift Monitoring with Service Mesh += Configure OpenShift Monitoring with Service Mesh sidecar mode [role="_abstract"] -You can integrate {SMProductName} with user-workload monitoring to enable observability in your service mesh. User-workload monitoring provides access to essential built-in tools. Kiali requires this feature to run the dedicated console for {istio}. +Integrate {SMProductName} sidecar mode with user-workload monitoring, a feature of the Monitoring stack for Red{nbsp}Hat OpenShift. Kiali requires this feature to run the dedicated console for {istio}. .Prerequisites * You have installed the {SMProductName} Operator. -* You have enabled the user-workload monitoring. +* You have enabled user-workload monitoring. + [NOTE] ==== -You can enable user-workload monitoring by applying the `ConfigMap` change for metrics integration. For more information, see "Configuring user workload monitoring". +You can enable user-workload monitoring by applying the `ConfigMap` change for metrics integration. For more information, see "Configuring user workload monitoring" in the Monitoring stack for Red{nbsp}Hat OpenShift documentation. ==== .Procedure diff --git a/modules/ossm-config-otel-kiali.adoc b/modules/ossm-config-otel-kiali.adoc index 40a2c15478e..d51b64d1395 100644 --- a/modules/ossm-config-otel-kiali.adoc +++ b/modules/ossm-config-otel-kiali.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-config-otel-kiali_{context}"] -= Configuring {DTProductName} with {KialiProduct} += Configure {DTProductName} with {KialiProduct} [role="_abstract"] @@ -12,8 +12,6 @@ Analyze service communication and troubleshoot request flows within the mesh by .Prerequisites -* You have installed {SMProductName}. - * You have configured {DTShortName} with {SMProductName}. .Procedure diff --git a/modules/ossm-config-otel.adoc b/modules/ossm-config-otel.adoc index f4594c25f1b..893e4e48264 100644 --- a/modules/ossm-config-otel.adoc +++ b/modules/ossm-config-otel.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-config-otel_{context}"] -= Configuring {OTELName} with Service Mesh += Configure {OTELName} with Service Mesh [role="_abstract"] diff --git a/modules/ossm-configure-traffic-routing.adoc b/modules/ossm-configure-traffic-routing.adoc index 330029b0f1e..596bbcbdfb2 100644 --- a/modules/ossm-configure-traffic-routing.adoc +++ b/modules/ossm-configure-traffic-routing.adoc @@ -4,10 +4,8 @@ :_mod-docs-content-type: CONCEPT [id="ossm-configure-traffic-routing_{context}"] -= Traffic routing += Control traffic entering and leaving the mesh [role="_abstract"] -Control how traffic is distributed between application versions by configuring routing rules. The resources you use depend on your data plane mode. - -The following procedures use the Bookinfo application to demonstrate traffic splitting. +Configure ingress gateways to route external traffic into the mesh and egress gateways to control outbound traffic to external services. Gateway configuration resources depend on your data plane mode and the traffic management approach you choose. diff --git a/modules/ossm-configuring-istio-ha-replicacount.adoc b/modules/ossm-configuring-istio-ha-replicacount.adoc index 9ee119a2897..eae6b5ab410 100644 --- a/modules/ossm-configuring-istio-ha-replicacount.adoc +++ b/modules/ossm-configuring-istio-ha-replicacount.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-configuring-istio-ha-replicacount_{context}"] -= Configuring Istio HA by using replica count += Configure Istio HA with a replica count [role="_abstract"] diff --git a/modules/ossm-configuring-sm-pqc-ambient.adoc b/modules/ossm-configuring-sm-pqc-ambient.adoc index a936d39e582..40e58205ceb 100644 --- a/modules/ossm-configuring-sm-pqc-ambient.adoc +++ b/modules/ossm-configuring-sm-pqc-ambient.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-configuring-sm-pqc-ambient_{context}"] -= Configuring service mesh in ambient mode with {pqc-short} += Configure PQC for service mesh in ambient mode [role="_abstract"] diff --git a/modules/ossm-configuring-sm-pqc-gateways.adoc b/modules/ossm-configuring-sm-pqc-gateways.adoc index ef7744410c2..4ff71dd77cc 100644 --- a/modules/ossm-configuring-sm-pqc-gateways.adoc +++ b/modules/ossm-configuring-sm-pqc-gateways.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-configuring-sm-pqc-gateways_{context}"] -= Configuring service mesh with {pqc-short} for gateways += Set the PQC key exchange for a gateway [role="_abstract"] diff --git a/modules/ossm-configuring-sm-pqc-mesh-wide.adoc b/modules/ossm-configuring-sm-pqc-mesh-wide.adoc index 6dc6f83e07b..d1e84387808 100644 --- a/modules/ossm-configuring-sm-pqc-mesh-wide.adoc +++ b/modules/ossm-configuring-sm-pqc-mesh-wide.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-configuring-sm-pqc-mesh-wide_{context}"] -= Configuring service mesh with mesh-wide {pqc-short} += Configure PQC for service mesh in sidecar mode [role="_abstract"] diff --git a/modules/ossm-configuring-ztunnel-grace-period.adoc b/modules/ossm-configuring-ztunnel-grace-period.adoc index 9e9ccaa2d85..92c9da10632 100644 --- a/modules/ossm-configuring-ztunnel-grace-period.adoc +++ b/modules/ossm-configuring-ztunnel-grace-period.adoc @@ -4,15 +4,15 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-configuring-ztunnel-grace-period_{context}"] -= Configuring the Ztunnel termination grace period += Configure the ztunnel termination grace period [role="_abstract"] -Configure a high termination grace period in the `ZTunnel` custom resource (CR) for the application pods to ensure that active connections close gracefully during a rolling update. +Configure a high termination grace period in the `ztunnel` custom resource (CR) for the application pods to ensure that active connections close gracefully during a rolling update. .Procedure -* Update the `terminationGracePeriodSeconds` value in the `ZTunnel` CR to a higher value similar to the following example: +* Update the `terminationGracePeriodSeconds` value in the `ztunnel` CR to a higher value similar to the following example: + [source,yaml,subs="attributes,verbatim"] ---- diff --git a/modules/ossm-creating-certificates-for-a-multi-cluster-topology.adoc b/modules/ossm-creating-certificates-for-a-multi-cluster-topology.adoc index 6915598f0cf..bd5922c8485 100644 --- a/modules/ossm-creating-certificates-for-a-multi-cluster-topology.adoc +++ b/modules/ossm-creating-certificates-for-a-multi-cluster-topology.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-creating-certificates-for-a-multi-cluster-topology_{context}"] -= Creating certificates for a multi-cluster topology += Create certificates for a multi-cluster topology [role="_abstract"] diff --git a/modules/ossm-customizing-istio-configuration.adoc b/modules/ossm-customizing-istio-configuration.adoc index 5e92d3d4483..884f4f8481c 100644 --- a/modules/ossm-customizing-istio-configuration.adoc +++ b/modules/ossm-customizing-istio-configuration.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-customizing-istio_{context}"] -= Customizing {istio} configuration += Edit the control plane YAML [role="_abstract"] diff --git a/modules/ossm-decide-if-service-mesh-fits.adoc b/modules/ossm-decide-if-service-mesh-fits.adoc index 18fae5e59bc..4564b064e3d 100644 --- a/modules/ossm-decide-if-service-mesh-fits.adoc +++ b/modules/ossm-decide-if-service-mesh-fits.adoc @@ -4,15 +4,16 @@ :_mod-docs-content-type: CONCEPT [id="ossm-decide-if-service-mesh-fits_{context}"] -= Decide if a service mesh is right for you += Decide if {SMProduct} is right for you [role="_abstract"] If your applications communicate across multiple services, a service mesh can simplify how you secure, observe, and manage that communication. -Microservice architectures split the work of an application into modular services, which makes scaling and maintenance easier. However, as the number of services grows, the communication between them becomes difficult to understand and manage. Without a service mesh, each application team must implement its own solutions for encryption, authentication, traffic routing, and failure handling. Each team must also keep those solutions consistent as the environment grows. +Without a service mesh, each application team must implement its own solutions for encryption, authentication, traffic routing, and failure handling — and keep those solutions consistent as the environment grows. -{SMProduct} handles these concerns at the infrastructure level, so your application code stays focused on business logic. Consider {SMProductShortName} if your environment has any of the following characteristics: +{SMProductShortName} handles these concerns at the infrastructure level, so your application code stays focused on business logic. +Consider {SMProductShortName} if your environment has any of the following characteristics: * Multiple services that need encrypted, authenticated communication * A requirement to enforce consistent security and traffic policies across teams diff --git a/modules/ossm-deploy-in-ambient-mode.adoc b/modules/ossm-deploy-in-ambient-mode.adoc index 80d733f3686..1cd59214830 100644 --- a/modules/ossm-deploy-in-ambient-mode.adoc +++ b/modules/ossm-deploy-in-ambient-mode.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: CONCEPT [id="ossm-deploy-in-ambient-mode_{context}"] -= Deploy a mesh in ambient mode += Deploy in ambient mode [role="_abstract"] diff --git a/modules/ossm-deploying-first-control-plane.adoc b/modules/ossm-deploying-first-control-plane.adoc index 8d0249f2d12..af324b0913d 100644 --- a/modules/ossm-deploying-first-control-plane.adoc +++ b/modules/ossm-deploying-first-control-plane.adoc @@ -4,11 +4,11 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-deploying-first-control-plane_{context}"] -= Deploying the first control plane += Deploy the first control plane [role="_abstract"] -You deploy the first control plane by creating its assigned namespace. +To deploy the first control plane, create its assigned namespace. .Prerequisites diff --git a/modules/ossm-deploying-second-control-plane.adoc b/modules/ossm-deploying-second-control-plane.adoc index 146dbf4ad05..99619255a09 100644 --- a/modules/ossm-deploying-second-control-plane.adoc +++ b/modules/ossm-deploying-second-control-plane.adoc @@ -4,11 +4,11 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-deploying-second-control-plane_{context}"] -= Deploying the second control plane += Deploy the second control plane [role="_abstract"] -After deploying the first control plane, you can deploy the second control plane by creating its assigned namespace. +After deploying the first control plane, deploy the second control plane by creating its assigned namespace. .Procedure diff --git a/modules/ossm-edge-traffic-planning.adoc b/modules/ossm-edge-traffic-planning.adoc index cfc26261963..6f00a561df9 100644 --- a/modules/ossm-edge-traffic-planning.adoc +++ b/modules/ossm-edge-traffic-planning.adoc @@ -17,7 +17,6 @@ Gateways provide a managed entry and exit point where you can enforce policies a * An ingress gateway accepts traffic from external clients and routes it to services inside the mesh. * An egress gateway routes traffic from mesh services to external destinations. -[id="security-at-the-mesh-boundary_{context}"] == Security at the mesh boundary Mutual TLS (mTLS) encrypts traffic automatically between proxies inside the mesh, but it is a proxy-to-proxy protocol. mTLS does not extend to external clients or services that are not part of the mesh. diff --git a/modules/ossm-enable-pqc.adoc b/modules/ossm-enable-pqc.adoc new file mode 100644 index 00000000000..6ff9af47692 --- /dev/null +++ b/modules/ossm-enable-pqc.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-enable-pqc_{context}"] += Configure post-quantum cryptography (PQC) + +[role="_abstract"] + +Protect your mesh against future quantum computing threats by enabling {pqc} ({pqc-short}) for mesh-internal traffic, gateway traffic, or both. Each area is configured independently, so you can adopt {pqc-short} incrementally based on your security requirements. diff --git a/modules/ossm-generating-tls-certificates.adoc b/modules/ossm-generating-tls-certificates.adoc index 294c605a8b8..f97a05aa489 100644 --- a/modules/ossm-generating-tls-certificates.adoc +++ b/modules/ossm-generating-tls-certificates.adoc @@ -4,11 +4,11 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-generating-tls-certificates_{context}"] -= Generating TLS certificates += Generate TLS certificates to secure an ingress gateway [role="_abstract"] -Generate Transport Layer Security (TLS) certificates and create a secret to secure ingress traffic for a service mesh gateway. +Generate Transport Layer Security (TLS) certificates and create a secret to secure ingress traffic for a service mesh gateway. This procedure uses sample domain names and the HTTPbin application. .Procedure diff --git a/modules/ossm-install-console-plugin-ocp-cli.adoc b/modules/ossm-install-console-plugin-ocp-cli.adoc index 08dae9f48bd..eeb7f7c3ea7 100644 --- a/modules/ossm-install-console-plugin-ocp-cli.adoc +++ b/modules/ossm-install-console-plugin-ocp-cli.adoc @@ -8,7 +8,7 @@ [role="_abstract"] -You can install the {SMPlugin} by using the {ocp-short-name} CLI. +Create an `OSSMConsole` resource from the command line to add {SMProductShortName} observability views to the {ocp-short-name} web console. .Prerequisites diff --git a/modules/ossm-install-console-plugin-ocp-web-console.adoc b/modules/ossm-install-console-plugin-ocp-web-console.adoc index 8a33bde0f49..23d98225f4a 100644 --- a/modules/ossm-install-console-plugin-ocp-web-console.adoc +++ b/modules/ossm-install-console-plugin-ocp-web-console.adoc @@ -4,11 +4,11 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-install-console-plugin-ocp-web-console_{context}"] -= Installing {SMPluginShort} by using the {ocp-product-title} web console += Install {SMPluginShort} with the {ocp-product-title} web console [role="_abstract"] -You can install the {SMPlugin} by using the {ocp-product-title} web console. +Create an `OSSMConsole` resource from the {ocp-short-name} web console to add {SMProductShortName} observability views to the console. .Prerequisites @@ -16,9 +16,9 @@ You can install the {SMPlugin} by using the {ocp-product-title} web console. * You have installed the {SMProduct} (OSSM). -* You have installed the `{istio}` control plane from OSSM 3.0. +* You have installed the `{istio}` control plane from OSSM 3. -* You have installed the {KialiServer} 2.4. +* You have installed the {KialiServer} 2.4 or a later version. .Procedure @@ -41,4 +41,4 @@ The *Version* field must match with the `spec.version` field in your Kiali custo . Wait for the web console to confirm the {SMPluginShort} installation and prompt you to refresh. -. Verify that the *{SMProductShortName}* category shows up in the main {ocp-product-title} web console navigation. \ No newline at end of file +. Verify that the *{SMProductShortName}* category shows up in the main {ocp-product-title} web console navigation. diff --git a/modules/ossm-install-kiali-operator.adoc b/modules/ossm-install-kiali-operator.adoc index 1e6c3839827..cfe46528ff5 100644 --- a/modules/ossm-install-kiali-operator.adoc +++ b/modules/ossm-install-kiali-operator.adoc @@ -4,11 +4,11 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-install-kiali-operator_{context}"] -= Installing the {KialiProduct} += Install the {KialiProduct} [role="_abstract"] -The following steps show how to install the {KialiProduct}. +Install the {KialiProduct} from the {ocp-short-name} web console to enable the Kiali observability console and the {SMPlugin} for your mesh. [WARNING] ==== diff --git a/modules/ossm-installing-cert-manager.adoc b/modules/ossm-installing-cert-manager.adoc index 48f441bff44..57ef08e438d 100644 --- a/modules/ossm-installing-cert-manager.adoc +++ b/modules/ossm-installing-cert-manager.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-installing-cert-manager_{context}"] -= Integrating Service Mesh with the cert-manager Operator by using the istio-csr agent += Integrate {SMProductShortName} with cert-manager [role="_abstract"] diff --git a/modules/ossm-installing-external-control-plane.adoc b/modules/ossm-installing-external-control-plane.adoc index 67bf7810c93..be8d5c49f1f 100644 --- a/modules/ossm-installing-external-control-plane.adoc +++ b/modules/ossm-installing-external-control-plane.adoc @@ -4,16 +4,11 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-installing-external-control-plane_{context}"] -= Installing the control plane and data plane on separate clusters += Install the control plane and data plane on separate clusters [role="_abstract"] -Install {istio} on a control plane cluster and a separate data plane cluster. This installation approach provides increased security. - -[NOTE] -==== -You can adapt these instructions for a mesh spanning more than one data plane cluster. You can also adapt these instructions for multiple meshes with multiple control planes on the same control plane cluster. -==== +To isolate mesh management from application workloads, install {istio} on a dedicated control plane cluster and deploy a separate data plane cluster that connects to it. .Prerequisites @@ -21,6 +16,11 @@ You can adapt these instructions for a mesh spanning more than one data plane cl * You have `istioctl` installed on the laptop you will use to run these instructions. +[NOTE] +==== +You can adapt the following steps for a mesh spanning more than one data plane cluster. You can also adapt these instructions for multiple meshes with multiple control planes on the same control plane cluster. +==== + .Procedure . Create an `ISTIO_VERSION` environment variable that defines the {istio} version to install on all the clusters by running the following command: diff --git a/modules/ossm-installing-istio-with-inplace-strategy.adoc b/modules/ossm-installing-istio-with-inplace-strategy.adoc index 1c579907df1..23bbb0434f1 100644 --- a/modules/ossm-installing-istio-with-inplace-strategy.adoc +++ b/modules/ossm-installing-istio-with-inplace-strategy.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="installing-istio-with-inplace-strategy_{context}"] -= Installing with InPlace update strategy += Install the control plane with InPlace strategy [role="_abstract"] diff --git a/modules/ossm-installing-istio-with-revisionbased-strategy-istiorevisiontag.adoc b/modules/ossm-installing-istio-with-revisionbased-strategy-istiorevisiontag.adoc index 9f5f2fb6055..4ba69426fba 100644 --- a/modules/ossm-installing-istio-with-revisionbased-strategy-istiorevisiontag.adoc +++ b/modules/ossm-installing-istio-with-revisionbased-strategy-istiorevisiontag.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="installing-istio-with-revisionbased-strategy-istiorevisiontag_{context}"] -= Installing Istio with RevisionBased strategy and IstioRevisionTag += Install the control plane with RevisionBased strategy and IstioRevisionTag [role="_abstract"] diff --git a/modules/ossm-installing-istio-with-revisionbased-strategy.adoc b/modules/ossm-installing-istio-with-revisionbased-strategy.adoc index d0d0c30d4f9..25727a8c6e9 100644 --- a/modules/ossm-installing-istio-with-revisionbased-strategy.adoc +++ b/modules/ossm-installing-istio-with-revisionbased-strategy.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="installing-istio-with-revisionbased-strategy_{context}"] -= Installing Istio with RevisionBased strategy += Install the control plane with RevisionBased strategy [role="_abstract"] diff --git a/modules/ossm-installing-kiali-multi-cluster-mesh.adoc b/modules/ossm-installing-kiali-multi-cluster-mesh.adoc index 2b73ba9e9ad..deca8ea0558 100644 --- a/modules/ossm-installing-kiali-multi-cluster-mesh.adoc +++ b/modules/ossm-installing-kiali-multi-cluster-mesh.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-installing-kiali-multi-cluster-mesh_{context}"] -= Installing Kiali in a multi-cluster mesh += Install Kiali in a multi-cluster mesh [role="_abstract"] diff --git a/modules/ossm-installing-kiali-operator-on-remote-clusters.adoc b/modules/ossm-installing-kiali-operator-on-remote-clusters.adoc index a1dc1da996b..c556bc44969 100644 --- a/modules/ossm-installing-kiali-operator-on-remote-clusters.adoc +++ b/modules/ossm-installing-kiali-operator-on-remote-clusters.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-installing-kiali-operator-on-remote-clusters_{context}"] -= Installing Kiali Operator on remote clusters += Install Kiali Operator on remote clusters [role="_abstract"] diff --git a/modules/ossm-installing-multi-primary-multi-network-mesh-ambient.adoc b/modules/ossm-installing-multi-primary-multi-network-mesh-ambient.adoc index 2cc2fc34d11..38a7aba9755 100644 --- a/modules/ossm-installing-multi-primary-multi-network-mesh-ambient.adoc +++ b/modules/ossm-installing-multi-primary-multi-network-mesh-ambient.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-installing-multi-primary-multi-network-mesh-ambient_{context}"] -= Installing a multi-primary multi-network mesh in ambient mode += Install a multi-primary multi-network mesh in ambient mode [role="_abstract"] Install {istio} and configure it for ambient mode in the multi-primary multi-network topology on two {ocp-product-title} clusters. @@ -194,7 +194,7 @@ EOF $ oc get project ztunnel --context "${CTX_CLUSTER2}" || oc new-project ztunnel --context "${CTX_CLUSTER2}" ---- -.. Create a ztunnel custom resource as shown in the following example: +.. Create a ztunnel custom resource as shown in the following example: + [source,terminal] ---- @@ -256,24 +256,24 @@ $ oc --context="${CTX_CLUSTER2}" wait gateway/istio-eastwestgateway -n istio-sys + [source,terminal] ---- -$ oc --context="${CTX_CLUSTER1}" create serviceaccount istio-reader-service-account -n istio-system +$ oc --context="${CTX_CLUSTER1}" create serviceaccount istio-reader-service-account -n istio-system ---- . Create the `istio-reader-service-account` service account for the West cluster by running the following command: + [source,terminal] ---- -$ oc --context="${CTX_CLUSTER2}" create serviceaccount istio-reader-service-account -n istio-system +$ oc --context="${CTX_CLUSTER2}" create serviceaccount istio-reader-service-account -n istio-system ---- -. Add the `cluster-reader` role to the East cluster by running the following command: +. Add the `cluster-reader` role to the East cluster by running the following command: + [source,terminal] ---- $ oc --context="${CTX_CLUSTER1}" adm policy add-cluster-role-to-user cluster-reader -z istio-reader-service-account -n istio-system ---- -. Add the `cluster-reader` role to the West cluster by running the following command: +. Add the `cluster-reader` role to the West cluster by running the following command: + [source,terminal] ---- @@ -288,7 +288,7 @@ $ istioctl create-remote-secret \ --context="${CTX_CLUSTER2}" \ --name=cluster2 \ --create-service-account=false | \ - oc --context="${CTX_CLUSTER1}" apply -f - + oc --context="${CTX_CLUSTER1}" apply -f - ---- . Install a remote secret on the West cluster that provides access to the API server on the East cluster by running the following command: diff --git a/modules/ossm-installing-multi-primary-multi-network-mesh.adoc b/modules/ossm-installing-multi-primary-multi-network-mesh.adoc index b7adbb1a645..1df0d3d109c 100644 --- a/modules/ossm-installing-multi-primary-multi-network-mesh.adoc +++ b/modules/ossm-installing-multi-primary-multi-network-mesh.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-installing-multi-primary-multi-network-mesh_{context}"] -= Installing a multi-primary multi-network mesh with sidecar support += Install a multi-primary multi-network mesh with sidecar support [role="_abstract"] @@ -156,17 +156,17 @@ $ oc --context="${CTX_CLUSTER1}" create serviceaccount istio-reader-service-acco + [source,terminal] ---- -$ oc --context="${CTX_CLUSTER2}" create serviceaccount istio-reader-service-account -n istio-system +$ oc --context="${CTX_CLUSTER2}" create serviceaccount istio-reader-service-account -n istio-system ---- -. Add the `cluster-reader` role to the East cluster by running the following command: +. Add the `cluster-reader` role to the East cluster by running the following command: + [source,terminal] ---- $ oc --context="${CTX_CLUSTER1}" adm policy add-cluster-role-to-user cluster-reader -z istio-reader-service-account -n istio-system ---- -. Add the `cluster-reader` role to the West cluster by running the following command: +. Add the `cluster-reader` role to the West cluster by running the following command: + [source,terminal] ---- @@ -181,7 +181,7 @@ $ istioctl create-remote-secret \ --context="${CTX_CLUSTER2}" \ --name=cluster2 \ --create-service-account=false | \ - oc --context="${CTX_CLUSTER1}" apply -f - + oc --context="${CTX_CLUSTER1}" apply -f - ---- . Install a remote secret on the West cluster that provides access to the API server on the East cluster by running the following command: @@ -192,5 +192,5 @@ $ istioctl create-remote-secret \ --context="${CTX_CLUSTER1}" \ --name=cluster1 \ --create-service-account=false | \ - oc --context="${CTX_CLUSTER2}" apply -f - + oc --context="${CTX_CLUSTER2}" apply -f - ---- \ No newline at end of file diff --git a/modules/ossm-installing-operator.adoc b/modules/ossm-installing-operator.adoc index 879a0d18e5e..9d1e1fecfd2 100644 --- a/modules/ossm-installing-operator.adoc +++ b/modules/ossm-installing-operator.adoc @@ -8,7 +8,7 @@ [role="_abstract"] -Install the {SMProductName} Operator from the {ocp-product-title} web console. After installation, you can create custom resources to deploy the control plane in your chosen data plane mode. +The {SMProductName} Operator installs the custom resource definitions (CRDs) you need to deploy and configure {istio} control planes. After you install the Operator, you create custom resources such as `Istio` and `IstioCNI` to deploy the control plane, and the Operator manages their lifecycle. .Prerequisites diff --git a/modules/ossm-installing-primary-remote-multi-network-mesh.adoc b/modules/ossm-installing-primary-remote-multi-network-mesh.adoc index dd4b8a5c6fb..ceff10fa06a 100644 --- a/modules/ossm-installing-primary-remote-multi-network-mesh.adoc +++ b/modules/ossm-installing-primary-remote-multi-network-mesh.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-installing-primary-remote-multi-network-mesh_{context}"] -= Installing a primary-remote multi-network mesh += Install a primary-remote multi-network mesh [role="_abstract"] diff --git a/modules/ossm-installing-the-istioctl-tool.adoc b/modules/ossm-installing-the-istioctl-tool.adoc index 4738870e2f7..0f0dd97dbbc 100644 --- a/modules/ossm-installing-the-istioctl-tool.adoc +++ b/modules/ossm-installing-the-istioctl-tool.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-installing-the-istioctl-tool_{context}"] -= Installing the Istioctl tool += Install the Istioctl tool [role="_abstract"] diff --git a/modules/ossm-integrating-kiali-otel.adoc b/modules/ossm-integrating-kiali-otel.adoc index a06fd9840ce..e102d59d4c0 100644 --- a/modules/ossm-integrating-kiali-otel.adoc +++ b/modules/ossm-integrating-kiali-otel.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: CONCEPT [id="ossm-integrating-kiali-otel_{context}"] -= Integrating {DTProductName} with {KialiProduct} += Distributed tracing integration for Kiali [role="_abstract"] diff --git a/modules/ossm-isolate-workloads-multiple-meshes.adoc b/modules/ossm-isolate-workloads-multiple-meshes.adoc new file mode 100644 index 00000000000..29241708a04 --- /dev/null +++ b/modules/ossm-isolate-workloads-multiple-meshes.adoc @@ -0,0 +1,11 @@ +:_mod-docs-content-type: CONCEPT +[id="ossm-isolate-workloads-multiple-meshes_{context}"] += Isolate workloads with independent meshes on one cluster + +[role="_abstract"] +You can operate many service meshes in a single cluster, with each mesh managed by a separate control plane. This gives teams independent control over their mesh policies, security configuration, and upgrade lifecycle without affecting other teams on the same cluster. + +[NOTE] +==== +Running multiple meshes on a single cluster is supported in sidecar mode only. +==== diff --git a/modules/ossm-istioctl-tool-concept.adoc b/modules/ossm-istioctl-tool-concept.adoc new file mode 100644 index 00000000000..a5ebeb301ec --- /dev/null +++ b/modules/ossm-istioctl-tool-concept.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-istioctl-tool-concept_{context}"] += Diagnose and debug with Istioctl + +[role="_abstract"] + +Use the `istioctl` command line utility to perform diagnostic and debugging tasks for {SMProduct} 3 service mesh components. diff --git a/modules/ossm-kiali-about.adoc b/modules/ossm-kiali-about.adoc index 2a88f3ffdda..90cd63da42e 100644 --- a/modules/ossm-kiali-about.adoc +++ b/modules/ossm-kiali-about.adoc @@ -4,13 +4,11 @@ :_mod-docs-content-type: CONCEPT [id="ossm-kiali-about_{context}"] -= About Kiali += Kiali for {SMProductName} [role="_abstract"] -After you add an application to your mesh, you can use Kiali Operator provided by Red Hat to view the data flowing through the application. - -{KialiProduct} is the management console for {SMProductName} and derives its core functionality from the open source Kiali project. It provides dashboards, observability, and robust configuration and validation capabilities. +{KialiProduct} is the management console for {SMProduct} and derives its core functionality from the open source Kiali project. It provides dashboards, observability, and robust configuration and validation capabilities. [id="kiali-architecture_{context}"] == Kiali architecture diff --git a/modules/ossm-kiali-ambient-mode.adoc b/modules/ossm-kiali-ambient-mode.adoc index 0816037deaa..d5df77037d5 100644 --- a/modules/ossm-kiali-ambient-mode.adoc +++ b/modules/ossm-kiali-ambient-mode.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: CONCEPT [id="ossm-kiali-ambient-mode_{context}"] -= About Kiali and Istio ambient mode += Kiali and {SMProduct} ambient mode [role="_abstract"] diff --git a/modules/ossm-kiali-planning.adoc b/modules/ossm-kiali-planning.adoc index fca1463d034..0fa25320688 100644 --- a/modules/ossm-kiali-planning.adoc +++ b/modules/ossm-kiali-planning.adoc @@ -8,11 +8,14 @@ [role="_abstract"] -Kiali is the observability console for {SMProductShortName}. It provides a visual interface for monitoring, configuring, and troubleshooting your service mesh without requiring command-line tools. +Kiali is the observability console for {SMProductShortName}. +It provides a visual interface for monitoring, configuring, and troubleshooting your service mesh without requiring command-line tools. -Kiali is provided by a separate Operator that you install alongside {SMProductShortName}. You can access Kiali as a standalone console, or you can install the {SMProductShortName} console plugin to embed Kiali's functionality directly into the {ocp-short-name} web console. Both options are provided by the Kiali Operator. +Kiali is provided by a separate Operator that you install alongside {SMProductShortName}. + +You can access Kiali as a standalone console, or you can install the {SMProductShortName} console plugin to embed Kiali's functionality directly into the {ocp-short-name} web console. +Both options are provided by the Kiali Operator. -[id="what-kiali-provides_{context}"] == What Kiali provides Kiali gives you visibility into your mesh from a single console: @@ -28,10 +31,9 @@ Configuration validation:: Kiali validates mesh configuration and flags errors or inconsistencies in routing rules, authorization policies, and other mesh resources. Integration with tracing and metrics:: -Kiali integrates with Perses or Grafana for detailed metric dashboards and with the {TempoName} for distributed tracing, so you can move from a high-level traffic view to detailed diagnostics without switching tools. +Kiali integrates with Grafana for detailed metric dashboards and with the {TempoName} for distributed tracing, so you can move from a high-level traffic view to detailed diagnostics without switching tools. -[id="kiali-and-data-plane-modes_{context}"] == Kiali and data plane modes Kiali works with both sidecar and ambient modes. -In ambient mode, Kiali consumes metrics from both ztunnel and waypoint proxies. It displays ambient-specific visualizations, including badges for enrolled namespaces and dedicated pages for waypoint and ztunnel components. +In ambient mode, Kiali collects metrics from both ztunnel and waypoint proxies. It displays ambient-specific visualizations, including badges for enrolled namespaces and dedicated pages for waypoint and ztunnel components. diff --git a/modules/ossm-mixed-data-plane-modes.adoc b/modules/ossm-mixed-data-plane-modes.adoc new file mode 100644 index 00000000000..bd4d5c56ca3 --- /dev/null +++ b/modules/ossm-mixed-data-plane-modes.adoc @@ -0,0 +1,6 @@ +:_mod-docs-content-type: CONCEPT +[id="ossm-mixed-data-plane-modes_{context}"] += Support mixed data plane modes in your mesh + +[role="_abstract"] +{SMProductName} supports running sidecar and ambient workloads in the same {istio} mesh. Use this capability to migrate workloads to ambient mode in increments. You can keep specific workloads in sidecar mode if they depend on features that ambient mode does not yet support. diff --git a/modules/ossm-plan-upgrade-release-alignment.adoc b/modules/ossm-plan-upgrade-release-alignment.adoc new file mode 100644 index 00000000000..ec1f87d0f64 --- /dev/null +++ b/modules/ossm-plan-upgrade-release-alignment.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-plan-upgrade-release-alignment_{context}"] += Coordinate upgrades by aligning component updates + +[role="_abstract"] + +{SMProductName} upgrade lifecycle involves aligning product and {istio} versions through specific Operator channels and orchestrated workflows for the control plane and data plane. diff --git a/modules/ossm-plan-upgrade-strategy.adoc b/modules/ossm-plan-upgrade-strategy.adoc index 6765374dbaa..62980d770e9 100644 --- a/modules/ossm-plan-upgrade-strategy.adoc +++ b/modules/ossm-plan-upgrade-strategy.adoc @@ -8,11 +8,11 @@ [role="_abstract"] -Upgrading {SMProductShortName} involves two layers of decisions: how the Operator itself receives updates, and how the Istio control plane moves to a new version. +Upgrading {SMProductShortName} involves two layers of decisions: how the Operator itself receives updates, and how the Istio control plane moves to a new version. Understanding how these layers connect helps you choose an upgrade approach that matches your risk tolerance and operational requirements. * *Layer 1:* Which channel delivers Operator updates, and whether those updates are applied automatically or require your approval. -* *Layer 2:* Which control plane update strategy the Operator uses to move to a new {istio} version. +* *Layer 2:* Which control plane update strategy the Operator uses to move to a new Istio version. Your data plane mode also affects how upgrades are applied to your workloads. diff --git a/modules/ossm-pqc-gateways.adoc b/modules/ossm-pqc-gateways.adoc new file mode 100644 index 00000000000..5d7852521ce --- /dev/null +++ b/modules/ossm-pqc-gateways.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// install/ossm-pqc-install.adoc + +:_mod-docs-content-type: CONCEPT +[id="ossm-pqc-gateways_{context}"] += Configure {pqc-short} for gateway traffic + +[role="_abstract"] + +You can enable quantum-resistant encryption for traffic entering and leaving the mesh by configuring {pqc-short} key exchange on your gateways. This process is independent of mesh-internal PQC settings. diff --git a/modules/ossm-pqc-mesh-internal.adoc b/modules/ossm-pqc-mesh-internal.adoc new file mode 100644 index 00000000000..3a63cbb3c54 --- /dev/null +++ b/modules/ossm-pqc-mesh-internal.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// install/ossm-pqc-install.adoc + +:_mod-docs-content-type: CONCEPT +[id="ossm-pqc-mesh-internal_{context}"] += Configure {pqc-short} for mesh traffic + +[role="_abstract"] + +You can enable quantum-resistant encryption for service-to-service communication within the mesh by setting a {pqc-short} compliance policy on the control plane. The configuration differs depending on your data plane mode. diff --git a/modules/ossm-release-notes-3-4-1.adoc b/modules/ossm-release-notes-3-4-1.adoc new file mode 100644 index 00000000000..03ccc33da35 --- /dev/null +++ b/modules/ossm-release-notes-3-4-1.adoc @@ -0,0 +1,20 @@ +// Module included in the following assembly: +// +// * ossm-release-notes/ossm-release-notes.adoc + +:_mod-docs-content-type: REFERENCE +[id="ossm-release-notes-3-4-1_{context}"] += {SMProductName} version 3.4.1 + +[role="_abstract"] +This release of {SMProductName} is included with the {SMProductName} Operator {SMProductVersion} and is supported on {ocp-product-title} 4.20 and later versions. This release addresses Common Vulnerabilities and Exposures (CVEs). + +For supported component versions in {SMProductShortName} {SMProductVersion}, see _Service Mesh component versions_. + +[id="ossm-fixed-issues-3-4-1_{context}"] +== Fixed issues + +Webhook error "failed calling webhook validation.istio.io" no longer occurs:: +After the {SMProductShortName} 3.3.4 upgrade, the `istiod-default-validator` webhook did not point to the control plane if the `Istio` CR used a non-default name with the `IstioRevisionTag` set to `default`. As a consequence, attempts to update Istio networking, security, or telemetry resources failed with the error `failed calling webhook "validation.istio.io"`. Existing mesh traffic continued to function, but you were unable to change the service mesh configuration. With this release, the validating webhook references the correct control plane service. As a result, Istio resource validation succeeds in deployments that use non-default `Istio` CR names. ++ +link:https://redhat.atlassian.net/browse/OSSM-14646[OSSM-14646] diff --git a/modules/ossm-release-notes-3-4-fixed-issues.adoc b/modules/ossm-release-notes-3-4-fixed-issues.adoc new file mode 100644 index 00000000000..d60a0acc2d9 --- /dev/null +++ b/modules/ossm-release-notes-3-4-fixed-issues.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/ossm-release-notes/ossm-release-notes.adoc + +:_mod-docs-content-type: REFERENCE +[id="ossm-release-3-X-fixed-issues_{context}"] += {SMProductName} version 3.4 fixed issues + +[role="_abstract"] +This release addresses the following fixed issues: + +Istiod containers include termination message policy for easier debugging:: +Before this update, istiod containers did not specify a `terminationMessagePolicy`. As a consequence, when an istiod container failed, you had to retrieve log information from log storage systems for troubleshooting. This release sets the `terminationMessagePolicy` to `FallbackToLogsOnError`. As a result, when a container fails, the last chunk of log output is captured in the pod status and accessible with `oc describe pod`, making initial debugging easier without requiring log storage access. ++ +link:https://issues.redhat.com/browse/OSSM-13701[OSSM-13701] + + +Kiali correctly validates Istio configuration for multiple meshes in a cluster:: +Before this update, when multiple Istio control planes ran in the same {ocp-short-name} cluster, Kiali used only one control plane's `MeshConfig` properties to validate all Istio configurations. As a consequence, Kiali reported incorrect `KIA1101` (`VirtualService`) and `KIA0203` (`DestinationRule`) validation errors. This release validates Istio resources within the context of each control plane's managed namespace, using each control plane's own `MeshConfig` properties. As a result, resources belonging to one mesh are validated independently, and false validation errors no longer appear. ++ +link:https://redhat.atlassian.net/browse/OSSM-12562[OSSM-12562] diff --git a/modules/ossm-release-notes-3-4-new-features-enhancements.adoc b/modules/ossm-release-notes-3-4-new-features-enhancements.adoc new file mode 100644 index 00000000000..14839b3f324 --- /dev/null +++ b/modules/ossm-release-notes-3-4-new-features-enhancements.adoc @@ -0,0 +1,117 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/ossm-release-notes/ossm-release-notes.adoc + +:_mod-docs-content-type: REFERENCE +[id="ossm-release-3-4-new-features-enhancements_{context}"] += {SMProductName} version 3.4 new features and enhancements + +[role="_abstract"] +This release makes {SMProductName} 3.4 generally available, adds new features, addresses Common Vulnerabilities and Exposures (CVEs), and is supported on {ocp-product-title} 4.20 and later versions. + +For lists of supported component versions and feature support levels, see: + +* _Service Mesh component versions_ +* _Service Mesh feature support tables_ + + +{SMProductShortName} compatibility with Red Hat Enterprise Linux 10:: +{SMProductName} 3.4 introduces native `nftables` support for traffic management in both sidecar and ambient modes. This support is required for clusters running on Red Hat Enterprise Linux (RHEL) 10 or Red Hat Enterprise Linux CoreOS (RHCOS) 10, where the legacy `iptables` framework has been removed. ++ +{SMProduct} relies on packet filtering rules to redirect network traffic to the proxy. Because RHEL 10 systems use `nftables` exclusively, you must enable native `nftables` support to ensure that the service mesh can initialize and manage network traffic correctly on these hosts. ++ +To enable native `nftables` support, set the `values.global.nativeNftables` parameter to `true` when you install or update the {SMProductShortName} control plane. ++ +If you use ambient mode, you might need to reboot nodes after enabling `nftables`. For guidance, see xref:../update/ossm-updating-openshift-service-mesh-in-ambient-mode.adoc#ossm-nftables-migration-ambient_ossm-updating-openshift-service-mesh-in-ambient-mode[Nftables migration in ambient mode]. ++ +link:https://redhat.atlassian.net/browse/OSSM-6748[OSSM-6748] + + +{SMProduct} supports FIPS 140-3 compliance:: +On FIPS-enabled {ocp-product-title} clusters, {SMProductShortName} supports FIPS 140-3 for both sidecar and ambient modes, ensuring continued compliance after the FIPS 140-2 standard expires on September 21, 2026. This release adds TLS 1.3 support for all mesh traffic in addition to the existing TLS 1.2 support, providing stronger encryption for mesh communications. The minimum TLS version remains TLS 1.2. ++ +link:https://issues.redhat.com/browse/OSSM-12531[OSSM-12531] + + +{SMProduct} supports the coexistence of sidecar and ambient mode workloads:: +{SMProductShortName} supports running sidecar proxy and ambient mode workloads simultaneously in separate namespaces within the same mesh (with limitations noted in the documentation). This coexistence enables an incremental migration to ambient mode. You can also maintain specific workloads in sidecar mode if they require features that ambient mode does not yet support. ++ +For more information, see xref:../install/ossm-ambient-sidecar-coexistence.adoc#ossm-ambient-sidecar-coexistence[Coexistence of ambient and sidecar modes]. ++ +link:https://redhat.atlassian.net/browse/OSSM-11487[OSSM-11487] + + +Kiali reduces false warnings in multi-cluster AuthorizationPolicies:: ++ +In this release, Kiali validates trust domains in `AuthorizationPolicies` by checking the `trustDomainAliases` field in the Istio `MeshConfig`. This enhanced validation provides more accurate feedback when working with federated multi-cluster meshes. ++ +This enhancement introduces two validation message changes: ++ +* New validation message `KIA0108 - Unable to verify principal, trust domain is not known to Kiali` appears when a trust domain is genuinely unknown. +* Existing validation `KIA0107 - Service Account for this principal found on a remote cluster` was downgraded from Warning to Informational, eliminating false warnings for working multi-cluster configurations. ++ +link:https://redhat.atlassian.net/browse/OSSM-13864[OSSM-13864] + + +Kiali supports stricter namespace access control for multi-tenancy environments:: +This release introduces a new configuration attribute, `KialiFeatureFlags.Authz.RequireNamespaceGet`, to improve multi-tenancy support in Kiali. By default, when Kiali runs in cluster-wide mode, it treats users with List permission to a namespace as also having Get permission, and displays all List namespaces in the Namespace dropdown. In environments where List and Get permissions differ, this can expose namespaces that users should not access. When you set `KialiFeatureFlags.Authz.RequireNamespaceGet=true`, Kiali limits the Namespace dropdown to only those namespaces for which users have Get permission, ensuring stricter access control. The default value is `false`, so existing deployments are not affected. ++ +link:https://issues.redhat.com/browse/OSSM-13288[OSSM-13288] + + +Kiali Overview page redesigned for performance and multi-cluster awareness:: +This release replaces the Kiali Overview page with a compact, multi-cluster-aware dashboard that provides a high-level view of mesh health at a glance. The redesigned page uses pre-computed and cached data to ensure fast rendering independent of mesh size. ++ +The Overview page displays summary cards for: ++ +* Cluster health +* Istio configuration validation +* Control plane status +* Namespace mesh participation (Ambient, Sidecar, or Out of mesh) +* An interactive application health donut chart +* Workload insights such as missing sidecars, high error rates, or failing probes ++ +This release also adds a dedicated Namespaces page. ++ +link:https://redhat.atlassian.net/browse/OSSM-11833[OSSM-11833] + + +Kiali Namespace detail page provides a comprehensive namespace view:: +Clicking a namespace in the Kiali Namespaces list opens a detail page with a split-panel layout showing namespace metadata, health, and traffic. ++ +The left panel displays: ++ +* Namespace attributes such as cluster, revision, status, mesh mode, and mTLS status +* Links to applications, services, workloads, and Istio configuration with health breakdowns +* Editable labels and annotations with click-to-filter navigation ++ +The right panel displays a namespace-scoped traffic minigraph. ++ +Additionally, an Actions menu lists options such as traffic policies. The page also supports breadcrumb navigation, view-only mode, and kiosk mode. ++ +link:https://redhat.atlassian.net/browse/OSSM-13271[OSSM-13271] + + +{SMProduct} supports Gateway API 1.5.1, in which the following features are now stable:: +* ListenerSet for simplified gateway listener configuration +* TLSRoute for routing encrypted non-HTTP traffic +* HTTPRoute CORS configuration for cross-origin API access +* Client certificate validation for mutual TLS authentication at the gateway +* Certificate selection for multi-domain gateway TLS configurations +* ReferenceGrant for cross-namespace access delegation ++ +Additionally, for teams serving AI/ML models with Red{nbsp}Hat {ocp-short-name}, this release supports Gateway API Inference Extension 1.4.0. This extension provides intelligent routing and load balancing optimized for GPU-accelerated inference workloads. ++ +link:https://redhat.atlassian.net/browse/OSSM-11956[OSSM-11956] + + +Performance and security improvements from upstream {istio} and the Sail Operator:: +As a distribution based on upstream {istio} and the Sail Operator, {SMProduct} inherits enhancements from these projects. Review the following upstream changes in this release to determine whether your deployment needs configuration updates: + +* Circuit breaker metrics tracking is disabled by default to improve proxy memory usage. Before this update, this tracking was enabled by default. To reenable it, set the environment variable `DISABLE_TRACK_REMAINING_CB_METRICS=false` in `istiod`. This affects the `track_remaining` setting in Envoy's circuit breaker configuration. + +* Debug endpoint authorization is now enabled by default. This change affects tools that access debug endpoints from non-system namespaces. For example, this change might affect Kiali if you deploy it in a different namespace from the {istio} control plane. This release restricts non-system namespaces to specific debug endpoints only, with access limited to `config_dump`, `ndsz`, and `edsz` for same-namespace proxies. To restore the previous behavior, set the environment variable `ENABLE_DEBUG_ENDPOINT_AUTH=false` in `istiod`. + +* HTTP compression for Envoy metrics is now enabled by default. The `sidecar.istio.io/statsCompression` annotation was removed. This release replaces it with a new `statsCompression` option in `proxyConfig` that defaults to `true`. Envoy now compresses metrics using brotli, gzip, or zstd based on the `Accept-Encoding` header. You can override per-pod compression, if needed, by using the `proxy.istio.io/config` annotation. + +* DNS proxying is now enabled by default for workloads in an ambient mesh. This ensures that {istio} correctly resolves and tracks `ServiceEntry` destinations. DNS traffic from already-running workloads is not automatically redirected through ztunnel when you enable or upgrade ambient mode. To enable DNS proxying for these existing pods, manually restart them. Alternatively, configure {istio} CNI with `--set cni.ambient.reconcileIptablesOnStartup=true` to reconcile the required `iptables` rules automatically. This setting is enabled by default in {istio} 1.29 and later versions. (Note that DNS capture is still not enabled by default in sidecar mode, as `ServiceEntry` resources are correctly handled at the sidecar proxy with default settings.) diff --git a/modules/ossm-release-notes-3-4-technology-preview-features.adoc b/modules/ossm-release-notes-3-4-technology-preview-features.adoc new file mode 100644 index 00000000000..3e55c2ee9f3 --- /dev/null +++ b/modules/ossm-release-notes-3-4-technology-preview-features.adoc @@ -0,0 +1,46 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/ossm-release-notes/ossm-release-notes.adoc + +:_mod-docs-content-type: REFERENCE +[id="ossm-release-3-4-technology-preview-features_{context}"] += {SMProductName} version 3.4 Technology Preview features + +[role="_abstract"] +This release includes some features that are currently in Technology Preview. These experimental features are not intended for production use. + +For more information about the support scope of Red Hat Technology Preview features, see link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Support Scope]. + + +SPIRE integration enables zero-trust workload identity:: +{SMProductName} integrates with the SPIFFE Runtime Environment (SPIRE) to provide stronger cryptographically verifiable workload identities. SPIFFE (Secure Production Identity Framework for Everyone) is an open standard for establishing trust between workloads in distributed systems. ++ +While {SMProduct} already supports workload identity creation and management through the SPIFFE protocol, SPIRE extends this with: + +* *Deep workload attestation* - Verifies workload identity based on configurable criteria backed by hardware or cloud environment verification +* *Trust domain federation* - Enables workloads from different trust domains to authenticate and communicate securely ++ +SPIRE is supported as part of the OpenShift Zero Trust Workload Identity Manager. Integration with {SMProduct} is a Technology Preview feature. ++ +For more information, see xref:../install/ossm-SPIRE.adoc#ossm-SPIRE[SPIRE integration for mesh security]. ++ +link:https://redhat.atlassian.net/browse/OSSM-9387[OSSM-9387] + + +Multi-cluster support in {istio} ambient mode:: +Support for ambient mode in multi-primary multi-network topologies continues to be a Technology Preview feature. ++ +For more information, see xref:../install/ossm-multi-cluster-topologies.adoc#ossm-installing-multi-primary-multi-network-mesh-ambient_ossm-multi-cluster-topologies[Installing a multi-primary multi-network mesh in ambient mode]. ++ +link:https://redhat.atlassian.net/browse/OSSM-12578[OSSM-12578] + + +Multi-network ingress gateway support in ambient mode:: +This release adds cross-cluster networking for ingress gateways in multi-network ambient deployments. You can configure two environment variables in the {istio} resource under `spec.values.pilot.env`: ++ +* `AMBIENT_ENABLE_MULTI_NETWORK_INGRESS` - Allows ingress gateways to route traffic to remote clusters. This enables load balancing across local and remote pods and ensures requests are served even when local pods are unavailable. +* `AMBIENT_ENABLE_BAGGAGE` - Ensures service mesh telemetry metrics include accurate source and destination labels for cross-network traffic. ++ +Both variables support ambient mode in multi-primary multi-network topologies and are therefore Technology Preview features. ++ +link:https://redhat.atlassian.net/browse/OSSM-13455[OSSM-13455] diff --git a/modules/ossm-release-notes-concept.adoc b/modules/ossm-release-notes-concept.adoc new file mode 100644 index 00000000000..63bce4b6203 --- /dev/null +++ b/modules/ossm-release-notes-concept.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * ossm-release-notes/ossm-release-notes.adoc + +:_mod-docs-content-type: CONCEPT +[id="ossm-release-notes-concept_{context}"] += OpenShift Service Mesh release notes + +[role="_abstract"] + +Review new features, compatibility updates, fixed issues, and known issues for Red Hat OpenShift Service Mesh to stay informed about changes across different product versions. diff --git a/modules/ossm-removing-multi-cluster-installation-from-development-environment.adoc b/modules/ossm-removing-multi-cluster-installation-from-development-environment.adoc index f0de3999704..cdc17b52723 100644 --- a/modules/ossm-removing-multi-cluster-installation-from-development-environment.adoc +++ b/modules/ossm-removing-multi-cluster-installation-from-development-environment.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-removing-multi-cluster-installation-from-development-environment_{context}"] -= Removing a multi-cluster topology from a development environment += Remove a multi-cluster topology from a development environment [role="_abstract"] diff --git a/modules/ossm-routing-traffic-using-virtualservice.adoc b/modules/ossm-routing-traffic-using-virtualservice.adoc index db799d6684b..b6404381271 100644 --- a/modules/ossm-routing-traffic-using-virtualservice.adoc +++ b/modules/ossm-routing-traffic-using-virtualservice.adoc @@ -86,4 +86,4 @@ $ oc exec "$(oc get pod -l app=ratings -n bookinfo \ -- curl -sS productpage:9080/productpage | grep -om1 'reviews-v[12]' ---- + -Most responses (90%) contain `reviews-v1` output, while a smaller part (10%) contain `reviews-v2` output. +Most responses (90%) will contain `reviews-v1` output, while a smaller part (10%) will contain `reviews-v2` output. diff --git a/modules/ossm-routing-traffic-using-waypoint-proxies.adoc b/modules/ossm-routing-traffic-using-waypoint-proxies.adoc index 06938f89ece..1c6dcf81b43 100644 --- a/modules/ossm-routing-traffic-using-waypoint-proxies.adoc +++ b/modules/ossm-routing-traffic-using-waypoint-proxies.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-routing-traffic-using-waypoint-proxies_{context}"] -= Routing traffic using waypoint proxies += Route traffic in an ambient mesh [role="_abstract"] diff --git a/modules/ossm-scoping-service-mesh-with-discoveryselectors.adoc b/modules/ossm-scoping-service-mesh-with-discoveryselectors.adoc index 76a09e9b9e1..566799ae998 100644 --- a/modules/ossm-scoping-service-mesh-with-discoveryselectors.adoc +++ b/modules/ossm-scoping-service-mesh-with-discoveryselectors.adoc @@ -4,18 +4,10 @@ :_mod-docs-content-type: CONCEPT [id="ossm-scoping-service-mesh-with-discoveryselectors_{context}"] -= Scoping the Service Mesh with discovery selectors += Focus mesh resources on specific namespaces [role="_abstract"] -{SMProductShortName} includes workloads that meet the following criteria: +By default, the mesh control plane discovers workloads in all namespaces across a cluster. Each proxy receives configuration for every namespace, including workloads not enrolled in the mesh. -* The control plane has discovered the workload. -* The workload has an Envoy proxy sidecar injected. - -By default, the control plane discovers workloads in all namespaces across the cluster, with the following results: - -* Each proxy instance receives configuration for all namespaces, including workloads not enrolled in the mesh. -* Any workload with the appropriate pod or namespace injection label receives a proxy sidecar. - -In shared clusters, you might want to limit the scope of {SMProductShortName} to only certain namespaces. This approach is especially useful if many service meshes run in the same cluster. \ No newline at end of file +Use discovery selectors to limit the mesh to specific namespaces. This reduces unnecessary processing and is especially useful when running many service meshes in the same cluster. diff --git a/modules/ossm-scoping-sm-discovery-selectors-istio-ambient-mode.adoc b/modules/ossm-scoping-sm-discovery-selectors-istio-ambient-mode.adoc index e0da369535c..125dba9e08b 100644 --- a/modules/ossm-scoping-sm-discovery-selectors-istio-ambient-mode.adoc +++ b/modules/ossm-scoping-sm-discovery-selectors-istio-ambient-mode.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-scoping-sm-discovery-selectors-istio-ambient-mode_{context}"] -= Scoping the Service Mesh with discovery selectors in Istio ambient mode += Configure discovery selectors in ambient mode [role="_abstract"] diff --git a/modules/ossm-selecting-inplace-strategy.adoc b/modules/ossm-selecting-inplace-strategy.adoc index 79ebef876e7..4f9e511f6cd 100644 --- a/modules/ossm-selecting-inplace-strategy.adoc +++ b/modules/ossm-selecting-inplace-strategy.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: CONCEPT [id="selecting-inplace-strategy_{context}"] -= Selecting InPlace strategy += When to use the InPlace strategy [role="_abstract"] @@ -22,4 +22,4 @@ spec: You can set this value while creating the resource or edit it later. If you edit the resource after creation, make the change before updating the {istio} control plane. -Running the {istio} resource in High Availability mode to minimize traffic disruptions requires additional property settings. For more information, see "About Istio High Availability". \ No newline at end of file +Running the {istio} resource in High Availability mode to minimize traffic disruptions requires additional property settings. For more information, see "Istio High Availability (HA) mode". \ No newline at end of file diff --git a/modules/ossm-selecting-revisionbased-strategy.adoc b/modules/ossm-selecting-revisionbased-strategy.adoc index 3165a32035a..fe6dbd93e01 100644 --- a/modules/ossm-selecting-revisionbased-strategy.adoc +++ b/modules/ossm-selecting-revisionbased-strategy.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: CONCEPT [id="selecting-revision-based-strategy_{context}"] -= Selecting RevisionBased strategy += When to use the RevisionBased strategy [role="_abstract"] diff --git a/modules/ossm-service-mesh-deployment-resources.adoc b/modules/ossm-service-mesh-deployment-resources.adoc index d73eacbb45a..06d7a96d6f0 100644 --- a/modules/ossm-service-mesh-deployment-resources.adoc +++ b/modules/ossm-service-mesh-deployment-resources.adoc @@ -8,7 +8,7 @@ [role="_abstract"] -After you install the {SMProductName} Operator, you use the following resources to deploy and manage the {istio} control plane (`istiod`). You create `Istio` and `IstioCNI` resources to deploy the mesh, and the Operator creates `IstioRevision` resources to track control plane instances. +After you install the {SMProductName} Operator, you use the following resources to deploy and manage the {istio} control plane. You create `Istio` and `IstioCNI` resources to deploy the mesh, and the Operator creates `IstioRevision` resources to track control plane instances. [NOTE] ==== @@ -17,10 +17,9 @@ Ambient mode deployments also require a `ZTunnel` resource. For more information The following sections provide an overview of each resource. For deployment steps, see the sidecar mode or ambient mode installation procedures. -[id="the-istio-resource_{context}"] == The {istio} resource -The `{istio}` resource manages your {istio} control planes. When you create this resource, the Operator deploys `istiod`, the control plane process that handles service discovery, configuration distribution, and certificate management. It is a cluster-wide resource, because the {istio} control plane operates in and requires access to the entire cluster. +The `{istio}` resource manages your {istio} control planes. It is a cluster-wide resource, because the {istio} control plane operates in and requires access to the entire cluster. To select a namespace to run the control plane pods in, you can use the `spec.namespace` field. @@ -52,17 +51,16 @@ spec: You can run the following command to see all the customization options: -[source,terminal] +[source, terminal] ---- $ oc explain istios.spec.values ---- You can set the `version` field by using the full version or the `v.-latest` alias to automatically select the latest version for a specific minor version. For example, setting `v1.23-latest` ensures that the Operator maintains the latest version of {istio} 1.23. -[id="the-istiocni-resource_{context}"] == The IstioCNI resource -The {SMProduct} Operator manages the lifecycle of {istio}'s Container Network Interface (CNI) plugin separately. The `IstioCNI` resource is a cluster-wide resource that installs a daemon set operating on all nodes of your cluster. +The {SMProduct} Operator manages the lifecycle of {istio}'s CNI plugin separately. The `IstioCNI` resource is a cluster-wide resource that installs a daemon set operating on all nodes of your cluster. You can select a version by setting the `spec.version` field. To update the CNI plugin, change the version field to the version you want to install. Similar to the `Istio` resource, `IstioCNI` has a `values` field that exposes all of the options provided in the `istio-cni` chart: @@ -89,7 +87,6 @@ You can run the following command to see all the customization options: $ oc explain istiocnis.spec.values ---- -[id="the-istiorevision-resource_{context}"] == The IstioRevision resource The `IstioRevision` is a cluster-wide resource that represents a revision of the control plane. The Operator creates `IstioRevision` resources automatically when you create an `{istio}` resource; you do not create them directly. @@ -108,7 +105,6 @@ To see available revisions, run the following command: $ oc get istiorevisions ---- -[id="the-istiorevisiontag-resource_{context}"] == The IstioRevisionTag resource The `IstioRevisionTag` resource is a stable alias for an {istio} control plane revision. When you perform an upgrade to a control plane with a new revision name, you can update your tag to point to the new revision instead of having to relabel your workloads and namespaces. @@ -136,4 +132,4 @@ When using an `{istio}` resource as the target, the Operator automatically updat [IMPORTANT] ==== You can only use the `istio-injection` label for revisions and revision tags that have the name `default`. -==== +==== \ No newline at end of file diff --git a/modules/ossm-setup-observability-console.adoc b/modules/ossm-setup-observability-console.adoc index e800541b881..b48998b57c6 100644 --- a/modules/ossm-setup-observability-console.adoc +++ b/modules/ossm-setup-observability-console.adoc @@ -8,7 +8,7 @@ [role="_abstract"] -You can observe your {SMProductShortName} environment by using either Kiali as a standalone console or the {SMPlugin}, which integrates its features directly into the {ocp-short-name} web interface. Installing Kiali provides the standalone UI and enables this integrated option. +You can observe your {SMProductShortName} environment by using either Kiali as a standalone console or the {SMPlugin}, which integrates Kiali features directly into the {ocp-short-name} web interface. Installing Kiali provides the standalone UI and enables this integrated option. You can also integrate {DTShortName} to view trace data in the console. diff --git a/modules/ossm-support-for-istioctl.adoc b/modules/ossm-support-for-istioctl.adoc index 279991918e2..d7d7567b340 100644 --- a/modules/ossm-support-for-istioctl.adoc +++ b/modules/ossm-support-for-istioctl.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: REFERENCE [id="ossm-support-for-istioctl_{context}"] -= Support for Istioctl += Supported Istioctl commands [role="_abstract"] diff --git a/modules/ossm-tls-gateways.adoc b/modules/ossm-tls-gateways.adoc index 973710165f9..c2ce0cb50ea 100644 --- a/modules/ossm-tls-gateways.adoc +++ b/modules/ossm-tls-gateways.adoc @@ -8,4 +8,4 @@ [role="_abstract"] -Secure traffic entering and leaving the mesh by configuring Transport Layer Security (TLS) on your gateways. TLS encryption is a baseline requirement for any gateway and is independent of other security features such as {pqc-short}. +Secure traffic entering and leaving the mesh by configuring Transport Layer Security (TLS) on your gateways. Mutual TLS (mTLS) encrypts traffic between services inside the mesh but does not protect traffic at the mesh boundary. You must configure TLS on your gateways separately to encrypt ingress and egress connections. diff --git a/modules/ossm-understanding-operator-updates-and-channels.adoc b/modules/ossm-understanding-operator-updates-and-channels.adoc index 5cf5be7f80e..9705cda8adb 100644 --- a/modules/ossm-understanding-operator-updates-and-channels.adoc +++ b/modules/ossm-understanding-operator-updates-and-channels.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: CONCEPT [id="ossm-understanding-operator-updates-and-channels_{context}"] -= Understanding Operator updates and channels += Operator update channels and approval strategies [role="_abstract"] diff --git a/modules/ossm-understanding-sm-istio-versions.adoc b/modules/ossm-understanding-sm-istio-versions.adoc index 5de862e7a94..6fcdb8108f6 100644 --- a/modules/ossm-understanding-sm-istio-versions.adoc +++ b/modules/ossm-understanding-sm-istio-versions.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: CONCEPT [id="ossm-understanding-sm-istio-versions_{context}"] -= Understanding Service Mesh and Istio versions += Service Mesh and Istio version compatibility [role="_abstract"] diff --git a/modules/ossm-uninstall-console-plugin-ocp-cli.adoc b/modules/ossm-uninstall-console-plugin-ocp-cli.adoc index 61b2a819850..943112f7045 100644 --- a/modules/ossm-uninstall-console-plugin-ocp-cli.adoc +++ b/modules/ossm-uninstall-console-plugin-ocp-cli.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-uninstall-console-plugin-ocp-cli_{context}"] -= Uninstalling {SMPluginShort} by using the CLI += Uninstall the OSSMC plugin with the CLI [role="_abstract"] diff --git a/modules/ossm-uninstall-console-plugin-ocp-web-console.adoc b/modules/ossm-uninstall-console-plugin-ocp-web-console.adoc index b3bf8e41c25..a8d41e289e7 100644 --- a/modules/ossm-uninstall-console-plugin-ocp-web-console.adoc +++ b/modules/ossm-uninstall-console-plugin-ocp-web-console.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-uninstall-console-plugin-ocp-web-console_{context}"] -= Uninstalling {SMPluginShort} by using the web console += Unstall the OSSMC plugin with the web console [role="_abstract"] diff --git a/modules/ossm-uninstalling-cert-manager.adoc b/modules/ossm-uninstalling-cert-manager.adoc index 88b98838e9e..7eb472c7fd9 100644 --- a/modules/ossm-uninstalling-cert-manager.adoc +++ b/modules/ossm-uninstalling-cert-manager.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-uninstalling-cert-manager_{context}"] -= Uninstalling Service Mesh with the cert-manager Operator by using the istio-csr agent += Uninstall cert-manager [role="_abstract"] diff --git a/modules/ossm-update-istio-cni-plugin.adoc b/modules/ossm-update-istio-cni-plugin.adoc new file mode 100644 index 00000000000..6204a827d64 --- /dev/null +++ b/modules/ossm-update-istio-cni-plugin.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-update-istio-cni-plugin_{context}"] += Update the Istio CNI plugin to match your control plane + +[role="_abstract"] + +Review the update procedure for the {istio} Container Network Interface (CNI). Ensure the CNI plugin remains compatible with the {SMProduct} control plane during an upgrade. diff --git a/modules/ossm-updating-control-plane-inplace.adoc b/modules/ossm-updating-control-plane-inplace.adoc new file mode 100644 index 00000000000..55eb1954196 --- /dev/null +++ b/modules/ossm-updating-control-plane-inplace.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-updating-control-plane-inplace_{context}"] += Update the control plane with InPlace strategy + +[role="_abstract"] + +With the InPlace strategy, the Operator replaces the control plane without creating a second revision. A single control plane is running at all times, and workload sidecars automatically reconnect to the updated instance. + +You can upgrade only one minor version at a time. After the control plane restarts, you must restart application workloads and gateways to refresh the Envoy proxies. + +Choose this strategy when you want a simpler update workflow and can tolerate a brief window where workload pods that restart during the control plane update might experience traffic interruption. You can reduce this risk by running multiple replicas of the control plane. diff --git a/modules/ossm-updating-control-plane-revisionbased.adoc b/modules/ossm-updating-control-plane-revisionbased.adoc new file mode 100644 index 00000000000..6b997ade5c6 --- /dev/null +++ b/modules/ossm-updating-control-plane-revisionbased.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-updating-control-plane-revisionbased_{context}"] += Upgrade the control plane with a RevisionBased canary deployment + +[role="_abstract"] + +Update the Istio control plane by deploying a new revision alongside the existing one. The RevisionBased strategy runs both control plane versions simultaneously, so you can validate the update with a subset of workloads before migrating the rest. + +Workloads remain connected to the old control plane until you explicitly migrate them by updating namespace labels and restarting pods. After all workloads move to the new revision, the Operator removes the old control plane. + +Choose this strategy when you need to upgrade across more than one minor version, when you want to run canary validation before committing, or when your mesh serves mission-critical workloads that require zero-downtime transitions. You can migrate workloads by updating the `istio.io/rev` label directly or by using an IstioRevisionTag resource for stable label references that do not require relabeling namespaces on each upgrade. diff --git a/modules/ossm-updating-cross-namespace-waypoint.adoc b/modules/ossm-updating-cross-namespace-waypoint.adoc index d83f2db5e54..c0e0613c620 100644 --- a/modules/ossm-updating-cross-namespace-waypoint.adoc +++ b/modules/ossm-updating-cross-namespace-waypoint.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-updating-cross-namespace-waypoint_{context}"] -= Updating cross-namespace waypoint += Update cross-namespace waypoints [role="_abstract"] diff --git a/modules/ossm-updating-istio-cni-resource-version.adoc b/modules/ossm-updating-istio-cni-resource-version.adoc index 49de34ddde1..c1db4304066 100644 --- a/modules/ossm-updating-istio-cni-resource-version.adoc +++ b/modules/ossm-updating-istio-cni-resource-version.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-updating-istio-cni-resource-version_{context}"] -= Updating the Istio CNI resource version += Update the Istio CNI plugin version [role="_abstract"] diff --git a/modules/ossm-updating-istio-control-plane-with-revisionbased-istiorevisiontag.adoc b/modules/ossm-updating-istio-control-plane-with-revisionbased-istiorevisiontag.adoc index 3357ec9cb4e..049cf69cd0f 100644 --- a/modules/ossm-updating-istio-control-plane-with-revisionbased-istiorevisiontag.adoc +++ b/modules/ossm-updating-istio-control-plane-with-revisionbased-istiorevisiontag.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="updating-istio-control-plane-with-revisionbased-istiorevisiontag_{context}"] -= Updating Istio control plane with RevisionBased strategy and IstioRevisionTag += Upgrade the control plane with RevisionBased strategy and IstioRevisionTag [role="_abstract"] diff --git a/modules/ossm-updating-istio-control-plane-with-revisionbased.adoc b/modules/ossm-updating-istio-control-plane-with-revisionbased.adoc index 80d27ddd1ef..32f735faad7 100644 --- a/modules/ossm-updating-istio-control-plane-with-revisionbased.adoc +++ b/modules/ossm-updating-istio-control-plane-with-revisionbased.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="updating-istio-control-plane-with-revisionbased_{context}"] -= Updating Istio control plane with RevisionBased strategy += Upgrade the control plane with RevisionBased strategy [role="_abstract"] diff --git a/modules/ossm-updating-waypoint-proxies-with-inplace-strategy.adoc b/modules/ossm-updating-waypoint-proxies-with-inplace-strategy.adoc index 6ce75422979..48c24d894ea 100644 --- a/modules/ossm-updating-waypoint-proxies-with-inplace-strategy.adoc +++ b/modules/ossm-updating-waypoint-proxies-with-inplace-strategy.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-updating-waypoint-proxies-with-inplace-strategy_{context}"] -= Updating waypoint proxies with InPlace strategy in ambient mode += Update waypoint proxies with InPlace strategy [role="_abstract"] diff --git a/modules/ossm-updating-waypoint-proxies-with-revisionbased-strategy.adoc b/modules/ossm-updating-waypoint-proxies-with-revisionbased-strategy.adoc index 657b785f56e..1b8c0de102d 100644 --- a/modules/ossm-updating-waypoint-proxies-with-revisionbased-strategy.adoc +++ b/modules/ossm-updating-waypoint-proxies-with-revisionbased-strategy.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-updating-waypoint-proxies-with-revisionbased-strategy_{context}"] -= Updating waypoint proxies with RevisionBased strategy in ambient mode += Update waypoint proxies with RevisionBased strategy [role="_abstract"] diff --git a/modules/ossm-updating-ztunnel-with-node-draining.adoc b/modules/ossm-updating-ztunnel-with-node-draining.adoc index 0374f2f0776..3d55d371d57 100644 --- a/modules/ossm-updating-ztunnel-with-node-draining.adoc +++ b/modules/ossm-updating-ztunnel-with-node-draining.adoc @@ -4,15 +4,15 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-updating-ztunnel-with-node-draining_{context}"] -= Updating Ztunnel using node draining += Drain nodes to update ztunnel [role="_abstract"] -Drain nodes to force long-lived TCP connections to reconnect through a new `Ztunnel` instance, without risking traffic loss because the node is empty during the proxy swap. +Drain nodes to force long-lived TCP connections to reconnect through a new `ztunnel` instance, without risking traffic loss because the node is empty during the proxy swap. .Procedure -. Configure the `OnDelete` update strategy in the `ZTunnel` custom resource (CR) to need manual pod deletion before the update to the new version starts, similar to the following example: +. Configure the `OnDelete` update strategy in the `ztunnel` custom resource (CR) to need manual pod deletion before the update to the new version starts, similar to the following example: + [source,yaml,subs="attributes,verbatim"] ---- @@ -29,11 +29,11 @@ spec: type: OnDelete ---- -. Update the `version` field in the `ZTunnel` CR to the target version. +. Update the `version` field in the `ztunnel` CR to the target version. . Drain a node to force all applications to move to other nodes, allowing their long-lived connections to close gracefully based on their `terminationGracePeriodSeconds`. -. Delete the old `Ztunnel` pod on the empty node and wait for the new pod to start. +. Delete the old `ztunnel` pod on the empty node and wait for the new pod to start. . Mark the node as `schedulable`. Applications that return to the node will automatically use the new Ztunnel. diff --git a/modules/ossm-upgrade-core-platform-infrastructure.adoc b/modules/ossm-upgrade-core-platform-infrastructure.adoc new file mode 100644 index 00000000000..937836fe54a --- /dev/null +++ b/modules/ossm-upgrade-core-platform-infrastructure.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-upgrade-core-platform-infrastructure_{context}"] += Upgrade the core service mesh platform infrastructure + +[role="_abstract"] + +Compare the available strategies for updating the {istio} control plane in {SMProductName}. Identify when to use the `InPlace` or `RevisionBased` strategy and learn how to apply each during an upgrade. diff --git a/modules/ossm-upgrade-node-level-infrastructure-ambient.adoc b/modules/ossm-upgrade-node-level-infrastructure-ambient.adoc new file mode 100644 index 00000000000..a28decd14c8 --- /dev/null +++ b/modules/ossm-upgrade-node-level-infrastructure-ambient.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-upgrade-node-level-infrastructure-ambient_{context}"] += Upgrade node-level infrastructure in ambient mode + +[role="_abstract"] + +Update {SMProductName} in ambient mode by transitioning the control plane and waypoint proxies to new revisions while maintaining Layer 7 (L7) functionality and resource compatibility. diff --git a/modules/ossm-using-discoveryselectors-scope-service-mesh.adoc b/modules/ossm-using-discoveryselectors-scope-service-mesh.adoc index e339acb2a7e..c041958777c 100644 --- a/modules/ossm-using-discoveryselectors-scope-service-mesh.adoc +++ b/modules/ossm-using-discoveryselectors-scope-service-mesh.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-discoveryselectors-scope-service-mesh_{context}"] -= Scoping a Service Mesh by using discovery selectors += Configure discovery selectors in sidecar mode [role="_abstract"] diff --git a/modules/ossm-verifying-cert-manager-ambient.adoc b/modules/ossm-verifying-cert-manager-ambient.adoc index 3ee400d90d1..468237c030a 100644 --- a/modules/ossm-verifying-cert-manager-ambient.adoc +++ b/modules/ossm-verifying-cert-manager-ambient.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-verifying-cert-manager-ambient_{context}"] -= Verifying {SMProductShortName} Ambient Mode with the cert-manager Operator and istio-csr += Verify cert-manager in ambient mode [role="_abstract"] diff --git a/modules/ossm-verifying-cert-manager.adoc b/modules/ossm-verifying-cert-manager.adoc index f4451717b02..4c950e9f248 100644 --- a/modules/ossm-verifying-cert-manager.adoc +++ b/modules/ossm-verifying-cert-manager.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-verifying-cert-manager_{context}"] -= Verifying the Service Mesh Sidecar with the cert-manager Operator by using the istio-csr agent += Verify cert-manager in sidecar mode [role="_abstract"] diff --git a/modules/ossm-verifying-l7-features-with-authorization-policies.adoc b/modules/ossm-verifying-l7-features-with-authorization-policies.adoc index c434b63a08c..01bab6e18db 100644 --- a/modules/ossm-verifying-l7-features-with-authorization-policies.adoc +++ b/modules/ossm-verifying-l7-features-with-authorization-policies.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-verifying-l7-features-with-authorization-policies_{context}"] -= Verifying Layer 7 (L7) features with authorization policies += Verify L7 authorization policies after waypoint updates [role="_abstract"] diff --git a/modules/ossm-verifying-l7-features-with-traffic-routing.adoc b/modules/ossm-verifying-l7-features-with-traffic-routing.adoc index aec6274e89c..9d5460ed98b 100644 --- a/modules/ossm-verifying-l7-features-with-traffic-routing.adoc +++ b/modules/ossm-verifying-l7-features-with-traffic-routing.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-verifying-l7-features-with-traffic-routing_{context}"] -= Verifying Layer 7 (L7) features with traffic routing += Verify L7 traffic routing after waypoint updates [role="_abstract"] diff --git a/modules/ossm-verifying-metrics-ambient-mode.adoc b/modules/ossm-verifying-metrics-ambient-mode.adoc index d40047a7af3..65f4f697a09 100644 --- a/modules/ossm-verifying-metrics-ambient-mode.adoc +++ b/modules/ossm-verifying-metrics-ambient-mode.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-validating-metrics-ambient-mode_{context}"] -= Verifying metrics in ambient mode += Verify metrics in ambient mode [role="_abstract"] @@ -12,7 +12,7 @@ You can verify that the metrics for your application available in the OpenShift .Prerequisites -* You have deployed the Bookinfo application in ambient mode to use the following example. For more information, see "Deploying the Bookinfo application in {istio} ambient mode". +* You have deployed the Bookinfo application in ambient mode to use the following example. For more information, see "Deploy Bookinfo in ambient mode". .Procedure diff --git a/modules/ossm-verifying-multi-cluster-topology-ambient.adoc b/modules/ossm-verifying-multi-cluster-topology-ambient.adoc index 8d47d2a6f57..d218b3e59d8 100644 --- a/modules/ossm-verifying-multi-cluster-topology-ambient.adoc +++ b/modules/ossm-verifying-multi-cluster-topology-ambient.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-verifying-multi-cluster-topology-ambient_{context}"] -= Verifying a multi-primary multi-network mesh in ambient mode += Verify a multi-primary multi-network mesh in ambient mode [role="_abstract"] diff --git a/modules/ossm-verifying-multi-cluster-topology.adoc b/modules/ossm-verifying-multi-cluster-topology.adoc index 62330ef716c..68718cbfb42 100644 --- a/modules/ossm-verifying-multi-cluster-topology.adoc +++ b/modules/ossm-verifying-multi-cluster-topology.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-verifying-multi-cluster-topology_{context}"] -= Verifying a multi-primary multi-network mesh with sidecar deployment += Verify a multi-primary multi-network mesh with sidecar deployment [role="_abstract"] diff --git a/modules/ossm-verifying-multiple-control-planes.adoc b/modules/ossm-verifying-multiple-control-planes.adoc index 25e01dfb287..ad7a7e1dd8b 100644 --- a/modules/ossm-verifying-multiple-control-planes.adoc +++ b/modules/ossm-verifying-multiple-control-planes.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-verifying-multiple-control-planes_{context}"] -= Verifying multiple control planes += Verify multiple control planes [role="_abstract"] diff --git a/modules/ossm-verifying-traces-ambient-mode.adoc b/modules/ossm-verifying-traces-ambient-mode.adoc index bf3fd49b2fc..dac9d4a8e06 100644 --- a/modules/ossm-verifying-traces-ambient-mode.adoc +++ b/modules/ossm-verifying-traces-ambient-mode.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-verifying-traces-ambient-mode_{context}"] -= Verifying traces in ambient mode += Verify traces in ambient mode [role="_abstract"] @@ -12,9 +12,9 @@ You can verify that the traces for your application are in ambient mode. The fol .Prerequisites -* You have deployed the Bookinfo application in ambient mode to use the following example. For more information, see "Deploying the Bookinfo application in Istio ambient mode". +* You have deployed the Bookinfo application in ambient mode to use the following example. For more information, see "Deploy Bookinfo in ambient mode". -* You have deployed a waypoint proxy and enrolled the `bookinfo` namespace to use the waypoint. For more information, see "Deploying a waypoint proxy". +* You have deployed a waypoint proxy and enrolled the `bookinfo` namespace to use the waypoint. For more information, see "Deploy waypoint proxies for Bookinfo". .Procedure diff --git a/modules/ossm-ztunnel-update-lifecycle.adoc b/modules/ossm-ztunnel-update-lifecycle.adoc index 83f84fb9e11..14fe74267de 100644 --- a/modules/ossm-ztunnel-update-lifecycle.adoc +++ b/modules/ossm-ztunnel-update-lifecycle.adoc @@ -4,7 +4,7 @@ :_mod-docs-content-type: CONCEPT [id="ossm-ztunnel-update-lifecycle_{context}"] -= About Ztunnel update lifecycle += Ztunnel rolling update lifecycle [role="_abstract"] @@ -14,12 +14,12 @@ Ztunnel operates at Layer 4 (L4) of the Open Systems Interconnection (OSI) model Ztunnel operates at Layer 4 (L4) of the Open Systems Interconnection (OSI) model and proxies TCP traffic. Ztunnel cannot transfer connection states to another process. Upgrading the Ztunnel DaemonSet affects all traffic on at least one node at a time. By default, the Ztunnel DaemonSet uses a `RollingUpdate` strategy. During a restart, each node goes through the following phases: -* Startup: A new `Ztunnel` pod starts on the node while the old pod continues running. +* Startup: A new `ztunnel` pod starts on the node while the old pod continues running. -* Readiness: The new `Ztunnel` establishes listeners in each pod on the node and marks itself as ready. For a brief period, both instances run simultaneously, and either one might handle new connections. +* Readiness: The new `ztunnel` establishes listeners in each pod on the node and marks itself as ready. For a brief period, both instances run simultaneously, and either one might handle new connections. -* Draining: {k8s} sends a `SIGTERM` to the old `Ztunnel`, which begins the draining process. The old instance closes its listeners so that only the new `Ztunnel` accepts new connections. At all times, at least one `Ztunnel` remains available to handle incoming connections. +* Draining: {k8s} sends a `SIGTERM` to the old `ztunnel`, which begins the draining process. The old instance closes its listeners so that only the new `ztunnel` accepts new connections. At all times, at least one `ztunnel` remains available to handle incoming connections. -* Connection processing: The old Ztunnel continues processing existing connections until the `terminationGracePeriodSeconds` expires. +* Connection processing: The old `ztunnel` continues processing existing connections until the `terminationGracePeriodSeconds` expires. -* Termination: Once the `terminationGracePeriodSeconds` expires, the old `Ztunnel` forcefully terminates any remaining connections. \ No newline at end of file +* Termination: Once the `terminationGracePeriodSeconds` expires, the old `ztunnel` forcefully terminates any remaining connections. \ No newline at end of file