diff --git a/.gitignore b/.gitignore index 050e00a4a0b..41a46d7ce52 100644 --- a/.gitignore +++ b/.gitignore @@ -16,5 +16,13 @@ bin commercial_package .vscode .vale/styles/AsciiDoc +.vale/styles/AsciiDocDITA .vale/styles/OpenShiftAsciiDoc .vale/styles/RedHat +migrating/JIRA-9894-dns-capture-documentation-plan.md +migrating/modules/ossm-migrating-a-multitenant-deployment.html +analysis/ +artifacts/ +update/ossm-preparing-for-rhel-10-migration.adoc +modules/ossm-migrate-to-nftables-rhel10-ambient.adoc +modules/ossm-migrate-to-nftables-rhel10-sidecar.adoc diff --git a/.vale.ini b/.vale.ini index 4746c2d9f60..9ee89b9301c 100644 --- a/.vale.ini +++ b/.vale.ini @@ -2,11 +2,11 @@ StylesPath = .vale/styles MinAlertLevel = suggestion -Packages = RedHat, AsciiDoc, OpenShiftAsciiDoc +Packages = RedHat, AsciiDoc, OpenShiftAsciiDoc, https://github.com/jhradilek/asciidoctor-dita-vale/releases/latest/download/AsciiDocDITA.zip # Ignore files in dirs starting with `.` to avoid raising errors for `.vale/fixtures/*/testinvalid.adoc` files [[!.]*.adoc] -BasedOnStyles = RedHat, AsciiDoc, OpenShiftAsciiDoc +BasedOnStyles = RedHat, AsciiDoc, OpenShiftAsciiDoc, AsciiDocDITA # Disabling rules (NO) RedHat.ReleaseNotes = NO diff --git a/.vale/styles/Vocab/OpenShiftDocs/accept.txt b/.vale/styles/Vocab/OpenShiftDocs/accept.txt index 5ef46f47740..ff8df6faadf 100644 --- a/.vale/styles/Vocab/OpenShiftDocs/accept.txt +++ b/.vale/styles/Vocab/OpenShiftDocs/accept.txt @@ -18,3 +18,5 @@ Operators NICs? Mellanox VFs? +[Ww]aypoint +[Zz]tunnel diff --git a/_attributes/common-attributes.adoc b/_attributes/common-attributes.adoc index c01645a67eb..5962c45d301 100644 --- a/_attributes/common-attributes.adoc +++ b/_attributes/common-attributes.adoc @@ -17,7 +17,7 @@ :SMProductName: Red{nbsp}Hat OpenShift Service Mesh :SMProduct: OpenShift Service Mesh :SMProductShortName: Service Mesh -:SMProductVersion: 3.2.0 +:SMProductVersion: 3.4.0 //service mesh v2 //Update when there is a new 2.6.z release :SMv2Version: 2.6.10 diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 6af76027313..031add3b7ff 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -10,53 +10,55 @@ Topics: - Name: Service Mesh 3.x feature support tables File: ossm-release-notes-feature-support-tables --- -Name: Migrating from Service Mesh 2 to Service Mesh 3 -Dir: migrating -Distros: openshift-service-mesh -Topics: -- Name: Migrating from Service Mesh 2 to Service Mesh 3 - File: ossm-migrating-from-service-mesh-2-to-3 -- Name: Before migrating - Dir: checklists - Topics: - - Name: Important information to know before migrating - File: ossm-migrating-read-me - - Name: Premigration checklists - File: ossm-migrating-premigration-checklists - - Name: Migrating network policies - File: ossm-migrating-network-policies - - Name: Kiali differences for Service Mesh 3 - File: ossm-migrating-kiali-differences -- Name: Multitenant migration guide - Dir: multitenant - Topics: - - Name: Multitenant migration guide - File: ossm-migrating-multitenant -- Name: Cluster-wide migration guide - Dir: cluster-wide - Topics: - - Name: Cluster-wide migration guide - File: ossm-migrating-cluster-wide -- Name: Migrating gateways - Dir: migrating-gateways - Topics: - - Name: Migrating gateways - File: ossm-migrating-gateways -- Name: Completing the migration - Dir: done - Topics: - - Name: Completing the Migration - File: ossm-migrating-complete -- Name: Reference - Dir: reference - Topics: - - Name: Migrating references - File: ossm-migrating-references ---- +# Name: Migrating from Service Mesh 2 to Service Mesh 3 +# Dir: migrating +# Distros: openshift-service-mesh +# Topics: +# - Name: Migrating from Service Mesh 2 to Service Mesh 3 +# File: ossm-migrating-from-service-mesh-2-to-3 +# - Name: Before migrating +# Dir: checklists +# Topics: +# - Name: Important information to know before migrating +# File: ossm-migrating-read-me +# - Name: Premigration checklists +# File: ossm-migrating-premigration-checklists +# - Name: Migrating network policies +# File: ossm-migrating-network-policies +# - Name: Kiali differences for Service Mesh 3 +# File: ossm-migrating-kiali-differences +# - Name: Multitenant migration guide +# Dir: multitenant +# Topics: +# - Name: Multitenant migration guide +# File: ossm-migrating-multitenant +# - Name: Cluster-wide migration guide +# Dir: cluster-wide +# Topics: +# - Name: Cluster-wide migration guide +# File: ossm-migrating-cluster-wide +# - Name: Migrating gateways +# Dir: migrating-gateways +# Topics: +# - Name: Migrating gateways +# File: ossm-migrating-gateways +# - Name: Completing the migration +# Dir: done +# Topics: +# - Name: Completing the Migration +# File: ossm-migrating-complete +# - Name: Reference +# Dir: reference +# Topics: +# - Name: Migrating references +# File: ossm-migrating-references +# --- Name: About Dir: about Distros: openshift-service-mesh Topics: +- Name: Planning your service mesh deployment + File: ossm-planning - Name: About OpenShift Service Mesh File: ossm-about-openshift-service-mesh - Name: Understanding Service Mesh @@ -74,8 +76,12 @@ Topics: File: ossm-sidecar-injection - Name: Istio ambient mode File: ossm-istio-ambient-mode +- Name: Coexistence of ambient and sidecar modes + File: ossm-ambient-sidecar-coexistence - Name: Red Hat OpenShift Service Mesh and cert-manager File: ossm-cert-manager +- Name: SPIRE integration for mesh security + File: ossm-SPIRE - Name: Multi-Cluster topologies File: ossm-multi-cluster-topologies - Name: Deploying multiple service meshes on a single cluster diff --git a/modules/ossm-api-settings-mesh-ha-replicacount.adoc b/_unused_topics/unused_modules/ossm-api-settings-mesh-ha-replicacount.adoc similarity index 99% rename from modules/ossm-api-settings-mesh-ha-replicacount.adoc rename to _unused_topics/unused_modules/ossm-api-settings-mesh-ha-replicacount.adoc index 837c792879f..2907e26104c 100644 --- a/modules/ossm-api-settings-mesh-ha-replicacount.adoc +++ b/_unused_topics/unused_modules/ossm-api-settings-mesh-ha-replicacount.adoc @@ -1,4 +1,5 @@ // This module is used in the following assemblies: +// // * service-mesh-docs-main/install/ossm-installing-service-mesh.adoc :_mod-docs-content-type: REFERENCE diff --git a/modules/ossm-cert-manager-installing-istio-resource.adoc b/_unused_topics/unused_modules/ossm-cert-manager-installing-istio-resource.adoc similarity index 87% rename from modules/ossm-cert-manager-installing-istio-resource.adoc rename to _unused_topics/unused_modules/ossm-cert-manager-installing-istio-resource.adoc index 0a433ab1ca3..8a592c0c9aa 100644 --- a/modules/ossm-cert-manager-installing-istio-resource.adoc +++ b/_unused_topics/unused_modules/ossm-cert-manager-installing-istio-resource.adoc @@ -8,11 +8,6 @@ [role="_abstract"] -//TP1 content influx. Title, etc may change. -//Content is very similar to 2.x content -//all kinds of formatting things to fix. want to see if a build will generate to have a look, and see how it fits structurally with the IA. - - After you have installed `istio-csr` by following the procedure for either an in place or revision based update strategy, you can install the `Istio` resource. You need to disable Istio's built in CA server and tell istiod to use the `istio-csr` CA server. The `istio-csr` CA server issues certificates for both istiod and user workloads. diff --git a/modules/ossm-cert-manager-istio-csr-inplace-update-strategy.adoc b/_unused_topics/unused_modules/ossm-cert-manager-istio-csr-inplace-update-strategy.adoc similarity index 100% rename from modules/ossm-cert-manager-istio-csr-inplace-update-strategy.adoc rename to _unused_topics/unused_modules/ossm-cert-manager-istio-csr-inplace-update-strategy.adoc diff --git a/modules/ossm-cert-manager-istio-csr-revisionbased-strategy.adoc b/_unused_topics/unused_modules/ossm-cert-manager-istio-csr-revisionbased-strategy.adoc similarity index 100% rename from modules/ossm-cert-manager-istio-csr-revisionbased-strategy.adoc rename to _unused_topics/unused_modules/ossm-cert-manager-istio-csr-revisionbased-strategy.adoc diff --git a/modules/ossm-cert-manager-update-istio-csr-revisionbased-only.adoc b/_unused_topics/unused_modules/ossm-cert-manager-update-istio-csr-revisionbased-only.adoc similarity index 100% rename from modules/ossm-cert-manager-update-istio-csr-revisionbased-only.adoc rename to _unused_topics/unused_modules/ossm-cert-manager-update-istio-csr-revisionbased-only.adoc diff --git a/modules/ossm-cert-manager-verifying-install.adoc b/_unused_topics/unused_modules/ossm-cert-manager-verifying-install.adoc similarity index 92% rename from modules/ossm-cert-manager-verifying-install.adoc rename to _unused_topics/unused_modules/ossm-cert-manager-verifying-install.adoc index 38b7f0b429b..45bc68f7c45 100644 --- a/modules/ossm-cert-manager-verifying-install.adoc +++ b/_unused_topics/unused_modules/ossm-cert-manager-verifying-install.adoc @@ -8,10 +8,6 @@ [role="_abstract"] -//TP1 content influx. Title, etc may change. -//Content is very similar to 2.x content -//all kinds of formatting things to fix. want to see if a build will generate to have a look, and see how it fits structurally with the IA. - You can use the sample `httpbin` service and `sleep` application to check communication between the workloads. You can also check the workload certificate of the proxy to verify that the cert-manager tool is installed correctly. .Procedure diff --git a/modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label-with-cert-manager.adoc b/_unused_topics/unused_modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label-with-cert-manager.adoc similarity index 76% rename from modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label-with-cert-manager.adoc rename to _unused_topics/unused_modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label-with-cert-manager.adoc index 5430945a1a7..72ae200cf5a 100644 --- a/modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label-with-cert-manager.adoc +++ b/_unused_topics/unused_modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label-with-cert-manager.adoc @@ -12,7 +12,7 @@ You can perform a canary upgrade with the gradual migration of data plane namesp You must relabel all of the data plane namespaces. However, it is safe to restart any of the workloads at any point during the migration process. -The `bookinfo` application is used as an example for the `Istio` resource. For more information about configuration differences between the {SMProduct} 2 `ServiceMeshControlPlane` resource and the {SMProduct} 3 `Istio` resource, see "ServiceMeshControlPlane resource to Istio resource fields mapping". +The `bookinfo` application is used as an example for the `{istio}` resource. For more information about configuration differences between the {SMProduct} 2 `ServiceMeshControlPlane` resource and the {SMProduct} 3 `{istio}` resource, see "ServiceMeshControlPlane resource to Istio resource fields mapping". .Prerequisites @@ -31,7 +31,8 @@ The `bookinfo` application is used as an example for the `Istio` resource. For m . Check that your {SMProduct} 2 `ServiceMeshControlPlane` resource is configured with the cert-manager-tool: + -.Example `ServiceMeshControlPlane` cert-manager configuration +You can see the following example configuration for reference: ++ [source,yaml] ---- apiVersion: maistra.io/v2 @@ -62,10 +63,12 @@ spec: --reuse-values \ --namespace istio-system \ --wait \ - --set "app.istio.revisions={basic,ossm-3-v1-24-3}" <1> + --set "app.istio.revisions={basic,ossm-3-v1-24-3}" ---- + -<1> The `app.istio.revisions` field needs to include your {SMProduct} 3.0 control plane revision _before_ you create your `Istio` resource so that proxies can properly communicate with the {SMProduct} 3.0 control plane. +where: + +`app.istio.revisions`:: This field should include your {SMProduct} 3.0 control plane revision _before_ you create your `{istio}` resource so that proxies can properly communicate with the {SMProduct} 3.0 control plane. . Identify the namespaces that contain a 2.6 control plane by running the following command: + @@ -74,7 +77,8 @@ spec: $ oc get smcp -A ---- + -.Example output: +You get an output similar to the following example: ++ [source,terminal] ---- NAMESPACE NAME READY STATUS PROFILES VERSION AGE @@ -88,21 +92,22 @@ istio-system install-istio-system 6/6 ComponentsReady ["default"] 2. In the following example configuration, the {istio} control plane has access to all namespaces on the cluster. If you want to limit the namespaces the control plan has access to, you must define discovery selectors. You must match all the data plane namespaces that you plan to migrate from version 2.6. ==== + -.Example `Istio` resource +You can see the following example configuration for reference: ++ [source,yaml,subs="attributes,verbatim"] ---- apiVersion: sailoperator.io/v1 kind: Istio metadata: - name: ossm-3 # <1> + name: ossm-3 spec: updateStrategy: type: RevisionBased - namespace: istio-system # <2> + namespace: istio-system version: v1.24.3 values: meshConfig: - extensionProviders: # <3> + extensionProviders: - name: prometheus prometheus: {} - name: otel @@ -115,9 +120,9 @@ spec: env: ENABLE_CA_SERVER: "false" ---- -<1> The `name`, `updateStrategy`, and `version` fields specify how the `IstioRevision` resource name is created. For more information, see "Identifying the revision name". -<2> The 3.0 and 2.6 control planes must run in the same namespace. -<3> If you are migrating metrics and tracing, update the `extensionProviders` fields according to your tracing and metrics configurations. +* `metadata.name` specifies the name of the `IstioRevision` resource. The `updateStrategy` and `version` fields specify how the resource is updated. For more information, see "Identifying the revision name". +* `spec.namespace` specifies the namespace where the 3.0 and 2.6 control planes must run. +* `spec.values` specifies the configuration values for the 3.0 control plane. If you are migrating metrics and tracing, update the `extensionProviders` fields according to your tracing and metrics configurations. + [NOTE] ==== @@ -138,7 +143,8 @@ $ oc apply -f ossm-3.yaml $ oc logs deployments/istiod-ossm-3-v1-24-3 -n istio-system | grep 'Load signing key and cert from existing secret' ---- + -.Example output: +You get an output similar to the following example: ++ [source,terminal] ---- 2024-12-18T08:13:53.788959Z info pkica Load signing key and cert from existing secret istio-system/istio-ca-secret diff --git a/modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label-with-cert-manager.adoc b/_unused_topics/unused_modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label-with-cert-manager.adoc similarity index 67% rename from modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label-with-cert-manager.adoc rename to _unused_topics/unused_modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label-with-cert-manager.adoc index 54c706b0415..8547c324f01 100644 --- a/modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label-with-cert-manager.adoc +++ b/_unused_topics/unused_modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label-with-cert-manager.adoc @@ -10,14 +10,14 @@ You can perform a canary upgrade with the gradual migration of data plane namespaces for a cluster-wide deployment by using the `istio.io/rev` label with cert-manager. -The `bookinfo` application is used as an example for the `Istio` resource. For more information on configuration differences between the {SMProduct} 2 `ServiceMeshControlPlane` resource and the {SMProduct} 3 `Istio` resource, see "Configuration fields mapping between Service Mesh 2 and Service Mesh 3." +The `bookinfo` application is used as an example for the `{istio}` resource. For more information on configuration differences between the {SMProduct} 2 `ServiceMeshControlPlane` resource and the {SMProduct} 3 `{istio}` resource, see "Configuration fields mapping between Service Mesh 2 and Service Mesh 3." You can follow these same steps with your own workloads. .Prerequisites * You have deployed {ocp-product-title} 4.14 or later. -* You are logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role. +* You have logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role. * You have completed the premigration checklists. * You have installed the {SMProduct} {SMv2Version} Operator. * You have installed the {SMProduct} 3 Operator. @@ -30,7 +30,8 @@ You can follow these same steps with your own workloads. . Check that your {SMProduct} 2 `ServiceMeshControlPlane` resource is configured with the cert-manager tool. + -.Example `ServiceMeshControlPlane` cert-manager configuration +You can see the following example configuration for reference: ++ [source,yaml] ---- apiVersion: maistra.io/v2 @@ -61,10 +62,12 @@ spec: --reuse-values \ --namespace istio-system \ --wait \ - --set "app.istio.revisions={basic,ossm-3-v1-24-3}" <1> + --set "app.istio.revisions={basic,ossm-3-v1-24-3}" ---- + -<1> The `app.istio.revisions` field must include your {SMProduct} 3.0 control plane revision _before_ you create your `Istio` resource so that proxies can properly communicate with the {SMProduct} 3.0 control plane. +where: ++ +`app.istio.revisions`:: This field must include your {SMProduct} 3.0 control plane revision _before_ you create your `Istio` resource so that proxies can properly communicate with the {SMProduct} 3.0 control plane. . Identify the namespaces that contain a 2.6 control plane by running the following command: + @@ -73,30 +76,32 @@ spec: $ oc get smcp -A ---- + -.Example output: +You get an output similar to the following example: ++ [source,terminal] ---- NAMESPACE NAME READY STATUS PROFILES VERSION AGE istio-system install-istio-system 6/6 ComponentsReady ["default"] 2.6.6 115m ---- -. Create a YAML file named `ossm-3.yaml`. This procedure creates the {istio} resource for the 3.0 installation in the same namespace as the `ServiceMeshControlPlane` resource for the 2.6 installation: +. Create a YAML file named `ossm-3.yaml`. This procedure creates the `{istio}` resource for the 3.0 installation in the same namespace as the `ServiceMeshControlPlane` resource for the 2.6 installation: ++ +You can see the following example configuration for reference: + -.Example `Istio` resource [source,yaml,subs="attributes,verbatim"] ---- apiVersion: sailoperator.io/v1 kind: Istio metadata: - name: ossm-3 # <1> + name: ossm-3 spec: updateStrategy: type: RevisionBased - namespace: istio-system # <2> + namespace: istio-system version: v1.24.3 values: meshConfig: - extensionProviders: # <3> + extensionProviders: - name: prometheus prometheus: {} - name: otel @@ -109,9 +114,9 @@ spec: env: ENABLE_CA_SERVER: "false" ---- -<1> The `name`, `updateStrategy`, and `version` fields specify how the `IstioRevision` resource name is created. For more information, see "Identifying the revision name." -<2> The 3.0 and 2.6 control planes must run in the same namespace. -<3> If you are migrating metrics and tracing, update the `extensionProviders` fields according to your tracing and metrics configurations. +* `metadata.name` specifies the name of the `IstioRevision` resource. The `updateStrategy` and `version` fields specify how the resource is updated. For more information, see "Identifying the revision name." +* `spec.namespace` specifies the namespace where the 3.0 and 2.6 control planes must run. +* `spec.values` specifies the configuration values for the 3.0 control plane. If you are migrating metrics and tracing, update the `extensionProviders` fields according to your tracing and metrics configurations. . Apply the YAML file by running the following command: + @@ -127,7 +132,8 @@ $ oc apply -f ossm-3.yaml $ oc logs deployments/istiod-ossm-3-v1-24-3 -n istio-system | grep 'Load signing key and cert from existing secret' ---- + -.Example output: +You get an output similar to the following example: ++ [source,terminal] ---- 2024-12-18T08:13:53.788959Z info pkica Load signing key and cert from existing secret istio-system/istio-ca-secret diff --git a/modules/ossm-migrating-workloads-using-the-istio-injection-label-with-cert-manager.adoc b/_unused_topics/unused_modules/ossm-migrating-workloads-using-the-istio-injection-label-with-cert-manager.adoc similarity index 94% rename from modules/ossm-migrating-workloads-using-the-istio-injection-label-with-cert-manager.adoc rename to _unused_topics/unused_modules/ossm-migrating-workloads-using-the-istio-injection-label-with-cert-manager.adoc index ac7e465049b..92d282e0885 100644 --- a/modules/ossm-migrating-workloads-using-the-istio-injection-label-with-cert-manager.adoc +++ b/_unused_topics/unused_modules/ossm-migrating-workloads-using-the-istio-injection-label-with-cert-manager.adoc @@ -24,7 +24,7 @@ You can migrate workloads and gateways separately, and in any order. For more in $ oc get istios ---- + -.Example output +You get an output similar to the following example: + [source,terminal] ---- @@ -63,7 +63,6 @@ After you apply the `maistra.io/ignore-namespace` label, any new pod that gets c + .. To restart all the workloads at the same time so that the new pods are injected with the {SMProduct} 3.0 proxy, run the following command: + -.Example command for `bookinfo` application [source,terminal] ---- $ oc rollout restart deployments -n bookinfo @@ -71,7 +70,6 @@ $ oc rollout restart deployments -n bookinfo .. To restart each workload individually, run the following command for each workload: + -.Example command for `bookinfo` application [source,terminal] ---- $ oc rollout restart deployments productpage-v1 -n bookinfo @@ -86,14 +84,15 @@ $ oc rollout status deployment productpage-v1 -n bookinfo .Verification -. Verify that the the new control plane manages the expected workloads by running the following command: +. Verify that the new control plane manages the expected workloads by running the following command: + [source,terminal] ---- $ istioctl ps -n bookinfo ---- + -.Example output: +You get an output similar to the following example: ++ [source,terminal] ---- NAME CLUSTER CDS LDS EDS RDS ECDS ISTIOD VERSION @@ -107,7 +106,7 @@ reviews-v3-5c5d764c9b-rrx8w.bookinfo Kubernetes SYNCED SYN + The output shows that the `productpage-v1` deployment is the only deployment that has been restarted and was injected with the 3.0 proxy. Even if there are different versions of the proxies, communication between the services still works. -. If the 2.6 installation contains additional namespaces, migrate the next namespace now. +. If the 2.6 installation has additional namespaces, migrate the next namespace now. + [NOTE] ==== diff --git a/modules/ossm-migrating-workloads-using-the-istio-revision-label-with-cert-manager.adoc b/_unused_topics/unused_modules/ossm-migrating-workloads-using-the-istio-revision-label-with-cert-manager.adoc similarity index 100% rename from modules/ossm-migrating-workloads-using-the-istio-revision-label-with-cert-manager.adoc rename to _unused_topics/unused_modules/ossm-migrating-workloads-using-the-istio-revision-label-with-cert-manager.adoc diff --git a/modules/ossm-release-notes-making-open-source-inclusive.adoc b/_unused_topics/unused_modules/ossm-release-notes-making-open-source-inclusive.adoc similarity index 79% rename from modules/ossm-release-notes-making-open-source-inclusive.adoc rename to _unused_topics/unused_modules/ossm-release-notes-making-open-source-inclusive.adoc index fde686cb713..96e8cfa0366 100644 --- a/modules/ossm-release-notes-making-open-source-inclusive.adoc +++ b/_unused_topics/unused_modules/ossm-release-notes-making-open-source-inclusive.adoc @@ -1,8 +1,7 @@ -//// -Module included in the following assemblies: -* service-mesh-docs-main/ossm-release-notes.adoc -* service-mesh-docs-main/ossm-support-tables.adoc -//// +// Module included in the following assemblies: +// +// * service-mesh-docs-main/ossm-release-notes.adoc +// * service-mesh-docs-main/ossm-support-tables.adoc :_mod-docs-content-type: CONCEPT [id="making-open-source-more-inclusive_{context}"] diff --git a/modules/ossm-running-v2-v3-cluster-wide-deployment-model.adoc b/_unused_topics/unused_modules/ossm-running-v2-v3-cluster-wide-deployment-model.adoc similarity index 74% rename from modules/ossm-running-v2-v3-cluster-wide-deployment-model.adoc rename to _unused_topics/unused_modules/ossm-running-v2-v3-cluster-wide-deployment-model.adoc index 9be3cd66dc2..2a606e6554b 100644 --- a/modules/ossm-running-v2-v3-cluster-wide-deployment-model.adoc +++ b/_unused_topics/unused_modules/ossm-running-v2-v3-cluster-wide-deployment-model.adoc @@ -8,14 +8,9 @@ [role="_abstract"] -//TP1 content influx. Title, etc may change. -//No IA as of 10/23/2024 so this content is likely to move. - If you are moving from {SMProductName} 2.6 in a cluster-wide deployment model, you can run {SMProduct} 2.6 side-by-side with {SMProduct} 3.0, in one cluster, without them interfering with each other. -In {SMProduct} 2.6, you can check your deployment model from the `ServiceMeshControlPlane` under `spec.mode`: - -.Example `ServiceMeshControlPlane` yaml +In {SMProduct} 2.6, you can check your deployment model from the `ServiceMeshControlPlane` under `spec.mode`, similar to the following example: [source, yaml] ---- apiVersion: maistra.io/v2 @@ -28,27 +23,21 @@ spec: To prevent conflicts with {SMProduct} 3.0 when using the {SMProduct} 2.6 cluster-wide deployment model, you need to configure the `ServiceMeshControlPlane` resource to restrict namespaces to only those belonging to (SMProduct) 2.6. -//NOTES: 10/23/2024 - -//DO NOT USE VERSION NUMBER ATTRIBUTE. It is set for 3.0, will likely change, and it is unclear if later versions would impact this procedure for moving from 2.6. -//Only moving from 2.6 has been tested and verified by QE. -//Cluster-wide requires changes to OSSM 2.6 ServiceMeshControlPlane before installing OSSM 3.0 - .Prerequisites * You are running {ocp-product-title} 4.14 or later. + * You are running {SMProduct} 2.6. + [IMPORTANT] ==== -If you are not running {SMProduct} 2.6, you must upgrade to 2.6 before following this procedure. To upgrade to {SMProduct} version to 2.6, see: link:https://docs.openshift.com/container-platform/4.17/service_mesh/v2x/upgrading-ossm.html[Upgrading Service Mesh 2.x] +If you are not running {SMProduct} 2.6, you must upgrade to 2.6 before following this procedure. To upgrade to {SMProduct} version to 2.6, see: "Upgrading Service Mesh 2.x". ==== .Procedure -. Configure `discoverySelectors`, and set the `ENABLE_ENHANCED_RESOURCE_SCOPING` environment variable on the pilot container to `true` in your {SMProduct} 2.6 `ServiceMeshControlPlane` custom resource (CR): +. Configure `discoverySelectors`, and set the `ENABLE_ENHANCED_RESOURCE_SCOPING` environment variable on the pilot container to `true` in your {SMProduct} 2.6 `ServiceMeshControlPlane` custom resource (CR), similar to the following example: + -.Example `ServiceMeshControlPlane` CR [source, yaml] ---- apiVersion: maistra.io/v2 @@ -76,20 +65,19 @@ spec: . Create an `IstioCNI` resource in the `istio-cni` namespace. -. Create an `Istio` resource in a different namespace than the namespace used in the `ServiceMeshControlPlane` resource in {SMProduct} 2.6. This example uses the `istio-system3` namespace: +. Create an `{istio}` resource in a different namespace than the namespace used in the `ServiceMeshControlPlane` resource in {SMProduct} 2.6. This example uses the `istio-system3` namespace, similar to the following example: + -.Example `Istio` resource with `istio-system3` [source, yaml] ---- kind: Istio apiVersion: sailoperator.io/v1 metadata: - name: ossm3 # <1> + name: ossm3 spec: - namespace: istio-system3 # <2> + namespace: istio-system3 values: meshConfig: - discoverySelectors: # <3> + discoverySelectors: - matchExpressions: - key: maistra.io/member-of operator: DoesNotExist @@ -97,14 +85,9 @@ spec: type: InPlace version: v1.23.0 ---- -<1> Do not use `default` as the name. -<2> Must be different from the namespace used in the `ServiceMeshControlPlane` resource in {SMProduct} 2.6. This example uses the `istio-system3` namespace. -<3> To ignore {SMProduct} 2.6 namespaces, configure the `discoverySelectors` section as shown. All other namespaces will be part of the {SMProduct} 3.0 mesh. -+ - -//. install `Red Hat OpenShift Service Mesh 3` operator -//. create `IstioCNI` resource in `istio-cni` namespace -//. create following `Istio` resource in `istio-system3` (must be a different namespace than a namespace running OSSM 2). Make sure to use discovery selectors which are ignoring OSSM 2 namespaces and NOT to use `default` name for `Istio` resource. You can optionally restrict discovered namespaces even more. Configuration shown in the example only ignores OSSM 2 namespaces but all other namespaces will be part of OSSM 3 mesh. +* `metadata.name`, for this example, do not use `default` as the name. +* `spec.namespace`, for this example, the value must be different from the namespace used in the `ServiceMeshControlPlane` resource in {SMProduct} 2.6. This example uses the `istio-system3` namespace. +* `spec.values.meshConfig.discoverySelectors`, for this example, configures the discovery selectors to ignore {SMProduct} 2.6 namespaces. All other namespaces will be part of the {SMProduct} 3.0 mesh. . Deploy your workloads and label the namespaces with `istio.io/rev=ossm3` label by running the following command: + @@ -118,14 +101,15 @@ $ oc label namespace istio.io/rev=ossm3 If you have changed `spec.memberSelectors` in `ServiceMeshMemberRoll` in the `ServiceMeshControlPlane` resource in {SMProduct} 2.6., then use the `istio-injection=enabled` label for your {SMProduct} 3.0 workload namespaces. ==== -. Confirm the application workloads are managed by their respective control planes by running the following command: +. Confirm that each control plane manages the required application workloads by running the following command: + [source,terminal] ---- $ istioctl ps -i istio-system ---- + -.Sample output `istio-system` +You will get an output similar to the following example: ++ [source, terminal] ---- $ istioctl ps -i istio-system @@ -142,7 +126,8 @@ reviews-v2-5c7ff5b77b-5bpc4.bookinfo Kubernetes SYNCED SYNCED reviews-v3-5c5d764c9b-mk8vn.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-install-istio-system-bd58bdcd5-2htkf 1.20.8 ---- + -.Sample output `istio-system3` +You will get an output similar to the following example: ++ [source,terminal] ---- $ istioctl ps -i istio-system3 @@ -153,4 +138,4 @@ ratings-v1-fb764cb99-kx2dr.bookinfo2 Kubernetes SYNCED (2m40s) reviews-v1-8bd5549cf-xqqmd.bookinfo2 Kubernetes SYNCED (2m40s) SYNCED (2m40s) SYNCED (2m34s) SYNCED (2m40s) IGNORED istiod-ossm3-5b46b6b8cb-gbjx6 1.23.0 reviews-v2-7f7cc8bf5c-5rvln.bookinfo2 Kubernetes SYNCED (2m40s) SYNCED (2m40s) SYNCED (2m34s) SYNCED (2m40s) IGNORED istiod-ossm3-5b46b6b8cb-gbjx6 1.23.0 reviews-v3-84f674b88c-ftcqg.bookinfo2 Kubernetes SYNCED (2m40s) SYNCED (2m40s) SYNCED (2m34s) SYNCED (2m40s) IGNORED istiod-ossm3-5b46b6b8cb-gbjx6 1.23.0 ----- +---- \ No newline at end of file diff --git a/modules/ossm-running-v2-v3-multitenant-deployment-model.adoc b/_unused_topics/unused_modules/ossm-running-v2-v3-multitenant-deployment-model.adoc similarity index 73% rename from modules/ossm-running-v2-v3-multitenant-deployment-model.adoc rename to _unused_topics/unused_modules/ossm-running-v2-v3-multitenant-deployment-model.adoc index 80316da4904..1874f1eb670 100644 --- a/modules/ossm-running-v2-v3-multitenant-deployment-model.adoc +++ b/_unused_topics/unused_modules/ossm-running-v2-v3-multitenant-deployment-model.adoc @@ -4,18 +4,14 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-running-v2-v3-multitenant-deployment-model_{context}"] -= Running {SMProduct} 2.6 and {SMProduct} 3 using multi-tenant deployment model += Running {SMProduct} 2.6 and {SMProduct} 3 using multitenant deployment model [role="_abstract"] -//TP1 content influx. Title, etc may change. -//No IA as of 10/23/2024 so this content is likely to move. +Perform a phased migration by running {SMProduct} 3.0 and version 2.6 concurrently in a single cluster without conflicts between the two mesh versions. -If you are moving from {SMProductName} 2.6 from the default multi-tenant deployment model, you can run {SMProduct} 2.6 side-by-side with {SMProduct} 3.0, in one cluster, without them interfering with each other. +In {SMProduct} 2.6, you can check your deployment model from the `ServiceMeshControlPlane` under `spec.mode`, similar to the following example: -In {SMProduct} 2.6, you can check your deployment model from the `ServiceMeshControlPlane` under `spec.mode`: - -.Example `ServiceMeshControlPlane` yaml [source, yaml] ---- apiVersion: maistra.io/v2 @@ -26,20 +22,15 @@ spec: mode: MultiTenant ---- -//NOTES: 10/23/2024 - -//DO NOT USE VERSION NUMBER ATTRIBUTE. It is set for 3.0, will likely change, and it is unclear if later versions would impact this procedure for moving from 2.6. -//Only moving from 2.6 has been tested and verified by QE. -//Mulitenant has no changes to OSSM 2.6, separate module. - .Prerequisites * You are running {ocp-product-title} 4.14 or later. + * You are running {SMProduct} 2.6. + [IMPORTANT] ==== -If you are not running {SMProduct} 2.6, you must upgrade to 2.6 before following this procedure. To upgrade to {SMProduct} version to 2.6, see: link:https://docs.openshift.com/container-platform/4.17/service_mesh/v2x/upgrading-ossm.html[Upgrading Service Mesh 2.x] +If you are not running {SMProduct} 2.6, you must upgrade to 2.6 before following this procedure. To upgrade to {SMProduct} version to 2.6, see "Upgrading Service Mesh 2.x". ==== .Procedure @@ -48,20 +39,19 @@ If you are not running {SMProduct} 2.6, you must upgrade to 2.6 before following . Create an `IstioCNI` resource in the `istio-cni` namespace. -. Create an `Istio` resource in a different namespace than the namespace used in the `ServiceMeshControlPlane` resource in {SMProduct} 2.6. This example uses the `istio-system3` namespace: +. Create an `{istio}` resource in a different namespace than the namespace used in the `ServiceMeshControlPlane` resource in {SMProduct} 2.6. This example uses the `istio-system3` namespace, similar to the following example: + -.Example `Istio` resource with `istio-system3` [source, yaml] ---- kind: Istio apiVersion: sailoperator.io/v1alpha1 metadata: - name: ossm3 # <1> + name: ossm3 spec: - namespace: istio-system3 # <2> + namespace: istio-system3 values: meshConfig: - discoverySelectors: # <3> + discoverySelectors: - matchExpressions: - key: maistra.io/member-of operator: DoesNotExist @@ -69,9 +59,9 @@ spec: type: InPlace version: v1.23.0 ---- -<1> Do not use `default` as the name. -<2> Must be different from the namespace used in the `ServiceMeshControlPlane` resource in {SMProduct} 2.6. This example uses the `istio-system3` namespace. -<3> To ignore {SMProduct} 2.6 namespaces, configure the `discoverySelectors` section as shown. All other namespaces will be part of the {SMProduct} 3.0 mesh. +* `metadata.name`, for this example, do not use `default` as the name. +* `spec.namespace`, for this example, the value must be different from the namespace used in the `ServiceMeshControlPlane` resource in {SMProduct} 2.6. This example uses the `istio-system3` namespace. +* `spec.values.meshConfig.discoverySelectors`, for this example, configures the discovery selectors to ignore {SMProduct} 2.6 namespaces. All other namespaces will be part of the {SMProduct} 3.0 mesh. . Deploy your workloads and label the namespaces with `istio.io/rev=ossm3` label by running the following command: + @@ -85,14 +75,15 @@ $ oc label namespace istio.io/rev= If you have changed `spec.memberSelectors` in `ServiceMeshMemberRoll` in the `ServiceMeshControlPlane` resource in {SMProduct} 2.6., then use the `istio-injection=enabled` label for your {SMProduct} 3.0 workload namespaces. ==== -. Confirm the application workloads are managed by their respective control planes by running the following command: +. Confirm that each control plane manages the required application workloads by running the following command: + [source,terminal] ---- $ istioctl ps -i istio-system ---- + -.Sample output `istio-system` +You will get an output similar to the following example: ++ [source, terminal] ---- $ istioctl ps -i istio-system @@ -109,7 +100,8 @@ reviews-v2-5c7ff5b77b-5bpc4.bookinfo Kubernetes SYNCED SYNCED reviews-v3-5c5d764c9b-mk8vn.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-install-istio-system-bd58bdcd5-2htkf 1.20.8 ---- + -.Sample output `istio-system3` +You will get an output similar to the following example: ++ [source,terminal] ---- $ istioctl ps -i istio-system3 diff --git a/about/ossm-about-concepts.adoc b/about/ossm-about-concepts.adoc index 28343c7cd3c..4ce036286d7 100644 --- a/about/ossm-about-concepts.adoc +++ b/about/ossm-about-concepts.adoc @@ -8,7 +8,7 @@ toc::[] [role="_abstract"] -You can use {SMProductName} to connect, secure, and monitor microservices in your {SMProductName} environment. Core resources, Kiali integrations, and observability components comprise the service mesh ecosystem. +You can use {SMProductName} to connect, secure, and monitor microservices in your {SMProductName} environment. Core resources, Kiali integrations, and observability components form the service mesh ecosystem. include::modules/ossm-about-concepts-resources.adoc[leveloffset=+1] @@ -18,4 +18,24 @@ include::modules/ossm-about-concepts-observability.adoc[leveloffset=+1] include::modules/ossm-about-concepts-cert-manager.adoc[leveloffset=+1] -include::modules/ossm-about-concepts-argo-rollouts.adoc[leveloffset=+1] \ No newline at end of file +include::modules/ossm-about-concepts-argo-rollouts.adoc[leveloffset=+1] + +[role="_additional-resources"] +[id="additional-resources_{context}"] +== Additional resources + +* link:https://istio.io/latest/docs/setup/upgrade/canary/#stable-revision-labels[Stable revision labels ({istio} documentation)] + +* link:https://kiali.io/[Kiali project] + +* link:https://grafana.com/oss/tempo/[Grafana Tempo] + +* link:https://docs.redhat.com/en/documentation/red_hat_openshift_distributed_tracing_platform/latest[{TempoName}] + +* link:https://opentelemetry.io/[OpenTelemetry project] + +* link:https://opentelemetry.io/docs/collector/[OpenTelemetry Collector] + +* link:https://docs.redhat.com/en/documentation/red_hat_build_of_opentelemetry/latest[{OTELName}] + +* link:https://docs.openshift.com/gitops/1.14/argo_rollouts/routing-traffic-by-using-argo-rollouts-for-openshift-service-mesh.html[Routing traffic by using Argo Rollouts for {SMProductName}] \ No newline at end of file diff --git a/about/ossm-about-openshift-service-mesh.adoc b/about/ossm-about-openshift-service-mesh.adoc index 42067cce5ff..920db4ded1e 100644 --- a/about/ossm-about-openshift-service-mesh.adoc +++ b/about/ossm-about-openshift-service-mesh.adoc @@ -8,9 +8,16 @@ toc::[] [role="_abstract"] -You can use {SMProductName} to manage the connectivity, security, and observability of microservices. Based on the link:https://istio.io/[{istio} project], {SMProduct} provides a centralized control point in your application. +You can use {SMProductName} to manage the connectivity, security, and observability of microservices. Based on the "{istio} project", {SMProduct} provides a centralized control point in your application. include::modules/ossm-service-mesh-overview.adoc[leveloffset=+1] include::modules/ossm-core-features.adoc[leveloffset=+1] +[role="_additional-resources"] +[id="additional-resources_{context}"] +== Additional resources + +* link:https://istio.io/[{istio} project] + + diff --git a/about/ossm-planning.adoc b/about/ossm-planning.adoc new file mode 100644 index 00000000000..61ad1d03c7a --- /dev/null +++ b/about/ossm-planning.adoc @@ -0,0 +1,39 @@ +:_mod-docs-content-type: ASSEMBLY +[id="ossm-planning"] += Planning your service mesh deployment +include::_attributes/common-attributes.adoc[] +:context: ossm-planning + +toc::[] + +[role="_abstract"] + +Plan your service mesh deployment by evaluating whether it fits your needs, choosing a data plane mode, and making decisions about security, traffic routing, observability, and upgrades. + +include::modules/ossm-decide-if-service-mesh-fits.adoc[leveloffset=+1] + +include::modules/ossm-choose-data-plane-mode.adoc[leveloffset=+1] + +include::modules/ossm-about-sidecar-proxies.adoc[leveloffset=+2] + +include::modules/ossm-mesh-security-planning.adoc[leveloffset=+1] + +include::modules/ossm-about-mtls-planning.adoc[leveloffset=+2] + +include::modules/ossm-cert-manager-planning.adoc[leveloffset=+2] + +include::modules/ossm-edge-traffic-planning.adoc[leveloffset=+1] + +include::modules/ossm-plan-mesh-observability.adoc[leveloffset=+1] + +include::modules/ossm-about-metrics-and-observability.adoc[leveloffset=+2] + +include::modules/ossm-kiali-planning.adoc[leveloffset=+2] + +include::modules/ossm-plan-upgrade-strategy.adoc[leveloffset=+1] + +include::modules/ossm-about-operator-updates-delivery.adoc[leveloffset=+2] + +include::modules/ossm-about-control-plane-update-strategies.adoc[leveloffset=+2] + +include::modules/ossm-about-upgrades-by-data-plane-mode.adoc[leveloffset=+2] diff --git a/gateways/ossm-about-gateways.adoc b/gateways/ossm-about-gateways.adoc index c3921952d45..18e2a372d8f 100644 --- a/gateways/ossm-about-gateways.adoc +++ b/gateways/ossm-about-gateways.adoc @@ -1,4 +1,4 @@ -:_content-type: ASSEMBLY +:_mod-docs-content-type: ASSEMBLY [id="ossm-about-gateways"] = About gateways include::_attributes/common-attributes.adoc[] @@ -7,10 +7,11 @@ include::_attributes/common-attributes.adoc[] toc::[] [role="_abstract"] -A gateway is a standalone Envoy proxy deployment and an associated Kubernetes service operating at the edge of a service mesh. You can configure a gateway to give fine-grained control over the traffic that enters or leaves the mesh. In {SMProductName}, you can install gateways by using gateway injection or via the Gateway API. -{SMProductName} supports different gateway configurations based on the deployment mode. You can deploy gateways by using gateway injection and configure them with {istio} Gateway and `VirtualService` resources in sidecar mode or with {k8s} Gateway API resources in both sidecar and ambient modes. +Manage ingress and egress traffic by using gateway injection or the {k8s} Gateway API to deploy Envoy proxies across sidecar and ambient architectures. + +include::modules/ossm-understanding-gateways.adoc[leveloffset=+1] include::modules/ossm-about-gateway-injection.adoc[leveloffset=+1] -include::modules/ossm-installing-gateway-using-gateway-injection.adoc[leveloffset=+2] +include::modules/ossm-installing-gateway-using-gateway-injection.adoc[leveloffset=+2] \ No newline at end of file diff --git a/gateways/ossm-configuring-quantum-secure-gateways.adoc b/gateways/ossm-configuring-quantum-secure-gateways.adoc index 2884412aa03..f424430db52 100644 --- a/gateways/ossm-configuring-quantum-secure-gateways.adoc +++ b/gateways/ossm-configuring-quantum-secure-gateways.adoc @@ -1,4 +1,4 @@ -:_content-type: ASSEMBLY +:_mod-docs-content-type: ASSEMBLY [id="ossm-configuring-quantum-secure-gateways"] = Configuring quantum secure gateways include::_attributes/common-attributes.adoc[] @@ -17,7 +17,7 @@ include::modules/ossm-deploying-quantum-secure-gateway.adoc[leveloffset=+1] include::modules/ossm-verifying-quantum-secure-gateway.adoc[leveloffset=+1] [role="_additional-resources"] -[id="additional-resources-configuring-quantum-secure-gateways"] +[id="additional-resources_{context}"] == Additional resources * xref:../install/ossm-pqc-install.adoc#ossm-pqc-install[Post-quantum cryptography] diff --git a/gateways/ossm-directing-outbound-traffic.adoc b/gateways/ossm-directing-outbound-traffic.adoc index 280f6573ba6..8e7584bbfe8 100644 --- a/gateways/ossm-directing-outbound-traffic.adoc +++ b/gateways/ossm-directing-outbound-traffic.adoc @@ -1,4 +1,4 @@ -:_content-type: ASSEMBLY +:_mod-docs-content-type: ASSEMBLY [id="ossm-directing-outbound-traffic-through-a-gateway"] = Directing outbound traffic through a gateway include::_attributes/common-attributes.adoc[] @@ -7,7 +7,8 @@ include::_attributes/common-attributes.adoc[] toc::[] [role="_abstract"] -Using {istio} APIs, you can configure gateway proxies that were installed using gateway injection to direct traffic that is bound for an external service. + +Using {istio} APIs, you configure gateway proxies, installed through gateway injection, to direct traffic bound for an external service. include::modules/ossm-about-directing-egress-traffic-through-a-gateway.adoc[leveloffset=+1] @@ -17,8 +18,9 @@ include::modules/ossm-directing-egress-traffic-through-a-gateway-using-kubernete include::modules/ossm-directing-egress-traffic-through-a-gateway-kubernetes-gateway-api-ambient-mode.adoc[leveloffset=+1] -[role="_additional-resources-egress"] -.Additional resources +[role="_additional-resources"] +[id="additional-resources_{context}"] +== Additional resources * link:https://istio.io/latest/docs/tasks/traffic-management/egress/egress-gateway/[Egress gateways (Istio documentation)] diff --git a/gateways/ossm-getting-traffic-into-a-mesh.adoc b/gateways/ossm-getting-traffic-into-a-mesh.adoc index 5beae55de5d..a66fe457ddb 100644 --- a/gateways/ossm-getting-traffic-into-a-mesh.adoc +++ b/gateways/ossm-getting-traffic-into-a-mesh.adoc @@ -1,47 +1,37 @@ -:_content-type: ASSEMBLY +:_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 toc::[] [role="_abstract"] -Using {istio} APIs, you can configure gateway proxies that were installed using gateway injection to accept traffic originating from outside the mesh, and route that traffic to the services within the mesh. -You can expose gateway proxies to traffic outside a cluster by using either a `LoadBalancer` type `Service` or {ocp-short-name} `Routes`. +Route external traffic to mesh services by configuring {istio} gateway proxies and exposing them through `LoadBalancer` services or {ocp-short-name} routes. include::modules/ossm-about-configuring-a-gateway-to-accept-ingress-traffic.adoc[leveloffset=+1] -[role="_additional-resources"] -.Additional resources - -* xref:../gateways/ossm-about-gateways.adoc#ossm-about-gateway-injection_ossm-about-gateways[About gateway injection] - include::modules/ossm-exposing-service-using-istio-gateway-and-virtualservice.adoc[leveloffset=+1] -[role="_additional-resources"] -.Additional resources - -* https://istio.io/latest/docs/reference/config/networking/gateway/#Gateway[Istio Gateway resource API reference (Istio documentation)] -* https://istio.io/latest/docs/reference/config/networking/virtual-service/#VirtualService[VirtualService API reference (Istio documentation)] - include::modules/ossm-about-exposing-services-to-traffic-outside-a-cluster.adoc[leveloffset=+1] include::modules/ossm-exposing-a-gateway-to-traffic-outside-the-cluster-using-openshift-routes.adoc[leveloffset=+2] -[role="_additional-resources"] -.Additional resources +include::modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api.adoc[leveloffset=+1] -* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/networking/configuring-routes#nw-creating-a-route_route-configuration[Creating an HTTP-based Route] +include::modules/ossm-about-ingress-routing-ambient-mode.adoc[leveloffset=+1] -include::modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api.adoc[leveloffset=+1] +include::modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api-in-ambient-mode.adoc[leveloffset=+1] [role="_additional-resources"] -.Additional resources +[id="additional-resources_{context}"] +== Additional resources -* link:https://kubernetes.io/docs/concepts/services-networking/gateway/[Kubernetes Gateway API concept (Kubernetes documentation)] +* link:https://istio.io/latest/docs/reference/config/networking/gateway/#Gateway[Istio Gateway resource API reference (Istio documentation)] -include::modules/ossm-about-ingress-routing-ambient-mode.adoc[leveloffset=+1] +* link:https://istio.io/latest/docs/reference/config/networking/virtual-service/#VirtualService[VirtualService API reference (Istio documentation)] + +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/networking/configuring-routes#nw-creating-a-route_route-configuration[Creating an HTTP-based Route] -include::modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api-in-ambient-mode.adoc[leveloffset=+1] \ No newline at end of file +* link:https://kubernetes.io/docs/concepts/services-networking/gateway/[Kubernetes Gateway API concept (Kubernetes documentation)] \ No newline at end of file diff --git a/install/ossm-SPIRE.adoc b/install/ossm-SPIRE.adoc new file mode 100644 index 00000000000..5812e87649e --- /dev/null +++ b/install/ossm-SPIRE.adoc @@ -0,0 +1,63 @@ +:_mod-docs-content-type: ASSEMBLY +[id="ossm-SPIRE_{context}"] += Secure workload identity with SPIRE +include::_attributes/common-attributes.adoc[] +:context: ossm-SPIRE + +toc::[] + +[role="_abstract"] + +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[] + +You can deploy SPIRE as a standalone solution or integrate it with cert-manager. When used together, cert-manager acts as the root Certificate Authority (CA), automatically issuing intermediate signing certificates to SPIRE, while SPIRE handles workload identity for mesh communication. + +[id="about-spire-and-spiffe_{context}"] +== About SPIRE and SPIFFE + +SPIRE implements the Secure Production Identity Framework for Everyone (SPIFFE) open standards. It issues short-lived cryptographic credentials, called SPIFFE Verifiable Identity Documents (SVIDs), to workloads and service mesh components. The architecture uses a central server and node agents to integrate with the {SMProduct} data plane through a local UNIX domain socket API. + +Before issuing an SVID, SPIRE enforces rigorous verification. Node attestation verifies the underlying host platform, while workload attestation inspects runtime attributes such as pod namespaces and service accounts. This process ensures cryptographically verified identities and strong workload authentication before any communication across the mesh begins. + +[id="benefits-of-spire_{context}"] +== Benefits of SPIRE + +SPIRE provides the following key benefits: + +* Zero-trust architecture: Every workload interaction requires cryptographic verification based on attested identity, with no implicit trust zones. + +* Cross-platform authentication: Uses SPIFFE identities for workload authentication across clouds, virtual machines, and bare-metal environments. + +* Network-independent security: Authentication does not depend on network boundaries, IP addresses, or firewall rules. + +* Automatic credential management: Automatically issues and rotates credentials for workloads, eliminating embedded passwords, API keys, and certificates. + +[IMPORTANT] +==== +Currently, only single-cluster sidecar deployments of {SMProduct} integrate with SPIRE. +==== + +include::modules/ossm-SPIRE-install-ZTWIM.adoc[leveloffset=+1] + +include::modules/ossm-SPIRE-istio-integrate.adoc[leveloffset=+1] + +include::modules/ossm-SPIREex-traffic-in-mesh.adoc[leveloffset=+1] + +include::modules/ossm-SPIREex-traffic-entering-mesh.adoc[leveloffset=+1] + + +[role="_additional-resources"] +[id="additional-resources_{context}"] +== Additional resources + +* link:https://developers.redhat.com/blog/2026/04/23/sky-computing-openshift-service-mesh-and-spire-foundations[Sky computing with {SMProduct} and SPIRE] + +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/security_and_compliance/zero-trust-workload-identity-manager[Zero Trust Workload Identity Manager] + +* link:https://www.redhat.com/en/topics/security/spiffe-and-spire[What are SPIFFE and SPIRE?] + +* link:https://spiffe.io/docs/latest/spiffe-about/spiffe-concepts/[SPIFFE Concepts] + +* link:https://istio.io/latest/docs/ops/integrations/spire/[SPIRE] \ No newline at end of file diff --git a/install/ossm-ambient-sidecar-coexistence.adoc b/install/ossm-ambient-sidecar-coexistence.adoc new file mode 100644 index 00000000000..779c003773c --- /dev/null +++ b/install/ossm-ambient-sidecar-coexistence.adoc @@ -0,0 +1,31 @@ +:_mod-docs-content-type: ASSEMBLY +[id="ossm-ambient-sidecar-coexistence"] += Coexistence of ambient and sidecar modes + +include::_attributes/common-attributes.adoc[] +:context: ossm-ambient-sidecar-coexistence + +toc::[] + +[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. + +include::modules/ossm-about-ambient-sidecar-coexistence.adoc[leveloffset=+1] + +include::modules/ossm-enable-ambient-on-existing-sidecar-mesh.adoc[leveloffset=+1] + +include::modules/ossm-enable-sidecar-on-existing-ambient-mesh.adoc[leveloffset=+1] + +[role="_additional-resources"] +[id="additional-resources-ossm-ambient-sidecar-coexistence_{context}"] +== Additional resources + +* xref:ossm-sidecar-injection.adoc#ossm-enabling-sidecar-injection-namespace-labels_ossm-sidecar-injection[Enabling sidecar injection with namespace labels] + +* xref:ossm-istio-ambient-mode.adoc#ossm-istio-ambient-mode[Istio ambient mode] + +* xref:ossm-sidecar-injection.adoc#ossm-sidecar-injection[Sidecar injection] + +* link:https://istio.io/latest/docs/ambient/usage/add-workloads/[Adding workloads to a mesh in ambient mode (Istio documentation)] + +* link:https://istio.io/latest/docs/reference/commands/pilot-discovery/#enable-ingress-waypoint-routing[ENABLE_INGRESS_WAYPOINT_ROUTING (Istio documentation)] diff --git a/install/ossm-cert-manager.adoc b/install/ossm-cert-manager.adoc index aa31d152896..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] @@ -16,12 +16,6 @@ include::modules/ossm-installing-cert-manager.adoc[leveloffset=+2] include::modules/ossm-verifying-cert-manager.adoc[leveloffset=+2] -include::modules/ossm-uninstalling-cert-manager.adoc[leveloffset=+2] - +include::modules/ossm-verifying-cert-manager-ambient.adoc[leveloffset=+2] -[role="_additional-resources"] -[id="additional-resources-ossm-cert-manager_{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 +include::modules/ossm-uninstalling-cert-manager.adoc[leveloffset=+2] diff --git a/install/ossm-deploying-multiple-service-meshes-on-single-cluster.adoc b/install/ossm-deploying-multiple-service-meshes-on-single-cluster.adoc index b24f5875df8..895cfbf54ff 100644 --- a/install/ossm-deploying-multiple-service-meshes-on-single-cluster.adoc +++ b/install/ossm-deploying-multiple-service-meshes-on-single-cluster.adoc @@ -23,7 +23,7 @@ include::modules/ossm-verifying-multiple-control-planes.adoc[leveloffset=+2] include::modules/ossm-deploy-application-workloads-in-each-mesh.adoc[leveloffset=+1] [role="_additional-resources"] -[id="additional-resources-ossm-deploying-multiple-service-meshes-on-single-cluster_{context}"] +[id="additional-resources_{context}"] == Additional resources -* xref:../install/ossm-installing-openshift-service-mesh.adoc#ossm-scoping-service-mesh-with-discoveryselectors_ossm-installing-openshift-service-mesh[Scoping Service Mesh with discoverySelectors] \ No newline at end of file +* xref:../install/ossm-installing-openshift-service-mesh.adoc#ossm-scoping-service-mesh-with-discoveryselectors_ossm-installing-openshift-service-mesh[Scoping the mesh with discovery selectors] diff --git a/install/ossm-enabling-mtls.adoc b/install/ossm-enabling-mtls.adoc index 17c6544e70a..6ac76ae9fbd 100644 --- a/install/ossm-enabling-mtls.adoc +++ b/install/ossm-enabling-mtls.adoc @@ -1,15 +1,14 @@ :_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 - 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] @@ -20,7 +19,7 @@ include::modules/ossm-enabling-strict-mtls-whole-service-mesh.adoc[leveloffset=+ include::modules/ossm-validating-encryptions-with-kiali.adoc[leveloffset=+1] [role="_additional-resources"] -[id="additional-resources-enabling-mtls"] +[id="additional-resources_{context}"] == Additional resources * link:https://istio.io/latest/docs/tasks/security/tls-configuration/workload-min-tls-version/[Istio workload minimum TLS version configuration (Istio documentation)] diff --git a/install/ossm-installing-openshift-service-mesh.adoc b/install/ossm-installing-openshift-service-mesh.adoc index d887efeb25e..3e9e3a61679 100644 --- a/install/ossm-installing-openshift-service-mesh.adoc +++ b/install/ossm-installing-openshift-service-mesh.adoc @@ -4,16 +4,17 @@ include::_attributes/common-attributes.adoc[] :context: ossm-installing-openshift-service-mesh +include::_attributes/attributes-microshift.adoc[] +:context: ossm-installing-openshift-service-mesh + +include::_attributes/attributes-openshift-dedicated.adoc[] +:context: ossm-installing-openshift-service-mesh + toc::[] [role="_abstract"] -Installing {ocp-short-name} {SMProductShortName} consists of three main tasks: installing the {ocp-short-name} Operator, deploying {istio}, and customizing the {istio} configuration. Then, you can also choose to install the sample `bookinfo` application to push data through the mesh and explore mesh functionality. - -[WARNING] -==== -Before installing {SMProduct} 3, make sure you are not running {SMProduct} 3 and {SMProduct} 2 in the same cluster, because it causes conflicts unless configured correctly. To migrate from {SMProduct} 2, see xref:../migrating/checklists/ossm-migrating-read-me.adoc#ossm-migrating-read-me[Migrating from {SMProduct} 2.6]. -==== +Installing {ocp-short-name} {SMProductShortName} consists of three main tasks: installing the {ocp-short-name} Operator, deploying {istio}, and customizing the {istio} configuration. Then, you can also install the sample `bookinfo` application to push data through the mesh and explore mesh functionality. include::modules/ossm-about-deploying-istio-using-service-mesh-operator.adoc[leveloffset=+1] @@ -60,11 +61,23 @@ include::modules/ossm-api-settings-mesh-ha-autoscaling.adoc[leveloffset=+3] include::modules/ossm-configuring-istio-ha-replicacount.adoc[leveloffset=+2] [role="_additional-resources"] -[id="additional-resources-ossm-installing-service-mesh_{context}"] +[id="additional-resources_{context}"] == Additional resources +* link:https://istio.io/latest/docs/examples/bookinfo/[Bookinfo Application (Istio documentation)] + * xref:../install/ossm-deploying-multiple-service-meshes-on-single-cluster.adoc#ossm-deploying-multiple-service-meshes-on-single-cluster[Deploying multiple service meshes on a single cluster] * link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/networking/configuring-ingress-cluster-traffic[Configuring ingress cluster traffic] -* link:https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/[Horizontal Pod Autoscaling (Kubernetes documentation)] \ No newline at end of file +* link:https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/[Horizontal Pod Autoscaling (Kubernetes documentation)] + +* link:https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors[Label selectors (Kubernetes documentation)] + +* link:https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#resources-that-support-set-based-requirements[Resources that support set-based requirements (Kubernetes documentation)] + +* link:https://artifacthub.io/packages/search?org=istio&sort=relevance&page=1[Istio's artifacthub chart documentation] + +* link:https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/#configurable-scaling-behavior[Configurable Scaling Behavior] + +* link:https://docs.redhat.com/en/documentation/red_hat_openshift_service_mesh/3.0/html/migrating_from_service_mesh_2_to_service_mesh_3/ossm-migrating-from-service-mesh-2-to-3[Migrating from {SMProduct} 2.6] \ No newline at end of file diff --git a/install/ossm-istio-ambient-mode.adoc b/install/ossm-istio-ambient-mode.adoc index 8bf24331b96..dc71b014a55 100644 --- a/install/ossm-istio-ambient-mode.adoc +++ b/install/ossm-istio-ambient-mode.adoc @@ -4,6 +4,12 @@ include::_attributes/common-attributes.adoc[] :context: ossm-istio-ambient-mode +include::_attributes/attributes-microshift.adoc[] +:context: ossm-istio-ambient-mode + +include::_attributes/attributes-openshift-dedicated.adoc[] +:context: ossm-istio-ambient-mode + toc::[] [role="_abstract"] @@ -35,10 +41,10 @@ include::modules/ossm-routing-traffic-using-waypoint-proxies.adoc[leveloffset=+1 include::modules/ossm-adding-authorization-policy.adoc[leveloffset=+1] [role="_additional-resources"] -[id="additional-resources-ossm-istio-ambient-mode_{context}"] +[id="additional-resources_{context}"] == Additional resources -* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/ovn-kubernetes_network_plugin/configuring-gateway-mode[Configuring gateway mode] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/ovn-kubernetes_network_plugin/configuring-gateway[Configuring gateway mode] * xref:../install/ossm-installing-openshift-service-mesh.adoc#ossm-scoping-service-mesh-with-discoveryselectors_ossm-installing-openshift-service-mesh[Scoping the mesh with discovery selectors] diff --git a/install/ossm-multi-cluster-topologies.adoc b/install/ossm-multi-cluster-topologies.adoc index 602ea8c1002..be9a42f86ad 100644 --- a/install/ossm-multi-cluster-topologies.adoc +++ b/install/ossm-multi-cluster-topologies.adoc @@ -22,14 +22,18 @@ include::modules/ossm-installing-multi-primary-multi-network-mesh.adoc[leveloffs include::modules/ossm-verifying-multi-cluster-topology.adoc[leveloffset=+2] -include::modules/ossm-removing-multi-cluster-installation-from-development-environment.adoc[leveloffset=+2] +include::modules/ossm-installing-multi-primary-multi-network-mesh-ambient.adoc[leveloffset=+1] + +include::modules/ossm-verifying-multi-cluster-topology-ambient.adoc[leveloffset=+2] + +include::modules/ossm-removing-multi-cluster-installation-from-development-environment.adoc[leveloffset=+1] include::modules/ossm-installing-primary-remote-multi-network-mesh.adoc[leveloffset=+1] include::modules/ossm-installing-kiali-multi-cluster-mesh.adoc[leveloffset=+1] [role="_additional-resources"] -[id="ossm-kiali-multi-cluster-additional-resource_{context}"] +[id="additional-resources_{context}"] == Additional resources * xref:../observability/kiali/ossm-kiali.adoc#ossm-kiali[Using Kiali Operator provided by Red Hat] diff --git a/install/ossm-pqc-install.adoc b/install/ossm-pqc-install.adoc index 08884e0e587..2768b971cbf 100644 --- a/install/ossm-pqc-install.adoc +++ b/install/ossm-pqc-install.adoc @@ -19,7 +19,7 @@ include::modules/ossm-configuring-sm-pqc-mesh-wide.adoc[leveloffset=+1] include::modules/ossm-configuring-sm-pqc-ambient.adoc[leveloffset=+1] [role="_additional-resources"] -[id="additional-resources-ossm-pqc-install"] +[id="additional-resources_{context}"] == Additional resources * xref:../gateways/ossm-configuring-quantum-secure-gateways.adoc#ossm-configuring-quantum-secure-gateways[Configuring quantum secure gateways] diff --git a/install/ossm-running-v2-same-cluster-as-v3-assembly.adoc b/install/ossm-running-v2-same-cluster-as-v3-assembly.adoc index e1c41ef08bc..9f43e68d6a2 100644 --- a/install/ossm-running-v2-same-cluster-as-v3-assembly.adoc +++ b/install/ossm-running-v2-same-cluster-as-v3-assembly.adoc @@ -15,7 +15,7 @@ include::modules/ossm-running-v2-v3-multitenant-deployment-model.adoc[leveloffse include::modules/ossm-running-v2-v3-cluster-wide-deployment-model.adoc[leveloffset=+1] [role="_additional-resources"] -[id="additional-resources-running-v2-same-cluster-as-v3"] +[id="additional-resources_{context}"] == Additional resources * xref:../install/ossm-installing-openshift-service-mesh.adoc#ossm-installing-operator_ossm-about-deployment-and-update-strategies[Installing {SMProduct} Operator] diff --git a/install/ossm-sidecar-injection.adoc b/install/ossm-sidecar-injection.adoc index 00fef49204b..c5ab592a5e1 100644 --- a/install/ossm-sidecar-injection.adoc +++ b/install/ossm-sidecar-injection.adoc @@ -8,7 +8,7 @@ toc::[] [role="_abstract"] -Sidecar proxies are deployed into each application pod to intercept network traffic and enable service mesh features like security, observability, and traffic management. +Enable security, observability, and traffic management by deploying sidecar proxies to intercept network traffic within each application pod in the mesh. include::modules/ossm-about-sidecar-injection.adoc[leveloffset=+1] @@ -16,11 +16,16 @@ include::modules/ossm-identifying-revision-name.adoc[leveloffset=+1] include::modules/ossm-enabling-sidecar-injection.adoc[leveloffset=+1] -include::modules/ossm-enabling-sidecar-injection-istio-revision-tag-resource.adoc[leveloffset=+1] +include::modules/ossm-enabling-sidecar-injection-namespace-labels.adoc[leveloffset=+2] + +include::modules/ossm-enabling-sidecar-injection-exclude-workload-from-mesh.adoc[leveloffset=+2] +include::modules/ossm-enabling-sidecar-injection-pod-labels.adoc[leveloffset=+2] + +include::modules/ossm-enabling-sidecar-injection-istio-revision-tag-resource.adoc[leveloffset=+1] [role="_additional-resources"] -[id="additional-resources-sidecar-injection"] +[id="additional-resources_{context}"] == Additional resources * link:https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/[About admission controllers (Kubernetes documentation)] diff --git a/install/ossm-supported-platforms-configurations.adoc b/install/ossm-supported-platforms-configurations.adoc index c448d74dcbb..13e8c34b2fd 100644 --- a/install/ossm-supported-platforms-configurations.adoc +++ b/install/ossm-supported-platforms-configurations.adoc @@ -1,6 +1,6 @@ :_mod-docs-content-type: ASSEMBLY [id="ossm-supported-platforms-configurations"] -= Supported platforms and configurations += Check platform prerequisites include::_attributes/common-attributes.adoc[] :context: ossm-supported-platforms-configurations @@ -8,7 +8,19 @@ toc::[] [role="_abstract"] -Before you can install {SMProductName} {SMProductVersion}, you must subscribe to {ocp-product-title} and install {ocp-product-title} in a supported configuration. If you do not have a subscription on your Red Hat account, contact your sales representative for more information. +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] @@ -24,16 +36,24 @@ include::modules/ossm-supported-configurations-kiali.adoc[leveloffset=+1] * link:https://access.redhat.com/support/policy/updates/openshift_operators[OpenShift Operator Life Cycles] -* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/installation_overview/ocp-installation-overview#installation-overview_ocp-installation-overview[About OpenShift Container Platform installation] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/installation_overview/ocp-installation-overview#installation-overview_ocp-installation-overview[About {product-title} installation] + +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/installing_on_aws/installing-methods-aws[Installing {product-title} on AWS] + +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/installing_on_aws/user-provisioned-infrastructure[Installing {product-title} on AWS with user-provisioned infrastructure] + +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/installing_on_bare_metal/preparing-to-install-on-bare-metal[Installing {product-title} on bare metal] + +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/installing_on_vmware_vsphere/preparing-to-install-on-vsphere[Installing {product-title} on vSphere] -* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/installing_on_aws/preparing-to-install-on-aws#preparing-to-install-on-aws[Installing OpenShift Container Platform on AWS] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/installing_on_ibm_z_and_ibm_linuxone/preparing-to-install-on-ibm-z[Installing {product-title} on {ibm-z-title}® and IBM® LinuxONE] -* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/installing_on_aws/user-provisioned-infrastructure[Installing OpenShift Container Platform on AWS with user-provisioned infrastructure] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/installing_on_ibm_power/preparing-to-install-on-ibm-power[Installing {product-title} on {ibm-power-title}®] -* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/installing_on_bare_metal/preparing-to-install-on-bare-metal[Installing OpenShift Container Platform on bare metal] +* link:https://docs.redhat.com/en/documentation/openshift_dedicated/latest/html/networking/ovn-kubernetes-network-plugin#about-ovn-kubernetes[About the OVN-Kubernetes network plugin] -* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/installing_on_vmware_vsphere/preparing-to-install-on-vsphere[Installing OpenShift Container Platform on vSphere] +* link:https://access.redhat.com/articles/5436171[Certified OpenShift CNI plugins] -* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/installing_on_ibm_z_and_ibm_linuxone/preparing-to-install-on-ibm-z[Installing OpenShift Container Platform on IBM Z® and IBM® LinuxONE] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/installation_overview/installing-preparing#supported-installation-methods-for-different-platforms[Restricted network] -* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/installing_on_ibm_power/preparing-to-install-on-ibm-power[Installing OpenShift Container Platform on IBM Power®] \ No newline at end of file +* link:https://access.redhat.com/support/policy/updates/openshift_operators[Support Policy] \ No newline at end of file diff --git a/migrating/checklists/ossm-migrating-kiali-differences.adoc b/migrating/checklists/ossm-migrating-kiali-differences.adoc index 6cd25c73a21..ef851338a30 100644 --- a/migrating/checklists/ossm-migrating-kiali-differences.adoc +++ b/migrating/checklists/ossm-migrating-kiali-differences.adoc @@ -1,7 +1,3 @@ -// This module is used in the following assemblies: - -// * migrating/checklists/ossm-kiali-differences-assembly.adoc - :_mod-docs-content-type: ASSEMBLY [id="ossm-migrating-kiali-differences"] = Kiali differences for {SMProductName} 3 @@ -10,52 +6,8 @@ include::_attributes/common-attributes.adoc[] toc::[] -{kialiproduct} with {SMProductName} 3 introduces the following changes: - -* New topology graphs -* Deprecated configuration settings -* Renamed configuration settings - -[id="new-topology-graphs_{context}"] -== New topology graphs - -The **Traffic Page Graph** page has been reorganized and built using Patternfly topology with a new topology view showcasing the mesh infrastructure. - -[id="deprecated-config-settings_{context}"] -== Deprecated configuration settings - -To control which namespaces are accessible or visible to users in {smproduct} 3, Kiali relies on `discoverySelectors`. - -By default, `deployment.cluster_wide_access=true` is enabled, granting Kiali cluster-wide access to all namespaces in the local cluster. If you are migrating a cluster-wide deployment with Kiali, you must remove the following deprecated and unavailable configuration settings from your Kiali custom resource (CR): - -* `spec.deployment.accessible_namespaces` -* `api.namespaces.exclude` -* `api.namespaces.include` -* `api.namespaces.label_selector_exclude` -* `api.namespaces.label_selector_include` - -If you are are using discovery selectors in Istio to restrict the namespaces that `Istiod` watches, then those must match the discovery selectors in your Kiali CR. - -[id="renamed-config-settings_{context}"] -== Renamed configuration settings - -The following configuration settings have been renamed: - -[cols="1,1"] -|=== -|Old configuration |New configuration - -|`external_service.grafana.in_cluster_url` -|`external_service.grafana.internal_url` - -|`external_service.grafana.url` -|`external_service.grafana.external_url` - -|`external_service.tracing.in_cluster_url` -|`external_service.tracing.internal_url` +[role="_abstract"] -|`external_service.tracing.url` -|`external_service.tracing.external_url` -|=== +Review the architectural and configuration changes in Kiali for {SMProductName} 3, including updated topology graphs, deprecated namespace settings, and renamed service URLs. -These changes reflect evolving capabilities and configuration standards of Kiali within {SMProduct} 3. +include::modules/ossm-migrating-about-kiali-differences.adoc[leveloffset=+1] \ No newline at end of file diff --git a/migrating/checklists/ossm-migrating-network-policies.adoc b/migrating/checklists/ossm-migrating-network-policies.adoc index f8abfb537ef..da6b9526961 100644 --- a/migrating/checklists/ossm-migrating-network-policies.adoc +++ b/migrating/checklists/ossm-migrating-network-policies.adoc @@ -6,16 +6,8 @@ include::_attributes/common-attributes.adoc[] toc::[] -In {SMProductName} 2, network policies are created by default when the `spec.security.manageNetworkPolicy` field is set to `true` in the `ServiceMeshControlPlane` resource. During the migration to {SMProduct} 3, these policies are removed. +[role="_abstract"] -It is recommended to re-create your network policies after you have migrated your deployment and workloads. However, if your security policies require you to keep your network policies, you must re-create them first, and then set the `spec.security.manageNetworkPolicy` field to `false` as outlined in the migration checklists. +{SMProduct} 3 changes how network security is managed by removing the automatic generation of network policies previously controlled by the `spec.security.manageNetworkPolicy` field in {SMProductName} 2. -include::modules/ossm-migrating-network-policies-setup-during-migration.adoc[leveloffset=+1] - -.Next steps -* In {SMProduct} 2, set the `spec.security.manageNetworkPolicy` field to `false` in your `ServiceMeshControlPlane` resource, and continue with the migration checklists. - -//exrefs handled by OSSM-8852 - - -//Note to self: migrating-done-network-policies is file name in dir for migrating network policies after completely deployment and workloads migration. +include::modules/ossm-migrating-network-policies-setup-during-migration.adoc[leveloffset=+1] \ No newline at end of file diff --git a/migrating/checklists/ossm-migrating-premigration-checklists.adoc b/migrating/checklists/ossm-migrating-premigration-checklists.adoc index 0b77dd070fc..65caf7bc013 100644 --- a/migrating/checklists/ossm-migrating-premigration-checklists.adoc +++ b/migrating/checklists/ossm-migrating-premigration-checklists.adoc @@ -8,145 +8,56 @@ toc::[] [role="_abstract"] -.Before you begin +Complete these premigration checklists to prepare your {SMProduct} 2 environment for an upgrade by disabling traditional add-ons, migrating gateway configurations, and validating resource compatibility for {SMProduct} 3. -* You have read "Migrating from Service Mesh 2 to Service Mesh 3". -* You have read and understand the xref:../../migrating/checklists/ossm-migrating-read-me.adoc#ossm-2-and-3-differences_ossm-migrating-read-me[differences between OpenShift Service Mesh 2 and OpenShift Service Mesh 3]. -* You have reviewed the xref:../../migrating/reference/ossm-migrating-references.adoc[Migrating references] material. -* You want to migrate from {SMProduct} 2 to {SMProduct} 3. -* You are running {SMProduct} {SMv2Version}. -* You have upgraded your `ServiceMeshControlPlane` resource to the latest version. -* If you are using the {KialiProduct}, you are running the latest version. -* You have installed the {SMProduct} Operator 3. To install the {SMProduct} 3 Operator, see: xref:../../install/ossm-installing-openshift-service-mesh.adoc[Installing OpenShift Service Mesh] +include::modules/ossm-migrating-premigration-before-you-begin.adoc[leveloffset=+1] -[IMPORTANT] -==== -You must complete the following checklists before you can begin migrating your deployment and workloads. -==== +include::modules/ossm-migrating-disable-add-ons-and-reconfigure-replacements.adoc[leveloffset=+1] -[id="disable-add-ons-and-reconfigure-replacements_{context}"] -== Disable add-ons and reconfigure replacements +include::modules/ossm-migrating-to-explicitly-managed-routes.adoc[leveloffset=+1] -* [ ] Disable Prometheus in your `ServiceMeshControlPlane` resource: `spec.addons.prometheus.enabled=false` -** [ ] Configure the `ServiceMeshControlPlane` with OpenShift Monitoring as the replacement. These instructions also include installing a standalone `Kiali` resource. Both can be done at the same time. link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/service_mesh/service-mesh-2-x#ossm-integrating-with-user-workload-monitoring_observability[Integration user-workload monitoring] -** [ ] If you are not using OpenShift monitoring, see: link:https://docs.redhat.com/en/documentation/red_hat_openshift_service_on_aws/4/html/service_mesh/service-mesh-2-x#integration-with-external-prometheus-installation[Integration with external Prometheus installation]. +include::modules/ossm-migrating-to-gateway-injection.adoc[leveloffset=+1] -* [ ] Disable tracing in your `ServiceMeshControlPlane` resource: `spec.tracing.type=None` -** [ ] Configure the `ServiceMeshControlPlane` with OpenShift Distributed Tracing as the replacement: link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/service_mesh/service-mesh-2-x#ossm-configuring-distr-tracing-tempo_observability[Configuring {TempoName} and the Red{nbsp}Hat build of OpenTelemetry]. +include::modules/ossm-migrating-disable-network-policy-management.adoc[leveloffset=+1] -* [ ] Disable Kiali in your `ServiceMeshControlPlane` resource: `spec.addons.kiali.enabled=false` -** [ ] If you did not create a standalone `Kiali` resource as part of Prometheus or tracing, see: "Using {KialiProduct}". +include::modules/ossm-migrating-disable-grafana-in-service-mesh-2.adoc[leveloffset=+1] -[WARNING] -==== -{SMProductName} 3 fails to install if outdated `ServiceEntry` custom resources are present in the cluster. The upstream {istio} version 1.24 introduced schema changes that cause installation failures for `ServiceEntry` resources that miss port numbers or exceed 256 hostnames. You can check for affected resources by running the following commands: - -* For `ServiceEntry` with hostnames over 256, run the following command: -+ -[source,terminal] ----- -$ oc get serviceentries -A -o json | jq -r '.items[] | select(.spec.hosts | length > 256) | "\(.metadata.namespace)/\(.metadata.name): \(.spec.hosts | length) hosts"' ----- - -* For `ServiceEntry` with missing port numbers, run the following command: -+ -[source,terminal] ----- -$ oc get serviceentries -A -o json | jq -r '.items[] | select(.spec.ports == null or (.spec.ports | length == 0)) | "\(.metadata.namespace)/\(.metadata.name)"' ----- - -To ensure a seamless migration to {SMProductName} 3, perform the following corrective actions before installing the OSSM 3 operator: - -* Split `ServiceEntry` resources: You must split any `ServiceEntry` containing more than 256 hosts into multiple smaller resources. -* Validate port configurations: You must ensure that all the `ServiceEntry` definitions include the required port specifications. -==== - -[id="migrate-to-explicitly-managed-routes_{context}"] -== Migrate to explicitly managed routes - -Automatic route creation, also known as Istio OpenShift Routing (IOR), is a deprecated feature that is disabled by default for any `ServiceMeshControlPlane` resource created using {SMProduct} 2.5 and later. To move from {SMProduct} 2 to {SMProduct} 3, you need to migrate from IOR to explicitly-managed routes. - -If you already moved to explicitly-managed routes in {SMProduct} 2, then continue to gateway injection. - -* [ ] Migrate from Istio OpenShift Routing (IOR) to to explicitly-managed routes: link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/service_mesh/service-mesh-2-x#ossm-route-migration[Service Mesh route migration]. - -[id="migrate-to-gateway-injection_{context}"] -== Migrate to gateway injection - -Gateways were controlled by the `ServiceMeshControlPlane` (SMCP) resource in {SMProduct} 2. The {SMProduct} 3 control plane does not manage gateways so you must migrate from SMCP-Defined gateways to gateway injection. - -* [ ] link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/service_mesh/service-mesh-2-x#ossm-gateway-migration[Service Mesh gateway migration]. - -[id="disable-network-policy-management_{context}"] -== Disable network policy management +include::modules/ossm-migrating-premigration-checklists-resource-files.adoc[leveloffset=+1] -If you do not want your network policies in place during your migration: +include::modules/ossm-migrating-find-your-deployment-model.adoc[leveloffset=+1] -* [ ] Disable network policy management in the {SMProduct} 2 `ServiceMeshControlPlane` resource: `spec.security.manageNetworkPolicy=false`. -* [ ] Complete the rest of the checklists. -* [ ] Migrate your deployment and workloads. -* [ ] Manually recreate your network policies after you have migrated your workloads. +include::modules/ossm-migrating-based-on-your-deployment-model.adoc[leveloffset=+1] -If you want your network policies in place during your migration: +include::modules/ossm-migrating-premigration-checklists-using-the-cert-manager-tool-with-your-deployment.adoc[leveloffset=+1] -* [ ] Manually xref:../../migrating/checklists/ossm-migrating-network-policies.adoc#ossm-migrating-network-policies-setup-during-migration_ossm-migrating-network-policies[set up network policies to use during migration]. -* [ ] Disable network policy management in the {SMProduct} 2 `ServiceMeshControlPlane` resource: `spec.security.manageNetworkPolicy=false`. -* [ ] Complete the rest of the checklists. -* [ ] Migrate your deployment and workloads. +[role="_additional-resources"] +[id="additional-resources_{context}"] +== Additional resources -[id="disable-grafana-in-service-mesh-2_{context}"] -== Disable Grafana in {SMProduct} 2 +* xref:../../migrating/checklists/ossm-migrating-read-me.adoc#ossm-2-and-3-differences_ossm-migrating-read-me[Differences between OpenShift Service Mesh 2 and OpenShift Service Mesh 3] -Grafana is not supported in {SMProduct} 3, and must be disabled in your {SMProduct} 2 `ServiceMeshControlPlane`. +* xref:../../migrating/reference/ossm-migrating-references.adoc#migrating-references[Migrating references] - * [ ] Disable Grafana in your {SMProduct} 2 `ServiceMeshControlPlane`: `spec.addons.grafana.enabled=false`. +* xref:../../install/ossm-installing-openshift-service-mesh.adoc#ossm-installing-openshift-service-mesh[Installing OpenShift Service Mesh] -include::modules/ossm-migrating-premigration-checklists-resource-files.adoc[leveloffset=+1] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/service_mesh/service-mesh-2-x#ossm-integrating-with-user-workload-monitoring_observability[Integration with user-workload monitoring] -[id="find-your-deployment-model_{context}"] -== Find your deployment model +* link:https://docs.redhat.com/en/documentation/red_hat_openshift_service_on_aws/4/html/service_mesh/service-mesh-2-x#integration-with-external-prometheus-installation[Integration with external Prometheus installation] -Run the following command to find your deployment model: +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/service_mesh/service-mesh-2-x#ossm-configuring-distr-tracing-tempo_observability[Configuring {TempoName} and the Red{nbsp}Hat build of OpenTelemetry] -[source,terminal] ----- -oc get smcp -n -o jsonpath='{.spec.mode}' ----- +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/service_mesh/service-mesh-2-x#ossm-route-migration[Service Mesh route migration] -[NOTE] -==== -If you did not set a value for the `.spec.mode` parameter in your `ServiceMeshControlPlane` resource, your deployment is multitenant. -==== +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/service_mesh/service-mesh-2-x#ossm-gateway-migration[Service Mesh gateway migration] -[id="migrate-based-on-your-deployment-model_{context}"] -== Migrate based on your deployment model +* xref:../../migrating/checklists/ossm-migrating-network-policies.adoc#ossm-migrating-network-policies-setup-during-migration_ossm-migrating-network-policies[Migrating network policies from Service Mesh 2 to Service Mesh 3] -If you are not using the cert-manager tool with your deployment, you are ready to migrate your deployment. +* xref:../../observability/kiali/ossm-kiali.adoc#ossm-kiali[Using {kialiproduct}] * xref:../../migrating/multitenant/ossm-migrating-multitenant.adoc#ossm-migrating-multitenant[Multitenant migration guide] -* xref:../../migrating/cluster-wide/ossm-migrating-cluster-wide.adoc#ossm-migrating-cluster-wide[Cluster-wide migration guide] - -If you are unsure, you can check if you are using the cert-manager tool with your deployment. - -include::modules/ossm-migrating-premigration-checklists-using-the-cert-manager-tool-with-your-deployment.adoc[leveloffset=+1] - -.Next steps for migrating with the cert-manager tool -There are some configurations you must complete first before you can start migrating your deployments. +* xref:../../migrating/cluster-wide/ossm-migrating-cluster-wide.adoc#ossm-migrating-cluster-wide[Cluster-wide migration guide] * xref:../../migrating/multitenant/ossm-migrating-multitenant.adoc#migrating-multitenant-with-cert-manager_ossm-migrating-multitenant[Migrating a multitenant deployment with the cert-manager tool] -* xref:../../migrating/cluster-wide/ossm-migrating-cluster-wide.adoc#ossm-cluster-wide-migration-methods_ossm-migrating-cluster-wide[Cluster-wide migration methods] -//Per engineering, uncomment Final check after GA -//move to module when uncommenting -//== Final check before migrating your deployment and workloads - -//Once you have configured your `ServiceMeshControlPlane` according to the checklists, you can run the following script to detect any issues with your environment: - -//* [ ] Run the [migration-checker script](migration-checker.sh) to detect any issues with your environment. - -[role="_additional-resources"] -[id="additional-resources-checklists_{context}"] -== Additional resources - -* xref:../../observability/kiali/ossm-kiali.adoc#ossm-kiali[Using {kialiproduct}] +* xref:../../migrating/cluster-wide/ossm-migrating-cluster-wide.adoc#ossm-cluster-wide-migration-methods_ossm-migrating-cluster-wide[Cluster-wide migration methods] diff --git a/migrating/checklists/ossm-migrating-read-me.adoc b/migrating/checklists/ossm-migrating-read-me.adoc index cf5b59d3ff1..82384004b9f 100644 --- a/migrating/checklists/ossm-migrating-read-me.adoc +++ b/migrating/checklists/ossm-migrating-read-me.adoc @@ -6,55 +6,67 @@ include::_attributes/common-attributes.adoc[] toc::[] -If you are moving from {SMProductName} 2.6 to {SMProductName} 3, read the content in this section first as it contains important information and explanations on the differences between the versions. These differences have a direct impact on your installation and configuration of {SMProduct} 3. +[role="_abstract"] + +Identify the architectural and functional differences between {SMProductName} 2.6 and {SMProductName} 3 to prepare for the specific installation and configuration changes required for a successful migration. include::modules/ossm-migrating-2-and-3-differences.adoc[leveloffset=+1] + include::modules/ossm-migrating-read-me-new-operator.adoc[leveloffset=+1] + include::modules/ossm-migrating-read-me-new-resources.adoc[leveloffset=+1] + include::modules/ossm-migrating-read-me-observability-integrations.adoc[leveloffset=+1] -include::modules/ossm-migrating-read-me-scoping-discovery-selectors.adoc[leveloffset=+1] -.Next steps -* xref:../../install/ossm-installing-openshift-service-mesh.adoc#ossm-scoping-service-mesh-with-discoveryselectors_ossm-installing-openshift-service-mesh[Scoping Service Mesh with discoverySelectors] +include::modules/ossm-migrating-read-me-scoping-discovery-selectors.adoc[leveloffset=+1] include::modules/ossm-migrating-read-me-sidecar-injection-considerations.adoc[leveloffset=+1] -include::modules/ossm-migrating-read-me-support-for-multiple-control-planes.adoc[leveloffset=+1] -include::modules/ossm-migrating-read-me-independently-managed-gateways.adoc[leveloffset=+1] -.Next steps -If you are using {SMProduct} 2.6, and have not migrated from `ServiceMeshControlPlane` defined gateways to gateway injection, then you must follow the {SMProduct} 2.x gateway migration procedure before you can move to {SMProduct} 3. +include::modules/ossm-migrating-read-me-support-for-multiple-control-planes.adoc[leveloffset=+1] -* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/service_mesh/service-mesh-2-x#ossm-about-gateway-migration_gateway-migration[Gateway migration] +include::modules/ossm-migrating-read-me-independently-managed-gateways.adoc[leveloffset=+1] include::modules/ossm-migrating-read-me-explicitly-create-openshift-routes.adoc[leveloffset=+1] -include::modules/ossm-migrating-read-me-introducing-canary-updates.adoc[leveloffset=+1] - -.Next steps -You can set `updateStrategy` to `RevisionBased` to use canary updates. - -* xref:../../update/ossm-updating-openshift-service-mesh.adoc#about-revisionbased-strategy_ossm-performing-inplace-update[About RevisionBased strategy] - -Be aware that setting the `updateStrategy` to `RevisionBased` also has implications for some integrations with {SMProduct}, such as the cert-manager tool integration. -* xref:../../install/ossm-cert-manager.adoc#updating-istio-csr-revision-based-only_ossm-cert-manager[Updating istio-csr agents with revision-based update strategies] +include::modules/ossm-migrating-read-me-introducing-canary-updates.adoc[leveloffset=+1] include::modules/ossm-migrating-read-me-supported-multi-cluster-topologies.adoc[leveloffset=+1] -include::modules/ossm-migrating-read-me-support-for-istioctl.adoc[leveloffset=+1] -.Next steps -* You can install the xref:../../install/ossm-istioctl-tool.adoc#ossm-installing-the-istioctl-tool_ossm-istioctl-tool[Istioctl tool]. +include::modules/ossm-migrating-read-me-support-for-istioctl.adoc[leveloffset=+1] include::modules/ossm-migrating-read-me-kubernetes-network-policy-management.adoc[leveloffset=+1] + include::modules/ossm-migrating-read-me-tls-configuration-change.adoc[leveloffset=+1] +include::modules/ossm-migrating-read-me-dns-capture-configuration.adoc[leveloffset=+1] + [role="_additional-resources"] -[id="additional-resource_{context}"] -== Additional Resources +[id="additional-resources_{context}"] +== Additional resources * link:https://docs.redhat.com/en/documentation/openshift_container_platform/#Observability[Red Hat OpenShift Observability] + * link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/logging/index[Logging] + * link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/monitoring/index[User workload monitoring] + * link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/distributed_tracing/index[{DTProductName}] -* link:https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/[Labels and Selectors] (Kubernetes documentation) -* link:https://istio.io/latest/docs/tasks/security/tls-configuration/workload-min-tls-version/[Istio Workload Minimum TLS Version Configuration] (Istio documentation) -* link:https://istio.io/latest/docs/reference/config/security/authorization-policy/[Authorization Policies] (Istio documentation) + +* link:https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/[Labels and Selectors (Kubernetes documentation)] + +* link:https://istio.io/latest/docs/tasks/security/tls-configuration/workload-min-tls-version/[Istio Workload Minimum TLS Version Configuration (Istio documentation)] + +* link:https://istio.io/latest/docs/reference/config/security/authorization-policy/[Authorization Policies (Istio documentation)] + +* link:https://istio.io/[Istio project] + +* xref:../../install/ossm-installing-openshift-service-mesh.adoc#ossm-scoping-service-mesh-with-discoveryselectors_ossm-installing-openshift-service-mesh[Scoping Service Mesh with discoverySelectors] + +* xref:../../update/ossm-updating-openshift-service-mesh.adoc#about-revisionbased-strategy_ossm-performing-inplace-update[About RevisionBased strategy] + +* xref:../../install/ossm-cert-manager.adoc#updating-istio-csr-revision-based-only_ossm-cert-manager[Updating istio-csr agents with revision-based update strategies] + +* xref:../../install/ossm-istioctl-tool.adoc#ossm-installing-the-istioctl-tool_ossm-istioctl-tool[Istioctl tool] + +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/service_mesh/service-mesh-2-x#ossm-about-gateway-migration_gateway-migration[Gateway migration] + diff --git a/migrating/cluster-wide/ossm-migrating-cluster-wide.adoc b/migrating/cluster-wide/ossm-migrating-cluster-wide.adoc index 46c5772d186..22142293ca9 100644 --- a/migrating/cluster-wide/ossm-migrating-cluster-wide.adoc +++ b/migrating/cluster-wide/ossm-migrating-cluster-wide.adoc @@ -1,7 +1,3 @@ -// Module included in the following assemblies: -// -// * service-mesh-docs-main/migrating/cluster-wide/ossm-migrating-cluster-wide-assembly.adoc - :_mod-docs-content-type: ASSEMBLY [id="ossm-migrating-cluster-wide"] = Cluster-wide migration guide @@ -10,6 +6,8 @@ include::_attributes/common-attributes.adoc[] toc::[] +[role="_abstract"] + This guide is for users who are running a cluster-wide deployment of {SMProductName} {SMv2Version} and are migrating to {SMProduct} 3.0. [IMPORTANT] @@ -19,16 +17,6 @@ You must complete the premigration checklists before you start migrating your de include::modules/ossm-control-plane-configuration-migration-requirements.adoc[leveloffset=+1] -[role="_additional-resources"] -[id="additional-resources-cluster-wide_{context}"] -.Additional resources - -* xref:../../install/ossm-sidecar-injection.adoc#ossm-about-sidecar-injection_ossm-sidecar-injection[About sidecar injection] - -* xref:../../migrating/checklists/ossm-migrating-network-policies.adoc#ossm-migrating-network-policies-setup-during-migration_ossm-migrating-network-policies[Set up network policies to use during migration] - -* xref:../../install/ossm-installing-openshift-service-mesh.adoc#ossm-scoping-service-mesh-with-discoveryselectors_ossm-installing-openshift-service-mesh[Scoping the mesh with discoverySelectors] - include::modules/ossm-cluster-wide-migration-methods.adoc[leveloffset=+1] // This sets the context to build the tasks for cluster-wide migration using the Istio revision label @@ -38,16 +26,6 @@ include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revisi include::modules/ossm-migrating-workloads-using-the-istio-revision-label.adoc[leveloffset=+2] -.Next steps - -If you are using gateways, you must migrate them before you complete the migration process. - -* xref:../../migrating/migrating-gateways/ossm-migrating-gateways.adoc#ossm-migrating-gateways[Migrating gateways] - -If you are not using gateways, and have verified your cluster-wide migration, you can proceed to complete the migration and remove {SMProduct} 2 resources. - -* xref:../../migrating/done/ossm-migrating-complete.adoc#ossm-migrating-complete[Completing the Migration] - // This sets the context to build the tasks for cluster-wide migration using the Istio revision label with cert-manager tasks :context: cw-revision-cm @@ -55,16 +33,6 @@ include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revisi include::modules/ossm-migrating-workloads-using-the-istio-revision-label.adoc[leveloffset=+2] -.Next steps - -If you are using gateways, you must migrate them before you complete the migration process. - -* xref:../../migrating/migrating-gateways/ossm-migrating-gateways.adoc#ossm-migrating-gateways[Migrating gateways] - -If you are not using gateways, and have verified your cluster-wide migration, you can proceed to complete the migration and remove {SMProduct} 2 resources. - -* xref:../../migrating/done/ossm-migrating-complete.adoc#ossm-migrating-complete[Completing the Migration] - // This sets the context to build the tasks for cluster-wide migration using the Istio injection label :context: cw-injection @@ -72,26 +40,9 @@ include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-inject include::modules/ossm-migrating-workloads-using-the-istio-injection-label.adoc[leveloffset=+2] -.Next steps - -If you are using gateways, you must migrate them before you complete the migration process. - -* xref:../../migrating/migrating-gateways/ossm-migrating-gateways.adoc#ossm-migrating-gateways[Migrating gateways] - -If you are not using gateways, and have verified your cluster-wide migration, create a default revision tag and relabel namespaces. - include::modules/ossm-creating-a-default-revision-tag-and-relabeling-the-namespaces.adoc[leveloffset=+2] -.Next steps - -You can proceed to complete the migration and remove {SMProduct} 2 resources. - -* xref:../../migrating/done/ossm-migrating-complete.adoc#ossm-migrating-complete[Completing the Migration] - -[IMPORTANT] -==== -Before creating a default revision tag and relabelling the namespaces, you must migrate all remaining workload namespaces, including gateways. -==== +include::snippets/ossm-migrate-all-namespaces.adoc[] // This sets the context to build the tasks for cluster-wide migration using the Istio injection label with cert-manager :context: cw-injection-cm @@ -100,18 +51,7 @@ include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-inject include::modules/ossm-migrating-workloads-using-the-istio-injection-label.adoc[leveloffset=+2] -.Next steps - -If you are using gateways, you must migrate them before you complete the migration process. - -* xref:../../migrating/migrating-gateways/ossm-migrating-gateways.adoc#ossm-migrating-gateways[Migrating gateways] - -If you are not using gateways, and have verified your cluster-wide migration, create a default revision tag and relabel namespaces. - -[IMPORTANT] -==== -Before creating a default revision tag and relabelling the namespaces, you must migrate all remaining workload namespaces, including gateways. -==== +include::snippets/ossm-migrate-all-namespaces.adoc[] include::modules/ossm-creating-a-default-revision-tag-and-relabeling-the-namespaces-with-cert-manager.adoc[leveloffset=+2] @@ -121,18 +61,18 @@ include::modules/ossm-creating-a-default-revision-tag-and-relabeling-the-namespa include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-simple-migration-method.adoc[leveloffset=+1] include::modules/ossm-migrating-workloads-using-the-simple-migration-method.adoc[leveloffset=+2] -.Next steps +[role="_additional-resources"] +[id="additional-resources_{context}"] +== Additional resources -If you are using gateways, you must migrate them before you complete the migration process. +* xref:../../install/ossm-sidecar-injection.adoc#ossm-about-sidecar-injection_ossm-sidecar-injection[About sidecar injection] -* xref:../../migrating/migrating-gateways/ossm-migrating-gateways.adoc#ossm-migrating-gateways[Migrating gateways] +* xref:../../migrating/checklists/ossm-migrating-network-policies.adoc#ossm-migrating-network-policies-setup-during-migration_ossm-migrating-network-policies[Set up network policies to use during migration] -If you are not using gateways, you can complete your migration. +* xref:../../install/ossm-installing-openshift-service-mesh.adoc#ossm-scoping-service-mesh-with-discoveryselectors_ossm-installing-openshift-service-mesh[Scoping the mesh with discoverySelectors] -* xref:../../migrating/done/ossm-migrating-complete.adoc#ossm-migrating-complete[Completing the Migration] +* xref:../../install/ossm-sidecar-injection.adoc#ossm-identifying-revision-name_ossm-sidecar-injection[Identifying the revision name] -[role="_additional-resources"] -[id="additional-resources_{context}"] -== Additional resources +* xref:../../migrating/migrating-gateways/ossm-migrating-gateways.adoc#ossm-migrating-gateways[Migrating gateways] -* xref:../../install/ossm-sidecar-injection.adoc#ossm-identifying-revision-name_ossm-sidecar-injection[Identifying the revision name] +* xref:../../migrating/done/ossm-migrating-complete.adoc#ossm-migrating-complete[Completing the Migration] diff --git a/migrating/done/ossm-migrating-complete.adoc b/migrating/done/ossm-migrating-complete.adoc index 4ccb75dd33d..3e4ec5bab8c 100644 --- a/migrating/done/ossm-migrating-complete.adoc +++ b/migrating/done/ossm-migrating-complete.adoc @@ -6,26 +6,22 @@ include::_attributes/common-attributes.adoc[] toc::[] -At this stage, you have completed the migration process. It is safe to remove {SMProduct} {smv2version}. +[role="_abstract"] -//need to add cleanup/delete 2.6 content - -Optionally, if you already have Kiali installed, before you delete {SMProduct} {SMv2Version}, you can verify that all data plane namespaces have been migrated by checking the Kiali **Mesh** page. To learn more about the Kiali **Mesh** page, see "Istio infrastructure status (Kiali.io)". +Once the migration is complete, you can uninstall {SMProduct} {smv2version} and optionally verify the migration status of data plane namespaces by using the Kiali *Mesh* page. include::modules/ossm-migrating-done-network-policies.adoc[leveloffset=+1] -include::modules/ossm-migrating-complete-multitenant-cert-manager.adoc[leveloffset=+1] -.Next steps - -* Remove {Smproduct} 2 +include::modules/ossm-migrating-complete-multitenant-cert-manager.adoc[leveloffset=+1] include::modules/ossm-migrating-complete-remove-2-6-control-plane.adoc[leveloffset=+1] + include::modules/ossm-migrating-complete-remove-2-6-operator-crds.adoc[leveloffset=+1] -include::modules/ossm-migrating-complete-remove-maistra-labels.adoc[leveloffset=+1] +include::modules/ossm-migrating-complete-remove-maistra-labels.adoc[leveloffset=+1] [role="_additional-resources"] -[id="additional-resources-complete_{context}"] -== Additional Resources +[id="additional-resources_{context}"] +== Additional resources -* link:https://kiali.io/docs/features/istio-component-status/#control-plane-namespace[Istio infrastructure status] (Kiali.io documentation) +* link:https://kiali.io/docs/features/istio-component-status/#control-plane-namespace[Istio infrastructure status (Kiali.io documentation)] diff --git a/migrating/migrating-gateways/ossm-migrating-gateways.adoc b/migrating/migrating-gateways/ossm-migrating-gateways.adoc index 9b04aae6790..0e152483151 100644 --- a/migrating/migrating-gateways/ossm-migrating-gateways.adoc +++ b/migrating/migrating-gateways/ossm-migrating-gateways.adoc @@ -6,31 +6,20 @@ include::_attributes/common-attributes.adoc[] toc::[] -If you are using gateways with {SMProductName} {SMv2Version} and migrating them to {smproduct} 3.0, you can migrate gateways from {SMProduct} 2 to {SMProduct} 3 just like regular workloads. +[role="_abstract"] -Use one of the following two methods for migrating gateways from {SMProductName} 2 to {SMProduct} 3: - -* Gateway canary migration -* Gateway in place migration +Migrate {SMProductName} gateways from version 2 to version 3 by using either a canary or an in-place migration strategy to ensure continuous traffic management. include::modules/ossm-migrating-gateways-canary.adoc[leveloffset=+1] -.Next steps - -* xref:../../migrating/done/ossm-migrating-complete.adoc#ossm-migrating-complete[Completing your migration] - include::modules/ossm-migrating-gateways-in-place.adoc[leveloffset=+1] -.Next steps - -* xref:../../migrating/done/ossm-migrating-complete.adoc#ossm-migrating-complete[Completing your migration] - [role="_additional-resources"] -[id="additional-resources-gateways_{context}"] +[id="additional-resources_{context}"] == Additional resources +* xref:../../migrating/done/ossm-migrating-complete.adoc#ossm-migrating-complete[Completing your migration] + * xref:../../migrating/multitenant/ossm-migrating-multitenant.adoc#ossm-migrating-multitenant[Multitenant migration guide] -* xref:../../migrating/cluster-wide/ossm-migrating-cluster-wide.adoc#ossm-migrating-cluster-wide[Cluster-wide migration guide] -//there is already a Gateways dir that contains 3.0 concept and procedure content for configuring and using gateways in 3.0. -//named this dir migrating-gateways for clarity \ No newline at end of file +* xref:../../migrating/cluster-wide/ossm-migrating-cluster-wide.adoc#ossm-migrating-cluster-wide[Cluster-wide migration guide] \ No newline at end of file diff --git a/migrating/multitenant/ossm-migrating-multitenant.adoc b/migrating/multitenant/ossm-migrating-multitenant.adoc index 1d2ecdb39ed..e1baae9c1b2 100644 --- a/migrating/multitenant/ossm-migrating-multitenant.adoc +++ b/migrating/multitenant/ossm-migrating-multitenant.adoc @@ -6,37 +6,24 @@ include::_attributes/common-attributes.adoc[] toc::[] -This guide is for users who are currently running a multitenant deployment of {SMProductName} {SMv2Version}, and are migrating to {SMProduct} 3.0. +[role="_abstract"] -[IMPORTANT] -==== -If you have not completed the premigration checklists, you must complete them first before you can start migrating your deployment. -==== +This guide is for users who are currently running a multitenant deployment of {SMProductName} {SMv2Version}, and are migrating to {SMProduct} 3.0. include::modules/ossm-migrating-a-multitenant-deployment.adoc[leveloffset=+1] -include::modules/ossm-migrating-multitenant-workloads.adoc[leveloffset=+1] - -.Next steps - -If you are using gateways, you must migrate them before you complete the migration process for your deployment and workloads. - -* xref:../migrating-gateways/ossm-migrating-gateways.adoc#ossm-migrating-gateways[Migrating gateways] - -If you are not using gateways, and have verified your mulitenant migration, you can proceed to complete the migration and remove {SMProduct} 2 resources. -* xref:../done/ossm-migrating-complete.adoc[Completing the Migration] +include::modules/ossm-migrating-multitenant-workloads.adoc[leveloffset=+1] include::modules/ossm-migrating-multitenant-with-cert-manager.adoc[leveloffset=+1] + include::modules/ossm-migrating-multitenant-workloads-with-cert-manager.adoc[leveloffset=+1] -.Next steps +[role="_additional-resources"] +[id="additional-resources_{context}"] +== Additional resources -If you are using gateways, you must migrate them before you can complete the migration process for your deployment and workloads. +* xref:../modules/ossm-migrating-read-me-new-resources.adoc#ossm-istio-resource-replaces-smcp[The Istio resource replaces the ServiceMeshControlPlane resource] * xref:../migrating-gateways/ossm-migrating-gateways.adoc#ossm-migrating-gateways[Migrating gateways] -After you have migrated your gateways, you must update the `app.controller.configmapNamespaceSelector` field in your `istio-csr` deployment. - -If you are not using gateways, you can complete your migration with cert-manager. - -* xref:../../migrating/done/ossm-migrating-complete.adoc#ossm-migrating-complete[Completing the Migration] \ No newline at end of file +* xref:../done/ossm-migrating-complete.adoc#ossm-migrating-complete[Completing the Migration] \ No newline at end of file diff --git a/migrating/ossm-migrating-from-service-mesh-2-to-3.adoc b/migrating/ossm-migrating-from-service-mesh-2-to-3.adoc index ec6d8b6f5ae..2cd81233f80 100644 --- a/migrating/ossm-migrating-from-service-mesh-2-to-3.adoc +++ b/migrating/ossm-migrating-from-service-mesh-2-to-3.adoc @@ -6,20 +6,26 @@ include::_attributes/common-attributes.adoc[] toc::[] -The content in this migration section applies only in the following cases: +[role="_abstract"] -* You are an existing {SMProductName} user running {SMProduct} {SMv2Version}. -* You want to move to {SMProduct} 3.0. +Transition your environment from {SMProduct} 2.6 to 3.0 by following a guided migration path that includes pre-migration readiness checks, workload relocation strategies, and best practices for maintaining service availability throughout the upgrade process. -[IMPORTANT] -==== -If you are not running {SMProduct} {smv2version}, you must update before you can continue. For more information, see link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/service_mesh/service-mesh-2-x#upgrading-ossm[Upgrading Service Mesh]. -==== - -During the migration process, you might need to reference, or you might be directed to {SMProduct} 2.x content. It can be beneficial to open link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/service_mesh/service-mesh-2-x[OpenShift Service Mesh 2.x] in a new tab or window for easier reference. This can be especially helpful when you move between {SMProduct} 2 `ServiceMeshControlPlane` resource content and {SMProduct} 3 `Istio` resource content. +include::modules/ossm-migrating-about.adoc[leveloffset=+1] include::modules/ossm-migrating-hub-recommendations-for-migrating.adoc[leveloffset=+1] + include::modules/ossm-migrating-hub-how-to-use-migration-guides.adoc[leveloffset=+1] + include::modules/ossm-migrating-hub-premigration-checklists.adoc[leveloffset=+1] + include::modules/ossm-migrating-hub-deployment-workloads.adoc[leveloffset=+1] + include::modules/ossm-migrating-hub-completing-your-migration.adoc[leveloffset=+1] + +[role="_additional-resources"] +[id="additional-resources_{context}"] +== Additional resources + +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/service_mesh/service-mesh-2-x[OpenShift Service Mesh 2.x] + +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/service_mesh/service-mesh-2-x#upgrading-ossm[Upgrading Service Mesh] \ No newline at end of file diff --git a/migrating/reference/ossm-migrating-references.adoc b/migrating/reference/ossm-migrating-references.adoc index 83da9f20ae9..1fc959ea123 100644 --- a/migrating/reference/ossm-migrating-references.adoc +++ b/migrating/reference/ossm-migrating-references.adoc @@ -3,19 +3,19 @@ = Migrating references include::_attributes/common-attributes.adoc[] :context: ossm-migrating-references + toc::[] -Many configuration options in the {SMProduct} 2 `ServiceMeshControlPlane` resource have changed location in the {SMProduct} 3 `Istio` resource. The following tables provide guidance for creating a new `Istio` resource in {SMProduct} 3 based on your existing {SMProduct} 2 `ServiceMeshControlPlane` resource. +[role="_abstract"] + +Many configuration options in the {SMProduct} 2 `ServiceMeshControlPlane` resource have changed location in the {SMProduct} 3 `{istio}` resource. The following tables offer guidance for creating a new `{istio}` resource in {SMProduct} 3 based on your existing {SMProduct} 2 `ServiceMeshControlPlane` resource. include::modules/ossm-migrating-reference-smcp-configurations.adoc[leveloffset=+1] + include::modules/ossm-migrating-reference-unsupported-configurations.adoc[leveloffset=+1] [role="_additional-resources"] -[id="additional-resources-reference_{context}"] -== Additional Resources - -* xref:../../observability/ossm-observability-service-mesh.adoc#ossm-observability-service-mesh[Observability and Service Mesh] +[id="additional-resources_{context}"] +== Additional resources -//* add exref to "Deploying multiple service meshes on a single cluster" -//exrefs handled by OSSM-8852 -//titles handled by OSM-8852 \ No newline at end of file +* xref:../../observability/ossm-observability-service-mesh.adoc#ossm-observability-service-mesh[Observability and Service Mesh] \ No newline at end of file diff --git a/modules/ossm-SPIRE-install-ZTWIM.adoc b/modules/ossm-SPIRE-install-ZTWIM.adoc new file mode 100644 index 00000000000..b3798014435 --- /dev/null +++ b/modules/ossm-SPIRE-install-ZTWIM.adoc @@ -0,0 +1,54 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/install/ossm-SPIRE.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ossm-SPIRE-install-ZTWIM_{context}"] += Install the Operator and components for SPIRE + +[role="_abstract"] +Before you integrate the SPIFFE Runtime Environment (SPIRE) security framework with {SMProduct}, you must install the Zero Trust Workload Identity Manager Operator. It manages SPIRE components on your {ocp-product-title} cluster. + +include::snippets/technology-preview-SPIRE.adoc[] + +.Prerequisites + +* You have deployed a cluster on {ocp-product-title} 4.18 or later. + +.Procedure + +. Install the Operator by following the steps in link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/security_and_compliance/zero-trust-workload-identity-manager#zero-trust-manager-install[Installing the Zero Trust Workload Identity Manager] (which is {ocp-product-title} documentation). ++ +You can install the Zero Trust Workload Identity Manager by using either the web console or CLI. + +. Configure the Operator to work in `CreateOnly` mode by running the following command: ++ +[source,terminal] +---- +$ oc -n zero-trust-workload-identity-manager patch subscription \ + openshift-zero-trust-workload-identity-manager \ + --type='merge' -p '{"spec":{"config":{"env":[{"name":"CREATE_ONLY_MODE","value":"true"}]}}}' +---- ++ +`CreateOnly` mode prevents the Operator from automatically overwriting your SPIRE configurations during {istio} integration. + +. Define required environment variables: ++ +[source,terminal,subs="+quotes"] +---- +$ export TRUST_DOMAIN=____ +$ export ZTWIM_NS=zero-trust-workload-identity-manager +$ export JWT_ISSUER="https://oidc-discovery.$(oc get ingresses.config/cluster -o jsonpath={.spec.domain})" +---- +where: ++ +`TRUST_DOMAIN`:: The SPIFFE trust domain for the service mesh. +`ZTWIM_NS`:: The namespace where the Zero Trust Workload Identity Manager is deployed. +`JWT_ISSUER`:: The OpenID Connect (OIDC) discovery endpoint URL for the SPIRE OIDC Discovery Provider. SPIRE exposes SPIFFE identities as OIDC-compatible JSON Web Tokens (JWTs) through this endpoint, enabling Istio to validate workload identities with standard OIDC authentication protocols. + +. Deploy the Operator components according to the {ocp-product-title} documentation link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/security_and_compliance/zero-trust-workload-identity-manager#zero-trust-manager-configuration_zero-trust-manager-install[Deploying Zero Trust Workload Identity Manager operands]. The components (operands) are: +** `ZeroTrustWorkloadIdentityManager` CR +** SPIRE server +** SPIRE agent +** SPIFFE Container Storage Interface (CSI) driver +** SPIRE OpenID Connect (OIDC) discovery provider diff --git a/modules/ossm-SPIRE-istio-integrate.adoc b/modules/ossm-SPIRE-istio-integrate.adoc new file mode 100644 index 00000000000..bc9dbb12330 --- /dev/null +++ b/modules/ossm-SPIRE-istio-integrate.adoc @@ -0,0 +1,188 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/install/ossm-SPIRE.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ossm-SPIRE-istio-integrate_{context}"] += Integrate the {istio} CR with SPIRE + +[role="_abstract"] +To implement zero-trust security in your mesh, configure the {istio} CR to integrate with the SPIFFE Runtime Environment (SPIRE). This configuration connects {istio} proxies to the SPIRE agent. Workloads receive SPIFFE identities instead of using default {istio} certificates. + +.Prerequisites + +* You have deployed a cluster on {ocp-product-title} 4.18 or later. + +* You have installed the {SMProduct} Operator. + +* You have installed the Zero Trust Workload Identity Manager and deployed the associated components. + +* You have deployed an `IstioCNI` CR. + + +.Procedure + +. Define environment variables for the {istio} configuration, as shown in the following example: ++ +[source,terminal,subs="+quotes"] +---- +$ export ZTWIM_NS=zero-trust-workload-identity-manager +$ export TRUST_DOMAIN=____ +$ export JWT_ISSUER="https://oidc-discovery.$(oc get ingresses.config/cluster -o jsonpath={.spec.domain})" +$ export OSSM_NS=istio-system +$ export OSSM_CNI=istio-cni +$ export VERIFY_NS=verify-ossm-ztwim +$ export EXTRA_ROOT_CA="$(oc get secret oidc-serving-cert \ + -n ${ZTWIM_NS} -o json | \ + jq -r '.data."tls.crt"' | \ + base64 -d | \ + sed 's/^/ /')" +---- +where: ++ +`ZTWIM_NS`:: The namespace where the Zero Trust Workload Identity Manager is deployed. Use the value from your Zero Trust Workload Identity Manager configuration. +`TRUST_DOMAIN`:: The SPIFFE trust domain for the service mesh, which is the same domain specified in your Zero Trust Workload Identity Manager configuration. +`JWT_ISSUER`:: The OpenID Connect (OIDC) discovery endpoint URL for the SPIRE OIDC Discovery Provider. SPIRE exposes SPIFFE identities as OIDC-compatible JSON Web Tokens (JWTs) through this endpoint, enabling {istio} to validate workload identities by using standard OIDC authentication protocols. This URL must match the URL specified in your Zero Trust Workload Identity Manager configuration. +`OSSM_NS`:: The namespace where you deploy the {istio} control plane. +`OSSM_CNI`:: The namespace where you deployed the {istio} CNI component. +`VERIFY_NS`:: The namespace for deploying verification workloads. +`EXTRA_ROOT_CA`:: The root CA certificate from the SPIRE OIDC Discovery Provider. This certificate enables {istio}'s `pilot` component to trust and verify JWTs issued by the SPIRE OIDC provider. + +. Create the {istio} CR according to the following example: ++ +[source,terminal] +---- +$ oc new-project "${OSSM_NS}" 2>/dev/null +# Create Istiod +$ cat < /dev/null; do sleep 3; done +oc wait --for=condition=Available deployment/istiod -n "${OSSM_NS}" --timeout=300s +---- +where: ++ +`PILOT_JWT_ENABLE_REMOTE_JWKS`:: Enables Istio's `pilot` component to fetch JSON Web Key Sets (JWKS) from remote OIDC endpoints. Pilot uses these keys to validate JWTs issued by the SPIRE OIDC Discovery Provider. +`WORKLOAD_IDENTITY_SOCKET_FILE`:: Specifies the UNIX domain socket filename that sidecar proxies use to communicate with the SPIRE agent and obtain SPIFFE identities. +`sidecarInjectorWebhook.templates.spire`:: Custom injection template for regular workload sidecars. It mounts the SPIFFE CSI driver volume at `/run/secrets/workload-spiffe-uds`. This directory has the UNIX domain socket file that sidecars use to communicate with the SPIRE agent and obtain SPIFFE identities. +`sidecarInjectorWebhook.templates.spireGateway`:: Custom injection template for ingress and egress gateway pods. It mounts the SPIFFE Container Storage Interface (CSI) driver volume at `/run/secrets/workload-spiffe-uds`. This directory has the UNIX domain socket file that gateways use to communicate with the SPIRE agent and obtain SPIFFE identities. +`csi.spiffe.io`:: The SPIFFE CSI driver that provides workloads with access to the SPIRE agent's UNIX domain socket for obtaining SPIFFE identities. + +.Verification + +Deploy a test workload and verify that it receives a SPIFFE identity from SPIRE. + +. Create a test namespace with sidecar injection enabled: ++ +[source,terminal] +---- +$ oc new-project "${VERIFY_NS}" +$ oc label namespace "${VERIFY_NS}" istio-injection=enabled +---- + +. Deploy the httpbin test application and wait for it to become available: ++ +[source,terminal] +---- +$ cat < chain.pem +$ openssl x509 -in chain.pem -text | grep SPIRE +---- ++ +The following output confirms that SPIRE issued the certificate: ++ +[source,terminal] +---- +Issuer: C=US, O=Sky Computing Corporation, CN=SPIRE Server CA/serialNumber=... +Subject: C=US, O=SPIRE +---- ++ +[NOTE] +==== +SPIRE issues two types of identities: X.509 SPIFFE Verifiable Identity Documents (SVIDs) for mTLS communication, and JWT-SVIDs for HTTP-based authentication. This verification confirms X.509 SVID functionality only. +==== + diff --git a/modules/ossm-SPIREex-traffic-entering-mesh.adoc b/modules/ossm-SPIREex-traffic-entering-mesh.adoc new file mode 100644 index 00000000000..5539c66e879 --- /dev/null +++ b/modules/ossm-SPIREex-traffic-entering-mesh.adoc @@ -0,0 +1,113 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/install/ossm-SPIRE.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ossm-SPIREex-traffic-entering-mesh_{context}"] += Test the Istio ingress gateway with SPIRE + +[role="_abstract"] +Deploy an Istio ingress gateway that obtains SPIFFE identities from SPIRE to test how external traffic can securely access services in the mesh. The gateway uses these identities to establish mTLS connections to backend services. + +.Prerequisites + +* You have integrated the {istio} CR with SPIRE. + +* You have verified mTLS connectivity between the two applications in the previous test procedure. + +* You have the Helm CLI installed. (See the {ocp-product-title} documentation link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/cli_tools/helm-cli[Installing the Helm CLI].) + +.Procedure + +. Grant the necessary security context permissions for the gateway pod: ++ +[source,terminal] +---- +$ oc adm policy add-scc-to-user anyuid system:serviceaccount:istio-system:istio-gateway +---- + +. Add the Istio Helm repository: ++ +[source,terminal] +---- +$ helm repo add istio https://istio-release.storage.googleapis.com/charts +$ helm repo update +---- + +. Install the ingress gateway and enable it to communicate with the SPIRE agent: ++ +[source,terminal] +---- +$ helm install istio-gateway -n "${OSSM_NS}" \ + istio/gateway --set-json \ + 'podAnnotations={"inject.istio.io/templates":"gateway,spireGateway"}' +$ oc wait --for=condition=Available deployment/istio-gateway -n "${OSSM_NS}" --timeout=300s +---- ++ +The pod annotation `inject.istio.io/templates: gateway,spireGateway` mounts the SPIRE agent socket into the gateway pod. The gateway uses this socket to request and receive SPIFFE identities from SPIRE. + +. Create the `Gateway` resource to define ingress routing rules: ++ +[source,terminal] +---- +$ cat <.-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. +To perform canary updates of the control plane, {SMProduct} supports many {istio} versions. You can set the `version` field to the new version by either 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. {SMProduct} supports two different update strategies for your control planes: `InPlace`:: The {SMProduct} Operator immediately replaces your existing control plane resources with the ones for the new version. -`RevisionBased`:: Uses Istio's canary update mechanism by creating a second control plane to which you can migrate your workloads to complete the update. +`RevisionBased`:: Uses {istio}'s canary update mechanism by creating a second control plane to which you can migrate your workloads to complete the update. -After creating an Istio resource, {SMProduct} generates a revision name for the resource based on the `updateStrategy`, and creates a corresponding `IstioRevision`. +After creating an {istio} resource, {SMProduct} generates a revision name for the resource based on the `updateStrategy`, and creates a corresponding `IstioRevision`. [id="istiorevision-resource_{context}"] == IstioRevision resource -The `IstioRevision` is a cluster-wide resource and the lowest-level API {SMProduct} provides. It is usually not created by the user, but by the Operator itself. Its schema closely resembles that of the `Istio` resource - but instead of representing the state of a control plane you want to be present in your cluster, it represents a revision of that control plane. +The `IstioRevision` is a cluster-wide resource and the lowest-level API {SMProduct} provides. It is usually not created by the user, but by the Operator itself. Its schema closely resembles that of the `{istio}` resource. Instead of representing the state of a control plane you want to be present in your cluster, it represents a revision of that control plane. -A revision of the control plane you want to be present in your cluster is an instance of Istio with a specific version and revision name, and its revision name can be used to add workloads or entire namespaces to the mesh. For example: by using the `istio.io/rev=` label. +A revision of the control plane you want to be present in your cluster is an instance of {istio} with a specific version and revision name, and you can use its revision name to add workloads or entire namespaces to the mesh. For example: by using the `istio.io/rev=` label. -You can think of the relationship between the `Istio` and `IstioRevision` resources as similar to the relationship between Kubernetes' replica set and pod: a replica set can be created by users and results in the automatic creation of pods, which will trigger the instantiation of your containers. +You can think of the relationship between the `{istio}` and `IstioRevision` resources as similar to the relationship between {k8s}' replica set and pod. Users can create a replica set, and results in the automatic creation of pods, which will trigger the instantiation of your containers. -Similarly, users create an `Istio` resource which instructs the {SMProduct} Operator to create a matching `IstioRevision` resource, which then in turn triggers the creation of the Istio control plane. To do that, the {SMProduct} Operator will copy all of your relevant configuration from the `Istio` resource to the `IstioRevision` resource. +Similarly, users create an `{istio}` resource that instructs the {SMProduct} Operator to create a matching `IstioRevision` resource, which then in turn triggers the creation of the {istio} control plane. To do that, the {SMProduct} Operator will copy all of your relevant configuration from the `{istio}` resource to the `IstioRevision` resource. [id="istiorevisiontag-resource_{context}"] == IstioRevisionTag resource -The `IstioRevisionTag` resource represents a stable revision tag that functions as an alias for Istio control plane revisions. With the stable tag, `prod`, you can use the label `istio.io/rev=prod` to inject proxies into your workloads. 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. For more information, see link:https://istio.io/latest/docs/setup/upgrade/canary/#stable-revision-labels[Stable revision labels] (Istio documentation). +The `IstioRevisionTag` resource represents a stable revision tag that functions as an alias for {istio} control plane revisions. With the stable tag, `prod`, you can use the label `istio.io/rev=prod` to inject proxies into your workloads. 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. For more information, see "Stable revision labels". -You can use the `IstioRevisionTag` resource with the {SMProduct} Operator. Therefore you can reference both an `IstioRevision` and an `Istio` resource. When using an `Istio` resource, after you update your control plane, the underlying `IstioRevision` resource changes, and the {SMProduct} Operator automatically updates your revision tag. You only need to restart your deployments to re-inject the new proxies. +You can use the `IstioRevisionTag` resource with the {SMProduct} Operator. Therefore you can reference both an `IstioRevision` and an `Istio` resource. When using an `{istio}` resource, after you update your control plane, the underlying `IstioRevision` resource changes, and the {SMProduct} Operator automatically updates your revision tag. You only need to restart your deployments to re-inject the new proxies. -The `IstioRevisionTag` has one field in its `spec:` field, `targetRef`, which can reference an `Istio` or `IstioRevision` resource. After deploying the `IstioRevisionTag`, you can use both the `istio.io/rev=default` and `istio-injection=enabled` labels to inject proxies into your workloads. +The `IstioRevisionTag` has one field in its `spec:` field, `targetRef`, which can reference an `{istio}` or `IstioRevision` resource. After deploying the `IstioRevisionTag`, you can use both the `istio.io/rev=default` and `istio-injection=enabled` labels to inject proxies into your workloads. -[Important] +[IMPORTANT] ==== -The `istio-injection` label can only be used for revisions and revision tags that have the name `default`, like the `IstioRevisionTag` resource in the following example: +You can only use the `istio-injection` label for revisions and revision tags that have the name `default`, such as the `IstioRevisionTag` resource in the following example: -.Example `IstioRevisionTag` resource [source,yaml] ---- apiVersion: sailoperator.io/v1 @@ -120,21 +120,21 @@ metadata: name: default spec: targetRef: - kind: Istio <1> - name: prod <2> + kind: Istio + name: prod ---- -<1> This value can be either `Istio` or `IstioRevision`. -<2> The name of the `Istio` or `IstioRevision` resource. +* `spec.targetRef.kind`:: The kind of resource the tag references. The value can be either `{istio}` or `IstioRevision`. + +* `spec.targetRef.name`:: The name of the resource the tag references. The value can be either the name of an `{istio}` or `IstioRevision` resource. ==== [id="istiocni-resource_{context}"] == IstioCNI resource -The lifecycle of Istio's Container Network Interface (CNI) plugin is managed separately when using {SMProduct} Operator. To install Istio's CNI plugin, you create an `IstioCNI` resource. +The {SMProduct} Operator manages the lifecycle of {istio}'s Container Network Interface (CNI) plugin separately. To install {istio}'s CNI plugin, you create an `IstioCNI` resource. -The `IstioCNI` resource is a cluster-wide resource as it installs a daemon set that operates on all nodes of your cluster. You can select a version by setting the `spec.version` field, as you can see in the example that follows. To update the CNI plugin, change the version field to the version you want to install. Like the `Istio` resource, it also has a `values` field that exposes all of the options provided in the `istio-cni` chart: +The `IstioCNI` resource is a cluster-wide resource as it installs a daemon set that operates on all nodes of your cluster. You can select a version by setting the `spec.version` field, as you can see in the example that follows. To update the CNI plugin, change the version field to the version you want to install. Similar to the `Istio` resource, it also has a `values` field that exposes all of the options provided in the `istio-cni` chart: -.Example `IstioCNI` resource [source,yaml] ---- apiVersion: sailoperator.io/v1 @@ -149,16 +149,4 @@ spec: cniConfDir: /etc/cni/net.d excludeNamespaces: - kube-system ----- - -//commenting out in case it is needed when more resources are added -//[role="_additional-resources"] -//[id="additional-resources_{context}"] -//== Additional resources - - -//== Kiali --> own module -//== Tracing --> own module -//== Metrics --> own module -//== cert-manager --> own module -//== Argo rollouts -- own module \ No newline at end of file +---- \ No newline at end of file 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 6ca29c615ce..2028c3ba9e3 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 @@ -1,10 +1,10 @@ // Module included in the following assemblies: - +// // gateways/ossm-getting-traffic-into-a-mesh.adoc :_mod-docs-content-type: CONCEPT [id="ossm-about-configuring-a-gateway-to-accept-ingress-traffic_{context}"] -= About ingress traffic routing approaches += Approaches to routing ingress traffic [role="_abstract"] @@ -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 can be used for 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. +==== \ No newline at end of file diff --git a/modules/ossm-about-console-plugin.adoc b/modules/ossm-about-console-plugin.adoc index 5ffde4c6258..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] ==== @@ -23,7 +23,7 @@ Traffic Graph:: Provides a full topology view of your mesh, represented by nodes {istio} config:: Provides a list of all {istio} configuration files in your mesh, with a column that provides a quick way to know if the configuration for each resource is valid. -Mesh:: Provides detailed information about the {istio} infrastructure status. It shows an infrastructure topology view with core and add-on components, their health, and how they are connected to each other. +Mesh:: Provides detailed information about the {istio} infrastructure status. It shows an infrastructure topology view with core and add-on components, their health, and how they connect to each other. In the web console *Workloads* details page, the {SMPluginShort} adds a *{SMProductShortName}* tab that has the following subtabs: @@ -31,11 +31,11 @@ Overview:: Shows a summary of the selected workload, including a localized topol Traffic:: Shows information about all inbound and outbound traffic to the workload. -Logs:: Shows the logs for the workload's containers. You can see container logs individually ordered by log time and how the Envoy sidecar proxy logs relate to your workload's application logs. You can enable the tracing span integration, which allows you to see which logs correspond to trace spans. +Logs:: Shows the logs for the workload's containers. You can see container logs individually ordered by log time and how the Envoy sidecar proxy logs relate to your workload's application logs. You can enable tracing span integration to see logs that correspond to specific trace spans. -Metrics:: Shows inbound and outbound metric graphs in the corresponding subtabs. All the workload metrics are here, providing a detailed view of the performance of your workload. You can enable the tracing span integration, which allows you to see which spans occurred at the same time as the metrics. With the span marker in the graph, you can see the specific spans associated with that timeframe. +Metrics:: Shows inbound and outbound metric graphs in the corresponding subtabs. All the workload metrics are here, providing a detailed view of the performance of your workload. You can enable the tracing span integration to see spans that occurred at the same time as the metrics. With the span marker in the graph, you can see the specific spans associated with that time frame. -Traces:: Provides a chart showing the trace spans collected over the given timeframe. The trace spans show the most low-level detail within your workload application. The trace details further show heatmaps that provide a comparison of one span in relation to other requests and spans in the same timeframe. +Traces:: Provides a chart showing the trace spans collected over the given time frame. The trace spans show the lowest-level detail within your workload application. The trace details further show heatmaps that offer a comparison of one span in relation to other requests and spans in the same time frame. Envoy:: Shows information about the Envoy sidecar configuration. diff --git a/modules/ossm-about-control-plane-update-strategies.adoc b/modules/ossm-about-control-plane-update-strategies.adoc new file mode 100644 index 00000000000..ba779d43642 --- /dev/null +++ b/modules/ossm-about-control-plane-update-strategies.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-about-control-plane-update-strategies_{context}"] += Control plane update strategies + +[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. + +InPlace:: +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. + +== 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. + +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 ae31e4647c4..501d7cd7867 100644 --- a/modules/ossm-about-deploying-istio-using-service-mesh-operator.adoc +++ b/modules/ossm-about-deploying-istio-using-service-mesh-operator.adoc @@ -1,12 +1,11 @@ // Module included in the following assemblies: +// // install/ossm-installing-openshift-service-mesh.adoc :_mod-docs-content-type: CONCEPT [id="ossm-about-deploying-istio-using-service-mesh-operator_{context}"] -= About deploying Istio using the {SMProductName} Operator += About deploying {istio} using the {SMProductName} Operator [role="_abstract"] -To deploy {istio} using the {SMProductName} Operator, you must create an `{istio}` resource. Then, the Operator creates an `IstioRevision` resource, which represents one revision of the {istio} control plane. Based on the `IstioRevision` resource, the Operator deploys the {istio} control plane, which includes the `istiod` `Deployment` resource and other resources. - -The {SMProductName} Operator may create additional instances of the `IstioRevision` resource, depending on the update strategy defined in the `{istio}` resource. +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 1346cfd6023..d1f6bac374c 100644 --- a/modules/ossm-about-deploying-multiple-control-planes.adoc +++ b/modules/ossm-about-deploying-multiple-control-planes.adoc @@ -1,19 +1,20 @@ // Module included in the following assemblies: +// // install/ossm-deploying-multiple-service-meshes-on-single-cluster.adoc :_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"] -To configure a cluster to host two control planes, set up separate {istio} resources with unique names in independent {istio} system namespaces. Assign a unique revision name to each {istio} resource to identify the control planes, workloads, or namespaces it manages. Apply these revision names using injection or `istio.io/rev` labels to specify which control plane injects the sidecar proxy into application pods. +You can configure a cluster to host multiple control planes by deploying unique `{istio}` resources in separate namespaces and using revision labels to manage sidecar injection for specific workloads. -Each `{istio}` resource must also configure discovery selectors to specify which namespaces the {istio} control plane observes. Only namespaces with labels that match the configured discovery selectors can join the mesh. Additionally, discovery selectors determine which control plane creates the `istio-ca-root-cert` config map in each namespace, which is used to encrypt traffic between services with mutual TLS within each mesh. +Each `{istio}` resource must also configure discovery selectors to specify which namespaces the {istio} control plane observes. Only namespaces with labels that match the configured discovery selectors can join the mesh. Additionally, discovery selectors determine which control plane creates the `istio-ca-root-cert` config map in each namespace, which encrypts traffic between services with mutual TLS within each mesh. When adding an additional {istio} control plane to a cluster with an existing control plane, ensure that the existing `{istio}` instance has discovery selectors configured to avoid overlapping with the new control plane. [NOTE] ==== -Only one `IstioCNI` resource is shared by all control planes in a cluster, and you must update this resource independent of other cluster resources. +All control planes in a cluster share a single `IstioCNI` resource, and you must update this resource independent of other cluster resources. ==== \ No newline at end of file diff --git a/modules/ossm-about-directing-egress-traffic-through-a-gateway.adoc b/modules/ossm-about-directing-egress-traffic-through-a-gateway.adoc index 78c467ffbc3..370241dd4d7 100644 --- a/modules/ossm-about-directing-egress-traffic-through-a-gateway.adoc +++ b/modules/ossm-about-directing-egress-traffic-through-a-gateway.adoc @@ -1,29 +1,30 @@ // This procedure is used in the following assembly: +// // * gateways/ossm-directing-outbound-traffic-through-a-gateway -:_mod-docs-content-type: PROCEDURE +:_mod-docs-content-type: CONCEPT [id="ossm-about-directing-egress-traffic-through-a-gateway_{context}"] -= About directing egress traffic through a gateway += Approaches to routing egress traffic [role="_abstract"] You can configure a gateway installed through gateway injection as an exit point for traffic leaving the service mesh. It acts as a forward proxy for requests sent to services external to the mesh. -Egress gateway:: An egress gateway is configured as an exit point for traffic leaving the service mesh, acting as a forward proxy for requests sent to external services. You can configure an egress gateway to fulfill security requirements: +Egress gateway:: An egress gateway acts as a forward proxy and serves as the exit point for traffic exiting the service mesh toward external services. You can configure an egress gateway to fulfill security requirements: * Traffic Restrictions: In environments with strict traffic restrictions, an egress gateway ensures all outbound traffic flows through a dedicated set of nodes. * Network Policy Enforcement: When network policies prevent application nodes from directly accessing external services, the egress gateway handles the external access. + -In these scenarios, gateway proxies are deployed on dedicated egress nodes capable of accessing external services. These nodes can then be subjected to strict network policy enforcement or additional monitoring to enhance security. +In these scenarios, you deploy gateway proxies on dedicated egress nodes that can access external services. You can then enforce strict network policies or add monitoring to these nodes to enhance security. Configure egress traffic:: You can configure a gateway installed through gateway injection to direct the egress traffic by combining the following {istio} resources: -* Use the `ServiceEntry` resource to define the properties of an external service. The external service is added to the {istio} service registry for the mesh, which enables you to apply {istio} features, such as monitoring and routing rules, to the traffic exiting the mesh that is destined for an external service. +* The `ServiceEntry` adds the external service to the {istio} service registry. You can then apply {istio} features, such as monitoring and routing rules, to traffic heading toward that external service. * Use the `Gateway`, `VirtualService`, and `DestinationRule` resources to set up rules that route traffic from the mesh to the external service using the gateway proxy. Egress routing in ambient mode:: If your deployment uses ambient mode, you must configure egress routing using the {k8s} Gateway API instead of {istio} `Gateway` and `VirtualService` resources. The {k8s} Gateway API provides a standardized, {k8s}-native method for defining how traffic exits the mesh and reaches external services. + -You can use `Gateway` and `HTTPRoute` (or `GRPCRoute`) resources to control how mesh traffic is routed to destinations outside the cluster. The Gateway API is fully supported in ambient mode and can also be used with sidecar-based deployments, providing a consistent configuration model for both ingress and egress routing. \ No newline at end of file +You can use `Gateway` and `HTTPRoute` (or `GRPCRoute`) resources to route mesh traffic to destinations outside the cluster. {SMProductShortName} fully supports the Gateway API in ambient mode, and you can also use it with sidecar-based deployments, providing a consistent configuration model for both ingress and egress routing. \ No newline at end of file diff --git a/modules/ossm-about-discovery-selectors-istio-ambient-mode.adoc b/modules/ossm-about-discovery-selectors-istio-ambient-mode.adoc index 96120879be0..472ae07a95c 100644 --- a/modules/ossm-about-discovery-selectors-istio-ambient-mode.adoc +++ b/modules/ossm-about-discovery-selectors-istio-ambient-mode.adoc @@ -1,13 +1,13 @@ // Module included in the following assemblies: - +// // * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc :_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 multi-tenant clusters, limiting mesh participation to specific namespaces helps reduce configuration overhead and supports multiple service meshes within the same cluster. +{istio} ambient mode includes workloads when the control plane discovers each workload and the appropriate label enables traffic redirection through the Ztunnel proxy. -For more information on discovery selectors, see "Scoping the Service Mesh with discovery selectors". \ No newline at end of file +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. diff --git a/modules/ossm-about-discoveryselectors.adoc b/modules/ossm-about-discoveryselectors.adoc index f2def5fc3e9..0a657b4cea8 100644 --- a/modules/ossm-about-discoveryselectors.adoc +++ b/modules/ossm-about-discoveryselectors.adoc @@ -1,32 +1,29 @@ // Module included in the following assemblies: +// // install/ossm-installing-openshift-service-mesh.adoc :_mod-docs-content-type: CONCEPT [id="ossm-about-discoveryselectors_{context}"] -= About discovery selectors += How discovery selectors work [role="_abstract"] -With discovery selectors, the mesh administrator can control which namespaces the control plane can access. By using a {k8s} label selector, the administrator sets the criteria for the namespaces visible to the control plane, excluding any namespaces that do not match the specified criteria. +With discovery selectors, the mesh administrator can control the namespaces, which the control plane can access. By using a {k8s} label selector, the administrator sets the criteria for the namespaces visible to the control plane, excluding any namespaces that do not match the specified criteria. [NOTE] ==== -Istiod always opens a watch to {ocp-short-name} for all namespaces. However, discovery selectors ignore objects that are not selected very early in its processing, minimizing costs. +`istiod` always opens a watch to {ocp-short-name} for all namespaces. However, discovery selectors ignore objects that are not selected very early in its processing, minimizing costs. ==== The `discoverySelectors` field accepts an array of {k8s} selectors, which apply to labels on namespaces. You can configure each selector for different use cases: * Custom label names and values. For example, configure all namespaces with the label `istio-discovery=enabled`. -* A list of namespace labels by using set-based selectors with OR logic. For instance, configure namespaces with `istio-discovery=enabled` OR `region=us-east1`. -* Inclusion and exclusion of namespaces. For example, configure namespaces with `istio-discovery=enabled` AND the label `app=helloworld`. + +* A list of namespace labels by using set-based selectors with OR logic. For example, configure namespaces with `istio-discovery=enabled` OR `region=us-east1`. + +* Inclusion and exclusion of namespaces. For example, configure namespaces with `istio-discovery=enabled` and the label `app=helloworld`. [NOTE] ==== -Discovery selectors are not a security boundary. Istiod continues to have access to all namespaces even when you have configured the `discoverySelector` field. -==== - -[role="_additional-resources"] -[id="ossm-about-discoveryselectors-additional-resources_{context}"] -.Additional resources -* link:https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors[Label selectors] (Kubernetes documentation) -* link:https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#resources-that-support-set-based-requirements[Resources that support set-based requirements] (Kubernetes documentation) \ No newline at end of file +Discovery selectors are not a security boundary. `istiod` continues to have access to all namespaces even when you have configured the `discoverySelector` field. +==== \ No newline at end of file diff --git a/modules/ossm-about-distributed-tracing-and-service-mesh.adoc b/modules/ossm-about-distributed-tracing-and-service-mesh.adoc index 804b685fc4c..c69839e977b 100644 --- a/modules/ossm-about-distributed-tracing-and-service-mesh.adoc +++ b/modules/ossm-about-distributed-tracing-and-service-mesh.adoc @@ -4,18 +4,18 @@ :_mod-docs-content-type: CONCEPT [id="ossm-about-distributed-tracing-and-service-mesh_{context}"] -= About {DTProductName} and {SMProductName} += Trace requests across services [role="_abstract"] -Integrating {DTProductName} with {SMProductName} is made of up two parts: {TempoName} and {OTELName}. +Integrate {DTProductName} with {SMProductName} by using {TempoName} for trace storage and {OTELName} for standardized telemetry data collection and processing. -{TempoName}:: Provides distributed tracing to monitor and troubleshoot transactions in complex distributed systems. Tempo is based on the open source link:https://grafana.com/oss/tempo/[Grafana Tempo] project. +{TempoName}:: Provides {DTShortName} to monitor and troubleshoot transactions in complex distributed systems. Tempo derives its core functionality from the open source Grafana Tempo project. + -For more about information about {temposhortname}, its features, installation, and configuration, see: link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/distributed_tracing/distr-tracing-tempo-architecture[{TempoName}]. +For more about information about {temposhortname}, its features, installation, and configuration, see, "{TempoName}". -{OTELName}:: Is based on the open source link:https://opentelemetry.io/[OpenTelemetry project], which aims to provide unified, standardized, and vendor-neutral telemetry data collection for cloud-native software. {OTELName} product provides support for deploying and managing the OpenTelemetry Collector and simplifying the workload instrumentation. +{OTELName}:: Derives its core functionality from the open source "OpenTelemetry project", which aims to offer unified, standardized, and vendor-neutral telemetry data collection for cloud-native software. {OTELName} product provides support for deploying and managing the OpenTelemetry Collector and simplifying the instrumentation of workloads. + -The link:https://opentelemetry.io/docs/collector/[OpenTelemetry Collector] can receive, process, and forward telemetry data in many formats, making it the ideal component for telemetry processing and interoperability between telemetry systems. The Collector provides a unified solution for collecting and processing metrics, traces, and logs. +The "OpenTelemetry Collector" can receive, process, and forward telemetry data in many formats, making it the ideal component for telemetry processing and interoperability between telemetry systems. The Collector provides a unified solution for collecting and processing metrics, traces, and logs. + -For more information about {OTELShortName}, its features, installation, and configuration, see: link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/red_hat_build_of_opentelemetry/index[{OTELName}]. \ No newline at end of file +For more information about {OTELShortName}, its features, installation, and configuration, see: "{OTELName}". \ No newline at end of file diff --git a/modules/ossm-about-exposing-services-to-traffic-outside-a-cluster.adoc b/modules/ossm-about-exposing-services-to-traffic-outside-a-cluster.adoc index f6e389199ca..59d1c81f87f 100644 --- a/modules/ossm-about-exposing-services-to-traffic-outside-a-cluster.adoc +++ b/modules/ossm-about-exposing-services-to-traffic-outside-a-cluster.adoc @@ -1,5 +1,5 @@ // Module included in the following assemblies: - +// // gateways/ossm-about-gateways.adoc :_mod-docs-content-type: CONCEPT @@ -10,10 +10,6 @@ To enable traffic from outside an {ocp-short-name} cluster to access services in a mesh, you must expose a gateway proxy by either setting its `Service` type to `LoadBalancer` or by using the {ocp-short-name} Router. -Using Kubernetes load balancing to handle incoming traffic directly through the inbound gateway can reduce latency associated with data encryption. By managing encryption at the inbound gateway, you avoid the intermediate decryption and re-encryption steps within the mesh that often add latency. This approach allows mesh traffic to be encrypted and decrypted only once, which is generally more efficient. - -The {ocp-short-name} Router provides a standard approach for managing ingress traffic, and you can use the router to manage certificates for all cluster ingress traffic using the same methods. However, the {ocp-short-name} Router introduces an additional hop between the inbound traffic and the mesh applications. Typically, you route the traffic by decrypting it at the router and then re-encrypting it at the service mesh ingress gateway, which introduces latency. - -// If you are using the Gateway API with automatic deployment, this is the default setting. If you are using Gateway Injection, you have to set the field manually. +Using {k8s} load balancing to handle incoming traffic directly through the inbound gateway can reduce latency associated with data encryption. By managing encryption at the inbound gateway, you avoid the intermediate decryption and re-encryption steps within the mesh that often add latency. This approach encrypts and decrypts mesh traffic only once, which is generally more efficient. -// If you are using Gateway API, you must use the networking.istio.io/service-type annotation on the Kubernetes Gateway resource to set the spec.type parameter of the gateway Service. If you are using gateway injection, you have to set the field manually. +The {ocp-short-name} Router provides a standard approach for managing ingress traffic, and you can use the router to manage certificates for all cluster ingress traffic by using the same methods. However, the {ocp-short-name} Router introduces an additional hop between the inbound traffic and the mesh applications. Typically, you route the traffic by decrypting it at the router and then re-encrypting it at the service mesh ingress gateway, which introduces latency. diff --git a/modules/ossm-about-external-control-plane-topology.adoc b/modules/ossm-about-external-control-plane-topology.adoc index 9159971bf24..6627ec73346 100644 --- a/modules/ossm-about-external-control-plane-topology.adoc +++ b/modules/ossm-about-external-control-plane-topology.adoc @@ -1,10 +1,12 @@ // This procedure is used in the following assembly: +// // * install/ossm-multi-cluster-topologies.adoc :_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 allows the Service Mesh to be hosted as a service. In this installation configuration one cluster hosts and manages the {istio} control plane, and applications are hosted on other clusters. +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. \ No newline at end of file diff --git a/modules/ossm-about-gateway-injection.adoc b/modules/ossm-about-gateway-injection.adoc index 3f3178ccc4d..d70a41dead6 100644 --- a/modules/ossm-about-gateway-injection.adoc +++ b/modules/ossm-about-gateway-injection.adoc @@ -1,5 +1,5 @@ // Module included in the following assemblies: - +// // gateways/ossm-about-gateways.adoc :_mod-docs-content-type: CONCEPT @@ -8,5 +8,7 @@ [role="_abstract"] -Gateway injection relies upon the same mechanism as sidecar injection to inject the Envoy proxy into gateway pods. To install a gateway using gateway injection, you create a Kubernetes `Deployment` object and an associated Kubernetes `Service` object in a namespace that is visible to the {istio} control plane. When creating the `Deployment` object you label and annotate it so that the {istio} control plane injects a proxy, and the proxy is configured as a gateway. After installing the gateway, you configure it to control ingress and egress traffic using the {istio} `Gateway` and `VirtualService` resources. +You can install a gateway by applying labels and annotations to {k8s} `Deployment` and `Service` resources, triggering the {istio} control plane to inject and configure the gateway proxy. + +Gateway injection relies upon the same mechanism as sidecar injection to inject the Envoy proxy into gateway pods. To install a gateway by using gateway injection, you create a {k8s} `Deployment` object and an associated {k8s} `Service` object in a namespace that is visible to the {istio} control plane. When creating the `Deployment` object, you apply labels and annotations so the {istio} control plane injects and configures a proxy to act as a gateway. After installing the gateway, you configure it to control ingress and egress traffic by using the {istio} `Gateway` and `VirtualService` resources. diff --git a/modules/ossm-about-ingress-routing-ambient-mode.adoc b/modules/ossm-about-ingress-routing-ambient-mode.adoc index 27e29b95169..e647551fcf5 100644 --- a/modules/ossm-about-ingress-routing-ambient-mode.adoc +++ b/modules/ossm-about-ingress-routing-ambient-mode.adoc @@ -1,5 +1,5 @@ // Module included in the following assemblies: - +// // gateways/ossm-getting-traffic-into-a-mesh.adoc :_mod-docs-content-type: CONCEPT @@ -15,5 +15,5 @@ You can deploy a waypoint proxy in the namespace that has your service to apply [IMPORTANT] ==== -`VirtualService` resources are considered technology preview in ambient mode and should not be mixed with Gateway API configuration. The recommended approach in ambient mode is to use {k8s} Gateway API resources. +{SMProductShortName} classifies `VirtualService` resources as Technology Preview (TP) in ambient mode. Therefore, you should not mix them with Gateway API configuration. The recommended approach in ambient mode is to use {k8s} Gateway API resources. ==== diff --git a/modules/ossm-about-inplace-strategy.adoc b/modules/ossm-about-inplace-strategy.adoc index a0cfc703a8b..296cbeacec1 100644 --- a/modules/ossm-about-inplace-strategy.adoc +++ b/modules/ossm-about-inplace-strategy.adoc @@ -1,14 +1,15 @@ // Module included in the following assemblies: +// // update/ossm-updating-openshift-service-mesh.adoc :_mod-docs-content-type: CONCEPT [id="about-inplace-strategy_{context}"] -= About InPlace strategy += InPlace update strategy [role="_abstract"] -The `InPlace` update strategy runs only one revision of the control plane at a time. During an update, all the workloads immediately connect to the new control plane version. To maintain compatibility between the sidecars and the control plane, you can upgrade only one minor version at a time. +The `InPlace` update strategy runs only one revision of the control plane at a time. During an update, all the workloads immediately connect to the new control plane version. To support compatibility between the sidecars and the control plane, you can upgrade only one minor version at a time. The `InPlace` strategy updates and restarts the existing {istio} control plane in place. During this process, only one instance of the control plane exists, eliminating the need to move workloads to a new control plane instance. To complete the update, restart the application workloads and gateways to refresh the Envoy proxies. -While the `InPlace` strategy offers simplicity and efficiency, there's a slight possibility of application traffic interruption if a workload pod updates, restarts, or scales while the control plane is restarting. You can mitigate this risk by running multiple replicas of the {istio} control plane (istiod). \ No newline at end of file +While the `InPlace` strategy offers simplicity and efficiency, there's a slight possibility of application traffic interruption if a workload pod updates, restarts, or scales while the control plane is restarting. You can mitigate this risk by running many replicas of the {istio} control plane (istiod). \ No newline at end of file diff --git a/modules/ossm-about-installing-console-plugin.adoc b/modules/ossm-about-installing-console-plugin.adoc index 8393b5cf7e7..4a1964425a3 100644 --- a/modules/ossm-about-installing-console-plugin.adoc +++ b/modules/ossm-about-installing-console-plugin.adoc @@ -4,17 +4,18 @@ :_mod-docs-content-type: CONCEPT [id="ossm-about-installing-console-plugin_{context}"] -== About installing {sm-plugin-full} += Console plugin installation requirements [role="_abstract"] -You can install the {SMPluginShort} with the Kiali Operator by creating a `OSSMConsole` resource with the corresponding plugin settings. It is recommended to install the latest version of the Kiali Operator, even while installing a previous {SMPluginShort} version, as it includes the latest z-stream release. +Install the {SMPluginShort} by creating an `OSSMConsole` resource with the Kiali Operator to enable integrated service mesh management within the {ocp-short-name} console. + +You must install the latest version of the Kiali Operator, even while installing a earlier {SMPluginShort} version, because it includes the latest z-stream release. + +OSSM version compatibility:: -.OSSM version compatibility [options="header"] |=== -|OSSM version |Kiali Server version |OSSMC plugin version |OCP version - |3.1 |v2.11 |v2.11 |4.16+ |3.0 |v2.4 |v2.4 |4.15+ @@ -24,9 +25,9 @@ You can install the {SMPluginShort} with the Kiali Operator by creating a `OSSMC |2.5 |v1.73 |v1.73 |4.14-4.18 |=== +You can install the {SMPluginShort} by using the {ocp-product-title} web console or the {oc-first}. + [NOTE] ==== {SMPluginShort} is only supported on {ocp-product-title} 4.15 and above. For {ocp-product-title} 4.14 users, only the standalone Kiali console is accessible. -==== - -You can install the {SMPluginShort} by using the {ocp-product-title} web console or the {oc-first}. \ No newline at end of file +==== \ No newline at end of file diff --git a/modules/ossm-about-istio-ambient-mode.adoc b/modules/ossm-about-istio-ambient-mode.adoc index 54bd22fa3e1..f5b090c4fc0 100644 --- a/modules/ossm-about-istio-ambient-mode.adoc +++ b/modules/ossm-about-istio-ambient-mode.adoc @@ -1,43 +1,36 @@ // Module included in the following assemblies: - +// // * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc :_mod-docs-content-type: CONCEPT [id="ossm-about-istio-ambient-mode_{context}"] -= About Istio ambient mode += Ambient mode architecture [role="_abstract"] To understand the {istio} ambient mode architecture, see the following definitions: -ZTunnel proxy:: A per-node proxy that manages secure, transparent Transmission Control Protocol (TCP) connections for all workloads on the node. It operates at Layer 4 (L4), offloading mutual Transport Layer Security (mTLS) and L4 policy enforcement from application pods. +`ztunnel` proxy:: A per-node proxy that manages secure, transparent Transmission Control Protocol (TCP) connections for all workloads on the node. It operates at Layer 4 (L4), offloading mutual Transport Layer Security (mTLS) and L4 policy enforcement from application pods. -Waypoint proxy:: An optional proxy that runs per service account or namespace to provide advanced Layer 7 (L7) features such as traffic management, policy enforcement, and observability. You can apply L7 features selectively to avoid the overhead of sidecars for every service. +Waypoint proxy:: An optional proxy that runs per service account or namespace to offer advanced Layer 7 (L7) features such as traffic management, policy enforcement, and observability. You can apply L7 features selectively to avoid the resource cost of sidecars for every service. -Istio CNI plugin:: Redirects traffic to the Ztunnel proxy on each node, enabling transparent interception without requiring modifications to application pods. +Istio Container Network Interface (CNI) plugin:: Redirects traffic to the `ztunnel` proxy on each node, enabling transparent interception without requiring modifications to application pods. {Istio} ambient mode offers the following benefits: * *Simplified operations* that remove the need to manage sidecar injection, reducing the complexity of mesh adoption and operations. -* *Reduced resource consumption* with a per-node Ztunnel proxy that provides L4 service mesh features and an optional `waypoint` proxy that reduces resource overhead per pod. +* *Reduced resource consumption* with a per-node Ztunnel proxy that provides L4 service mesh features and an optional `waypoint` proxy that reduces resource consumption per pod. -* *Incremental adoption* that enables workloads to join the mesh with the L4 features like mutual Transport Layer Security (mTLS) and basic policies with optional `waypoint` proxies added later to use L7 service mesh features, such as HTTP(L7) traffic management. +* *Incremental adoption* that enables workloads to join the mesh with the L4 features such as mutual Transport Layer Security (mTLS) and basic policies with optional `waypoint` proxies added later to use L7 service mesh features, such as HTTP(L7) traffic management. + [NOTE] ==== -The L7 features require deploying `waypoint` proxies, which introduces minimal additional overhead for the selected services. +The L7 features require deploying `waypoint` proxies, which introduces minimal additional resource usage for the selected services. ==== * *Enhanced security* that provides a secure, zero-trust network foundation with mTLS by default for all meshed workloads. -[NOTE] -==== -Ambient mode is a newer architecture and may involve different operational considerations than traditional sidecar models. -==== - -While well-defined discovery selectors allow a service mesh deployed in ambient mode alongside a mesh in sidecar mode, this scenario has not been thoroughly validated. To avoid potential conflicts, install {istio} ambient mode only on clusters that do not have an existing {SMProductName} installation. Ambient mode remains a Technology Preview feature. - [IMPORTANT] ==== {istio} ambient mode is not compatible with clusters that use {SMProductName} 2.6 or earlier. You must not install or use them together. diff --git a/modules/ossm-about-istio-ambient-waypoint.adoc b/modules/ossm-about-istio-ambient-waypoint.adoc index 846c4e9a420..98e55a074c6 100644 --- a/modules/ossm-about-istio-ambient-waypoint.adoc +++ b/modules/ossm-about-istio-ambient-waypoint.adoc @@ -1,10 +1,10 @@ // Module included in the following assemblies: - +// // * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc :_mod-docs-content-type: CONCEPT [id="ossm-about-istio-ambient-waypoint_{context}"] -= About waypoint proxies in Istio ambient mode += Waypoint proxies in Istio ambient mode [role="_abstract"] @@ -18,11 +18,11 @@ After setting up {istio} ambient mode with ztunnel proxies, you can add waypoint A waypoint proxy is an Envoy-based proxy that performs L7 processing for workloads running in ambient mode. It functions as a gateway to a resource such as a namespace, service, or pod. You can install, upgrade, and scale waypoint proxies independently of applications. The configuration uses the {k8s} Gateway API. -Unlike the sidecar model, where each workload runs its own Envoy proxy, waypoint proxies reduce resource use by serving multiple workloads within the same security boundary, such as all workloads in a namespace. +You can lower resource usage in {SMProductName} by using waypoint proxies to serve many workloads within a shared security boundary, such as a namespace, instead of running a separate proxy for every pod. A destination waypoint enforces policies by acting as a gateway. All incoming traffic to a resource, such as a namespace, service, or pod, passes through the waypoint for policy enforcement. -The `ztunnel` node proxy manages L4 functions in ambient mode, including mutual Transport Layer Security (mTLS) encryption, L4 traffic processing, and telemetry. Ztunnel and waypoint proxies communicate using HBONE (HTTP-Based Overlay Network), a protocol that tunnels traffic over HTTP/2 CONNECT with mutual TLS (mTLS) on port `15008`. +The `ztunnel` node proxy manages L4 functions in ambient mode, including mutual Transport Layer Security (mTLS) encryption, L4 traffic processing, and telemetry. Ztunnel and waypoint proxies communicate using HTTP-Based Overlay Network (HBONE), a protocol that tunnels traffic over HTTP/2 CONNECT to mutual TLS (mTLS) on port `15008`. You can add a waypoint proxy if workloads require any of the following L7 capabilities: diff --git a/modules/ossm-about-istio-cni-update-process.adoc b/modules/ossm-about-istio-cni-update-process.adoc index 8b4527f6af0..8c470f267f5 100644 --- a/modules/ossm-about-istio-cni-update-process.adoc +++ b/modules/ossm-about-istio-cni-update-process.adoc @@ -1,10 +1,10 @@ // Module included in the following assemblies: - +// // update/ossm-updating-openshift-service-mesh.adoc :_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 66a7afee6d2..e960475e967 100644 --- a/modules/ossm-about-istio-control-plane-update-strategies.adoc +++ b/modules/ossm-about-istio-control-plane-update-strategies.adoc @@ -1,13 +1,16 @@ // Module included in the following assemblies: +// // update/ossm-updating-openshift-service-mesh.adoc :_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"] -The update strategy affects how the update process is performed. The `spec.updateStrategy` field in the `{istio}` resource configuration determines how the {SMProduct} Operator updates the {istio} control plane. When the Operator detects a change in the `spec.version` field or identifies a new minor release with a configured `vX.Y-latest` alias, it initiates an upgrade procedure. For each mesh, you select one of two strategies: +The update strategy affects how the Operator performs the update. The `spec.updateStrategy` field in the `{istio}` resource configuration determines how the {SMProduct} Operator updates the {istio} control plane. + +When the Operator detects a change in the `spec.version` field or identifies a new minor release with a configured `vX.Y-latest` alias, it initiates an upgrade procedure. For each mesh, you select one of two strategies: * `InPlace` * `RevisionBased` @@ -18,6 +21,6 @@ If you use ambient mode, you must update the {istio} Container Network Interface [IMPORTANT] ==== -The `InPlace` update strategy is recommended for ambient mode. Using `RevisionBased` updates with ambient mode has limitations and requires manual intervention. +{SMProductShortName} recommends the `InPlace` update strategy for ambient mode. Using `RevisionBased` updates with ambient mode has limitations and requires manual intervention. ==== diff --git a/modules/ossm-about-istio-deployment.adoc b/modules/ossm-about-istio-deployment.adoc index 987ea26b0b2..e1a39a98796 100644 --- a/modules/ossm-about-istio-deployment.adoc +++ b/modules/ossm-about-istio-deployment.adoc @@ -1,17 +1,21 @@ // Module included in the following assemblies: +// // install/ossm-installing-openshift-service-mesh.adoc :_mod-docs-content-type: CONCEPT [id="about-istio-deployment_{context}"] -= About Istio deployment += Deploy in sidecar mode [role="_abstract"] -To deploy {istio}, you must create two resources: `Istio` and `IstioCNI`. The `Istio` resource deploys and configures the {istio} Control Plane. The `IstioCNI` resource deploys and configures the {istio} Container Network Interface (CNI) plugin. You should create these resources in separate projects; therefore, you must create two projects as part of the {istio} deployment process. +To deploy {istio} in sidecar mode, you must create two resources: `Istio` and `IstioCNI`. The `Istio` resource deploys and configures the {istio} control plane. The `IstioCNI` resource deploys and configures the {istio} Container Network Interface (CNI) plugin. + +You should create these resources in separate projects; therefore, you must create two projects as part of the deployment process. You can use the {ocp-short-name} web console or the OpenShift CLI (oc) to create a project or a resource in your cluster. [NOTE] ==== -In the {ocp-product-title}, a project is essentially a Kubernetes namespace with additional annotations, such as the range of user IDs that can be used in the project. Typically, the {ocp-product-title} web console uses the term project, and the CLI uses the term namespace, but the terms are essentially synonymous. +In the {ocp-product-title}, a project functions as a {k8s} namespace with additional annotations that define the allowed range of user IDs. Typically, the {ocp-product-title} web console uses the term project, and the CLI uses the term namespace, but the terms are essentially synonymous. ==== + diff --git a/modules/ossm-about-istio-high-availability.adoc b/modules/ossm-about-istio-high-availability.adoc index 7a8ab36ffca..93e25f45b89 100644 --- a/modules/ossm-about-istio-high-availability.adoc +++ b/modules/ossm-about-istio-high-availability.adoc @@ -1,16 +1,19 @@ // This module is used in the following assemblies: +// // * service-mesh-docs-main/install/ossm-installing-service-mesh.adoc :_mod-docs-content-type: CONCEPT [id="ossm-about-istio-high-availability_{context}"] -= About Istio High Availability += {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. 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. +Running the {istio} control plane in High Availability (HA) mode ensures continuous mesh operation even if an `istiod` pod fails. + +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: * Defining a static replica count: This approach involves setting a fixed number of `istiod` pods, providing a consistent level of redundancy. -* Using autoscaling: This approach dynamically adjusts the number of `istiod` pods based on resource utilization or custom metrics, providing more efficient resource consumption for fluctuating workloads. \ No newline at end of file +* Using autoscaling: This approach dynamically adjusts the number of `istiod` pods based on resource usage or custom metrics, providing more efficient resource consumption for fluctuating workloads. \ No newline at end of file diff --git a/modules/ossm-about-istio-update-process.adoc b/modules/ossm-about-istio-update-process.adoc index 37c12076f6c..02c25793f87 100644 --- a/modules/ossm-about-istio-update-process.adoc +++ b/modules/ossm-about-istio-update-process.adoc @@ -1,10 +1,10 @@ // Module included in the following assemblies: - +// // * update/ossm-updating-openshift-service-mesh.adoc :_mod-docs-content-type: CONCEPT [id="ossm-about-istio-update-process_{context}"] -= About Istio update process += Control plane update process [role="_abstract"] @@ -12,11 +12,11 @@ After updating the {SMProduct} Operator, update the {istio} control plane to the The `{istio}` resource configuration includes the following fields that are relevant to the upgrade process: -`spec.version`:: specifies the version of {istio} to install. Use the format `vX.Y.Z`, where `X.Y.Z` is the desired {istio} release. For example, set the field to `v1.24.4` to install {istio} `1.24.4`. Alternatively, set the value to an alias such as `vX.Y-latest` to automatically install the latest supported patch version for the specified minor release. +`spec.version`:: specifies the version of {istio} to install. Use the format `vX.Y.Z`, where `X.Y.Z` is the required {istio} release. For example, set the field to `v1.24.4` to install {istio} `1.24.4`. Or, set the value to an alias such as `vX.Y-latest` to automatically install the latest supported patch version for the specified minor release. `spec.updateStrategy`:: defines the strategy for updating the {istio} control plane. The available update strategies are `InPlace` and `RevisionBased`. [NOTE] ==== -To enable automatic patch upgrades, set the approval strategy of the Operator to `Automatic`. When the Operator detects a new patch release and the `version` field uses the `vX.Y-latest` alias, the control plane is updated based on the configured `updateStrategy` type. +To enable automatic patch upgrades, set the approval strategy of the Operator to `Automatic`. When the Operator detects a new patch release and the `version` field uses the `vX.Y-latest` alias, it updates the control plane based on the configured `updateStrategy` type. ==== \ No newline at end of file diff --git a/modules/ossm-about-l7-features-ambient-mode.adoc b/modules/ossm-about-l7-features-ambient-mode.adoc index be8383b3e71..7f07b012467 100644 --- a/modules/ossm-about-l7-features-ambient-mode.adoc +++ b/modules/ossm-about-l7-features-ambient-mode.adoc @@ -1,5 +1,5 @@ // Module included in the following assemblies: - +// // * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc :_mod-docs-content-type: CONCEPT @@ -10,8 +10,8 @@ Ambient mode includes stable Layer 7 (L7) capabilities implemented through the Gateway API `HTTPRoute` resource and the {istio} `AuthorizationPolicy` resource. -The `AuthorizationPolicy` resource works in both sidecar and ambient modes. In ambient mode, authorization policies can be targeted for `ztunnel` enforcement or attached for waypoint enforcement. To attach a policy to a waypoint, include a `targetRef` that references either the waypoint itself or a Service configured to use that waypoint. +The `AuthorizationPolicy` resource works in both sidecar and ambient modes. In ambient mode, you can target authorization policies for ztunnel enforcement or attach them for waypoint enforcement. To attach a policy to a waypoint, include a `targetRef` that references either the waypoint itself or a Service configured to use that waypoint. -You can attach Layer 4 (L4) or L7 policies to the waypoint proxy to ensure correct identity-based enforcement, as the destination `ztunnel` recognizes traffic by the identity of the waypoint, once it is part of the traffic path. +You can attach Layer 4 (L4) or L7 policies to the waypoint proxy to ensure correct identity-based enforcement. The destination `ztunnel` recognizes traffic by the identity of the waypoint, after it is part of the traffic path. -{istio} peer authentication policies, which configure mutual TLS (mTLS) modes, are supported by ztunnel. In ambient mode, policies that set the mode to `DISABLE` are ignored because ztunnel and HBONE always enforce mTLS. For more information, see "Peer authentication". \ No newline at end of file +{istio} peer authentication policies, which configure mutual TLS (mTLS) modes, are supported by ztunnel. In ambient mode, ztunnel and HTTP-Based Overlay Network Environment (HBONE) ignore policies that set the mode to DISABLE because they always enforce mTLS. For more information, see "Peer authentication". \ No newline at end of file diff --git a/modules/ossm-about-metrics-and-observability.adoc b/modules/ossm-about-metrics-and-observability.adoc new file mode 100644 index 00000000000..eb3f689aa56 --- /dev/null +++ b/modules/ossm-about-metrics-and-observability.adoc @@ -0,0 +1,37 @@ +// Module included in the following assemblies: +// +// * TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-observability-planning_{context}"] += Metrics and observability in {SMProductShortName} + +[role="_abstract"] + +You can use mesh telemetry data to monitor service health, track performance, and diagnose problems. + +== How metrics are collected + +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 {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. + +== Tools for viewing mesh metrics + +The following tools surface the metrics that the mesh generates: + +{ocp-product-title} monitoring:: +Provides dashboards and alerting based on the metrics that Prometheus collects. +You can monitor CPU and memory usage, network connectivity, and request performance for meshed workloads. + +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 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. +{SMProductShortName} integrates with the {DTProductName} to collect and visualize traces. diff --git a/modules/ossm-about-metrics.adoc b/modules/ossm-about-metrics.adoc index 2c96c14902f..061fe999e95 100644 --- a/modules/ossm-about-metrics.adoc +++ b/modules/ossm-about-metrics.adoc @@ -4,14 +4,27 @@ :_mod-docs-content-type: CONCEPT [id="ossm-about-metrics_{context}"] -= About metrics += Collect mesh metrics for service health and dashboards [role="_abstract"] -Monitoring stack components are deployed by default in every {ocp-product-title} installation and are managed by the Cluster Monitoring Operator (CMO). 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 facilitate Remote Health Monitoring for clusters. +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. -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. +[id="monitoring-stack_{context}"] +== Monitoring stack -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. +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. -Ambient mode uses two proxy layers, which results in two types of metrics for each application service. You can collect Layer 4 (L4) TCP metrics from both the ztunnel and the waypoint proxies. You can collect Layer 7 (L7) metrics, such as HTTP traffic metrics, from the waypoint proxies. \ No newline at end of file +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 + +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 new file mode 100644 index 00000000000..39770ab3a6e --- /dev/null +++ b/modules/ossm-about-mtls-planning.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-about-mtls-planning_{context}"] += Mutual TLS in a service mesh + +[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. + +== 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. + +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. + +== 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. + +== 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 408f6da1240..0695454adcd 100644 --- a/modules/ossm-about-mtls.adoc +++ b/modules/ossm-about-mtls.adoc @@ -1,23 +1,19 @@ // Module included in the following assemblies: +// // install/ossm-enabling-mtls.adoc - :_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: +Review the following `{istio}` resources and concepts to configure mTLS settings properly: -`PeerAuthentication`:: defines the type of mTLS traffic a sidecar accepts. In `PERMISSIVE` mode, both plaintext and mTLS traffic are accepted. In `STRICT` mode, only mTLS traffic is allowed. +`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.. -`DestinationRule`:: configures the type of TLS traffic a sidecar sends. In `DISABLE` mode, the sidecar sends plaintext. In `SIMPLE`, `MUTUAL`, and `ISTIO_MUTUAL` modes, the sidecar establishes a TLS connection. +`DestinationRule`:: configures the type of TLS traffic a sidecar sends. In `DISABLE` mode, the sidecar sends plain text. In `SIMPLE`, `MUTUAL`, and `ISTIO_MUTUAL` modes, the sidecar establishes a TLS connection. -`Auto mTLS`:: ensures that all inter-mesh traffic is encrypted with mTLS by default, regardless of the `PeerAuthentication` mode configuration. `Auto mTLS` is controlled by the global mesh configuration field `enableAutoMtls`, which is enabled by default in {SMProduct} 2 and 3. The mTLS setting operates entirely between sidecar proxies, requiring no changes to application or service code. +`Auto mTLS`:: ensures the mesh uses mTLS by default to encrypt all inter-mesh traffic, regardless of the `PeerAuthentication` mode configuration. The `enableAutoMtls` global mesh configuration field controls `Auto mTLS`, which {SMProduct} 2 and 3 enable by default. The mTLS setting operates entirely between sidecar proxies, requiring no changes to application or service code. -By default, `PeerAuthentication` is set to `PERMISSIVE` mode, allowing sidecars in the {SMProductShortName} to accept both plain-text and mTLS-encrypted traffic. \ No newline at end of file +By default, `PeerAuthentication` uses `PERMISSIVE` mode, allowing sidecars in the {SMProductShortName} to accept both plain text and mTLS-encrypted traffic. \ No newline at end of file diff --git a/modules/ossm-about-multi-cluster-mesh-topologies.adoc b/modules/ossm-about-multi-cluster-mesh-topologies.adoc index 755e66cc252..6a9d5838daf 100644 --- a/modules/ossm-about-multi-cluster-mesh-topologies.adoc +++ b/modules/ossm-about-multi-cluster-mesh-topologies.adoc @@ -1,31 +1,38 @@ // This module is used in the following assemblies: - +// // * install/ossm-multi-cluster-topologies.adoc :_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"] -In a multi-cluster mesh topology, you install and manage a single {istio} mesh across multiple {ocp-product-title} clusters, enabling communication and service discovery between the services. Two factors determine the multi-cluster mesh topology: control plane topology and network topology. There are two options for each topology. Therefore, there are four possible multi-cluster mesh topology configurations. +In a multi-cluster mesh topology, you install and manage a single {istio} mesh across many {ocp-product-title} clusters, enabling communication and service discovery between the services. + +Two factors decide the multi-cluster mesh topology: control plane topology and network topology. There are two options for each topology. Therefore, there are four possible multi-cluster mesh topology configurations. -* Multi-Primary Single Network: Combines the multi-primary control plane topology and the single network network topology models. +* Multi-Primary Single Network: Combines the multi-primary control plane topology and the single network topology models. * Multi-Primary Multi-Network: Combines the multi-primary control plane topology and the multi-network network topology models. ++ +[IMPORTANT] +==== +For {SMProduct} in ambient mode, _multi-primary multi-network_ is the only supported configuration. +==== -* Primary-Remote Single Network: Combines the primary-remote control plane topology and the single network network topology models. +* Primary-Remote Single Network: Combines the primary-remote control plane topology and the single network topology models. -* Primary-Remote Multi-Network: Combines the primary-remote control plane topology and the multi-network network topology models. +* Primary-Remote Multi-Network: Combines the primary-remote control plane topology and the multi-network topology models. [id="ossm-control-plane-topology-models_{context}"] == Control plane topology models A multi-cluster mesh must use one of the following control plane topologies: -* Multi-Primary: In this configuration, a control plane resides on every cluster. Each control plane observes the API servers in all of the other clusters for services and endpoints. +* Multi-Primary: In this configuration, a control plane is present on every cluster. Each control plane observes the API servers in all of the other clusters for services and endpoints. -* Primary-Remote: In this configuration, the control plane resides only on one cluster, called the primary cluster. No control plane runs on any of the other clusters, called remote clusters. The control plane on the primary cluster discovers services and endpoints and configures the sidecar proxies for the workloads in all clusters. +* Primary-Remote: In this configuration, the control plane is present only on one cluster, called the primary cluster. No control plane runs on any of the other clusters, called remote clusters. The control plane on the primary cluster discovers services and endpoints and configures the sidecar proxies for the workloads in all clusters. [id="ossm-network-topology-models_{context}"] == Network topology models @@ -34,4 +41,4 @@ A multi-cluster mesh must use one of the following network topologies: * Single Network: All clusters reside on the same network and there is direct connectivity between the services in all the clusters. There is no need to use gateways for communication between the services across cluster boundaries. -* Multi-Network: Clusters reside on different networks and there is no direct connectivity between services. Gateways must be used to enable communication across network boundaries. +* Multi-Network: Clusters reside on different networks and there is no direct connectivity between services. Gateways enable communication across network boundaries. \ No newline at end of file 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-operator-update-process.adoc b/modules/ossm-about-operator-update-process.adoc index 1c167d56e7d..fe44dd82c7d 100644 --- a/modules/ossm-about-operator-update-process.adoc +++ b/modules/ossm-about-operator-update-process.adoc @@ -8,6 +8,8 @@ [role="_abstract"] -The {SMProduct} Operator will upgrade automatically to the latest available version based on the selected channel when the *approval strategy* field is set to `Automatic` (default). If the *approval strategy* field is set to `Manual`, {olm-first} will generate an update request, which a cluster administrator must approve to update the Operator to the latest version. +Manage the lifecycle of the {SMProduct} Operator and the {istio} control plane by configuring OLM approval strategies and resource update settings for automated or manual upgrades. -The Operator update process does not automatically update the {istio} control plane unless the `{istio}` resource version is set to an alias (for example, `vX.Y-latest`) and the `updateStrategy` is set to `InPlace`. This triggers a control plane update when a new version is available in the Operator. By default, the Operator will not update the {istio} control plane unless the `{istio}` resource is updated with a new version. \ No newline at end of file +The {SMProduct} Operator upgrades automatically to the latest available version based on the selected channel when you set the *approval strategy* field to `Automatic` (default). If you set the *approval strategy* field to `Manual`, {olm-first} generates an update request, which a cluster administrator must approve to update the Operator to the latest version. + +The Operator update process does not automatically update the {istio} control plane unless you set the `{istio}` resource version to an alias (for example, `vX.Y-latest`) and the `updateStrategy` to `InPlace`. This triggers a control plane update when a new version is available in the Operator. By default, the Operator will not update the {istio} control plane unless the `{istio}` resource is updated with a new version. \ No newline at end of file diff --git a/modules/ossm-about-operator-updates-delivery.adoc b/modules/ossm-about-operator-updates-delivery.adoc new file mode 100644 index 00000000000..cc0262f7083 --- /dev/null +++ b/modules/ossm-about-operator-updates-delivery.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-about-operator-updates-delivery_{context}"] += How Operator updates are delivered + +[role="_abstract"] + +Operator Lifecycle Manager (OLM) delivers {SMProductShortName} Operator updates through channels. Your choice of channel controls which updates are available, and your approval strategy controls when they are applied: + +Stable channel:: +Tracks the most recent Operator version and the latest supported Istio version. +New Operator versions and Istio updates are available immediately after release. + +Versioned channel:: +Restricts updates to patch releases within a specific minor version. +For example, the `stable-3.0` channel provides only `3.0.z` patch updates. +To move to a new minor version such as `3.1`, you must manually switch to the `stable-3.1` channel. + +Automatic approval:: +OLM applies available updates without manual intervention. + +Manual approval:: +OLM notifies you when an update is available, and you approve it before it is applied. + +An Operator update delivers a new Operator binary and might bundle multiple Istio versions. +However, updating the Operator does not automatically update the Istio control plane. diff --git a/modules/ossm-about-pqc-service-mesh.adoc b/modules/ossm-about-pqc-service-mesh.adoc index 4c19d7331a1..a4d3dc1cf04 100644 --- a/modules/ossm-about-pqc-service-mesh.adoc +++ b/modules/ossm-about-pqc-service-mesh.adoc @@ -4,15 +4,18 @@ :_mod-docs-content-type: CONCEPT [id="ossm-about-pqc-service-mesh_{context}"] -= About {pqc-short} in service mesh += {pqc} ({pqc-short}) in {SMProductName} -{pqc}, also known as quantum-resistant cryptography, uses encryption algorithms designed to resist attacks from quantum computers. +[role="_abstract"] -Quantum computers use principles of quantum mechanics to perform certain calculations significantly faster than classical computers, compromising widely used cryptographic algorithms. +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. -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. +{pqc} addresses this threat by introducing quantum-resistant key exchange algorithms. You can enable {pqc-short} in {SMProductName} to protect: -In {SMProductName}, cryptographic algorithms protect control plane and data plane communications, including mutual TLS (mTLS) between workloads. Enabling PQC strengthens these communications by introducing quantum-resistant key exchange mechanisms while maintaining compatibility with existing infrastructure. +* *Mesh-internal traffic* — mTLS communication between workloads, in both sidecar and ambient modes +* *Gateway traffic* — TLS connections at ingress and egress gateways + +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 c97f3278f98..685e5eecd17 100644 --- a/modules/ossm-about-revisionbased-strategy.adoc +++ b/modules/ossm-about-revisionbased-strategy.adoc @@ -1,14 +1,15 @@ // Module included in the following assemblies: +// // update/ossm-updating-openshift-service-mesh.adoc :_mod-docs-content-type: CONCEPT [id="about-revisionbased-strategy_{context}"] -= About RevisionBased strategy += RevisionBased update strategy [role="_abstract"] The `RevisionBased` strategy runs two revisions of the control plane during an upgrade. This approach supports gradual workload migration from the old control plane to the new one, enabling canary upgrades. It also supports upgrades across more than one minor version. -The `RevisionBased` strategy creates a new {istio} control plane instance for each change to the `spec.version` field. The existing control plane remains active until all workloads transition to the new instance. You can move the workloads to the new control plane by updating the `istio.io/rev` labels or using the `IstioRevisionTag` resource, followed by a restart. +The `RevisionBased` strategy creates a new {istio} control plane instance for each change to the `spec.version` field. The existing control plane remains active until all workloads move to the new instance. You can move the workloads to the new control plane by updating the `istio.io/rev` labels or using the `IstioRevisionTag` resource, followed by a restart. -Although the `RevisionBased` strategy involves additional steps and requires multiple control plane instances to run concurrently during the upgrade, it allows for gradual migration of workloads. This approach enables validation of the updated control plane with a subset of workloads before migrating the rest, making it useful for large meshes with mission-critical workloads. \ No newline at end of file +Although the `RevisionBased` strategy involves additional steps and requires many control plane instances to run concurrently during the upgrade, it allows for gradual migration of workloads. This approach enables validation of the updated control plane with a subset of workloads before migrating the rest, making it useful for large meshes with mission-critical workloads. \ No newline at end of file diff --git a/modules/ossm-about-service-mesh-custom-resource-definitions.adoc b/modules/ossm-about-service-mesh-custom-resource-definitions.adoc index 4d5e10ed9c3..49660951076 100644 --- a/modules/ossm-about-service-mesh-custom-resource-definitions.adoc +++ b/modules/ossm-about-service-mesh-custom-resource-definitions.adoc @@ -1,4 +1,5 @@ // Module included in the following assemblies: +// // * install/ossm-installing-openshift-service-mesh.adoc :_mod-docs-content-type: CONCEPT @@ -7,8 +8,14 @@ [role="_abstract"] -Installing the {SMProductName} Operator also installs custom resource definitions (CRD) that administrators can use to configure {istio} for {SMProductShortName} installations. The {olm-first} installs two categories of CRDs: {sail-operator} CRDs and {istio} CRDs. +Installing the {SMProductName} Operator also installs custom resource definitions (CRD) that administrators can use to configure {istio} for {SMProductShortName} installations. -{sail-operator} CRDs define custom resources for installing and maintaining the {istio} components required to operate a service mesh. These custom resources belong to the `sailoperator.io` API group and include the `Istio`, `IstioRevision`, `IstioCNI`, and `ZTunnel` resource kinds. For more information on how to configure these resources, see the `sailoperator.io` link:https://github.com/istio-ecosystem/sail-operator/blob/main/docs/api-reference/sailoperator.io.md[API reference] documentation. +The {olm-first} installs two categories of CRDs: -{istio} CRDs are associated with mesh configuration and service management. These CRDs define custom resources in several `istio.io` API groups, such as `networking.istio.io` and `security.istio.io`. The CRDs also include various resource kinds, such as `AuthorizationPolicy`, `DestinationRule`, and `VirtualService`, that administrators use to configure a service mesh. \ No newline at end of file +* {sail-operator} CRDs + +* {istio} CRDs. + +{sail-operator} CRDs define custom resources for installing and maintaining the {istio} components required to operate a service mesh. These custom resources belong to the `sailoperator.io` API group and include the `Istio`, `IstioRevision`, `IstioCNI`, and `ZTunnel` resource kinds. + +You can use {istio} CRDs to configure the mesh and manage your services. These CRDs define custom resources in several `istio.io` API groups, such as `networking.istio.io` and `security.istio.io`. The CRDs also include various resource kinds, such as `AuthorizationPolicy`, `DestinationRule`, and `VirtualService`, that administrators use to configure a service mesh. \ No newline at end of file diff --git a/modules/ossm-about-sidecar-injection.adoc b/modules/ossm-about-sidecar-injection.adoc index 8b7d4413cca..6273caa1566 100644 --- a/modules/ossm-about-sidecar-injection.adoc +++ b/modules/ossm-about-sidecar-injection.adoc @@ -1,16 +1,19 @@ // Module included in the following assemblies: +// // install/ossm-sidecar-injection :_mod-docs-content-type: CONCEPT [id="ossm-about-sidecar-injection_{context}"] -= About sidecar injection += Inject sidecars [role="_abstract"] -Sidecar injection is enabled using labels at the namespace or pod level. These labels also indicate the specific control plane managing the proxy. When you apply a valid injection label to the pod template defined in a deployment, any new pods created by that deployment automatically receive a sidecar. Similarly, applying a pod injection label at the namespace level ensures any new pods in that namespace include a sidecar. +When you apply a valid injection label, any new pods automatically receive a sidecar proxy. Injection happens at pod creation through an admission controller, so changes appear on individual pods rather than the deployment resources. -[NOTE] -==== -Injection happens at pod creation through an admission controller, so changes appear on individual pods rather than the deployment resources. To confirm sidecar injection, check the pod details directly using `oc describe`, where you can see the injected {istio} proxy container. -==== +You can enable sidecar injection by using one of the following methods: +Namespace labels:: Apply an injection label to a namespace to inject sidecars into all workloads in that namespace. This is the simplest approach when you want to include most workloads in the mesh. + +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. diff --git a/modules/ossm-about-sidecar-proxies.adoc b/modules/ossm-about-sidecar-proxies.adoc new file mode 100644 index 00000000000..1d1cbcc7400 --- /dev/null +++ b/modules/ossm-about-sidecar-proxies.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// * TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-about-sidecar-proxies_{context}"] += Sidecar proxy architecture + +[role="_abstract"] + +In sidecar mode, each application pod in the mesh receives a dedicated proxy container that runs alongside the application container. This proxy intercepts all inbound and outbound network traffic for the pod, enabling the mesh to apply traffic management, security, and observability features without requiring changes to application code. + +To understand the sidecar proxy architecture, see the following definitions: + +Sidecar proxy:: A per-pod proxy that intercepts all inbound and outbound TCP traffic for the application container in the same pod. It operates at both Layer 4 (L4) and Layer 7 (L7), handling mutual Transport Layer Security (mTLS) encryption, traffic routing, policy enforcement, and telemetry collection. + +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} 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: + +* *Per-pod isolation* that gives each workload its own dedicated proxy, providing fine-grained control over traffic management, security policies, and observability at the individual pod level. + +* *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. + +Sidecar mode has the following operational considerations: + +* *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. + +* *Injection management* because sidecar injection must be configured through namespace or pod labels, and workloads that are deployed before injection is enabled require a restart to join the mesh. diff --git a/modules/ossm-about-uninstalling-console-plugin.adoc b/modules/ossm-about-uninstalling-console-plugin.adoc index 97ebee74f06..bc5e3705b7d 100644 --- a/modules/ossm-about-uninstalling-console-plugin.adoc +++ b/modules/ossm-about-uninstalling-console-plugin.adoc @@ -4,13 +4,13 @@ :_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"] You can uninstall the {SMPluginShort} by using the {ocp-product-title} web console or the {oc-first}. -You must uninstall the {SMPluginShort} before removing the Kiali Operator. Deleting the Operator first may leave OSSMC and Kiali CRs stuck, requiring manual removal of the finalizer. Use the following command with `` as `kiali` or `ossmconsole` to remove the finalizer, if needed: +You must uninstall the {SMPluginShort} before removing the Kiali Operator. Deleting the Operator first might leave OSSMC and Kiali CRs stuck, requiring manual removal of the finalizer. Use the following command with `` as `kiali` or `ossmconsole` to remove the finalizer, if needed: [source,terminal] ---- diff --git a/modules/ossm-about-update-strategies-in-ambient-mode.adoc b/modules/ossm-about-update-strategies-in-ambient-mode.adoc index 4aedab5caa4..15e37641faf 100644 --- a/modules/ossm-about-update-strategies-in-ambient-mode.adoc +++ b/modules/ossm-about-update-strategies-in-ambient-mode.adoc @@ -4,11 +4,11 @@ :_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"] -In ambient mode, components update directly through `InPlace` updates. Unlike sidecar mode, ambient mode allows you to move application pods to an upgraded ztunnel proxy without restarting or rescheduling the pods. +In ambient mode, components update directly through `InPlace` updates. In ambient mode, you can move application pods to an upgraded ztunnel proxy without restarting or rescheduling them, unlike sidecar mode. Update sequence:: To update in ambient mode, use the following sequence: @@ -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-about-upgrades-by-data-plane-mode.adoc b/modules/ossm-about-upgrades-by-data-plane-mode.adoc new file mode 100644 index 00000000000..67868e00403 --- /dev/null +++ b/modules/ossm-about-upgrades-by-data-plane-mode.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-about-upgrades-by-data-plane-mode_{context}"] += How upgrades differ by data plane mode + +[role="_abstract"] + +The data plane mode you choose when deploying the mesh affects how upgrades are applied to your workloads. + +Sidecar mode:: +After a control plane update, the new control plane distributes a new proxy version. You must restart workloads so each pod receives the new proxy. +Both `InPlace` and `RevisionBased` strategies are fully supported in sidecar mode. + +Ambient mode:: +The ztunnel and waypoint proxies update independently of application workloads, so you do not need to restart workloads. +Red Hat recommends the `InPlace` strategy for ambient mode. `RevisionBased` updates in ambient mode have limitations and require manual intervention. diff --git a/modules/ossm-accessing-bookinfo-application-using-gateway-api.adoc b/modules/ossm-accessing-bookinfo-application-using-gateway-api.adoc index b0f7a85241e..ff08c2c0825 100644 --- a/modules/ossm-accessing-bookinfo-application-using-gateway-api.adoc +++ b/modules/ossm-accessing-bookinfo-application-using-gateway-api.adoc @@ -1,25 +1,31 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/install/ossm-installing-service-mesh.adoc + :_mod-docs-content-type: PROCEDURE [id="ossm-accessing-bookinfo-application-using-gateway-api"] = Accessing the Bookinfo application by using Gateway API [role="_abstract"] -The {k8s} Gateway API deploys a gateway by creating a `Gateway` resource. In {ocp-product-title} 4.15 and later, {SMProductName} implements the Gateway API custom resource definitions (CRDs). However, in {ocp-product-title} 4.18 and earlier, the CRDs are not installed by default. Hence, in {ocp-product-title} 4.15 through 4.18, you must manually install the CRDs. Starting with {ocp-product-title} 4.19, these CRDs are automatically installed and managed, and you can no longer create, update, or delete them. +Manage gateway resources in {SMProductName} by using the {k8s} Gateway API, which transitioned from manual installation to automated platform management in recent {ocp-product-title} releases. + +In {ocp-product-title} 4.15 and later, {SMProductName} implements the Gateway API custom resource definitions (CRDs). However, in {ocp-product-title} 4.18 and earlier, the CRDs are not installed by default. Therefore, in {ocp-product-title} 4.15 through 4.18, you must manually install the CRDs. Starting with {ocp-product-title} 4.19, these CRDs are automatically installed and managed, and you can no longer create, update, or delete them. For details about enabling Gateway API for Ingress in {ocp-product-title} 4.19 and later, see "Configuring ingress cluster traffic" in the {ocp-product-title} documentation. [NOTE] ==== -Red{nbsp}Hat provides support for using the {k8s} Gateway API with {SMProductName}. Red{nbsp}Hat does not provide support for the {k8s} Gateway API custom resource definitions (CRDs). In this procedure, the use of community Gateway API CRDs is shown for demonstration purposes only. +Red{nbsp}Hat provides support for using the {k8s} Gateway API with {SMProductName}. Red{nbsp}Hat does not offer support for the {k8s} Gateway API custom resource definitions (CRDs). This procedure uses community Gateway API CRDs for demonstration purposes only. ==== .Prerequisites -* You are logged in to the {ocp-product-title} web console as `cluster-admin`. +* You have logged in to the {ocp-product-title} web console as `cluster-admin`. -* The {SMProductName} Operator must be installed. +* You have installed the {SMProductName} Operator. -* The {istio} resource must be deployed. +* You have deployed the `{istio}` resource. .Procedure @@ -39,7 +45,7 @@ $ oc apply -f https://raw.githubusercontent.com/openshift-service-mesh/istio/rel + [NOTE] ==== -To configure a gateway with the `bookinfo` application by using the Gateway API, this example uses a sample gateway configuration file that must be applied in the namespace where the application is installed. +To configure a gateway with the `bookinfo` application by using the Gateway API, this example provides a sample gateway configuration file that you must apply to the application's namespace. ==== . Ensure that the Gateway API service is ready, and has an address allocated by running the following command: @@ -70,7 +76,7 @@ $ export INGRESS_PORT=$(oc get gtw bookinfo-gateway -n bookinfo -o jsonpath='{.s $ export GATEWAY_URL=$INGRESS_HOST:$INGRESS_PORT ---- -. Obtain the gateway host name and the URL of the product page by running the following command: +. Obtain the gateway hostname and the URL of the product page by running the following command: + [source,terminal] ---- diff --git a/modules/ossm-accessing-bookinfo-application-using-istio-gateway-injection.adoc b/modules/ossm-accessing-bookinfo-application-using-istio-gateway-injection.adoc index b5050e84294..f38c1e34f94 100644 --- a/modules/ossm-accessing-bookinfo-application-using-istio-gateway-injection.adoc +++ b/modules/ossm-accessing-bookinfo-application-using-istio-gateway-injection.adoc @@ -1,4 +1,5 @@ // Module included in the following assemblies: +// // install/ossm-installing-openshift-service-mesh.adoc :_mod-docs-content-type: PROCEDURE @@ -7,15 +8,15 @@ [role="_abstract"] -Gateway injection uses the same mechanisms as {istio} sidecar injection to create a gateway from a `Deployment` resource that is paired with a `Service` resource. The `Service` resource can be made accessible from outside an {ocp-product-title} cluster. +Gateway injection uses the same mechanisms as {istio} sidecar injection to create a gateway from a `Deployment` resource coupled with a `Service` resource. The `Service` resource is accessible from outside an {ocp-product-title} cluster. .Prerequisites -* You are logged in to the {ocp-product-title} web console as `cluster-admin`. +* You have logged in to the {ocp-product-title} web console as `cluster-admin`. -* The {SMProductName} Operator must be installed. +* You have installed the {SMProductName} Operator. -* The {istio} resource must be deployed. +* You have deployed the `{istio}` resource. .Procedure @@ -28,7 +29,7 @@ $ oc apply -n bookinfo -f ingress-gateway.yaml + [NOTE] ==== -This example uses a sample `ingress-gateway.yaml` https://raw.githubusercontent.com/istio-ecosystem/sail-operator/main/chart/samples/ingress-gateway.yaml[file] that is available in the Istio community repository. +This example uses a sample `ingress-gateway.yaml` https://raw.githubusercontent.com/istio-ecosystem/sail-operator/main/chart/samples/ingress-gateway.yaml[file] that is available in the {istio} community repository. ==== . Configure the `bookinfo` application to use the new gateway. Apply the gateway configuration by running the following command: @@ -40,7 +41,7 @@ $ oc apply -f https://raw.githubusercontent.com/openshift-service-mesh/istio/rel + [NOTE] ==== -To configure gateway injection with the `bookinfo` application, this example uses a sample gateway configuration file that must be applied in the namespace where the application is installed. +To configure gateway injection with the `bookinfo` application, this example provides a sample gateway configuration file that you must apply in the application's namespace. ==== . Use a route to expose the gateway external to the cluster by running the following command: @@ -50,9 +51,10 @@ To configure gateway injection with the `bookinfo` application, this example use $ oc expose service istio-ingressgateway -n bookinfo ---- -. Modify the YAML file to automatically scale the pod when ingress traffic increases. +. Change the YAML file to automatically scale the pod when ingress traffic increases. ++ +You can see the following example configuration for reference: + -.Example configuration [source,yaml] ---- apiVersion: autoscaling/v2 @@ -64,7 +66,7 @@ metadata: name: ingressgatewayhpa namespace: bookinfo spec: - maxReplicas: 5 <1> + maxReplicas: 5 metrics: - resource: name: cpu @@ -78,11 +80,13 @@ spec: kind: Deployment name: istio-ingressgateway ---- -<1> This example sets the the maximum replicas to `5` and the minimum replicas to `2`. It also creates another replica when utilization reaches 80%. ++ +* `spec.maxReplicas` shows an example that sets the maximum replicas to `5` and the minimum replicas to `2`. It also creates another replica when usage reaches 80%. . Specify the minimum number of pods that must be running on the node. + -.Example configuration +You can see the following example configuration for reference: ++ [source,yaml] ---- apiVersion: policy/v1 @@ -94,14 +98,15 @@ metadata: name: ingressgatewaypdb namespace: bookinfo spec: - minAvailable: 1 <1> + minAvailable: 1 selector: matchLabels: istio: ingressgateway ---- -<1> This example ensures one replica is running if a pod gets restarted on a new node. ++ +`spec.minAvailable` shows an example that ensures one replica is running if a pod gets restarted on a new node. -. Obtain the gateway host name and the URL for the product page by running the following command: +. Obtain the gateway hostname and the URL for the product page by running the following command: + [source,terminal] ---- diff --git a/modules/ossm-adding-authorization-policy.adoc b/modules/ossm-adding-authorization-policy.adoc index bf3b5bd7420..eb6c25ed9a4 100644 --- a/modules/ossm-adding-authorization-policy.adoc +++ b/modules/ossm-adding-authorization-policy.adoc @@ -1,20 +1,29 @@ // Module included in the following assemblies: - +// // * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc :_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 . Create the authorization policy similar to the following example: + -.Example configuration +You can see the following example configuration for reference: ++ [source,yaml] ---- apiVersion: security.istio.io/v1 @@ -44,7 +53,7 @@ spec: ---- $ oc apply -f authorization-policy.yaml ---- - ++ [NOTE] ==== The `targetRefs` field specifies the service targeted by the authorization policy of the waypoint proxy. @@ -81,7 +90,7 @@ $ oc -n curl exec deploy/curl -- sh -c \ 'curl -s -o /dev/null -w "HTTP %{http_code}\n" http://productpage.bookinfo.svc.cluster.local:9080/productpage' ---- -. Verify that a `POST` request to the same service is denied with an HTTP 403 response due to the applied authorization policy, by running the following command: +. Verify that the applied authorization policy denies a `POST` request to the same service with an HTTP 403 response, by running the following command: + [source,terminal] ---- diff --git a/modules/ossm-api-settings-mesh-ha-autoscaling.adoc b/modules/ossm-api-settings-mesh-ha-autoscaling.adoc index 5ad74595380..e77790f216d 100644 --- a/modules/ossm-api-settings-mesh-ha-autoscaling.adoc +++ b/modules/ossm-api-settings-mesh-ha-autoscaling.adoc @@ -1,4 +1,5 @@ // This module is used in the following assemblies: +// // * service-mesh-docs-main/install/ossm-installing-service-mesh.adoc :_mod-docs-content-type: REFERENCE @@ -7,26 +8,26 @@ [role="_abstract"] -Use the following `istio` custom resource definition (CRD) parameters when you configure a service mesh for High Availability (HA) by using autoscaling. +Use the following `{istio}` custom resource definition (CRD) parameters when you configure a service mesh for High Availability (HA) by using autoscaling. .HA API parameters [cols="1,1"] |=== |Parameter |Description -|`autoScaleMin` | Defines the minimum number of `istiod` pods for an istio deployment. Each pod contains one instance of the {istio} control plane. +|`autoScaleMin` | Defines the minimum number of `istiod` pods for an istio deployment. Each pod has one instance of the {istio} control plane. -{ocp-short-name} only uses this parameter when the Horizontal Pod Autoscaler (HPA) is enabled for the {istio} deployment. This is the default behavior. -|`autoScaleMax` | Defines the maximum number of `istiod` pods for an {istio} deployment. Each pod contains one instance of the {istio} control plane. +{ocp-short-name} uses this parameter only if you enable the Horizontal Pod Autoscaler (HPA) for the {istio} deployment. This is the default behavior. +|`autoScaleMax` | Defines the maximum number of `istiod` pods for an {istio} deployment. Each pod has one instance of the {istio} control plane. For {ocp-short-name} to automatically scale the number of `istiod` pods based on load, you must set this parameter to a value that is greater than the value that you defined for the `autoScaleMin` parameter. -You must also configure metrics for autoscaling to work properly. If no metrics are configured, the autoscaler does not scale up or down. +You must also configure metrics for autoscaling to work properly. If you do not configure any metrics, the autoscaler cannot scale the deployment up or down. -{ocp-short-name} only uses this parameter when Horizontal Pod Autoscaler (HPA) is enabled for the {istio} deployment. This is the default behavior. -|`cpu.targetAverageUtilization` | Defines the target CPU utilization for the `istiod` pod. If the average CPU usage exceeds the threshold that this parameter defines, the HPA automatically increases the number of replica pods. -|`memory.targetAverageUtilization` | Defines the target memory utilization for the `istiod` pod. If the average memory usage exceeds the threshold that this parameter defines, the HPA automatically increases the number of replica pods. +{ocp-short-name} uses this parameter only if you enable the Horizontal Pod Autoscaler (HPA) for the {istio} deployment. This is the default behavior. +|`cpu.targetAverageUtilization` | Defines the target CPU usage for the `istiod` pod. If the average CPU usage exceeds the threshold that this parameter defines, the HPA automatically increases the number of replica pods. +|`memory.targetAverageUtilization` | Defines the target memory usage for the `istiod` pod. If the average memory usage exceeds the threshold that this parameter defines, the HPA automatically increases the number of replica pods. |`behavior` | You can use the `behavior` field to define additional policies that {ocp-short-name} uses to scale {istio} resources up or down. -For more information, see link:https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/#configurable-scaling-behavior[Configurable Scaling Behavior]. +For more information, see "Configurable Scaling Behavior". |=== 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 580ceb4efc4..f162ba35e02 100644 --- a/modules/ossm-applying-certificates-to-a-multi-cluster-topology.adoc +++ b/modules/ossm-applying-certificates-to-a-multi-cluster-topology.adoc @@ -1,10 +1,10 @@ // This module is used in the following assemblies: - +// // * install/ossm-multi-cluster-topologies.adoc :_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"] @@ -32,7 +32,7 @@ In this procedure, `CLUSTER1` is the East cluster and `CLUSTER2` is the West clu $ oc login -u https:// ---- -.. Set up the environment variable that contains the `oc` command context for the East cluster by running the following command: +.. Set up the environment variable that has the `oc` command context for the East cluster by running the following command: + [source,terminal] ---- @@ -66,7 +66,7 @@ $ oc get secret -n istio-system --context "${CTX_CLUSTER1}" cacerts || oc create + [NOTE] ==== -If you followed the instructions in "Creating certificates for a multi-cluster mesh", your certificates will reside in the `east/` directory. If your certificates reside in a different directory, modify the syntax accordingly. +If you followed the instructions in "Creating certificates for a multi-cluster mesh", your certificates will be present in the `east/` directory. If your certificates are present in a different directory, change the syntax. ==== . Apply the certificates to the West cluster of the multi-cluster topology: @@ -78,7 +78,7 @@ If you followed the instructions in "Creating certificates for a multi-cluster m $ oc login -u https:// ---- -.. Set up the environment variable that contains the `oc` command context for the West cluster by running the following command: +.. Set up the environment variable that has the `oc` command context for the West cluster by running the following command: + [source,terminal] ---- @@ -112,9 +112,9 @@ $ oc get secret -n istio-system --context "${CTX_CLUSTER2}" cacerts || oc create + [NOTE] ==== -If you followed the instructions in "Creating certificates for a multi-cluster mesh", your certificates will reside in the `west/` directory. If the certificates reside in a different directory, modify the syntax accordingly. +If you followed the instructions in "Creating certificates for a multi-cluster mesh", your certificates will be present in the `west/` directory. If your certificates are present in a different directory, change the syntax. ==== .Next steps -Install {istio} on all the clusters comprising the mesh topology. \ No newline at end of file +* Install {istio} on all the clusters comprising the mesh topology. \ No newline at end of file diff --git a/modules/ossm-architecture-control-data-plane.adoc b/modules/ossm-architecture-control-data-plane.adoc new file mode 100644 index 00000000000..44f639d5d80 --- /dev/null +++ b/modules/ossm-architecture-control-data-plane.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// + +:_mod-docs-content-type: CONCEPT +[id="ossm-architecture-control-data-plane_{context}"] += Service Mesh architecture + +[role="_abstract"] + +{SMProductName} separates its operational responsibilities into two distinct architectural layers: the control plane and the data plane. The control plane acts as the brain of the service mesh, and the data plane executes the decisions made by the control plane. + +[id="ossm-control-plane-functions_{context}"] +== What the control plane does + +The control plane (`istiod`) compiles high-level routing rules, security policies, and cryptographic credentials into low-level configurations. It then distributes them to the data plane proxies. The control plane performs the following functions: + +* Translates Kubernetes and {istio} custom resources (CRs) into proxy configurations. +* Acts as a Certificate Authority (CA) and issues short-lived X.509 certificates to workloads for mutual TLS (mTLS) authentication. +* Tracks active services, pods, and endpoints within the cluster. + +[id="ossm-data-plane-functions_{context}"] +== What the data plane does + +The data plane executes the security, traffic, and policy configurations made by the control plane. It intercepts network traffic entering, leaving, or flowing between services. Depending on your operational requirements, the data plane can run in sidecar mode or ambient mode. diff --git a/modules/ossm-cert-manager-planning.adoc b/modules/ossm-cert-manager-planning.adoc new file mode 100644 index 00000000000..ed5a09980d3 --- /dev/null +++ b/modules/ossm-cert-manager-planning.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// * TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-cert-manager-planning_{context}"] += Certificate management with cert-manager + +[role="_abstract"] + +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. + +== What cert-manager does + +The cert-manager tool automates the issuance, renewal, and rotation of X.509 certificates in a {k8s} environment. +It connects to certificate authorities through a unified API, so you can use a single tool to manage certificates regardless of the CA provider. + +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. + +== When to use cert-manager + +The built-in CA is sufficient for many deployments. +Consider using cert-manager when your organization has any of the following requirements: + +* Certificates must come from a specific CA, such as Vault, Let's Encrypt, or a private enterprise CA. +* Compliance or security policies require centralized certificate lifecycle management. +* 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. + +== Compatibility + +The cert-manager integration works with both sidecar and ambient data plane modes. +For multi-cluster deployments, you must configure cert-manager on every cluster that hosts a control plane, using the same root CA to establish cross-cluster trust. diff --git a/modules/ossm-choose-data-plane-mode.adoc b/modules/ossm-choose-data-plane-mode.adoc new file mode 100644 index 00000000000..b18fa338efc --- /dev/null +++ b/modules/ossm-choose-data-plane-mode.adoc @@ -0,0 +1,36 @@ +// Module included in the following assemblies: +// +// TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-choose-data-plane-mode_{context}"] += Choose how to handle service-to-service traffic + +[role="_abstract"] + +Before you deploy {SMProductName}, you must choose a data plane mode. +This is one of the most consequential decisions in your mesh deployment because it determines how you install, secure, manage, and upgrade the mesh. + +{SMProductShortName} supports two data plane modes: *sidecar mode* and *ambient mode*. +Each mode uses a different proxy architecture to intercept and manage traffic between services. + +[id="how-your-choice-of-mode-affects-the-mesh_{context}"] +== How your choice of mode affects the mesh + +The data plane mode you choose shapes how you work with the mesh at every stage, from initial deployment through Day 2 operations. +The following areas are affected: + +Deployment and enrollment:: +Each mode has its own installation procedure, namespace labels, and method for adding workloads to the mesh. + +Upgrades:: +The two modes handle control plane updates differently, including whether workloads require a restart to pick up new proxy versions. + +Traffic management:: +Sidecar mode and ambient mode use different API resources to configure routing, retries, and other traffic policies. + +Security and authorization:: +Authorization policy enforcement, supported security integrations, and the resources required for Layer 7 policy differ between modes. + +Resource consumption:: +The two modes distribute proxy resources differently across nodes and pods, which affects CPU and memory usage at scale. diff --git a/modules/ossm-cluster-wide-migration-methods.adoc b/modules/ossm-cluster-wide-migration-methods.adoc index acb2ae1c7b8..5c6c69ac48f 100644 --- a/modules/ossm-cluster-wide-migration-methods.adoc +++ b/modules/ossm-cluster-wide-migration-methods.adoc @@ -1,5 +1,5 @@ // Module included in the following assemblies: - +// // * service-mesh-docs-main/migrating/cluster-wide/ossm-migrating-cluster-wide.adoc :_mod-docs-content-type: CONCEPT diff --git a/modules/ossm-config-dt-ambient-mode.adoc b/modules/ossm-config-dt-ambient-mode.adoc index 1963bdb715c..d6d03775f8e 100644 --- a/modules/ossm-config-dt-ambient-mode.adoc +++ b/modules/ossm-config-dt-ambient-mode.adoc @@ -4,18 +4,21 @@ :_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"] -You can configure a {TempoShortName} with {SMProduct} ambient mode by using waypoint or gateway proxies to generate Layer 7 (L7) spans. The `ztunnel` component generates only Layer 4 (L4) data, so L7 spans appear only when a workload or service uses an attached proxy. +Generate Layer 7 (L7) tracing spans in {SMProduct} ambient mode by using waypoint or gateway proxies to capture application-level telemetry that the Layer 4 (L4) `ztunnel` component does not offer. .Prerequisites -* You have installed the {TempoOperator}. For more information see: link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/distributed_tracing/distr-tracing-tempo-installing#installing-the-tempo-operator_distr-tracing-tempo-installing[Installing the Tempo Operator]. -* You have installed the {OTELOperator}. For more information see: link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/red_hat_build_of_opentelemetry/install-otel[Installing the Red Hat build of OpenTelemetry] -* You have installed a `TempoStack` which is configured in a `tempo` namespace. For more information see: link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/distributed_tracing/distr-tracing-tempo-installing#installing-a-tempostack-instance_distr-tracing-tempo-installing[Installing a TempoStack instance]. -* You have created an {istio} instance. +* You have installed the {TempoOperator}. For more information, see "Installing the Tempo Operator". + +* You have installed the {OTELOperator}. For more information, see "Installing the Red Hat build of OpenTelemetry". + +* You have installed a `TempoStack` and configured it in a `tempo` namespace. For more information, see "Installing a `TempoStack` instance". + +* You have created an `{istio}` instance. .Procedure @@ -105,4 +108,4 @@ spec: After you can see the traces, lower the `randomSamplingPercentage` value or set it to `default` to reduce the number of requests. You can also use the `spec.targetRefs` field to enable tracing at a gateway or a waypoint level. ==== -. Optional: Use a single {istio} Telemetry resource for both a Prometheus metrics provider and a tracing provider by setting `spec.metrics.overrides.disabled` field to `false`. This enables the Prometheus metrics provider. You do not need this step if you have configured metrics through the OpenShift Cluster Monitoring approach described in the previous step. +. Optional: Use a single {istio} Telemetry resource for both a Prometheus metrics provider and a tracing provider by setting `spec.metrics.overrides.disabled` field to `false`. This enables the Prometheus metrics provider. You do not need this step if you have configured metrics through the OpenShift Cluster Monitoring approach described in the earlier step. diff --git a/modules/ossm-config-openshift-monitoring-ambient-mode.adoc b/modules/ossm-config-openshift-monitoring-ambient-mode.adoc index 2ee1087bcd5..7cb6efd332b 100644 --- a/modules/ossm-config-openshift-monitoring-ambient-mode.adoc +++ b/modules/ossm-config-openshift-monitoring-ambient-mode.adoc @@ -4,20 +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 and is required to run Kiali, 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 link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/monitoring/configuring-user-workload-monitoring[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 @@ -116,8 +117,8 @@ spec: where: `mesh_id`:: Specify the actual mesh ID. -`\\d+`:: The additional backslash is only used when you apply this replacement from a command line via heredoc. If you apply this from a yaml file, replace `\\d+` with `\d+`. -`\$`:: The backslash is only used when you apply this replacement from a command line via heredoc. If you apply this from a yaml file, replace `\$` with `$`. +`\\d+`:: The additional backslash is only used when you apply this replacement from a command line through heredoc. If you apply this from a YAML file, replace `\\d+` with `\d+`. +`\$`:: The backslash is only used when you apply this replacement from a command line through heredoc. If you apply this from a YAML file, replace `\$` with `$`. . Optional: Deploy a waypoint proxy to enable the Layer 7 (L7) {SMProduct} features in ambient mode: @@ -206,11 +207,11 @@ spec: where: `mesh_id`:: Specify the actual mesh ID. -`\\d+`:: The additional backslash is only used when you apply this replacement from a command line via heredoc. If you apply this from a yaml file, replace `\\d+` with `\d+`. -`\$`:: The backslash is only used when you apply this replacement from a command line via heredoc. If you apply this from a yaml file, replace `\$` with `$`. +`\\d+`:: The additional backslash is only used when you apply this replacement from a command line through heredoc. If you apply this from a YAML file, replace `\\d+` with `\d+`. +`\$`:: The backslash is only used when you apply this replacement from a command line through heredoc. If you apply this from a YAML file, replace `\$` with `$`. + [NOTE] ==== -A waypoint proxy generates Layer 4 (L4) and L7 metrics. It scopes these statistics by Envoy proxy functions. The Envoy statistic functions are described in Envoy proxy documentation, for example, `Upstream connection`, `Listener`, `HTTP Connection Manager`, `TCP proxy`, and `Router`. +A waypoint proxy generates Layer 4 (L4) and L7 metrics. It scopes these statistics by Envoy proxy functions. The Envoy proxy documentation describes the statistic functions, for example, `Upstream connection`, `Listener`, `HTTP Connection Manager`, `TCP proxy`, and `Router`. ==== diff --git a/modules/ossm-config-openshift-monitoring-kiali.adoc b/modules/ossm-config-openshift-monitoring-kiali.adoc index 76fc0b469c9..aba134d124c 100644 --- a/modules/ossm-config-openshift-monitoring-kiali.adoc +++ b/modules/ossm-config-openshift-monitoring-kiali.adoc @@ -4,27 +4,26 @@ :_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 -* {SMProductName} is installed. +* You have installed {SMProductName}. -* User-workload monitoring is enabled. See link:https://docs.openshift.com/container-platform/4.16/observability/monitoring/enabling-monitoring-for-user-defined-projects.html[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. -* OpenShift Monitoring has been configured with {SMProductShortName}. See "Configuring OpenShift Monitoring with Service Mesh". +* You have configured OpenShift Monitoring with {SMProductShortName}. -* {KialiProduct} 2.4 is installed. +* You have {KialiProduct} 2.4 or a later version installed. .Procedure -. Create a `ClusterRoleBinding` resource for Kiali: +. Create a `ClusterRoleBinding` resource for Kiali similar to the following example: + -.Example `ClusterRoleBinding` configuration [source,yaml] ---- apiVersion: rbac.authorization.k8s.io/v1 @@ -41,9 +40,8 @@ subjects: namespace: istio-system ---- -. Create a Kiali resource and point it to your Istio instance: +. Create a `Kiali` resource and point it to your {istio} instance similar to the following example: + -.Example Kiali resource configuration [source,yaml] ---- apiVersion: kiali.io/v1alpha1 @@ -62,7 +60,7 @@ spec: url: https://thanos-querier.openshift-monitoring.svc.cluster.local:9091 ---- -. When the Kiali resource is ready, get the Kiali URL from the Route by running the following command: +. When the `Kiali` resource is ready, get the Kiali URL from the Route by running the following command: + [source,terminal] ---- diff --git a/modules/ossm-config-openshift-monitoring-only.adoc b/modules/ossm-config-openshift-monitoring-only.adoc index c9996a61e70..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 and is required to run Kiali, 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 link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/monitoring/configuring-user-workload-monitoring[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 @@ -116,10 +116,10 @@ spec: + where: -`istio-system`:: Specifies that the `PodMonitor` object must be applied in all mesh namespaces, including the {istio} control plane namespace, because {ocp-product-title} monitoring ignores the `namespaceSelector` spec in `ServiceMonitor` and `PodMonitor` objects. +`istio-system`:: Specifies that you must apply the `PodMonitor` object in all mesh namespaces, including the {istio} control plane namespace, because {ocp-product-title} monitoring ignores the `namespaceSelector` spec in `ServiceMonitor` and `PodMonitor` objects. `mesh_id`:: Specify the actual mesh ID. -`\\d+`:: The additional backslash is only used when you apply this replacement from a command line via heredoc. If you apply this from a yaml file, replace `\\d+` with `\d+`. -`\$`:: The backslash is only used when you apply this replacement from a command line via heredoc. If you apply this from a yaml file, replace `\$` with `$`. +`\\d+`:: The additional backslash is only used when you apply this replacement from a command line through heredoc. If you apply this from a YAML file, replace `\\d+` with `\d+`. +`\$`:: The backslash is only used when you apply this replacement from a command line through heredoc. If you apply this from a YAML file, replace `\$` with `$`. . To validate that the `ServiceMonitor` and `PodMonitor` resources are monitoring the {istio} control plane, go to the {ocp-short-name} Console, navigate to *Observe* -> *Metrics*, and run the query `istio_requests_total`. Confirm that the metrics for the {istio} request are displayed. + diff --git a/modules/ossm-config-otel-kiali.adoc b/modules/ossm-config-otel-kiali.adoc index 32fb9488d69..d51b64d1395 100644 --- a/modules/ossm-config-otel-kiali.adoc +++ b/modules/ossm-config-otel-kiali.adoc @@ -4,49 +4,48 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-config-otel-kiali_{context}"] -= Configuring {DTProductName} with {KialiProduct} += Configure {DTProductName} with {KialiProduct} [role="_abstract"] -After you integrate {KialiProduct} with {DTProductName}, you can view distributed traces in the Kiali console. Viewing traces provides insight into the communication between services within the service mesh, helping you understand how requests are flowing through your system and where potential issues might reside. +Analyze service communication and troubleshoot request flows within the mesh by viewing distributed traces directly in the Kiali console. .Prerequisites -* You installed {SMProductName}. - -* You configured {DTShortName} with {SMProductName}. +* You have configured {DTShortName} with {SMProductName}. .Procedure . Update the `Kiali` resource `spec` configuration for tracing: + -.Example `Kiali` resource `spec` configuration for tracing +*Example `Kiali` resource `spec` configuration for tracing:* ++ [source,yaml] ---- spec: external_services: tracing: - enabled: true #<1> - provider: tempo #<2> + enabled: true + provider: tempo use_grpc: false - internal_url: https://tempo-sample-gateway.tempo.svc.cluster.local:8080/api/traces/v1/default/tempo #<3> + internal_url: https://tempo-sample-gateway.tempo.svc.cluster.local:8080/api/traces/v1/default/tempo external_url: https://tempo-sample-gateway-tempo.apps-crc.testing/api/traces/v1/default/search #<4> - health_check_url: https://tempo-sample-gateway-tempo.apps-crc.testing/api/traces/v1/default/tempo/api/echo #<5> + health_check_url: https://tempo-sample-gateway-tempo.apps-crc.testing/api/traces/v1/default/tempo/api/echo auth: #<6> ca_file: /var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt insecure_skip_verify: false type: bearer use_kiali_token: true tempo_config: - url_format: "jaeger" #<7> + url_format: "jaeger" ---- -<1> Specifies whether tracing is enabled. -<2> Specifies either {TempoShortName} or {JaegerShortName}. The {DTShortName} can expose a Jaeger API or a Tempo API. -<3> Specifies the internal URL for the Tempo API. When you deploy the {DTShortName} in multitenancy, include the tenant name in the URL path of the `internal_url` parameter. In this example, `default` represents the tenant name. -<4> Specifies the {ocp-short-name} route for the Jaeger UI. When you deploy the {DTShortName} in multitenancy, the gateway creates the route. Otherwise, you must create the route in the `Tempo` namespace. You can manually create the route for the `tempo-sample-query-frontend` service or update the `Tempo` custom resource with `.spec.template.queryFrontend.jaegerQuery.ingress.type: route`. -<5> Specifies the health check URL. Not required by default. When you deploy the {DTShortName} in multitenancy, it does not expose the default health check URL. This is an example of a valid health URL. -<6> Specifies the configuration used when the access URL is `HTTPS` or requires authentication. Not required by default. -<7> Specifies the configuration that defaults to `grafana`. Not required by default. Change to `jaeger` if the Kiali `View in tracing` link redirects to the Jaeger console UI. +* `spec.external_services.tracing.enabled` specifies whether you have enabled tracing. +* `spec.external_services.tracing.provider` specifies either {TempoShortName} or {JaegerShortName}. The {DTShortName} can expose a Jaeger API or a Tempo API. +* `spec.external_services.tracing.internal_url` specifies the internal URL for the Tempo API. When you deploy the {DTShortName} in multitenancy, include the tenant name in the URL path of the `internal_url` parameter. In this example, `default` represents the tenant name. +* `spec.external_services.tracing.external_url` specifies the external URL for the Jaeger UI. When you deploy the {DTShortName} in multitenancy, the gateway creates the route. Otherwise, you must create the route in the `Tempo` namespace. You can manually create the route for the `tempo-sample-query-frontend` service or update the `Tempo` custom resource with `.spec.template.queryFrontend.jaegerQuery.ingress.type: route`. +* `spec.external_services.tracing.health_check_url` specifies the health check URL. Not required by default. When you deploy the {DTShortName} in multitenancy, it does not expose the default health check URL. This is an example of a valid health URL. +* `spec.external_services.tracing.auth` specifies the configuration used when the access URL is `HTTPS` or requires authentication. Not required by default. +* `spec.external_services.tracing.tempo_config.url_format` specifies the configuration that defaults to `grafana`. Not required by default. Change to `jaeger` if the Kiali `View in tracing` link redirects to the Jaeger console UI. . Save the updated `spec` in `kiali_cr.yaml`. @@ -57,7 +56,7 @@ spec: $ oc patch -n istio-system kiali kiali --type merge -p "$(cat kiali_cr.yaml)" ---- + -.Example output: +*Example output:* + [source, terminal] ---- @@ -75,11 +74,4 @@ $ oc get route kiali ns istio-system . Navigate to the Kiali UI. -. Navigate to *Workload* → *Traces* tab to see traces in the Kiali UI. - -//Notes 10/30/2024: -//Grafana info removed for TP1. Requires further discussion for GA on the best user path, in addition to changes coming from Tempo that may or may not be ready when OSSM 3.0 GA's. - -//Note for later: there are things in here, like Kiali UI, that may need attributes. Attributes will be updated prior to GA. -//Note that "Kiali UI" is not the same as "Kiali Operator provided by Red Hat", and there currently is only 1 attribute related to Kiali, and it is for "Kiali Operator provided by Red Hat". -// \ No newline at end of file +. Navigate to *Workload* → *Traces* tab to see traces in the Kiali UI. \ No newline at end of file diff --git a/modules/ossm-config-otel.adoc b/modules/ossm-config-otel.adoc index 6fd7b262ece..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"] @@ -12,11 +12,15 @@ You can integrate {SMProductName} with {OTELName} to instrument, generate, colle .Prerequisites -* You have installed the {TempoOperator}. For more information see, link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/distributed_tracing/distr-tracing-tempo-installing#installing-the-tempo-operator_distr-tracing-tempo-installing[Installing the Tempo Operator]. -* You have installed the {OTELOperator}. For more information see, link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/red_hat_build_of_opentelemetry/install-otel[Installing the Red Hat build of OpenTelemetry]. -* You have installed a `TempoStack` which is configured in a `tempo` namespace. For more information see, link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/distributed_tracing/distr-tracing-tempo-installing#installing-a-tempostack-instance_distr-tracing-tempo-installing[Installing a TempoStack instance]. -* You have created an {istio} instance. -* You have created an {istio} CNI instance. +* You have installed the {TempoOperator}. For more information, see "Installing the Tempo Operator". + +* You have installed the {OTELOperator}. For more information, see "Installing the Red Hat build of OpenTelemetry". + +* You have installed a `TempoStack` and configured it in a `tempo` namespace. For more information, see "Installing a `TempoStack` instance". + +* You have created an `{istio}` instance. + +* You have created an `IstioCNI` instance. .Procedure @@ -73,9 +77,9 @@ spec: - name: otel opentelemetry: port: 4317 - service: otel-collector.istio-system.svc.cluster.local # <1> + service: otel-collector.istio-system.svc.cluster.local ---- -<1> The `service` field is the `OpenTelemetry` collector service in the `istio-system` namespace. +* `spec.values.meshConfig.ExtensionProviders.opentelemetry.service` is the `OpenTelemetry` collector service in the `istio-system` namespace. . Create an {istio} Telemetry resource to enable tracers defined in `spec.values.meshConfig.ExtensionProviders`, similar to the following example: + @@ -97,7 +101,7 @@ After you verify that you can see traces, lower the `randomSamplingPercentage` v + [NOTE] ==== -You can use a single {istio} Telemetry resource for both the Prometheus metrics provider and a tracing provider by setting `spec.metrics.overrides.disabled` to `false`. This enables the Prometheus metrics provider. This is an optional step and you can skip it if you configured metrics through the OpenShift Cluster Monitoring method described in the previous step. +You can use a single {istio} Telemetry resource for both the Prometheus metrics provider and a tracing provider by setting `spec.metrics.overrides.disabled` to `false`. This enables the Prometheus metrics provider. This is an optional step and you can skip it if you configured metrics through the OpenShift Cluster Monitoring method described in the earlier step. ==== . Create the `bookinfo` namespace by running the following command: @@ -125,7 +129,8 @@ $ oc label namespace curl istio-injection=enabled $ oc get istiorevisions.sailoperator.io ---- + -.Example output +You should see output similar to the following example: ++ [source,terminal] ---- NAME TYPE READY STATUS IN USE VERSION AGE @@ -162,5 +167,5 @@ $ oc get routes -n tempo tempo-sample-query-frontend + [NOTE] ==== -The {ocp-short-name} route for Jaeger UI must be created in the Tempo namespace. You can either manually create it for the `tempo-sample-query-frontend` service, or update the `Tempo` custom resource with `.spec.template.queryFrontend.jaegerQuery.ingress.type: route`. +You must create the {ocp-short-name} route for the Jaeger UI in the Tempo namespace. You can either manually create it for the `tempo-sample-query-frontend` service, or update the `Tempo` custom resource with `.spec.template.queryFrontend.jaegerQuery.ingress.type: route`. ==== \ No newline at end of file diff --git a/modules/ossm-configure-attested-workload-identity.adoc b/modules/ossm-configure-attested-workload-identity.adoc new file mode 100644 index 00000000000..a207b294926 --- /dev/null +++ b/modules/ossm-configure-attested-workload-identity.adoc @@ -0,0 +1,13 @@ +// Module included in the following assemblies: +// +// TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-configure-attested-workload-identity_{context}"] += Configure attested workload identity + +[role="_abstract"] + +In hybrid and multi-cluster environments, managing workload identity across different infrastructure boundaries can be complex. Attested workload identity replaces network-based trust with cryptographic proof. + +Each workload must pass a verification check before it receives an identity certificate and is allowed to participate in mesh communication. diff --git a/modules/ossm-configure-authorization-policies.adoc b/modules/ossm-configure-authorization-policies.adoc new file mode 100644 index 00000000000..eecd190fb76 --- /dev/null +++ b/modules/ossm-configure-authorization-policies.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-configure-authorization-policies_{context}"] += Configure service authorization policies + +[role="_abstract"] + +To control which services can communicate with each other in the mesh, apply authorization policies. + +After you enable mTLS to encrypt mesh traffic, you can further restrict access at the service level. Authorization policies evaluate attributes such as the source workload's service account, the HTTP method, and the request path to allow or deny traffic. + +Authorization policies work in both sidecar and ambient modes. In sidecar mode, the Envoy proxy on the destination workload enforces the policy directly. In ambient mode, you enforce Layer 7 authorization policies by routing traffic through a waypoint proxy. The waypoint proxy inspects request-level attributes and applies your authorization rules before forwarding traffic to the destination service. diff --git a/modules/ossm-configure-gateway-traffic-routing.adoc b/modules/ossm-configure-gateway-traffic-routing.adoc new file mode 100644 index 00000000000..6f44eddc48b --- /dev/null +++ b/modules/ossm-configure-gateway-traffic-routing.adoc @@ -0,0 +1,13 @@ +// Module included in the following assemblies: +// +// TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-configure-gateway-traffic-routing_{context}"] += Control traffic entering and leaving the mesh + +[role="_abstract"] + +Control how network traffic enters (ingress) and exits (egress) the service mesh by configuring traffic routing rules at the gateway edge. + +Gateways serve as the secure boundaries for your service mesh. They govern all communication between internal microservices and external networks. After you install a gateway, you define routing rules that determine which external traffic reaches your mesh services and how mesh workloads communicate with external destinations. diff --git a/modules/ossm-configure-traffic-routing.adoc b/modules/ossm-configure-traffic-routing.adoc new file mode 100644 index 00000000000..596bbcbdfb2 --- /dev/null +++ b/modules/ossm-configure-traffic-routing.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-configure-traffic-routing_{context}"] += Control traffic entering and leaving the mesh + +[role="_abstract"] + +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-autoscaling.adoc b/modules/ossm-configuring-istio-ha-autoscaling.adoc index 103480a5791..e66342afc32 100644 --- a/modules/ossm-configuring-istio-ha-autoscaling.adoc +++ b/modules/ossm-configuring-istio-ha-autoscaling.adoc @@ -1,4 +1,5 @@ // This procedure is used in the following assembly: +// // * service-mesh-docs-main/install/ossm-installing-service-mesh.adoc :_mod-docs-content-type: PROCEDURE @@ -7,15 +8,20 @@ [role="_abstract"] -Configure the {istio} control plane in High Availability (HA) mode to prevent a single point of failure, and ensure continuous mesh operation even if one of the `istiod` pods fails. Autoscaling defines the minimum and maximum number of {istio} control plane pods that can operate. {ocp-product-title} uses these values to scale the number of control planes in operation based on resource utilization, such as CPU or memory, to efficiently respond to the varying number of workloads and overall traffic patterns within the mesh. +Configure the {istio} control plane in High Availability (HA) mode to prevent a single point of failure, and ensure continuous mesh operation even if one of the `istiod` pods fails. + +[NOTE] +==== +Autoscaling defines the minimum and maximum number of {istio} control plane pods that can operate. {ocp-product-title} uses these values to scale the number of control planes in operation based on resource usage, such as CPU or memory, to efficiently respond to the varying number of workloads and overall traffic patterns within the mesh. +==== .Prerequisites -* You are logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role. +* You have logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role. * You have installed the {SMProductName} Operator. -* You have deployed the {istio} resource. +* You have deployed the `{istio}` resource. .Procedure @@ -29,9 +35,8 @@ Configure the {istio} control plane in High Availability (HA) mode to prevent a . Click *YAML*. -. Modify the `{istio}` custom resource (CR) similar to the following example: +. Change the `{istio}` custom resource (CR) similar to the following example: + -.Example configuration [source,yaml,subs="attributes,verbatim"] ---- apiVersion: sailoperator.io/v1 @@ -42,17 +47,17 @@ spec: namespace: istio-system values: pilot: - autoscaleMin: 2 # <1> - autoscaleMax: 5 # <2> + autoscaleMin: 2 + autoscaleMax: 5 cpu: - targetAverageUtilization: 80 # <3> + targetAverageUtilization: 80 memory: - targetAverageUtilization: 80 # <4> + targetAverageUtilization: 80 ---- -<1> Specifies the minimum number of {istio} control plane replicas that always run. -<2> Specifies the maximum number of {istio} control plane replicas, allowing for scaling based on load. To support HA, there must be at least two replicas. -<3> Specifies the target CPU utilization for autoscaling to 80%. If the average CPU usage exceeds this threshold, the Horizontal Pod Autoscaler (HPA) automatically increases the number of replicas. -<4> Specifies the target memory utilization for autoscaling to 80%. If the average memory usage exceeds this threshold, the HPA automatically increases the number of replicas. +* `spec.values.pilot.autoscaleMin` specifies the minimum number of {istio} control plane replicas that always run. +* `spec.values.pilot.autoscaleMax` specifies the maximum number of {istio} control plane replicas, allowing for scaling based on load. To support HA, there must be at least two replicas. +* `spec.values.pilot.cpu.targetAverageUtilization` specifies the target CPU usage for autoscaling to 80%. If the average CPU usage exceeds this threshold, the Horizontal Pod Autoscaler (HPA) automatically increases the number of replicas. +* `spec.values.pilot.memory.targetAverageUtilization` specifies the target memory usage for autoscaling to 80%. If the average memory usage exceeds this threshold, the HPA automatically increases the number of replicas. .Verification @@ -63,7 +68,8 @@ spec: $ oc get pods -n istio-system -l app=istiod ---- + -.Example output +You should see output similar to the following example: ++ [source,terminal] ---- NAME READY STATUS RESTARTS AGE diff --git a/modules/ossm-configuring-istio-ha-replicacount.adoc b/modules/ossm-configuring-istio-ha-replicacount.adoc index b73e63f82b1..eae6b5ab410 100644 --- a/modules/ossm-configuring-istio-ha-replicacount.adoc +++ b/modules/ossm-configuring-istio-ha-replicacount.adoc @@ -1,17 +1,23 @@ // This procedure is used in the following assembly: +// // * service-mesh-docs-main/install/ossm-installing-service-mesh.adoc :_mod-docs-content-type: PROCEDURE [id="ossm-configuring-istio-ha-replicacount_{context}"] -= Configuring Istio HA by using replica count += Configure Istio HA with a replica count [role="_abstract"] -Configure the {istio} control plane in High Availability (HA) mode to prevent a single point of failure, and ensure continuous mesh operation even if one of the `istiod` pods fails. The replica count defines a fixed number of {istio} control plane pods that can operate. Use replica count for mesh environments where the control plane workload is relatively stable or predictable, or when you prefer to manually scale the `istiod` pod. +Configure the {istio} control plane for high availability (HA) by setting a static replica count to ensure continuous mesh operation and redundancy across multiple `istiod` pods. + +[NOTE] +==== +The replica count defines a fixed number of {istio} control plane pods that can operate. Use replica count for mesh environments where the control plane workload is relatively stable or predictable, or when you prefer to manually scale the `istiod` pod. +==== .Prerequisites -* You are logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role. +* You have logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role. * You have installed the {SMProductName} Operator. @@ -26,7 +32,8 @@ Configure the {istio} control plane in High Availability (HA) mode to prevent a $ oc get istio -n istio-sytem ---- + -.Example output +You should see output similar to the following example: ++ [source,terminal] ---- NAME REVISIONS READY IN USE ACTIVE REVISION STATUS VERSION AGE @@ -43,23 +50,24 @@ $ oc patch istio default -n istio-system --type merge -p ' spec: values: pilot: - autoscaleEnabled: false <1> - replicaCount: 2 <2> + autoscaleEnabled: false + replicaCount: 2 ' ---- -<1> Specifies a setting that disables autoscaling and ensures that the number of replicas remains fixed. -<2> Specifies the number of {istio} control plane replicas. To support HA, there must be at least two replicas. +* `spec.values.pilot.autoscaleEnabled` specifies a setting that disables autoscaling and ensures that the number of replicas remains fixed. +* `spec.values.pilot.replicaCount` specifies the number of {istio} control plane replicas. To support HA, there must be at least two replicas. .Verification -. Verify the status of the {Istio} control pods by running the following command: +. Verify the status of the {istio} control pods by running the following command: + [source,terminal] ---- $ oc get pods -n istio-system -l app=istiod ---- + -.Example output +You should see output similar to the following example: ++ [source,terminal] ---- NAME READY STATUS RESTARTS AGE diff --git a/modules/ossm-configuring-sm-pqc-ambient.adoc b/modules/ossm-configuring-sm-pqc-ambient.adoc index e4a9b8fe11d..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"] @@ -12,7 +12,7 @@ Configure the {istio} control plane and ztunnel to enforce a {pqc-short} complia .Prerequisites -* You are logged in to the {ocp-product-title} web console 4.19+ as a user with the `cluster-admin` role. +* You have logged in to the {ocp-product-title} web console 4.19+ as a user with the `cluster-admin` role. * You have installed the {SMProductName} Operator 3.2.1+. diff --git a/modules/ossm-configuring-sm-pqc-gateways.adoc b/modules/ossm-configuring-sm-pqc-gateways.adoc index c5a2fd3947c..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"] @@ -12,7 +12,7 @@ Configure a quantum-secure gateway by using hybrid key exchange to protect servi .Prerequisites -* You are logged in to the {ocp-product-title} web console 4.19+ as a user with the `cluster-admin` role. +* You have logged in to the {ocp-product-title} web console 4.19+ as a user with the `cluster-admin` role. * You have installed the {SMProductName} Operator 3.2.1+. diff --git a/modules/ossm-configuring-sm-pqc-mesh-wide.adoc b/modules/ossm-configuring-sm-pqc-mesh-wide.adoc index eade6c5d8df..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"] @@ -12,7 +12,7 @@ Configure the {istio} control plane to enforce a {pqc-short} compliance policy, .Prerequisites -* You are logged in to the {ocp-product-title} web console 4.19+ as a user with the `cluster-admin` role. +* You have logged in to the {ocp-product-title} web console 4.19+ as a user with the `cluster-admin` role. * You have installed the {SMProductName} Operator 3.2.1+. 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-control-plane-configuration-migration-requirements.adoc b/modules/ossm-control-plane-configuration-migration-requirements.adoc index 71e293ffded..d3ade97fa44 100644 --- a/modules/ossm-control-plane-configuration-migration-requirements.adoc +++ b/modules/ossm-control-plane-configuration-migration-requirements.adoc @@ -1,5 +1,5 @@ // Module included in the following assemblies: - +// // * service-mesh-docs-main/migrating/cluster-wide/ossm-migrating-cluster-wide.adoc :_mod-docs-content-type: CONCEPT diff --git a/modules/ossm-core-features.adoc b/modules/ossm-core-features.adoc index 22b8e94023f..339c7877f08 100644 --- a/modules/ossm-core-features.adoc +++ b/modules/ossm-core-features.adoc @@ -1,7 +1,6 @@ -//// -Module included in the following assemblies: -* about/ossm-about-openshift-service-mesh.adoc -//// +// Module included in the following assemblies: +// +//* about/ossm-about-openshift-service-mesh.adoc :_mod-docs-content-type: CONCEPT [id="ossm-core-features_{context}"] @@ -9,9 +8,9 @@ Module included in the following assemblies: [role="_abstract"] -{SMProductName} provides a number of key capabilities uniformly across a network of services: +{SMProductName} provides several key capabilities uniformly across a network of services: +* *Zero-trust security* - Automatically encrypt and authenticate all service-to-service communication with mutual TLS (mTLS). Every service receives a cryptographic identity, and authorization policies control which services can communicate with each other. You can also integrate external security solutions to extend the zero-trust model with enterprise certificate management and attested workload identity. * *Traffic Management* - Control the flow of traffic and API calls between services, make calls more reliable, and make the network more robust in the face of adverse conditions. -* *Service Identity and Security* - Provide services in the mesh with a verifiable identity and provide the ability to protect service traffic as it flows over networks of varying degrees of trustworthiness. -* *Policy Enforcement* - Apply organizational policy to the interaction between services, ensure access policies are enforced and resources are fairly distributed among consumers. Policy changes are made by configuring the mesh, not by changing application code. -* *Telemetry* - Gain understanding of the dependencies between services and the nature and flow of traffic between them, providing the ability to quickly identify issues. \ No newline at end of file +* *Policy Enforcement* - Apply organizational policies to service interactions without changing application code. The mesh enforces access controls and distributes resources fairly among consumers. +* *Telemetry* - See how services depend on each other, monitor traffic flow, and identify issues quickly with automatically generated metrics and distributed tracing. \ No newline at end of file diff --git a/modules/ossm-creating-a-default-revision-tag-and-relabeling-the-namespaces-with-cert-manager.adoc b/modules/ossm-creating-a-default-revision-tag-and-relabeling-the-namespaces-with-cert-manager.adoc index 47e2d807ac0..8bced1cc91d 100644 --- a/modules/ossm-creating-a-default-revision-tag-and-relabeling-the-namespaces-with-cert-manager.adoc +++ b/modules/ossm-creating-a-default-revision-tag-and-relabeling-the-namespaces-with-cert-manager.adoc @@ -20,7 +20,8 @@ The `bookinfo` application is used as an example. . Create a YAML file called `rev-tag.yaml` that defines the `IstioRevisionTag` resource: + -.Example `IstioRevisionTag` resource +*Example `IstioRevisionTag` resource:* ++ [source,yaml,subs="attributes,verbatim"] ---- apiVersion: sailoperator.io/v1 @@ -47,7 +48,8 @@ $ oc apply -f rev-tag.yaml $ oc get istiorevisiontags ---- + -.Example output +*Example output:* ++ [source,terminal] ---- NNAME STATUS IN USE REVISION AGE @@ -87,7 +89,8 @@ Repeat steps 4 and 5 for each namespace you are migrating. $ oc get istiorevisiontags ---- + -.Example output +*Example output:* ++ [source,terminal] ---- NAME STATUS IN USE REVISION AGE @@ -101,7 +104,8 @@ default Healthy True ossm-3-v1-24-3 28s $ istioctl ps -n bookinfo ---- + -.Example output +*Example output:* ++ [source,terminal] ---- NAME CLUSTER CDS LDS EDS RDS ECDS ISTIOD VERSION diff --git a/modules/ossm-creating-a-default-revision-tag-and-relabeling-the-namespaces.adoc b/modules/ossm-creating-a-default-revision-tag-and-relabeling-the-namespaces.adoc index 757dbc6cb38..57cf33e4c10 100644 --- a/modules/ossm-creating-a-default-revision-tag-and-relabeling-the-namespaces.adoc +++ b/modules/ossm-creating-a-default-revision-tag-and-relabeling-the-namespaces.adoc @@ -20,7 +20,8 @@ The `bookinfo` application is used as an example. . Create a YAML file called `rev-tag.yaml` that defines the `IstioRevisionTag` resource: + -.Example `IstioRevisionTag` resource +*Example `IstioRevisionTag` resource:* ++ [source,yaml,subs="attributes,verbatim"] ---- apiVersion: sailoperator.io/v1 @@ -47,7 +48,8 @@ $ oc apply -f rev-tag.yaml $ oc get istiorevisiontags ---- + -.Example output +*Example output:* ++ [source,terminal] ---- NNAME STATUS IN USE REVISION AGE @@ -87,7 +89,8 @@ Repeat steps 4 and 5 for each namespace you are migrating. $ oc get istiorevisiontags ---- + -.Example output +*Example output:* ++ [source,terminal] ---- NAME STATUS IN USE REVISION AGE @@ -101,7 +104,8 @@ default Healthy True ossm-3-v1-24-3 28s $ istioctl ps -n bookinfo ---- + -.Example output +*Example output:* ++ [source,terminal] ---- NAME CLUSTER CDS LDS EDS RDS ECDS ISTIOD VERSION @@ -114,3 +118,9 @@ reviews-v2-65cb66b45c-6ggp9.bookinfo Kubernetes SYNCED (57s) SYN reviews-v2-698b86b848-v92xq.bookinfo Kubernetes SYNCED (3s) SYNCED (3s) SYNCED (3s) SYNCED (3s) IGNORED istiod-ossm-3-v1-24-3-6595bf8695-s8ktn 1.24.3 reviews-v3-6cbc49c8c8-v4jck.bookinfo Kubernetes SYNCED (11s) SYNCED (11s) SYNCED (3s) SYNCED (11s) IGNORED istiod-ossm-3-v1-24-3-6595bf8695-s8ktn 1.24.3 ---- + +.Next steps + +You can proceed to complete the migration and remove {SMProduct} 2 resources. + +* See: "Completing the Migration" 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 040d6c1e898..bd5922c8485 100644 --- a/modules/ossm-creating-certificates-for-a-multi-cluster-topology.adoc +++ b/modules/ossm-creating-certificates-for-a-multi-cluster-topology.adoc @@ -1,10 +1,10 @@ // This module is used in the following assemblies: - +// // * install/ossm-multi-cluster-topologies.adoc :_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"] @@ -27,7 +27,8 @@ $ openssl genrsa -out root-key.pem 4096 .. Create an OpenSSL configuration certificate file named `root-ca.conf` for the root CA certificates: + -.Example root certificate configuration file +You can see the following example configuration for reference: ++ [source,terminal] ---- encrypt_key = no @@ -85,7 +86,8 @@ $ openssl genrsa -out east/ca-key.pem 4096 .. Create an OpenSSL configuration file named `intermediate.conf` in the `east/` directory for the intermediate certificate of the East cluster. Copy the following example file and save it locally: + -.Example configuration file +You can see the following example configuration for reference: ++ [source,subs="attributes,verbatim"] ---- [ req ] @@ -154,9 +156,10 @@ $ mkdir west $ openssl genrsa -out west/ca-key.pem 4096 ---- -.. Create an OpenSSL configuration file named `intermediate.conf` in the `west/` directory for for the intermediate certificate of the West cluster. Copy the following example file and save it locally: +.. Create an OpenSSL configuration file named `intermediate.conf` in the `west/` directory for the intermediate certificate of the West cluster. Copy the following example file and save it locally: ++ +You can see the following example configuration for reference: + -.Example configuration file [source,subs="attributes,verbatim"] ---- [ req ] diff --git a/modules/ossm-creating-istio-cni-project-using-console.adoc b/modules/ossm-creating-istio-cni-project-using-console.adoc index ed99afe4df3..fc16d99f572 100644 --- a/modules/ossm-creating-istio-cni-project-using-console.adoc +++ b/modules/ossm-creating-istio-cni-project-using-console.adoc @@ -1,19 +1,20 @@ // Module included in the following assemblies: +// // install/ossm-installing-openshift-service-mesh.adoc :_mod-docs-content-type: PROCEDURE [id="ossm-creating-istio-cni-project_{context}"] -= Creating the IstioCNI project using the web console += Create the IstioCNI project using the web console [role="_abstract"] -The {SMProductShortName} Operator deploys the {istio} CNI plugin to a project that you create. In this example, `istio-cni` is the name of the project. +The {SMProductShortName} Operator deploys the {istio} Container Network Interface (CNI) plugin to a project that you create. In this example, `istio-cni` is the name of the project. -.Prerequisties +.Prerequisites -* The {SMProductName} Operator must be installed. +* You have installed the {SMProductName} Operator. -* You are logged in to the {ocp-product-title} web console as cluster-admin. +* You have logged in to the {ocp-product-title} web console as cluster-admin. .Procedure @@ -21,6 +22,6 @@ The {SMProductShortName} Operator deploys the {istio} CNI plugin to a project th . Click *Create Project*. -. At the prompt, you must enter a name for the project in the *Name* field. For example, `istio-cni`. The other fields provide supplementary information and are optional. +. At the prompt, you must enter a name for the project in the *Name* field. For example, `istio-cni`. The other fields offer supplementary information and are optional. . Click *Create*. diff --git a/modules/ossm-creating-istio-project-using-console.adoc b/modules/ossm-creating-istio-project-using-console.adoc index ce72d92a861..55a9280515c 100644 --- a/modules/ossm-creating-istio-project-using-console.adoc +++ b/modules/ossm-creating-istio-project-using-console.adoc @@ -1,19 +1,20 @@ // Module included in the following assemblies: +// // install/ossm-installing-openshift-service-mesh.adoc :_mod-docs-content-type: PROCEDURE [id="ossm-creating-istio-project_{context}"] -= Creating the Istio project using the web console += Create the Istio project using the web console [role="_abstract"] The {SMProductShortName} Operator deploys the {istio} control plane to a project that you create. In this example, `istio-system` is the name of the project. -.Prerequisties +.Prerequisites -* The {SMProductName} Operator must be installed. +* You have installed the {SMProductName} Operator. -* You are logged in to the {ocp-product-title} web console as cluster-admin. +* You have logged in to the {ocp-product-title} web console as cluster-admin. .Procedure @@ -21,6 +22,6 @@ The {SMProductShortName} Operator deploys the {istio} control plane to a project . Click *Create Project*. -. At the prompt, enter a name for the project in the *Name* field. For example, `istio-system`. The other fields provide supplementary information to the `Istio` resource definition and are optional. +. At the prompt, enter a name for the project in the *Name* field. For example, `istio-system`. The other fields offer supplementary information to the `{istio}` resource definition and are optional. . Click *Create*. The {SMProductShortName} Operator deploys {istio} to the project you specified. diff --git a/modules/ossm-creating-istio-resource-using-console.adoc b/modules/ossm-creating-istio-resource-using-console.adoc index 37b04d43b7b..8a9f3ae8bc9 100644 --- a/modules/ossm-creating-istio-resource-using-console.adoc +++ b/modules/ossm-creating-istio-resource-using-console.adoc @@ -1,19 +1,19 @@ // Module included in the following assemblies: +// // install/ossm-installing-openshift-service-mesh.adoc :_mod-docs-content-type: PROCEDURE [id="ossm-creating-istio-resource_{context}"] -= Creating the Istio resource using the web console += Create the Istio resource using the web console [role="_abstract"] +Create the {istio} resource to define the YAML configuration for your {istio} deployment. The {SMProductName} Operator uses information in the YAML file to create an instance of the {istio} control plane. -Create the {istio} resource that will contain the YAML configuration file for your {istio} deployment. The {SMProductName} Operator uses information in the YAML file to create an instance of the {istio} control plane. +.Prerequisites -.Prerequisties +* You have installed the {SMProductShortName} Operator. -* The {SMProductShortName} Operator must be installed. - -* You are logged in to the {ocp-product-title} web console as cluster-admin. +* You have logged in to the {ocp-product-title} web console as cluster-admin. .Procedure @@ -29,6 +29,23 @@ Create the {istio} resource that will contain the YAML configuration file for yo . Select the `istio-system` project from the *Namespace* drop-down menu. +. Click *YAML* to view the configuration. + +. If your cluster includes {op-system-base-full} 10 or {op-system-first} 10 nodes, you must enable native `nftables` support. In the YAML configuration, set the `nativeNftables` field to `true` within the `spec.values.global` section, as shown in the following example: ++ +[source,yaml] +---- +apiVersion: sailoperator.io/v1 +kind: Istio +metadata: + name: default +spec: + namespace: istio-system + values: + global: + nativeNftables: true +---- + . Click *Create*. This action deploys the {istio} control plane. + -When `State: Healthy` appears in the *Status* column, {istio} is successfully deployed. +When `State: Healthy` displays in the *Status* column, {istio} is successfully deployed. diff --git a/modules/ossm-creating-istiocni-resource-using-console.adoc b/modules/ossm-creating-istiocni-resource-using-console.adoc index f1fdb999d1f..a1917253bef 100644 --- a/modules/ossm-creating-istiocni-resource-using-console.adoc +++ b/modules/ossm-creating-istiocni-resource-using-console.adoc @@ -1,19 +1,19 @@ // Module included in the following assemblies: +// // install/ossm-installing-openshift-service-mesh.adoc :_mod-docs-content-type: PROCEDURE [id="ossm-creating-istiocni-resource_{context}"] -= Creating the IstioCNI resource using the web console += Create the IstioCNI resource using the web console [role="_abstract"] +Create an {istio} Container Network Interface (CNI) resource, which has the configuration file for the Istio CNI plugin. The {SMProductShortName} Operator uses the configuration specified by this resource to deploy the CNI pod. -Create an {istio} Container Network Interface (CNI) resource, which contains the configuration file for the Istio CNI plugin. The {SMProductShortName} Operator uses the configuration specified by this resource to deploy the CNI pod. +.Prerequisites -.Prerequisties +* You have installed the {SMProductName} Operator. -* The {SMProductName} Operator must be installed. - -* You are logged in to the {ocp-product-title} web console as cluster-admin. +* You have logged in to the {ocp-product-title} web console as cluster-admin. .Procedure @@ -29,6 +29,23 @@ Create an {istio} Container Network Interface (CNI) resource, which contains the . Ensure that the name is `default`. +. Click *YAML* to view the configuration. + +. If your cluster includes {op-system-base-full} 10 or {op-system-first} 10 nodes, you must enable native `nftables` support. In the YAML configuration, set the `nativeNftables` field to `true` within the `spec.values.global` section, as shown in the following example: ++ +[source,yaml] +---- +apiVersion: sailoperator.io/v1 +kind: IstioCNI +metadata: + name: default +spec: + namespace: istio-cni + values: + global: + nativeNftables: true +---- + . Click *Create*. This action deploys the Istio CNI plugin. + -When `State: Healthy` appears in the *Status* column, the Istio CNI plugin is successfully deployed. +When `State: Healthy` displays in the *Status* column, the Istio CNI plugin is successfully deployed. diff --git a/modules/ossm-customizing-istio-configuration.adoc b/modules/ossm-customizing-istio-configuration.adoc index ed0e225a068..884f4f8481c 100644 --- a/modules/ossm-customizing-istio-configuration.adoc +++ b/modules/ossm-customizing-istio-configuration.adoc @@ -1,30 +1,28 @@ // Module included in the following assemblies: +// // install/ossm-installing-openshift-service-mesh.adoc :_mod-docs-content-type: PROCEDURE [id="ossm-customizing-istio_{context}"] -= Customizing Istio configuration += Edit the control plane YAML [role="_abstract"] -The `values` field of the `Istio` custom resource definition, which was created when the control plane was deployed, can be used to customize Istio configuration using Istio's `Helm` configuration values. When you create this resource using the OpenShift Container Platform web console, it is pre-populated with configuration settings to enable Istio to run on OpenShift. +Customize the {istio} control plane by using the values field in the `{istio}` resource to apply advanced `Helm` configuration settings optimized for {ocp-short-name} environments. + +[NOTE] +==== +When you create this resource by using the {ocp-product-title} web console, it is pre-populated with configuration settings to enable {istio} to run on {ocp-short-name}. +==== .Procedure . Click *Operators* -> *Installed Operators*. -. Click *Istio* in the *Provided APIs* column. -. Click the `Istio` instance, named `default`, in the *Name* column. -. Click *YAML* to view the `Istio` configuration and make modifications. - -For a list of available configuration for the `values` field, refer to link:https://artifacthub.io/packages/search?org=istio&sort=relevance&page=1[Istio's artifacthub chart documentation]. - -* link:https://artifacthub.io/packages/helm/istio-official/base?modal=values[Base parameters] -* link:https://artifacthub.io/packages/helm/istio-official/istiod?modal=values[Istiod parameters] -* link:https://artifacthub.io/packages/helm/istio-official/gateway?modal=values[Gateway parameters] -* link:https://artifacthub.io/packages/helm/istio-official/cni?modal=values[CNI parameters] -* link:https://artifacthub.io/packages/helm/istio-official/ztunnel?modal=values[ZTunnel parameters] - -[role="_additional-resources"] -[id="ossm-customizing-istio-additional-resources_{context}"] -.Additional resources -* link:https://github.com/istio-ecosystem/sail-operator/blob/main/docs/README.md[Service Mesh 3.0 Operator community documentation] \ No newline at end of file + +. Click *{istio}* in the *Provided APIs* column. + +. Click the `{istio}` instance, named `default`, in the *Name* column. + +. Click *YAML* to view the `{istio}` configuration and make modifications. ++ +For a list of available configuration for the `values` field, refer to "{istio}'s artifacthub chart documentation". \ No newline at end of file diff --git a/modules/ossm-decide-if-service-mesh-fits.adoc b/modules/ossm-decide-if-service-mesh-fits.adoc new file mode 100644 index 00000000000..5cee53ce225 --- /dev/null +++ b/modules/ossm-decide-if-service-mesh-fits.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-decide-if-service-mesh-fits_{context}"] += 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. +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. + +{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 +* A need for visibility into service-to-service traffic, health, and performance +* Growing operational complexity as the number of services increases + diff --git a/modules/ossm-deploy-application-workloads-in-each-mesh.adoc b/modules/ossm-deploy-application-workloads-in-each-mesh.adoc index 2e5c472a574..b7927c45f7b 100644 --- a/modules/ossm-deploy-application-workloads-in-each-mesh.adoc +++ b/modules/ossm-deploy-application-workloads-in-each-mesh.adoc @@ -1,4 +1,5 @@ // Module included in the following assemblies: +// // install/ossm-deploying-multiple-service-meshes-on-single-cluster.adoc :_mod-docs-content-type: PROCEDURE @@ -18,14 +19,14 @@ To deploy application workloads, assign each workload to a separate namespace. $ oc create namespace app-ns-1 ---- -. To ensure that the namespace is discovered by the first control plane, add the `istio-discovery=mesh-1` label by running the following command: +. To ensure the first control plane discovers the namespace, add the `istio-discovery=mesh-1` label by running the following command: + [source,terminal] ---- $ oc label namespace app-ns-1 istio-discovery=mesh-1 ---- -. To enable sidecar injection into all the pods by default while ensuring that pods in this namespace are mapped to the first control plane, add the `istio.io/rev=mesh-1` label to the namespace by running the following command: +. To enable sidecar injection into all the pods by default, while mapping the pods in this namespace to the first control plane, add the `istio.io/rev=mesh-1` label to the namespace by running the following command: + [source,terminal] ---- @@ -55,7 +56,8 @@ $ oc apply -n app-ns-1 \ $ oc get pods -n app-ns-1 ---- + -.Example output +You should see output similar to the following example: ++ [source,terminal] ---- NAME READY STATUS RESTARTS AGE @@ -111,16 +113,17 @@ $ oc wait deployments -n app-ns-2 --all --for condition=Available .Verification -. Verify that each application workload is managed by its assigned control plane by using the `istioctl ps` command after deploying the applications: +. After deploying the applications, use the `istioctl ps` command to verify that the correct control plane manages each workload: -.. Verify that the workloads are assigned to the control plane in `istio-system-1` by running the following command: +.. Verify that the `istio-system-1` control plane manages the workloads by running the following command: + [source,terminal] ---- $ istioctl ps -i istio-system-1 ---- + -.Example output +You should see output similar to the following example: ++ [source,terminal] ---- NAME CLUSTER CDS LDS EDS RDS ECDS ISTIOD VERSION @@ -128,14 +131,15 @@ httpbin-7f56dc944b-vwfm5.app-ns-1 Kubernetes SYNCED (11m) SYNCED (11 sleep-5577c64d7c-d675f.app-ns-1 Kubernetes SYNCED (11m) SYNCED (11m) SYNCED (11m) SYNCED (11m) IGNORED istiod-mesh-1-b69646b6f-kxrwk 1.23.0 ---- -.. Verify that the workloads are assigned to the control plane in `istio-system-2` by running the following command: +.. Verify that the `istio-system-2` control plane manages the workloads by running the following command: + [source,terminal] ---- $ istioctl ps -i istio-system-2 ---- + -.Example output +You should see output similar to the following example: ++ [source,terminal] ---- NAME CLUSTER CDS LDS EDS RDS ECDS ISTIOD VERSION @@ -145,7 +149,7 @@ sleep-5577c64d7c-k9mxz.app-ns-2 Kubernetes SYNCED (4m1s) SYNCED ( sleep-5577c64d7c-m9hvm.app-ns-3 Kubernetes SYNCED (4m1s) SYNCED (4m1s) SYNCED (3m59s) SYNCED (4m1s) IGNORED istiod-mesh-2-8666fdfc6-mqp45 1.23.0 ---- -. Verify that the application connectivity is restricted to workloads within their respective mesh: +. Verify that the mesh restricts application connectivity to local workloads: .. Send a request from the `sleep` pod in `app-ns-1` to the `httpbin` service in `app-ns-2` to check that the communication fails by running the following command: + @@ -156,7 +160,8 @@ $ oc -n app-ns-1 exec deploy/sleep -c sleep -- curl -sIL http://httpbin.app-ns-2 + The `PeerAuthentication` resources created earlier enforce mutual TLS (mTLS) traffic in `STRICT` mode within each mesh. Each mesh uses its own root certificate, managed by the `istio-ca-root-cert` config map, which prevents communication between meshes. The output indicates a communication failure, similar to the following example: + -.Example output +You should see output similar to the following example: ++ [source,terminal] ---- HTTP/1.1 503 Service Unavailable @@ -166,14 +171,15 @@ date: Wed, 16 Oct 2024 12:05:37 GMT server: envoy ---- -.. Confirm that the communication works by sending a request from the `sleep` pod to the `httpbin` service that are present in the `app-ns-2` namespace which is managed by `mesh-2`. Run the following command: +.. Confirm that the communication works by sending a request from the `sleep` pod to the `httpbin` service that are present in the `app-ns-2` namespace, which `mesh-2` manages by running the following command: + [source,terminal] ---- $ oc -n app-ns-2 exec deploy/sleep -c sleep -- curl -sIL http://httpbin.app-ns-3.svc.cluster.local:8000 ---- + -.Example output +You should see output similar to the following example: ++ [source,terminal] ---- HTTP/1.1 200 OK diff --git a/modules/ossm-deploy-in-ambient-mode.adoc b/modules/ossm-deploy-in-ambient-mode.adoc new file mode 100644 index 00000000000..1cd59214830 --- /dev/null +++ b/modules/ossm-deploy-in-ambient-mode.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// install/ossm-installing-openshift-service-mesh.adoc + +:_mod-docs-content-type: CONCEPT +[id="ossm-deploy-in-ambient-mode_{context}"] += Deploy in ambient mode + +[role="_abstract"] + +Ambient mode uses a node-level proxy (ztunnel) to provide mTLS encryption and L4 traffic management without injecting sidecar containers into application pods. You can optionally deploy waypoint proxies to enable L7 traffic management and policy enforcement for specific namespaces or services. diff --git a/modules/ossm-deploying-bookinfo-application-istio-ambient-mode.adoc b/modules/ossm-deploying-bookinfo-application-istio-ambient-mode.adoc index 0c2356c2bca..032c4cee6cc 100644 --- a/modules/ossm-deploying-bookinfo-application-istio-ambient-mode.adoc +++ b/modules/ossm-deploying-bookinfo-application-istio-ambient-mode.adoc @@ -1,21 +1,25 @@ // Module included in the following assemblies: - +// // * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc :_mod-docs-content-type: PROCEDURE [id="ossm-deploying-bookinfo-application-istio-ambient-mode_{context}"] -= Deploying the Bookinfo application in Istio ambient mode += Deploy Bookinfo in ambient mode [role="_abstract"] -You can deploy the `bookinfo` sample application in {istio} ambient mode without sidecar injection by using the `ZTunnel` proxy. For more information on `bookinfo` application, see "About the Bookinfo application". +You can deploy the `bookinfo` sample application in {istio} ambient mode without sidecar injection by using the `ZTunnel` proxy. .Prerequisites * You have deployed a cluster on {ocp-product-title} 4.15 or later, which includes the supported {k8s} Gateway API custom resource definitions (CRDs) required for {istio} ambient mode. -* You are logged in to the {ocp-product-title} cluster either through the web console as a user with the `cluster-admin` role, or with the `oc login` command, depending on the installation method. + +* You have logged in to the {ocp-product-title} cluster either through the web console as a user with the `cluster-admin` role, or with the `oc login` command, depending on the installation method. + * You have installed the {SMProductName} Operator, created the {istio} resource, and the Operator has deployed {istio}. + * You have created an `IstioCNI` resource, and the Operator has deployed the necessary `IstioCNI` pods. + * You have created a `Ztunnel` resource, and the Operator has deployed the necessary `Ztunnel` pods. .Procedure @@ -55,7 +59,8 @@ $ oc apply -n bookinfo -f https://raw.githubusercontent.com/openshift-service-me $ oc -n bookinfo get pods ---- + -.Example output +You should see output similar to the following example: ++ [source,terminal] ---- NAME READY STATUS RESTARTS AGE @@ -101,7 +106,8 @@ Adding workloads to the ambient mesh does not require restarting or redeploying $ istioctl ztunnel-config workloads --namespace ztunnel ---- + -.Example output +You should see output similar to the following example: ++ [source,terminal] ---- NAMESPACE POD NAME ADDRESS NODE WAYPOINT PROTOCOL diff --git a/modules/ossm-deploying-bookinfo-application.adoc b/modules/ossm-deploying-bookinfo-application.adoc index d498723a2b0..48bcf6b276a 100644 --- a/modules/ossm-deploying-bookinfo-application.adoc +++ b/modules/ossm-deploying-bookinfo-application.adoc @@ -1,19 +1,26 @@ // Module included in the following assemblies: +// // install/ossm-installing-openshift-service-mesh.adoc :_mod-docs-content-type: PROCEDURE [id="deploying-book-info_{context}"] -= Deploying the Bookinfo application += Deploy Bookinfo with namespace labels [role="_abstract"] +Deploy the Bookinfo sample application to a sidecar mesh by labeling the namespace for automatic sidecar injection and applying the application YAML file. + .Prerequisites * You have deployed a cluster on {ocp-product-title} 4.15 or later. -* You are logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role. + +* You have logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role. + * You have access to the {ocp-short-name} CLI (oc). + * You have installed the {SMProductName} Operator, created the {istio} resource, and the Operator has deployed {istio}. -* You have created IstioCNI resource, and the Operator has deployed the necessary IstioCNI pods. + +* You have created `IstioCNI` resource, and the Operator has deployed the necessary `IstioCNI` pods. .Procedure @@ -23,11 +30,11 @@ . Enter `bookinfo` in the *Project name* field. + -The *Display name* and *Description* fields provide supplementary information and are not required. +The *Display name* and *Description* fields offer supplementary information and are not required. . Click *Create*. -. Apply the {Istio} discovery selector and injection label to the `bookinfo` namespace by entering the following command: +. Apply the {istio} discovery selector and injection label to the `bookinfo` namespace by entering the following command: + [source,terminal] ---- @@ -36,7 +43,7 @@ $ oc label namespace bookinfo istio-discovery=enabled istio-injection=enabled + [NOTE] ==== -In this example, the name of the Istio resource is `default`. If the Istio resource name is different, you must set the `istio.io/rev` label to the name of the Istio resource instead of adding the `istio-injection=enabled` label. +In this example, the name of the `{istio}` resource is `default`. If the `{istio}` resource name is different, you must set the `istio.io/rev` label to the name of the `{istio}` resource instead of adding the `istio-injection=enabled` label. ==== . Apply the `bookinfo` YAML file to deploy the `bookinfo` application by entering the following command: @@ -55,7 +62,8 @@ oc apply -f https://raw.githubusercontent.com/openshift-service-mesh/istio/relea $ oc get services -n bookinfo ---- + -.Example output +You should see output similar to the following example: ++ [source,terminal] ---- NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE @@ -72,7 +80,8 @@ reviews ClusterIP 172.30.175.88 9080/TCP 44s $ oc get pods -n bookinfo ---- + -.Example output +You should see output similar to the following example: ++ [source,terminal] ---- NAME READY STATUS RESTARTS AGE @@ -84,7 +93,7 @@ reviews-v2-5b667bcbf8-4lsfd 2/2 Running 0 65s reviews-v3-5b9bd44f4-44hr6 2/2 Running 0 65s ---- + -When the `Ready` columns displays `2/2`, the proxy sidecar was successfully injected. Confirm that `Running` appears in the `Status` column for each pod. +When the `Ready` columns displays `2/2`, the proxy sidecar was successfully injected. Confirm that `Running` displays in the `Status` column for each pod. . Verify that the `bookinfo` application is running by sending a request to the `bookinfo` page. Run the following command: + diff --git a/modules/ossm-deploying-first-control-plane.adoc b/modules/ossm-deploying-first-control-plane.adoc index d87ba5b0dbb..af324b0913d 100644 --- a/modules/ossm-deploying-first-control-plane.adoc +++ b/modules/ossm-deploying-first-control-plane.adoc @@ -1,13 +1,14 @@ // Module included in the following assemblies: +// // install/ossm-deploying-multiple-service-meshes-on-single-cluster.adoc :_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 @@ -41,16 +42,15 @@ You can have extended support for more than two control planes. The maximum numb $ oc new-project istio-system-1 ---- -. Add the following label to the first namespace, which is used with the {istio} `discoverySelectors` field by running the following command: +. Label the first namespace, which the {istio} `discoverySelectors` field uses by running the following command: + [source,terminal] ---- $ oc label namespace istio-system-1 istio-discovery=mesh-1 ---- -. Create a YAML file named `istio-1.yaml` with the name `mesh-1` and the `discoverySelector` as `mesh-1`: +. Create a YAML file named `istio-1.yaml` with the name `mesh-1` and the `discoverySelector` as `mesh-1` similar to the following example: + -.Example configuration [source,yaml,subs="attributes,verbatim"] ---- kind: Istio @@ -74,14 +74,15 @@ spec: $ oc apply -f istio-1.yaml ---- -. To restrict workloads in `mesh-1` from communicating freely with decrypted traffic between meshes, deploy a `PeerAuthentication` resource to enforce mutual TLS (mTLS) traffic within the `mesh-1` data plane. Apply the `PeerAuthentication` resource in the `istio-system-1` namespace by using a configuration file, such as `peer-auth-1.yaml`: +. To restrict workloads in `mesh-1` from communicating freely with decrypted traffic between meshes, deploy a `PeerAuthentication` resource to enforce mutual TLS (mTLS) traffic within the `mesh-1` data plane. Apply the `PeerAuthentication` resource in the `istio-system-1` namespace by using a configuration file, such as `peer-auth-1.yaml`, by running the following command: + [source,terminal] ---- $ oc apply -f peer-auth-1.yaml ---- + -.Example configuration +You can see the following example configuration for reference: ++ [source,yaml,subs="attributes,verbatim"] ---- apiVersion: security.istio.io/v1 @@ -92,4 +93,4 @@ metadata: spec: mtls: mode: STRICT ----- +---- \ No newline at end of file diff --git a/modules/ossm-deploying-istio.adoc b/modules/ossm-deploying-istio.adoc deleted file mode 100644 index 56089b3fd3a..00000000000 --- a/modules/ossm-deploying-istio.adoc +++ /dev/null @@ -1,26 +0,0 @@ -:_mod-docs-content-type: PROCEDURE -[id="ossm-deploying-istio"] -= Deploying Istio - -[role="_abstract"] - -.Procedure - -. Create the project where Istio is going to be deployed. In the following examaple, the project is called `istio-system`: -+ -[source,treminal] ----- -$ oc new-project istio-system ----- - -. In the OpenShift web console, select `istio-system` in the *Project* drop-down menu. - -. Click the {SMProductName} Operator. - -. Click *Istio*. - -. Click *Create Istio*. - -. Accept the defaults and click *Create*. This creates the Istio control plane. - -. Click *Workloads* -> *Pods*. Verify that the pods were created. `Running` should appear in the *Status* column. If the pods were successfully created, then Istio is installed and ready for use. For more information, see the upstream link:https://istio.io/latest/docs/setup/platform-setup/openshift/[Istio documentation]. diff --git a/modules/ossm-deploying-quantum-secure-gateway.adoc b/modules/ossm-deploying-quantum-secure-gateway.adoc index a1e712bdecc..d324b296f14 100644 --- a/modules/ossm-deploying-quantum-secure-gateway.adoc +++ b/modules/ossm-deploying-quantum-secure-gateway.adoc @@ -12,7 +12,7 @@ Configure and deploy a service mesh gateway by using the {k8s} Gateway API to en .Prerequisites -* You are logged in to the {ocp-product-title} web console 4.19+ as a user with the `cluster-admin` role. +* You have logged in to the {ocp-product-title} web console 4.19+ as a user with the `cluster-admin` role. * You have installed the {SMProductName} Operator 3.2.1+ diff --git a/modules/ossm-deploying-second-control-plane.adoc b/modules/ossm-deploying-second-control-plane.adoc index 0031cf144ae..99619255a09 100644 --- a/modules/ossm-deploying-second-control-plane.adoc +++ b/modules/ossm-deploying-second-control-plane.adoc @@ -1,13 +1,14 @@ // Module included in the following assemblies: +// // install/ossm-deploying-multiple-service-meshes-on-single-cluster.adoc :_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 @@ -18,16 +19,15 @@ After deploying the first control plane, you can deploy the second control plane $ oc new-project istio-system-2 ---- -. Add the following label to the second namespace, which is used with the {istio} `discoverySelectors` field by running the following command: +. Label the second namespace, which the {istio} `discoverySelectors` field uses by running the following command: + [source,terminal] ---- $ oc label namespace istio-system-2 istio-discovery=mesh-2 ---- -. Create a YAML file named `istio-2.yaml`: +. Create a YAML file named `istio-2.yaml` similar to the following example: + -.Example configuration [source,yaml,subs="attributes,verbatim"] ---- kind: Istio @@ -58,7 +58,8 @@ $ oc apply -f istio-2.yaml $ oc apply -f peer-auth-2.yaml ---- + -.Example configuration +You can see the following example configuration for reference: ++ [source,yaml,subs="attributes,verbatim"] ---- apiVersion: security.istio.io/v1 diff --git a/modules/ossm-deploying-waypoint-proxy.adoc b/modules/ossm-deploying-waypoint-proxy.adoc index 33e4ec1da7c..22f14bee55f 100644 --- a/modules/ossm-deploying-waypoint-proxy.adoc +++ b/modules/ossm-deploying-waypoint-proxy.adoc @@ -1,10 +1,10 @@ // Module included in the following assemblies: - +// // * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc :_mod-docs-content-type: PROCEDURE [id="ossm-deploying-waypoint-proxy_{context}"] -= Deploying a waypoint proxy += Deploy waypoint proxies for Bookinfo [role="_abstract"] @@ -26,7 +26,8 @@ You can deploy a waypoint proxy in the `bookinfo` application namespace to route . Deploy a waypoint proxy in the `bookinfo` application namespace similar to the following example: + -.Example configuration +You can see the following example configuration for reference: ++ [source,yaml] ---- apiVersion: gateway.networking.k8s.io/v1 @@ -59,19 +60,20 @@ The `istio.io/waypoint-for: service` label indicates that the waypoint handles t ---- $ oc label namespace bookinfo istio.io/use-waypoint=waypoint ---- - -After enrolling the namespace, requests from any pods using the ambient data plane to services in `bookinfo` will route through the waypoint for L7 processing and policy enforcement. ++ +After enrolling the namespace, requests from any pods by using the ambient data plane to services in `bookinfo` will route through the waypoint for L7 processing and policy enforcement. .Verification -. Confirm that the waypoint proxy is used by all the services in the `bookinfo` namespace by running the following command: +. Confirm that the waypoint proxy manages all the services in the `bookinfo` namespace by running the following command: + [source,terminal] ---- $ istioctl ztunnel-config svc --namespace ztunnel ---- + -.Example output +*Example output:* ++ [source,terminal] ---- NAMESPACE SERVICE NAME SERVICE VIP WAYPOINT ENDPOINTS @@ -90,5 +92,5 @@ bookinfo waypoint 172.30.92.147 None 1/1 [NOTE] ==== -You can also configure only specific services or pods to use a waypoint by labeling the respective service or pod. When enrolling a pod explicitly, also add the `istio.io/waypoint-for: workload` label to the corresponding `gateway` resource. +You can also configure only specific services or pods to use a waypoint by labeling the required service or pod. When enrolling a pod explicitly, also add the `istio.io/waypoint-for: workload` label to the corresponding `gateway` resource. ==== \ No newline at end of file diff --git a/modules/ossm-deploying-waypoint-using-gateway-api.adoc b/modules/ossm-deploying-waypoint-using-gateway-api.adoc index d06bf0517b2..5a0fc0cdbf2 100644 --- a/modules/ossm-deploying-waypoint-using-gateway-api.adoc +++ b/modules/ossm-deploying-waypoint-using-gateway-api.adoc @@ -1,5 +1,5 @@ // Module included in the following assemblies: - +// // * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc :_mod-docs-content-type: PROCEDURE @@ -8,11 +8,11 @@ [role="_abstract"] -You can deploy waypoint proxies using {k8s} Gateway resource. +You can deploy waypoint proxies by using {k8s} Gateway resource. .Prerequisites -* You have logged in to the {ocp-product-title} 4.19 or later, which provides supported {k8s} Gateway API CRDs required for ambient mode functionality. +* You have logged in to the {ocp-product-title} 4.19 or later, which provides supported {k8s} Gateway API custom resource definitions (CRDs) required for ambient mode functionality. * You have the {SMProductName} Operator 3.2.0 or later installed on the OpenShift cluster. @@ -35,9 +35,9 @@ $ oc get crd gateways.gateway.networking.k8s.io &> /dev/null || \ { oc apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/standard-install.yaml; } ---- + -From {ocp-product-title} 4.19 onwards, the Gateway API CRDs are installed by default. - +Starting with {ocp-product-title} 4.19, the Gateway API CRDs are installed by default. ++ [NOTE] ==== -The CRDs are community maintained and not supported by Red Hat. Upgrading to {ocp-product-title} 4.19 or later, which includes supported Gateway API CRDs, may disrupt applications. +The CRDs are community maintained and not supported by Red Hat. Upgrading to {ocp-product-title} 4.19 or later, which includes supported Gateway API CRDs, might disrupt applications. ==== \ No newline at end of file diff --git a/modules/ossm-directing-egress-traffic-through-a-gateway-kubernetes-gateway-api-ambient-mode.adoc b/modules/ossm-directing-egress-traffic-through-a-gateway-kubernetes-gateway-api-ambient-mode.adoc index 84738376e86..509ebe146a2 100644 --- a/modules/ossm-directing-egress-traffic-through-a-gateway-kubernetes-gateway-api-ambient-mode.adoc +++ b/modules/ossm-directing-egress-traffic-through-a-gateway-kubernetes-gateway-api-ambient-mode.adoc @@ -1,4 +1,5 @@ // This procedure is used in the following assembly: +// // * service-mesh-docs-main/gateways/ossm-directing-outbound-traffic-through-a-gateway :_mod-docs-content-type: PROCEDURE @@ -13,7 +14,7 @@ Use the {k8s} Gateway API and waypoint proxy to direct outbound HTTP traffic thr * You have installed the {SMProduct} Operator version 3.2 or later. -* You configured the `Istio` and `IstioCNI` resources with ambient profile. +* You configured the `{istio}` and `IstioCNI` resources with ambient profile. * You have created a `Ztunnel` resource. @@ -40,7 +41,7 @@ $ oc create namespace egress-gateway $ oc label namespace egress-gateway istio.io/dataplane-mode=ambient ---- -. Create a YAML file named `egress-se.yaml` that defines the `ServiceEntry`. +. Create a YAML file named `egress-se.yaml` that defines the `ServiceEntry`, similar to the following example: + [source,yaml] ---- @@ -93,7 +94,7 @@ spec: ---- $ oc apply -f waypoint.yaml ---- - ++ [NOTE] ==== As an alternate to creating the `waypoint.yaml` YAML file, you can also set up waypoint proxy by running the following command: diff --git a/modules/ossm-directing-egress-traffic-through-a-gateway-using-istio-apis.adoc b/modules/ossm-directing-egress-traffic-through-a-gateway-using-istio-apis.adoc index bd10aa5535c..bd0d5facb27 100644 --- a/modules/ossm-directing-egress-traffic-through-a-gateway-using-istio-apis.adoc +++ b/modules/ossm-directing-egress-traffic-through-a-gateway-using-istio-apis.adoc @@ -1,4 +1,5 @@ // This procedure is used in the following assembly: +// // * gateways/ossm-directing-outbound-traffic-through-a-gateway :_mod-docs-content-type: PROCEDURE @@ -7,7 +8,7 @@ [role="_abstract"] -Use {istio} APIs to direct outbound HTTP traffic through a gateway that was installed using gateway injection. +Use {istio} APIs to direct outbound HTTP traffic through a gateway that you installed using gateway injection. .Prerequisites @@ -40,7 +41,8 @@ $ oc label namespace curl istio-injection=enabled $ oc get istiorevisions.sailoperator.io ---- + -.Example output +You should see output similar to the following example: ++ [source,terminal] ---- NAME TYPE READY STATUS IN USE VERSION AGE @@ -62,14 +64,14 @@ $ oc label namespace curl istio.io/rev=default $ oc apply -n curl -f https://raw.githubusercontent.com/openshift-service-mesh/istio/refs/heads/master/samples/curl/curl.yaml ---- -. Export a `CURL_POD` environment variable that has been initialized with the name of the curl pod: +. Export a `CURL_POD` environment variable and initialize it with the name of the curl pod by running the following command: + [source,terminal] ---- $ export CURL_POD=$(oc get pod -n curl -l app=curl -o jsonpath='{.items[0].metadata.name}') ---- -. Create a YAML file named `http-se.yaml` that directs traffic from the mesh to an external service. The following example defines a `ServiceEntry` for a URL. +. Create a YAML file named `http-se.yaml` that directs traffic from the mesh to an external service. The following example defines a `ServiceEntry` for a URL: + [source,yaml,subs="attributes,verbatim"] ---- @@ -96,7 +98,7 @@ spec: $ oc apply -f http-se.yaml ---- -. Ensure the `ServiceEntry` configuration was applied correctly. Send an HTTP request to the host that you specified in the previous step by running the following command: +. Ensure that you applied the `ServiceEntry` configuration correctly. Send an HTTP request to the host that you specified in the previous step by running the following command: + [source,terminal] ---- @@ -105,7 +107,7 @@ $ oc exec "$CURL_POD" -n curl -c curl -- curl -sSL -o /dev/null -D - http://docs + This command should return HTTP status codes, such as `301` (redirect) or `200` (success), indicating that the connection works. -. Create a YAML file named `http-gtw.yaml` that creates an egress `Gateway` and routes traffic from the mesh to the host specified for the external service. +. Create a YAML file named `http-gtw.yaml` that creates an egress `Gateway` and routes traffic from the mesh to the host specified for the external service, similar to the following example: + [source,yaml,subs="attributes,verbatim"] ---- @@ -143,7 +145,7 @@ spec: $ oc apply -f http-gtw.yaml ---- -. Create a YAML file named `http-vs.yaml` that sets up a `VirtualService` to manage the flow of traffic from the application sidecars through the egress gateway to the external host. +. Create a YAML file named `http-vs.yaml` that sets up a `VirtualService` to manage the flow of traffic from the application sidecars through the egress gateway to the external host, similar to the following example: + [source,yaml,subs="attributes,verbatim"] ---- @@ -210,7 +212,7 @@ HTTP/2 200 Content-Type: text/html; charset=utf-8 ---- -. Ensure that the request was routed through the gateway by running the following command: +. Ensure that the gateway routed the request by running the following command: + [source,terminal] ---- @@ -219,7 +221,7 @@ $ oc logs deployment/ -n | tail -1 + [NOTE] ==== -Access logging must be enabled for this verification step to work. You can enable access logging to the standard output by setting the `spec.values.meshConfig.accessLogFile` field to `/dev/stdout` in the {istio} resource. +You must enable access logging for this verification step to work. You can enable access logging to the standard output by setting the `spec.values.meshConfig.accessLogFile` field to `/dev/stdout` in the {istio} resource. ==== + The terminal should display information similar to the following output: diff --git a/modules/ossm-directing-egress-traffic-through-a-gateway-using-kubernetes-gateway-api.adoc b/modules/ossm-directing-egress-traffic-through-a-gateway-using-kubernetes-gateway-api.adoc index c5a4db119a7..324ce4a1edf 100644 --- a/modules/ossm-directing-egress-traffic-through-a-gateway-using-kubernetes-gateway-api.adoc +++ b/modules/ossm-directing-egress-traffic-through-a-gateway-using-kubernetes-gateway-api.adoc @@ -1,4 +1,5 @@ // This procedure is used in the following assembly: +// // * service-mesh-docs-main/gateways/ossm-directing-outbound-traffic-through-a-gateway :_mod-docs-content-type: PROCEDURE @@ -24,7 +25,7 @@ Use the {k8s} Gateway API to direct outbound HTTP traffic through an egress gate As of {k8s} 1.28 and {ocp-product-title} 4.18 or earlier version of {product-title}, the {k8s} Gateway API CRDs are not available by default and you must install the CRDs before you can use them. {ocp-product-title} 4.19 and later versions install the CRDs by default. ==== -.. Create a YAML file named `gateway-cr.yaml` that enables the Kubernetes Gateway API CRDs. +.. Create a YAML file named `gateway-cr.yaml` that enables the Kubernetes Gateway API CRDs, similar to the following example: + [source,yaml,subs="attributes,verbatim"] ---- @@ -92,7 +93,7 @@ $ oc create namespace egress-gateway $ oc label namespace egress-gateway istio-injection=enabled ---- -. Create a YAML file named `egress-gateway-cr.yaml` that defines the egress gateway. +. Create a YAML file named `egress-gateway-cr.yaml` that defines the egress gateway, similar to the following example: + [source,yaml,subs="attributes,verbatim"] ---- @@ -178,7 +179,7 @@ $ oc apply -f egress-gateway-cr.yaml $ oc describe gateway -n egress-gateway ---- + -Desired output is indicated by `Programmed` showing in the `Status` column. +The `Status` column displays `Programmed` to indicate the required output. . Create a `curl` pod in the `egress-gateway` namespace by running the following command: + @@ -194,4 +195,4 @@ $ oc run test-pod --image=curlimages/curl:latest -n egress-gateway --rm -it --re $ curl -v http://httpbin.org/get ---- + -Desired output shows a response from `httpbin.org` that indicates egress traffic routes through the configured gateway. \ No newline at end of file +The required output shows a response from `httpbin.org` that indicates egress traffic routes through the configured gateway. \ No newline at end of file diff --git a/modules/ossm-edge-traffic-planning.adoc b/modules/ossm-edge-traffic-planning.adoc new file mode 100644 index 00000000000..6f00a561df9 --- /dev/null +++ b/modules/ossm-edge-traffic-planning.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-edge-traffic-planning_{context}"] += Plan your ingress and egress strategy + +[role="_abstract"] + +Most applications need to accept traffic from external clients or send traffic to external services. Gateways, which are standalone Envoy proxy deployments at the edge of the mesh, give you control over this traffic at the boundary. + +Without gateways, external traffic can still reach mesh services through direct pod access or {ocp-short-name} routes, but none of the mesh's routing rules, security policies, or observability features apply to that traffic. + +Gateways provide a managed entry and exit point where you can enforce policies and monitor traffic as it crosses the boundary: + +* 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. + +== 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. + +At the gateway boundary, you secure external connections by configuring standard TLS certificates on the gateway itself. Gateways can also require authentication of external requests and enforce authorization policies to control which external traffic is allowed into the mesh. + diff --git a/modules/ossm-enable-ambient-on-existing-sidecar-mesh.adoc b/modules/ossm-enable-ambient-on-existing-sidecar-mesh.adoc new file mode 100644 index 00000000000..751a43294c0 --- /dev/null +++ b/modules/ossm-enable-ambient-on-existing-sidecar-mesh.adoc @@ -0,0 +1,188 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/install/ossm-ambient-sidecar-coexistence.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ossm-enable-ambient-on-existing-sidecar-mesh_{context}"] += Enable ambient mode on an existing sidecar mesh + +[role="_abstract"] +Add ambient workloads to an existing sidecar-mode {SMProduct} installation by updating the control plane configuration and deploying the ztunnel proxy. After you complete this procedure, you can run sidecar and ambient workloads in separate namespaces within the same mesh. + +.Prerequisites + +* You have an existing {SMProduct} installation (version 3.2 or later) in sidecar mode on {ocp-product-title}. +* You are logged in to the {ocp-product-title} cluster as a user with the `cluster-admin` role. + +.Procedure + +. Update the existing `{istio}` CR to set `profile: ambient` and to configure the trusted `ztunnel` namespace, as shown in the following example. Save the configuration to a file named `istio_ambient.yaml`. ++ +[source,yaml] +---- +apiVersion: sailoperator.io/v1 +kind: Istio +metadata: + name: default +spec: + namespace: istio-system + profile: ambient + values: + pilot: + trustedZtunnelNamespace: ztunnel +---- ++ +[IMPORTANT] +==== +You must set `spec.profile` to `ambient` and set `spec.values.pilot.trustedZtunnelNamespace` to `ztunnel`. This is the namespace in which you install the `ZTunnel` resource. +==== + +. Apply the updated `{istio}` CR by running the following command: ++ +[source,terminal] +---- +$ oc apply -f istio_ambient.yaml +---- + +. Update the `IstioCNI` resource to enable the ambient profile, as shown in the following example. Save the configuration to a file named `istiocni_ambient.yaml`. ++ +[source,yaml] +---- +apiVersion: sailoperator.io/v1 +kind: IstioCNI +metadata: + name: default +spec: + profile: ambient +---- + +. Apply the updated `IstioCNI` resource by running the following command: ++ +[source,terminal] +---- +$ oc apply -f istiocni_ambient.yaml +---- + +. Confirm that the `IstioCNI` resource is ready by running the following command: ++ +[source,terminal] +---- +$ oc wait --for=condition=Ready istiocnis/default --timeout=3m +---- + +. Create the `ztunnel` namespace by running the following command: ++ +[source,terminal] +---- +$ oc create namespace ztunnel +---- + +. Create a file named `ztunnel.yaml` that has the `ZTunnel` resource. For example: ++ +[source,yaml] +---- +apiVersion: sailoperator.io/v1 +kind: ZTunnel +metadata: + name: default +spec: + namespace: ztunnel + targetRef: + kind: Istio + name: default +---- ++ +[NOTE] +==== +The `spec.targetRef` field associates the `ZTunnel` instance with an {istio} control plane. When you set this field, the system automatically copies values relevant to `ZTunnel`, such as `global`, `meshConfig`, and `revision`, from the referenced `Istio` or `IstioRevision` resource. Values that you set in the `ZTunnel` `spec.values` field override inherited values. +==== + +. Apply the `ZTunnel` CR by running the following command: ++ +[source,terminal] +---- +$ oc apply -f ztunnel.yaml +---- + +. Confirm that the `ZTunnel` resource is ready by running the following command: ++ +[source,terminal] +---- +$ oc wait --for=condition=Ready ztunnels/default --timeout=3m +---- + +. Confirm that the {istio} control plane is ready by running the following command: ++ +[source,terminal] +---- +$ oc wait --for=condition=Ready istios/default --timeout=3m +---- + +. Restart existing sidecar pods in each namespace that has sidecar workloads. Run the following command for each namespace: ++ +[source,terminal,subs="+quotes"] +---- +$ oc rollout restart deployment -n __ +---- ++ +The restart re-injects the pods with `ISTIO_META_ENABLE_HBONE` set to `true`. Without this setting, the sidecar proxies cannot communicate with workloads in the ambient data plane. If you have a large number of sidecar pods, consider restarting them in small batches or one at a time to avoid disruption. + +. Create a namespace for your ambient workloads by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc create namespace __ +---- + +. Label the namespace to enable ambient mode by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc label namespace __ istio.io/dataplane-mode=ambient +---- + +. Deploy your application workloads to `__`. ++ +The mesh uses the ztunnel proxy to intercept traffic for pods in this namespace. You do not need to change your workload manifests. + +.Verification + +. Verify that your ambient workloads run without a sidecar proxy: ++ +[source,terminal,subs="+quotes"] +---- +$ oc get pods -n __ +---- ++ +Example output: ++ +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +my-app-6d8f94b7c9-xk2pj 1/1 Running 0 45s +---- ++ +Pods in an ambient namespace show `1/1` containers in the `READY` column. This output confirms that the mesh did not inject a sidecar proxy into the pod. + +. Verify that ztunnel registered your ambient workloads and configured HBONE. Run the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ istioctl ztunnel-config workloads --namespace ztunnel --workload-namespace __ +---- ++ +The output lists the mesh workloads: ++ +[source,terminal] +---- +NAMESPACE POD NAME IP NODE WAYPOINT PROTOCOL +example example-gateway-istio-59dd7c96db-q9k6v 10.244.1.11 ambient-worker None TCP +example example-app-cf74bb974-5sqkp 10.244.1.5 ambient-worker None HBONE +---- ++ +Confirm that the PROTOCOL column displays HBONE for your new ambient pods. This protocol value indicates that ztunnel configured HBONE. + +[NOTE] +==== +When a sidecar pod sends traffic to an ambient pod, the traffic bypasses the waypoint proxy of the destination. As a result, the mesh enforces only L4 authorization policies on this path; L7 policies do not apply. +==== 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-enable-sidecar-on-existing-ambient-mesh.adoc b/modules/ossm-enable-sidecar-on-existing-ambient-mesh.adoc new file mode 100644 index 00000000000..8cc54d8be1f --- /dev/null +++ b/modules/ossm-enable-sidecar-on-existing-ambient-mesh.adoc @@ -0,0 +1,36 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/install/ossm-ambient-sidecar-coexistence.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ossm-enable-sidecar-on-existing-ambient-mesh_{context}"] += Enable sidecar mode on an existing ambient mesh + +[role="_abstract"] +Add sidecar workloads to an existing ambient-mode {SMProduct} installation by configuring automatic sidecar injection for a dedicated namespace. After you complete this procedure, you can run sidecar and ambient workloads in separate namespaces within the same mesh. + +.Prerequisites + +* You have an existing {SMProduct} installation (version 3.2 or later) in ambient mode on {ocp-product-title}. +* You are logged in to the {ocp-product-title} cluster as a user with the `cluster-admin` role. + +.Procedure + +* Follow the procedure _Enabling sidecar injection with namespace labels_ in this guide. ++ +[IMPORTANT] +==== +Do not apply the `istio.io/dataplane-mode: ambient` label to sidecar namespaces. If you apply both labels, sidecar injection takes precedence, but the resulting configuration is ambiguous and difficult to maintain. +==== + +.Verification + +* Confirm that the namespace does not have the ambient label: ++ +[source,terminal,subs="+quotes"] +---- +$ oc get namespace __ --show-labels +---- ++ +The output displays the active labels. Verify that the string `istio.io/dataplane-mode=ambient` does not appear. + diff --git a/modules/ossm-enabling-cross-namespace-waypoint-usage.adoc b/modules/ossm-enabling-cross-namespace-waypoint-usage.adoc index 21f578a1df7..cbc4f905528 100644 --- a/modules/ossm-enabling-cross-namespace-waypoint-usage.adoc +++ b/modules/ossm-enabling-cross-namespace-waypoint-usage.adoc @@ -1,10 +1,10 @@ // Module included in the following assemblies: - +// // * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc :_mod-docs-content-type: PROCEDURE [id="ossm-enabling-cross-namespace-waypoint-usage_{context}"] -= Enabling cross-namespace waypoint usage += Enable cross-namespace waypoint usage [role="_abstract"] @@ -21,7 +21,8 @@ $ oc label namespace default istio-discovery=enabled . Create a `Gateway` resource that allows workloads in the `bookinfo` namespace to use the `waypoint-default` from the `default` namespace similar to the following example: + -.Example configuration +You can see the following example configuration for reference: ++ [source,yaml] ---- apiVersion: gateway.networking.k8s.io/v1 @@ -52,7 +53,7 @@ $ oc apply -f waypoint-default.yaml . Add the labels required to use a cross-namespace waypoint: -.. Add the `istio.io/use-waypoint-namespace` label to specify the namespace where the waypoint resides by running the following command: +.. Add the `istio.io/use-waypoint-namespace` label to specify the namespace where the waypoint is present by running the following command: + [source,terminal] ---- diff --git a/modules/ossm-enabling-sidecar-injection-exclude-workload-from-mesh.adoc b/modules/ossm-enabling-sidecar-injection-exclude-workload-from-mesh.adoc new file mode 100644 index 00000000000..2c6d3132b4d --- /dev/null +++ b/modules/ossm-enabling-sidecar-injection-exclude-workload-from-mesh.adoc @@ -0,0 +1,68 @@ +// Module included in the following assemblies: +// +// install/ossm-sidecar-injection + +:_mod-docs-content-type: PROCEDURE +[id="ossm-enabling-sidecar-injection-exclude-workload-from-mesh_{context}"] += Exclude a workload from the mesh + +[role="_abstract"] + +You can exclude specific workloads from sidecar injection regardless of how injection was enabled. + +[NOTE] +==== +This example is for demonstration purposes only. The bookinfo application requires all workloads to be part of the mesh for proper functionality. +==== + +.Procedure + +. Open the application's `Deployment` resource in an editor. In this case, exclude the `ratings-v1` service. + +. Change the `spec.template.metadata.labels` section of your `Deployment` resource to include the label `sidecar.istio.io/inject: false` to disable sidecar injection. ++ +[source,yaml,subs="attributes,verbatim"] +---- +kind: Deployment +apiVersion: apps/v1 +metadata: +name: ratings-v1 +namespace: bookinfo +labels: + app: ratings + version: v1 +spec: + template: + metadata: + labels: + sidecar.istio.io/inject: 'false' +---- ++ +[NOTE] +==== +Adding the label to the top-level `labels` section of the `Deployment` does not affect sidecar injection. +==== ++ +Updating the deployment triggers a rollout, creating a new `ReplicaSet` with updated pod(s). + +.Verification + +. Verify that the updated pod(s) do not contain a sidecar container and show `1/1` containers as `Running` by running the following command: ++ +[source,terminal] +---- +$ oc get pods -n bookinfo +---- ++ +You should see output similar to the following example: ++ +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +details-v1-6bc7b69776-7f6wz 2/2 Running 0 29m +productpage-v1-54f48db985-gd5q9 2/2 Running 0 29m +ratings-v1-5d645c985f-xsw7p 1/1 Running 0 7s +reviews-v1-bd5f54b8c-zns4v 2/2 Running 0 29m +reviews-v2-5d7b9dbf97-wbpjr 2/2 Running 0 29m +reviews-v3-5fccc48c8c-bjktn 2/2 Running 0 29m +---- diff --git a/modules/ossm-enabling-sidecar-injection-istio-revision-tag-resource.adoc b/modules/ossm-enabling-sidecar-injection-istio-revision-tag-resource.adoc index af71f5625c4..27f7ba12b44 100644 --- a/modules/ossm-enabling-sidecar-injection-istio-revision-tag-resource.adoc +++ b/modules/ossm-enabling-sidecar-injection-istio-revision-tag-resource.adoc @@ -1,44 +1,48 @@ // Module included in the following assemblies: +// // install/ossm-sidecar-injection :_mod-docs-content-type: PROCEDURE [id="ossm-enabling-sidecar-injection-istio-revision-tag-resource_{context}"] -= Enabling sidecar injection with namespace labels and an IstioRevisionTag resource += Inject sidecars with an IstioRevisionTag resource [role="_abstract"] To use the `istio-injection=enabled` label when your revision name is not `default`, you must create an `IstioRevisionTag` resource with the name `default` that references your `Istio` resource. -//Prereqs lifted from existing content https://docs.redhat.com/en/documentation/red_hat_openshift_service_mesh/3.0/html/installing/ossm-sidecar-injection -//any changes made will need to be part of refactoring Jira issue OSSM-9078 so content is consistent .Prerequisites * You have installed the {SMProductName} Operator, created an `{istio}` resource, and the Operator has deployed {istio}. + * You have created the `IstioCNI` resource, and the Operator has deployed the necessary `IstioCNI` pods. + * You have created the namespaces that are to be part of the mesh, and they are discoverable by the {istio} control plane. -* Optional: You have deployed the workloads to be included in the mesh. In the following examples, the Bookinfo has been deployed to the `bookinfo` namespace, but sidecar injection (step 5 in "Deploying the Bookinfo application" procedure) has not been configured. For more information, see "Deploying the Bookinfo application". + +* Optional: You have deployed the workloads that you want to include in the mesh. In the following examples, you deployed the Bookinfo application to the `bookinfo` namespace, but did not configure sidecar injection (step 5 in "Deploying the Bookinfo application" procedure). For more information, see "Deploying the Bookinfo application". .Procedure -. Find the name of your `Istio` resource by running the following command: +. Find the name of your `{istio}` resource by running the following command: + [source,terminal] ---- $ oc get istio ---- + -.Example output +You should see output similar to the following example: ++ [source,terminal] ---- NAME REVISIONS READY IN USE ACTIVE REVISION STATUS VERSION AGE default 1 1 1 default-v1-24-3 Healthy v1.24.3 11s ---- + -In this example, the `Istio` resource has the name `default`, but the underlying revision is called `default-v1-24-3`. +In this example, the `{istio}` resource uses the name `default`, but the underlying revision is called `default-v1-24-3`. . Create the `IstioRevisionTag` resource in a YAML file: + -.Example `IstioRevistionTag` resource YAML file +You should see output similar to the following example: ++ [source,yaml] ---- apiVersion: sailoperator.io/v1 @@ -58,33 +62,32 @@ spec: $ oc apply -f istioRevisionTag.yaml ---- -. Verify that the `IstioRevisionTag` resource has been created successfully by running the following command: +. Verify that a new `IstioRevisionTag` resource exists in your cluster by running the following command: + [source,terminal] ---- $ oc get istiorevisiontags.sailoperator.io ---- + -.Example output +*Example output:* ++ [source,terminal] ---- NAME STATUS IN USE REVISION AGE default Healthy True default-v1-24-3 4m23s ---- + -In this example, the new tag is referencing your active revision, `default-v1-24-3`. Now you can use the `istio-injection=enabled` label as if your revision was called `default`. -+ -//lifted from existing content https://docs.redhat.com/en/documentation/red_hat_openshift_service_mesh/3.0/html/installing/ossm-sidecar-injection -//any changes made will need to be part of refactoring Jira issue OSSM-9078 so content is consistent +In this example, the new tag is referencing your active revision, `default-v1-24-3`. Now you can use the `istio-injection=enabled` label as if your revision has the name `default`. -. Confirm that the pods are running without sidecars by running the following command. Any workloads that are already running in the desired namespace should show `1/1` containers in the `READY` column. +. Confirm that the pods are running without sidecars by running the following command. Any workloads that are already running in the required namespace should show `1/1` containers in the `READY` column. + [source,terminal] ---- $ oc get pods -n bookinfo ---- + -.Example output +You should see output similar to the following example: ++ [source,terminal] ---- NAME READY STATUS RESTARTS AGE @@ -104,7 +107,7 @@ $ oc label namespace bookinfo istio-injection=enabled \ namespace/bookinfo labeled ---- -. To ensure sidecar injection is applied, redeploy the workloads in the `bookinfo` namespace by running the following command: +. To ensure the control plane applies sidecar injection, redeploy the workloads in the `bookinfo` namespace by running the following command: + [source,terminal] ---- @@ -120,7 +123,8 @@ $ oc -n bookinfo rollout restart deployments $ oc get pods -n bookinfo ---- + -.Example output +You should see output similar to the following example: ++ [source,terminal] ---- NAME READY STATUS RESTARTS AGE diff --git a/modules/ossm-enabling-sidecar-injection-namespace-labels.adoc b/modules/ossm-enabling-sidecar-injection-namespace-labels.adoc new file mode 100644 index 00000000000..cc2a353ec0c --- /dev/null +++ b/modules/ossm-enabling-sidecar-injection-namespace-labels.adoc @@ -0,0 +1,91 @@ +// Module included in the following assemblies: +// +// install/ossm-sidecar-injection + +:_mod-docs-content-type: PROCEDURE +[id="ossm-enabling-sidecar-injection-namespace-labels_{context}"] += Inject sidecars with namespace labels + +[role="_abstract"] + +In this example, the control plane injects a sidecar proxy into all workloads, making this the best approach when you want to include most workloads in the mesh. + +.Procedure + +. Verify the revision name of the {istio} control plane using the following command: ++ +[source,terminal] +---- +$ oc get istiorevisions +---- ++ +You should see output similar to the following example: ++ +*Example output:* ++ +[source,terminal] +---- +NAME TYPE READY STATUS IN USE VERSION AGE +default Local True Healthy False v1.23.0 4m57s +---- ++ +Since the revision name is default, you can use the default injection labels without referencing the exact revision name. + +. Verify that workloads already running in the required namespace show `1/1` containers as `READY` by using the following command. This confirms that the pods are running without sidecars. ++ +[source,terminal] +---- +$ oc get pods -n bookinfo +---- ++ +You should see output similar to the following example: ++ +*Example output:* ++ +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +details-v1-65cfcf56f9-gm6v7 1/1 Running 0 4m55s +productpage-v1-d5789fdfb-8x6bk 1/1 Running 0 4m53s +ratings-v1-7c9bd4b87f-6v7hg 1/1 Running 0 4m55s +reviews-v1-6584ddcf65-6wqtw 1/1 Running 0 4m54s +reviews-v2-6f85cb9b7c-w9l8s 1/1 Running 0 4m54s +reviews-v3-6f5b775685-mg5n6 1/1 Running 0 4m54s +---- + +. To apply the injection label to the `bookinfo` namespace, run the following command at the CLI: ++ +[source,terminal] +---- +$ oc label namespace bookinfo istio-injection=enabled +namespace/bookinfo labeled +---- + +. To ensure the control plane applies sidecar injection, redeploy the workloads in the `bookinfo` namespace. Use the following command to perform a rolling update of all workloads: ++ +[source,terminal] +---- +$ oc -n bookinfo rollout restart deployments +---- + +.Verification + +. Verify the rollout by checking that the new pods display `2/2` containers as `READY`, confirming successful sidecar injection by running the following command: ++ +[source,terminal] +---- +$ oc get pods -n bookinfo +---- ++ +You should see output similar to the following example: ++ +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +details-v1-7745f84ff-bpf8f 2/2 Running 0 55s +productpage-v1-54f48db985-gd5q9 2/2 Running 0 55s +ratings-v1-5d645c985f-xsw7p 2/2 Running 0 55s +reviews-v1-bd5f54b8c-zns4v 2/2 Running 0 55s +reviews-v2-5d7b9dbf97-wbpjr 2/2 Running 0 55s +reviews-v3-5fccc48c8c-bjktn 2/2 Running 0 55s +---- diff --git a/modules/ossm-enabling-sidecar-injection-pod-labels.adoc b/modules/ossm-enabling-sidecar-injection-pod-labels.adoc new file mode 100644 index 00000000000..f2da24f63b3 --- /dev/null +++ b/modules/ossm-enabling-sidecar-injection-pod-labels.adoc @@ -0,0 +1,103 @@ +// Module included in the following assemblies: +// +// install/ossm-sidecar-injection + +:_mod-docs-content-type: PROCEDURE +[id="ossm-enabling-sidecar-injection-pod-labels_{context}"] += Inject sidecars with pod labels + +[role="_abstract"] + +You can include individual workloads for sidecar injection instead of applying it to all workloads within a namespace, making it ideal for scenarios where only a few workloads need to be part of a service mesh. This example also demonstrates the use of a revision label for sidecar injection, where the `{istio}` resource is created with the name `my-mesh`. A unique `{istio}` resource name is required when multiple {istio} control planes are present in the same cluster or during a revision-based control plane upgrade. + +.Procedure + +. Verify the revision name of the {istio} control plane by running the following command: ++ +[source,terminal] +---- +$ oc get istiorevisions +---- ++ +You should see output similar to the following example: ++ +[source,terminal] +---- +NAME TYPE READY STATUS IN USE VERSION AGE +my-mesh Local True Healthy False v1.23.0 47s +---- ++ +Since the revision name is `my-mesh`, use the revision label `istio.io/rev=my-mesh` to enable sidecar injection. + + +. Verify that workloads already running show `1/1` containers as `READY`, indicating that the pods are running without sidecars by running the following command: ++ +[source,terminal] +---- +$ oc get pods -n bookinfo +---- ++ +You should see output similar to the following example: ++ +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +details-v1-65cfcf56f9-gm6v7 1/1 Running 0 4m55s +productpage-v1-d5789fdfb-8x6bk 1/1 Running 0 4m53s +ratings-v1-7c9bd4b87f-6v7hg 1/1 Running 0 4m55s +reviews-v1-6584ddcf65-6wqtw 1/1 Running 0 4m54s +reviews-v2-6f85cb9b7c-w9l8s 1/1 Running 0 4m54s +reviews-v3-6f5b775685-mg5n6 1/1 Running 0 4m54s +---- + +. Open the application `Deployment` resource in an editor. In this case, update the `ratings-v1` service. + +. Update the `spec.template.metadata.labels` section of your `Deployment` to include the appropriate pod injection or revision label. In this case, `istio.io/rev: my-mesh`: ++ +[source,yaml,subs="attributes,verbatim"] +---- +kind: Deployment +apiVersion: apps/v1 +metadata: +name: ratings-v1 +namespace: bookinfo +labels: + app: ratings + version: v1 +spec: + template: + metadata: + labels: + istio.io/rev: my-mesh +---- ++ +[NOTE] +==== +Adding the label to the top-level `labels` section of the `Deployment` resource does not impact sidecar injection. +==== ++ +Updating the deployment triggers a rollout, creating a new `ReplicaSet` with the updated pod(s). + +.Verification + +. Verify that only the ratings-v1 pod now shows `2/2` containers `READY`, indicating that the sidecar has been successfully injected by running the following command: ++ +[source,terminal] +---- +$ oc get pods -n bookinfo +---- ++ +You should see output similar to the following example: ++ +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +details-v1-559cd49f6c-b89hw 1/1 Running 0 42m +productpage-v1-5f48cdcb85-8ppz5 1/1 Running 0 42m +ratings-v1-848bf79888-krdch 2/2 Running 0 9s +reviews-v1-6b7444ffbd-7m5wp 1/1 Running 0 42m +reviews-v2-67876d7b7-9nmw5 1/1 Running 0 42m +reviews-v3-84b55b667c-x5t8s 1/1 Running 0 42m +---- + +. Repeat for other workloads that you want to include in the mesh. \ No newline at end of file diff --git a/modules/ossm-enabling-sidecar-injection.adoc b/modules/ossm-enabling-sidecar-injection.adoc index 816eb4c7920..ed7b5410efd 100644 --- a/modules/ossm-enabling-sidecar-injection.adoc +++ b/modules/ossm-enabling-sidecar-injection.adoc @@ -1,263 +1,21 @@ // Module included in the following assemblies: +// // install/ossm-sidecar-injection -:_mod-docs-content-type: PROCEDURE +:_mod-docs-content-type: CONCEPT [id="ossm-enabling-sidecar-injection_{context}"] = Enabling sidecar injection [role="_abstract"] -To demonstrate different approaches for configuring sidecar injection, the following procedures use the Bookinfo application. +To show different approaches for configuring sidecar injection, the following procedures use the Bookinfo application. -.Prerequisites +Prerequisites:: * You have installed the {SMProductName} Operator, created an `{istio}` resource, and the Operator has deployed {istio}. -* You have created the `IstioCNI` resource, and the Operator has deployed the necessary `IstioCNI` pods. -* You have created the namespaces that are to be part of the mesh, and they are discoverable by the Istio control plane. -* Optional: You have deployed the workloads to be included in the mesh. In the following examples, the Bookinfo has been deployed to the `bookinfo` namespace, but sidecar injection (step 5) has not been configured. For more information, see "Deploying the Bookinfo application". - -[id="ossm-enabling-sidecar-injection-namespace-labels_{context}"] -== Enabling sidecar injection with namespace labels -In this example, all workloads within a namespace receive a sidecar proxy injection, making it the best approach when the majority of workloads in the namespace should be included in the mesh. - -.Procedure - -. Verify the revision name of the {istio} control plane using the following command: -+ -[source,terminal] ----- -$ oc get istiorevisions ----- -+ -You should see output similar to the following example: -+ -.Example output -[source,terminal] ----- -NAME TYPE READY STATUS IN USE VERSION AGE -default Local True Healthy False v1.23.0 4m57s ----- -+ -Since the revision name is default, you can use the default injection labels without referencing the exact revision name. - -. Verify that workloads already running in the desired namespace show `1/1` containers as `READY` by using the following command. This confirms that the pods are running without sidecars. -+ -[source,terminal] ----- -$ oc get pods -n bookinfo ----- -+ -You should see output similar to the following example: -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -details-v1-65cfcf56f9-gm6v7 1/1 Running 0 4m55s -productpage-v1-d5789fdfb-8x6bk 1/1 Running 0 4m53s -ratings-v1-7c9bd4b87f-6v7hg 1/1 Running 0 4m55s -reviews-v1-6584ddcf65-6wqtw 1/1 Running 0 4m54s -reviews-v2-6f85cb9b7c-w9l8s 1/1 Running 0 4m54s -reviews-v3-6f5b775685-mg5n6 1/1 Running 0 4m54s ----- - -. To apply the injection label to the `bookinfo` namespace, run the following command at the CLI: -+ -[source,terminal] ----- -$ oc label namespace bookinfo istio-injection=enabled -namespace/bookinfo labeled ----- - -. To ensure sidecar injection is applied, redeploy the existing workloads in the `bookinfo` namespace. Use the following command to perform a rolling update of all workloads: -+ -[source,terminal] ----- -$ oc -n bookinfo rollout restart deployments ----- - -.Verification - -. Verify the rollout by checking that the new pods display `2/2` containers as `READY`, confirming successful sidecar injection by running the following command: -+ -[source,terminal] ----- -$ oc get pods -n bookinfo ----- -+ -You should see output similar to the following example: -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -details-v1-7745f84ff-bpf8f 2/2 Running 0 55s -productpage-v1-54f48db985-gd5q9 2/2 Running 0 55s -ratings-v1-5d645c985f-xsw7p 2/2 Running 0 55s -reviews-v1-bd5f54b8c-zns4v 2/2 Running 0 55s -reviews-v2-5d7b9dbf97-wbpjr 2/2 Running 0 55s -reviews-v3-5fccc48c8c-bjktn 2/2 Running 0 55s ----- - -[id="ossm-enabling-sidecar-injection-exclude-workload-from-mesh_{context}"] -== Exclude a workload from the mesh - -You can exclude specific workloads from sidecar injection within a namespace where injection is enabled for all workloads. - -[NOTE] -==== -This example is for demonstration purposes only. The bookinfo application requires all workloads to be part of the mesh for proper functionality. -==== - -.Procedure -. Open the application's `Deployment` resource in an editor. In this case, exclude the `ratings-v1` service. - -. Modify the `spec.template.metadata.labels` section of your `Deployment` resource to include the label `sidecar.istio.io/inject: false` to disable sidecar injection. -+ -[source,yaml,subs="attributes,verbatim"] ----- -kind: Deployment -apiVersion: apps/v1 -metadata: -name: ratings-v1 -namespace: bookinfo -labels: - app: ratings - version: v1 -spec: - template: - metadata: - labels: - sidecar.istio.io/inject: 'false' ----- -+ -[NOTE] -==== -Adding the label to the top-level `labels` section of the `Deployment` does not affect sidecar injection. -==== -+ -Updating the deployment triggers a rollout, creating a new ReplicaSet with updated pod(s). - -.Verification - -. Verify that the updated pod(s) do not contain a sidecar container and show `1/1` containers as `Running` by running the following command: -+ -[source,terminal] ----- -$ oc get pods -n bookinfo ----- -+ -You should see output similar to the following example: -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -details-v1-6bc7b69776-7f6wz 2/2 Running 0 29m -productpage-v1-54f48db985-gd5q9 2/2 Running 0 29m -ratings-v1-5d645c985f-xsw7p 1/1 Running 0 7s -reviews-v1-bd5f54b8c-zns4v 2/2 Running 0 29m -reviews-v2-5d7b9dbf97-wbpjr 2/2 Running 0 29m -reviews-v3-5fccc48c8c-bjktn 2/2 Running 0 29m ----- - -[id="ossm-enabling-sidecar-injection-pod-labels_{context}"] -== Enabling sidecar injection with pod labels - -This approach allows you to include individual workloads for sidecar injection instead of applying it to all workloads within a namespace, making it ideal for scenarios where only a few workloads need to be part of a service mesh. This example also demonstrates the use of a revision label for sidecar injection, where the `{istio}` resource is created with the name `my-mesh`. A unique `{istio}` resource name is required when multiple {istio} control planes are present in the same cluster or during a revision-based control plane upgrade. - -.Procedure - -. Verify the revision name of the {istio} control plane by running the following command: -+ -[source,terminal] ----- -$ oc get istiorevisions ----- -+ -You should see output similar to the following example: -+ -.Example output -[source,terminal] ----- -NAME TYPE READY STATUS IN USE VERSION AGE -my-mesh Local True Healthy False v1.23.0 47s ----- -+ -Since the revision name is `my-mesh`, use the revision label `istio.io/rev=my-mesh` to enable sidecar injection. - - -. Verify that workloads already running show `1/1` containers as `READY`, indicating that the pods are running without sidecars by running the following command: -+ -[source,terminal] ----- -$ oc get pods -n bookinfo ----- -+ -You should see output similar to the following example: -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -details-v1-65cfcf56f9-gm6v7 1/1 Running 0 4m55s -productpage-v1-d5789fdfb-8x6bk 1/1 Running 0 4m53s -ratings-v1-7c9bd4b87f-6v7hg 1/1 Running 0 4m55s -reviews-v1-6584ddcf65-6wqtw 1/1 Running 0 4m54s -reviews-v2-6f85cb9b7c-w9l8s 1/1 Running 0 4m54s -reviews-v3-6f5b775685-mg5n6 1/1 Running 0 4m54s ----- - -. Open the application’s `Deployment` resource in an editor. In this case, update the `ratings-v1` service. - -. Update the `spec.template.metadata.labels` section of your `Deployment` to include the appropriate pod injection or revision label. In this case, `istio.io/rev: my-mesh`: -+ -[source,yaml,subs="attributes,verbatim"] ----- -kind: Deployment -apiVersion: apps/v1 -metadata: -name: ratings-v1 -namespace: bookinfo -labels: - app: ratings - version: v1 -spec: - template: - metadata: - labels: - istio.io/rev: my-mesh ----- -+ -[NOTE] -==== -Adding the label to the top-level `labels` section of the `Deployment` resource does not impact sidecar injection. -==== -+ -Updating the deployment triggers a rollout, creating a new ReplicaSet with the updated pod(s). - -.Verification +* You have created the `IstioCNI` resource, and the Operator has deployed the necessary `IstioCNI` pods. -. Verify that only the ratings-v1 pod now shows `2/2` containers `READY`, indicating that the sidecar has been successfully injected by running the following command: -+ -[source,terminal] ----- -$ oc get pods -n bookinfo ----- -+ -You should see output similar to the following example: -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -details-v1-559cd49f6c-b89hw 1/1 Running 0 42m -productpage-v1-5f48cdcb85-8ppz5 1/1 Running 0 42m -ratings-v1-848bf79888-krdch 2/2 Running 0 9s -reviews-v1-6b7444ffbd-7m5wp 1/1 Running 0 42m -reviews-v2-67876d7b7-9nmw5 1/1 Running 0 42m -reviews-v3-84b55b667c-x5t8s 1/1 Running 0 42m ----- +* You have created the namespaces that are to be part of the mesh, and they are discoverable by the Istio control plane. -. Repeat for other workloads that you wish to include in the mesh. \ No newline at end of file +* Optional: You have deployed the workloads that you want to include in the mesh. In the following examples, you deployed the Bookinfo application to the `bookinfo` namespace, but did not configure sidecar injection (step 5 in "Deploying the Bookinfo application" procedure). For more information, see "Deploying the Bookinfo application". diff --git a/modules/ossm-enabling-strict-mtls-namespace.adoc b/modules/ossm-enabling-strict-mtls-namespace.adoc index 81274f047e6..88999df23de 100644 --- a/modules/ossm-enabling-strict-mtls-namespace.adoc +++ b/modules/ossm-enabling-strict-mtls-namespace.adoc @@ -1,4 +1,5 @@ // Module included in the following assemblies: +// // install/ossm-enabling-mtls.adoc @@ -10,7 +11,8 @@ You can restrict workloads to accept only encrypted mTLS traffic by enabling the `STRICT` mode in `PeerAuthentication`. -.Example `PeerAuthentication` policy for a namespace +You can see the following example configuration for reference: + [source,yaml,subs="attributes,verbatim"] ---- apiVersion: security.istio.io/v1 @@ -23,9 +25,10 @@ spec: mode: STRICT ---- -You can enable mTLS for all destination hosts in the `` by creating a `DestinationRule` resource with `MUTUAL` or `ISTIO_MUTUAL` mode when `auto mTLS` is disabled and `PeerAuthentication` is set to `STRICT` mode. +You can enable mTLS for all destination hosts in the `` by creating a `DestinationRule` resource with `MUTUAL` or `ISTIO_MUTUAL` mode if you disable `auto mTLS` and apply `STRICT` mode to `PeerAuthentication`. + +You can see the following example configuration for reference: -.Example `DestinationRule` policy for a namespace [source,yaml,subs="attributes,verbatim"] ---- apiVersion: networking.istio.io/v1 diff --git a/modules/ossm-enabling-strict-mtls-whole-service-mesh.adoc b/modules/ossm-enabling-strict-mtls-whole-service-mesh.adoc index c5cff3ceaf4..dc7fd0ea403 100644 --- a/modules/ossm-enabling-strict-mtls-whole-service-mesh.adoc +++ b/modules/ossm-enabling-strict-mtls-whole-service-mesh.adoc @@ -1,7 +1,7 @@ // Module included in the following assemblies: +// // install/ossm-enabling-mtls.adoc - :_mod-docs-content-type: CONCEPT [id="ossm-enabling-strict-mtls-whole-service-mesh_{context}"] = Enabling strict mTLS across the whole service mesh @@ -10,7 +10,8 @@ You can configure mTLS across the entire mesh by applying the `PeerAuthentication` policy to the `istiod` namespace, such as `istio-system`. The `istiod` namespace name must match to the `spec.namespace` field of your `Istio` resource. -.Example `PeerAuthentication` policy for the whole mesh +You can see the following example configuration for reference: + [source,yaml,subs="attributes,verbatim"] ---- apiVersion: security.istio.io/v1 @@ -25,7 +26,8 @@ spec: Additionally, create a `DestinationRule` resource to disable mTLS for communication with the API server, as it does not have a sidecar. Apply similar `DestinationRule` configurations for other services without sidecars. -.Example `DestinationRule` policy for the whole mesh +You can see the following example configuration for reference: + [source,yaml,subs="attributes,verbatim"] ---- apiVersion: networking.istio.io/v1 diff --git a/modules/ossm-exposing-a-gateway-to-traffic-outside-the-cluster-using-openshift-routes.adoc b/modules/ossm-exposing-a-gateway-to-traffic-outside-the-cluster-using-openshift-routes.adoc index 8f7b6f7e430..01ecbcc1be7 100644 --- a/modules/ossm-exposing-a-gateway-to-traffic-outside-the-cluster-using-openshift-routes.adoc +++ b/modules/ossm-exposing-a-gateway-to-traffic-outside-the-cluster-using-openshift-routes.adoc @@ -1,4 +1,5 @@ // This procedure is used in the following assembly: +// // * gateways/ossm-getting-traffic-into-a-mesh.adoc :_mod-docs-content-type: PROCEDURE @@ -7,22 +8,22 @@ [role="_abstract"] -You can expose a gateway to traffic outside the cluster by using {ocp-short-name} Routes. This approach provides an alternative to using Kubernetes load balancer service when you have to expose gateways to traffic outside the cluster. +You can expose a gateway to traffic outside the cluster by using {ocp-short-name} Routes. This approach provides an alternative to using {k8s} `LoadBalancer` service when you have to expose gateways to traffic outside the cluster. .Prerequisites -* You have completed the procedure, _Exposing a Service by using the {istio} Gateway and VirtualService resources_. +* You have completed the procedure, "Exposing a Service by using the {istio} `Gateway` and `VirtualService` resources". .Procedure -. Ensure that the `Service` type is set to `ClusterIP` by running the following command: +. Ensure that you set the `Service` type to `ClusterIP` by running the following command: + [source,terminal] ---- $ oc patch service -n -p '{"spec": {"type": "ClusterIP"}}' ---- -. Create a YAML file named `httpbin-route.yaml` that defines a `Route` for the `httpbin` service. +. Create a YAML file named `httpbin-route.yaml` that defines a `Route` for the `httpbin` service similar to the following example: + [source,yaml] ---- @@ -49,7 +50,7 @@ spec: $ oc apply -f httpbin-route.yaml ---- -. Verify that `httpbin` service can be accessed from outside the cluster through the ingress router. Ensure that you set the `INGRESS_HOST` variable appropriately for the environment that your cluster is running in. +. Verify that you can access the `httpbin` service from outside the cluster through the ingress router. Ensure that you set the `INGRESS_HOST` variable appropriately for the environment that your cluster is running in. .. If the cluster runs on AWS, set the `INGRESS_HOST` variable by running the following command: + diff --git a/modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api-in-ambient-mode.adoc b/modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api-in-ambient-mode.adoc index 6a5806a9365..8605119e8b0 100644 --- a/modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api-in-ambient-mode.adoc +++ b/modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api-in-ambient-mode.adoc @@ -1,4 +1,5 @@ // Module included in the following assemblies: +// // * service-mesh-docs-main/gateways/ossm-getting-traffic-into-a-mesh.adoc :_mod-docs-content-type: PROCEDURE @@ -11,7 +12,7 @@ You can use the {k8s} Gateway API to create `Gateway` and `HTTPRoute` resources .Prerequisites -* You are logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role. +* You have logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role. * You have installed the {SMProductName} Operator. @@ -23,7 +24,7 @@ You can use the {k8s} Gateway API to create `Gateway` and `HTTPRoute` resources [NOTE] ==== -When using ambient mode (`istio.io/dataplane-mode=ambient`), it is recommended to use the {k8s} Gateway API for ingress configuration, as {istio} `Gateway` and `VirtualService` resources are not fully compatible with ambient mode. +{SMProductShortName} recommends the {k8s} Gateway API for ingress configuration in ambient mode (`istio.io/dataplane-mode=ambient`), because {istio} `Gateway` and `VirtualService` resources lack full compatibility. ==== .Procedure @@ -83,7 +84,7 @@ $ oc apply -f httpbin-waypoint.yaml $ oc label service httpbin -n httpbin istio.io/ingress-use-waypoint=true ---- + -The label ensures that traffic from the ingress gateway routes through the waypoint proxy and the Layer 7 (L7) policies configured on the waypoint proxy are applied to the ingress traffic, before it reaches the `httpbin` service. +The label ensures that the ingress gateway routes traffic through the waypoint proxy, which applies its Layer 7 (L7) policies to the traffic before it reaches the `httpbin` service. . Apply the waypoint label to the namespace so that all the services inside the namespace routes through the waypoint, by running the following command: + @@ -141,7 +142,7 @@ spec: - name: httpbin port: 8000 ---- -* `spec.parentRefs` binds the `HTTPROUTE` resource to the {k8s} Gateway resource that was created in the earlier step. +* `spec.parentRefs` binds the `HTTPROUTE` resource to the {k8s} Gateway resource that you created in the previous step. * `spec.rules.backendRefs` routes the matching traffic to the `httpbin` service by defining a `backendRefs` that includes the name and port of the `httpbin` service. @@ -283,10 +284,10 @@ $ oc patch service httpbin-gateway-istio -n httpbin -p '{"spec": {"type": "LoadB + [NOTE] ==== -A gateway can also be exposed to traffic outside the cluster by using {ocp-short-name} Routes. For more information, see "Exposing a gateway to traffic outside the cluster using {ocp-short-name} Routes". +{ocp-short-name} Routes can also expose a gateway to traffic outside the cluster. For more information, see "Exposing a gateway to traffic outside the cluster using {ocp-short-name} Routes". ==== -. Verify that the `httpbin` service can be accessed from outside the cluster when using the external hostname or IP address of the gateway Service resource. Ensure that you set the `INGRESS_HOST` variable appropriately for the environment in which your cluster is running. +. Verify that the you can access the `httpbin` service from outside the cluster when using the external hostname or IP address of the gateway Service resource. Ensure that you set the `INGRESS_HOST` variable appropriately for the environment in which your cluster is running. .. Set the `INGRESS_HOST` variable by running the following command: + diff --git a/modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api.adoc b/modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api.adoc index 79957a92c26..fc31a5a9986 100644 --- a/modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api.adoc +++ b/modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api.adoc @@ -1,4 +1,5 @@ // Module included in the following assemblies: +// // * service-mesh-docs-main/gateways/ossm-getting-traffic-into-a-mesh.adoc :_mod-docs-content-type: PROCEDURE @@ -11,7 +12,7 @@ You can use the {k8s} Gateway API to create `Gateway` and `HTTPRoute` resources .Prerequisites -* You are logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role. +* You have logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role. * You installed the {SMProductName} Operator. @@ -108,7 +109,7 @@ spec: - name: httpbin port: 8000 ---- -* `spec.parentRefs` binds the `HTTPROUTE` resource to the {k8s} Gateway resource that was created in the earlier step. +* `spec.parentRefs` binds the `HTTPROUTE` resource to the {k8s} `Gateway` resource you created in the previous step. * `spec.rules.backendRefs` routes the matching traffic to the `httpbin` service by defining a `backendRefs` that includes the name and port of the `httpbin` service. @@ -122,7 +123,7 @@ The `HTTPRoute` resource specifies the rules that route traffic from the gateway $ oc apply -f httpbin-ingress-hr.yaml ---- -. Ensure that the Gateway API service is ready, and that an address is allocated to the service, by running the following command: +. Ensure that the Gateway API service is ready and has an allocated address by running the following command: + [source,terminal] ---- @@ -199,10 +200,10 @@ $ oc patch service -istio -n -p '{"spec": {"ty + [NOTE] ==== -A gateway can also be exposed to traffic outside the cluster by using {ocp-short-name} Routes. For more information, see "Exposing a gateway to traffic outside the cluster using {ocp-short-name} Routes". +{ocp-short-name} Routes can also expose a gateway to traffic outside the cluster. For more information, see "Exposing a gateway to traffic outside the cluster using {ocp-short-name} Routes". ==== -. Verify that the `httpbin` service can be accessed from outside the cluster when using the external hostname or IP address of the gateway Service resource. Ensure that you set the `INGRESS_HOST` variable appropriately for the environment in which your cluster is running. +. Verify that you can access the `httpbin` service from outside the cluster when using the external hostname or IP address of the gateway Service resource. Ensure that you set the `INGRESS_HOST` variable appropriately for the environment in which your cluster is running. .. Set the `INGRESS_HOST` variable by running the following command: + diff --git a/modules/ossm-exposing-service-using-istio-gateway-and-virtualservice.adoc b/modules/ossm-exposing-service-using-istio-gateway-and-virtualservice.adoc index 9ef25124187..2aab63f9497 100644 --- a/modules/ossm-exposing-service-using-istio-gateway-and-virtualservice.adoc +++ b/modules/ossm-exposing-service-using-istio-gateway-and-virtualservice.adoc @@ -1,4 +1,5 @@ // This procedure is used in the following assembly: +// // * gateways/ossm-getting-traffic-into-a-mesh.adoc :_mod-docs-content-type: PROCEDURE @@ -7,7 +8,12 @@ [role="_abstract"] -You can use the {istio} `Gateway` and `VirtualService` resources to configure a gateway that was deployed by using gateway injection. The resources expose a service in the mesh to traffic outside the mesh. You can set the gateway `Service` type to `LoadBalancer` to allow traffic from outside the cluster. +Expose mesh services to external traffic by configuring injected gateways with {istio} `Gateway` and `VirtualService` resources to route traffic from outside the cluster. + +[NOTE] +==== +You can set the gateway `Service` type to `LoadBalancer` to allow traffic from outside the cluster. +==== .Prerequisites @@ -44,7 +50,9 @@ If you are using the `RevisionBased` upgrade strategy, run the following command ---- $ oc get istiorevisions.sailoperator.io ---- -You will get an output similar to the following example: ++ +You should see output similar to the following example: ++ [source,terminal] ---- NAME TYPE READY STATUS IN USE VERSION AGE @@ -68,6 +76,8 @@ $ oc apply -n httpbin -f https://raw.githubusercontent.com/openshift-service-mes . Create a YAML file named `httpbin-gw.yaml` that defines an {istio} `Gateway` resource. This resource configures gateway proxies to expose port 80 (HTTP) for the host, `httpbin.example.com`. + +You can see the following example configuration for reference: ++ [source,yaml] ---- apiVersion: networking.istio.io/v1 @@ -77,17 +87,17 @@ metadata: namespace: httpbin spec: selector: - istio: <1> + istio: servers: - port: number: 80 name: http protocol: HTTP hosts: - - httpbin.example.com <2> + - httpbin.example.com ---- -<1> Set the `selector` to the unique label or set of labels specified in the pod template of the gateway proxy `Deployment`. By default, the {istio} `Gateway` resource configuration will apply to matching gateway pods in all namespaces. -<2> Using the `hosts` field, specify a list of addresses that can be used by clients when attempting to access a mesh service at the associated port. +* `spec.selector` specifies the unique label or set of labels in the pod template of the gateway proxy `Deployment`. By default, the {istio} `Gateway` resource configuration will apply to matching gateway pods in all namespaces. +* `spec.servers.hosts` specifies a list of addresses that the clients use when attempting to access a mesh service at the associated port. . Apply the YAML file by running the following command: + @@ -98,6 +108,8 @@ $ oc apply -f httpbin-gw.yaml . Create a YAML file named `httpbin-vs.yaml` for a `VirtualService`. The `VirtualService` defines the rules that route traffic from the gateway proxy to the `httpbin` service. + +You can see the following example configuration for reference: ++ [source,yaml] ---- apiVersion: networking.istio.io/v1 @@ -107,9 +119,9 @@ metadata: namespace: httpbin spec: hosts: - - httpbin.example.com <1> + - httpbin.example.com gateways: - - httpbin-gateway <2> + - httpbin-gateway http: - match: - uri: @@ -117,14 +129,14 @@ spec: - uri: prefix: /headers route: - - destination: <3> + - destination: port: number: 8000 host: httpbin ---- -<1> Specify the `hosts` that the routing rules of the `VirtualService` will be applied to. The `hosts` specified must be exposed by the {istio} `Gateway` resource the VirtualService is bound to. -<2> Bind the `VirtualService` to the {istio} `Gateway` resource created in the previous step by adding the `Gateway` name to the list of gateways. -<3> Route matching traffic to the `httpbin` service deployed earlier by defining a `destination` that includes the `host` and `port` of the `httpbin` `Service`. +* `spec.hosts` the destination `hosts` for the `VirtualService` routing rules. The {istio} `Gateway` resource must expose the hosts that you bind to the `VirtualService`. +* `spec.gateways` binds the `VirtualService` to the {istio} `Gateway` resource created in the previous step by adding the `Gateway` name to the list of gateways. +* `spec.http.route` route matching traffic to the `httpbin` service deployed earlier by defining a `destination` that includes the `host` and `port` of the `httpbin` `Service`. . Apply the YAML file by running the following command: + @@ -183,7 +195,7 @@ $ oc exec $CURL_POD -n curl -- \ ..svc.cluster.local/get ---- + -The response should return a `404 Not Found` status. This is expected because the `/get` endpoint does not have a matching URI prefix in the `httpbin` `VirtualService` resource. +The response should return a `404 Not Found` status as the `httpbin` `VirtualService` resource lacks a matching URI prefix for the `/get` endpoint. + [source,terminal] ---- @@ -201,10 +213,10 @@ $ oc patch service -n -p '{"spec": {"type": " + [NOTE] ==== -A gateway can also be exposed to traffic outside the cluster by using {ocp-short-name} Routes. For more information, see "Exposing a gateway to traffic outside the cluster using {ocp-short-name} Routes". +{ocp-short-name} Routes can also expose a gateway to traffic outside the cluster. For more information, see "Exposing a gateway to traffic outside the cluster using {ocp-short-name} Routes". ==== -. Verify that `httpbin` service can be accessed from outside the cluster when using the external hostname or IP address of the gateway `Service` resource. Ensure that you set the `INGRESS_HOST` variable appropriately for the environment that your cluster is running in. +. Verify that you can access the `httpbin` service from outside the cluster when using the external hostname or IP address of the gateway `Service` resource. Ensure that you set the `INGRESS_HOST` variable appropriately for the environment that your cluster is running in. .. If the cluster runs on AWS, set the `INGRESS_HOST` variable by running the following command: + 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-identifying-revision-name.adoc b/modules/ossm-identifying-revision-name.adoc index b0d66d81b2d..66d53785219 100644 --- a/modules/ossm-identifying-revision-name.adoc +++ b/modules/ossm-identifying-revision-name.adoc @@ -1,15 +1,16 @@ // Module included in the following assemblies: +// // install/ossm-sidecar-injection :_mod-docs-content-type: CONCEPT [id="ossm-identifying-revision-name_{context}"] -= Identifying the revision name += Identify the revision name for sidecar injection [role="_abstract"] -The label required to enable sidecar injection is determined by the specific control plane instance, known as a revision. Each revision is managed by an `IstioRevision` resource, which is automatically created and managed by the `{istio}` resource, so manual creation or modification of `IstioRevision` resources is generally unnecessary. +Manage sidecar injection by applying revision-specific labels to workloads, which allows the {SMProductName} Operator to automate control plane association through `IstioRevision` resources. -The naming of an `IstioRevision` depends on the `spec.updateStrategy.type` setting in the `{istio}` resource. If set to `InPlace`, the revision shares the `{istio}` resource name. If set to `RevisionBased`, the revision name follows the format `-v`. Typically, each `{istio}` resource corresponds to a single `IstioRevision`. However, during a revision-based upgrade, multiple `IstioRevision` resources may exist, each representing a distinct control plane instance. +The naming of an `IstioRevision` depends on the `spec.updateStrategy.type` setting in the `{istio}` resource. If set to `InPlace`, the revision shares the `{istio}` resource name. If set to `RevisionBased`, the revision name follows the format `-v`. Typically, each `{istio}` resource corresponds to a single `IstioRevision`. However, during a revision-based upgrade, many `IstioRevision` resources might exist, each representing a distinct control plane instance. To see available revision names, use the following command: @@ -20,7 +21,6 @@ $ oc get istiorevisions You should see output similar to the following example: -.Example output [source,terminal] ---- NAME READY STATUS IN USE VERSION AGE @@ -28,9 +28,9 @@ my-mesh-v1-23-0 True Healthy False v1.23.0 114s ---- [id="ossm-identifying-revision-name-default_{context}"] -== Enabling sidecar injection with default revision +== Enable sidecar injection with default revision -When the service mesh's `IstioRevision` name is `default`, it's possible to use the following labels on a namespace or a pod to enable sidecar injection: +When the service mesh's `IstioRevision` name is `default`, it is possible to use the following labels on a namespace or a pod to enable sidecar injection: [options="header"] |=== @@ -47,11 +47,11 @@ You can also enable injection by setting the `istio.io/rev: default` label in th ==== [id="ossm-identifying-revision-name-other_{context}"] -== Enabling sidecar injection with other revisions +== Enable sidecar injection with other revisions -When the `IstioRevision` name is not `default`, use the specific `IstioRevision` name with the `istio.io/rev` label to map the pod to the desired control plane and enable sidecar injection. To enable injection, set the `istio.io/rev: default` label in either the namespace or the pod, as adding it to both is not required. +When the `IstioRevision` name is not `default`, use the specific `IstioRevision` name with the `istio.io/rev` label to map the pod to the required control plane and enable sidecar injection. To enable injection, set the `istio.io/rev: default` label in either the namespace or the pod, as adding it to both is not required. -For example, with the revision shown above, the following labels would enable sidecar injection: +For example, with the revision shown earlier, the following labels would enable sidecar injection: [options="header"] |=== @@ -64,5 +64,5 @@ For example, with the revision shown above, the following labels would enable si [NOTE] ==== -When both `istio-injection` and `istio.io/rev` labels are applied, the `istio-injection` label takes precedence and treats the namespace as part of the default revision. +If you apply both labels, the `istio-injection` label overrides the revision label and assigns the namespace to the default revision. ==== \ No newline at end of file diff --git a/modules/ossm-install-and-deploy-service-mesh.adoc b/modules/ossm-install-and-deploy-service-mesh.adoc new file mode 100644 index 00000000000..a07279e799f --- /dev/null +++ b/modules/ossm-install-and-deploy-service-mesh.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// install/ossm-installing-openshift-service-mesh.adoc + +:_mod-docs-content-type: CONCEPT +[id="ossm-install-and-deploy-service-mesh_{context}"] += Install and deploy the service mesh + +[role="_abstract"] + +To get a fully operational service mesh, you install the {SMProductName} Operator and then deploy the mesh in either sidecar or ambient mode. + +The installation process consists of the following high-level tasks: + +. *Install the {SMProductShortName} Operator.* The Operator provides the custom resource definitions (CRDs) you need to deploy and manage {istio} control planes. + +. *Deploy the mesh in your chosen data plane mode:* ++ +-- +* *Sidecar mode* deploys an Envoy proxy container alongside each application pod. You create `Istio` and `IstioCNI` resources, then use labels to inject sidecars into your workloads. + +* *Ambient mode* uses a node-level proxy (ztunnel) to handle traffic without modifying application pods. You create `Istio`, `IstioCNI`, and `ZTunnel` resources, then label namespaces to enroll workloads in the mesh. +-- diff --git a/modules/ossm-install-console-plugin-ocp-cli.adoc b/modules/ossm-install-console-plugin-ocp-cli.adoc index 96bc1ed8805..eeb7f7c3ea7 100644 --- a/modules/ossm-install-console-plugin-ocp-cli.adoc +++ b/modules/ossm-install-console-plugin-ocp-cli.adoc @@ -8,13 +8,16 @@ [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 * You have access to the {oc-first} on the cluster as an administrator. + * You have installed the {SMProduct} (OSSM). + * You have installed the `{istio}` control plane from OSSM 3.0. + * You have installed the {KialiServer} 2.4. .Procedure @@ -41,7 +44,7 @@ The {ossmc-full} (OSSMC) version must match with the {KialiServer} version. If ` + The plugin resources deploy in the same namespace as the `OSSMConsole` CR. -. Optional: If more than one {KialiServer} is installed in the cluster, specify the `spec.kiali` setting in the OSSMC CR by running a command similar to the following example: +. Optional: If you installed more than one {KialiServer} in the cluster, specify the `spec.kiali` setting in the `OSSMConsole` CR similar to the following example: + [source,yaml,subs="attributes,verbatim"] ---- @@ -63,6 +66,6 @@ EOM . Go to the {ocp-product-title} web console. -. Verify that the *{SMProductShortName}* category is added in the main {ocp-product-title} web console navigation. +. Verify that the *{SMProductShortName}* category shows up in the main {ocp-product-title} web console navigation. -. If the {SMPluginShort} is not installed yet, wait until the web console notifies you that the {SMPluginShort} is installed and prompts you to refresh. \ No newline at end of file +. Wait for the web console to confirm the {SMPluginShort} installation and prompt you to refresh. \ No newline at end of file diff --git a/modules/ossm-install-console-plugin-ocp-web-console.adoc b/modules/ossm-install-console-plugin-ocp-web-console.adoc index 31850ad5909..f43af76bdf6 100644 --- a/modules/ossm-install-console-plugin-ocp-web-console.adoc +++ b/modules/ossm-install-console-plugin-ocp-web-console.adoc @@ -4,18 +4,21 @@ :_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 * You have the administrator access to 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 {KialiServer} 2.4. + +* You have installed the {KialiServer} 2.4 or a later version. .Procedure @@ -36,6 +39,6 @@ The *Version* field must match with the `spec.version` field in your Kiali custo .Verification -. Wait until the web console notifies you that the {SMPluginShort} is installed and prompts you to refresh. +. Wait for the web console to confirm the {SMPluginShort} installation and prompt you to refresh. -. Verify that the *{SMProductShortName}* category is added 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. \ No newline at end of file diff --git a/modules/ossm-install-kiali-operator.adoc b/modules/ossm-install-kiali-operator.adoc index 174689a6483..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] ==== @@ -17,7 +17,7 @@ Do not install the Community version of the Operator. The Community version is n .Prerequisites -* Access to the {product-title} web console. +* You have access to the {product-title} web console. .Procedure diff --git a/modules/ossm-installing-cert-manager.adoc b/modules/ossm-installing-cert-manager.adoc index b85110a678e..57ef08e438d 100644 --- a/modules/ossm-installing-cert-manager.adoc +++ b/modules/ossm-installing-cert-manager.adoc @@ -4,20 +4,27 @@ :_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"] -You can integrate the cert-manager Operator with {SMProduct} by deploying the `istio-csr` agent and configuring an `{istio}` resource that uses the `istio-csr` agent to process workload and control plane certificate signing requests. The following procedure creates a self-signed `issuer` object. +Integrate the cert-manager Operator with {SMProduct} by deploying the `istio-csr` agent and configuring an `{istio}` resource to process certificate signing requests for workloads and the control plane. .Prerequisites -* You have installed the {cert-manager-operator} version 1.15.1. -* You are logged in to {ocp-product-title} 4.14 or later. +* You have installed the {cert-manager-operator} version 1.18.0 or later. + +* You have logged in to {ocp-product-title} 4.14 or later. + * You have installed the {SMProduct} Operator. + * You have a `IstioCNI` instance running in the cluster. + +* If you use {istio} ambient mode, you have installed the `ztunnel` namespace and resource. For more information, see "Installing {istio} ambient mode". + * You have installed the `istioctl` command. + .Procedure . Create the `istio-system` namespace by running the following command: @@ -27,32 +34,22 @@ You can integrate the cert-manager Operator with {SMProduct} by deploying the `i $ oc create namespace istio-system ---- -. Patch the cert-manager Operator to install the `istio-csr` agent by running the following command: -+ -[source, terminal] ----- -$ oc -n cert-manager-operator patch subscription openshift-cert-manager-operator \ - --type='merge' -p \ - '{"spec":{"config":{"env":[{"name":"UNSUPPORTED_ADDON_FEATURES","value":"IstioCSR=true"}]}}}' ----- - . Create the root certificate authority (CA) issuer by creating an `Issuer` object for the `istio-csr` agent: -.. Create a new project for installing the `istio-csr` agent by running the following command: +.. Create a new project to install the `istio-csr` agent by running the following command: + [source, terminal] ---- $ oc new-project istio-csr ---- -.. Create an `Issuer` object similar to the following example: +.. Define an `Issuer` object similar to the following example: + [NOTE] ==== -The `selfSigned` issuer is intended for demonstration, testing, or proof-of-concept environments. For production deployments, use a secure and trusted CA. +The `selfSigned` issuer serves demonstration purposes, testing, or proof-of-concept environments. For production deployments, use a secure and trusted CA. ==== + -.Example `issuer.yaml` file [source, yaml] ---- apiVersion: cert-manager.io/v1 @@ -110,11 +107,10 @@ $ oc apply -f issuer.yaml $ oc wait --for=condition=Ready certificates/istio-ca -n istio-system ---- -. Create the `IstioCSR` custom resource: +. Deploy the `istio-csr` agent: -.. Create the `IstioCSR` custom resource similar to the following example: +.. Define the `IstioCSR` custom resource as shown in the following example: + -.Example `istioCSR.yaml` file [source, yaml] ---- apiVersion: operator.openshift.io/v1alpha1 @@ -135,7 +131,7 @@ spec: namespace: istio-system ---- -.. Create the `istio-csr` agent by by running the following command: +.. Run the following command to apply the custom resource configuration and deploy the `istio-csr` agent: + [source, terminal] + @@ -151,16 +147,15 @@ $ oc create -f istioCSR.yaml $ oc get deployment -n istio-csr ---- -. Install the `istio` resource: +. Install the `{istio}` resource: + [NOTE] ==== -The configuration disables the built-in CA server for {istio} and forwards certificate signing requests from `istiod` to the `istio-csr` agent. The `istio-csr` agent obtains certificates for both `istiod` and mesh workloads from the cert-manager Operator. The `istiod` TLS certificate that is generated by the `istio-csr` agent is mounted into the pod at a known location for use. +The configuration disables the built-in CA server for {istio} and forwards certificate signing requests from `istiod` to the `istio-csr` agent. The `istio-csr` agent obtains certificates for both `istiod` and mesh workloads from the cert-manager Operator. The `istio-csr` agent generates the `istiod` TLS certificate, and the system mounts it into the pod at a known location. ==== -.. Create the `{istio}` object similar to the following example: +.. Define the `{istio}` object to delegate certificate signing to the `istio-csr` agent. Refer to the following example: + -.Example `istio.yaml` file [source, yaml] ---- apiVersion: sailoperator.io/v1 @@ -168,15 +163,16 @@ kind: Istio metadata: name: default spec: - version: v1.24-latest namespace: istio-system values: global: caAddress: cert-manager-istio-csr.istio-csr.svc:443 - pilot: - env: - ENABLE_CA_SERVER: "false" ---- ++ +[NOTE] +==== +If you use {istio} ambient mode, remember to add the previous `caAddress` configuration to your `istiod` configuration. +==== .. Create the `{istio}` resource by running the following command: + @@ -186,7 +182,7 @@ spec: $ oc apply -f istio.yaml ---- -.. Verify that the `istio` resource displays the "Ready" status condition by running the following command: +.. Verify that the `{istio}` resource displays the "Ready" status condition by running the following command: + [source, terminal] ---- diff --git a/modules/ossm-installing-external-control-plane.adoc b/modules/ossm-installing-external-control-plane.adoc index 879f3e311d3..be8d5c49f1f 100644 --- a/modules/ossm-installing-external-control-plane.adoc +++ b/modules/ossm-installing-external-control-plane.adoc @@ -1,18 +1,14 @@ // This procedure is used in the following assembly: +// // * service-mesh-docs-main/install/ossm-multi-cluster-topologies.adoc :_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 @@ -20,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: @@ -125,14 +126,15 @@ spec: defaultRevision: external-istiod global: remotePilotAddress: ${EXTERNAL_ISTIOD_ADDR} - configCluster: true <1> + configCluster: true pilot: configMap: true istiodRemote: injectionPath: /inject/cluster/cluster2/net/network1 EOF ---- -<1> This setting identifies the data plane cluster as the source of the mesh configuration. ++ +* `spec.values.global.configCluster: true` identifies the data plane cluster as the source of the mesh configuration. . Create a project called `istio-cni` on the data plane cluster by running the following command: + @@ -381,7 +383,8 @@ $ oc --context="${CTX_DATA_PLANE_CLUSTER}" get pods -n sample + The terminal should return `2/2` for each pod on the `sample` namespace by running the following command: + -.Example output +*Example output:* ++ [source,terminal] ---- NAME READY STATUS RESTARTS AGE @@ -400,7 +403,8 @@ $ oc exec --context="${CTX_DATA_PLANE_CLUSTER}" -n sample -c sleep deploy/sleep + The terminal should return a response from the `helloworld` application: + -.Example output +*Example output:* ++ [source,terminal] ---- Hello version: v1, instance: helloworld-v1-6d65866976-jb6qc @@ -426,7 +430,8 @@ $ oc get pod -l app=istio-ingressgateway -n sample --context="${CTX_DATA_PLANE_C + The terminal should return output confirming that the gateway is running: + -.Example output +*Example output:* ++ [source,terminal] ---- NAME READY STATUS RESTARTS AGE @@ -460,7 +465,8 @@ $ curl -s "http://${GATEWAY_URL}/hello" + The `helloworld` application should return a response. + -.Example output +*Example output:* ++ [source,terminal] ---- Hello version: v1, instance: helloworld-v1-6d65866976-jb6qc diff --git a/modules/ossm-installing-gateway-using-gateway-injection.adoc b/modules/ossm-installing-gateway-using-gateway-injection.adoc index bba9152bfe0..56a76a77f7c 100644 --- a/modules/ossm-installing-gateway-using-gateway-injection.adoc +++ b/modules/ossm-installing-gateway-using-gateway-injection.adoc @@ -1,10 +1,14 @@ +// This procedure is used in the following assembly: +// +// * service-mesh-docs-main/gateways/ossm-about-gateways.adoc + :_mod-docs-content-type: PROCEDURE [id="ossm-installing-gateway-using-gateway-injection_{context}"] = Installing a gateway by using gateway injection [role="_abstract"] -This procedure explains how to install a gateway by using gateway injection. +Install a gateway by using gateway injection to deploy and configure an Envoy proxy for managing traffic at the edge of the mesh. [NOTE] ==== @@ -14,7 +18,9 @@ You can use this procedure to create ingress or egress gateways. .Prerequisites * You have installed the {SMProduct} Operator version 3.0 or later. + * You have created an {istio} control plane. + * You have created an `IstioCNI` resource. .Procedure @@ -30,10 +36,10 @@ $ oc create namespace ==== Install the gateway and the {istio} control plane in different namespaces. -You can install the gateway in a dedicated gateway namespace. This approach allows the gateway to be shared by many applications operating in different namespaces. Alternatively, you can install the gateway in an application namespace. In this approach, the gateway acts as a dedicated gateway for the application in that namespace. +You can install the gateway in a dedicated gateway namespace. This approach allows many applications in different namespaces to share the same gateway. Or, you can install the gateway in an application namespace. In this approach, the gateway acts as a dedicated gateway for the application in that namespace. ==== -. Create a YAML file named `secret-reader.yml` that defines the service account, role, and role binding for the gateway deployment. These settings enable the gateway to read the secrets, which is required for obtaining TLS credentials. +. Create a YAML file named `secret-reader.yml` that defines the service account, role, and role binding for the gateway deployment, similar to the following example: + [source,yaml,subs="attributes,verbatim"] ---- @@ -66,6 +72,8 @@ subjects: - kind: ServiceAccount name: secret-reader ---- ++ +These settings enable the gateway to read secrets so that it can obtain TLS credentials. . Apply the YAML file by running the following command: + @@ -74,7 +82,7 @@ subjects: $ oc apply -f secret-reader.yml ---- -. Create a YAML file named `gateway-deployment.yml` that defines the Kubernetes `Deployment` object for the gateway. +. Create a YAML file named `gateway-deployment.yml` that defines the Kubernetes `Deployment` object for the gateway, similar to the following example: + [source,yaml,subs="attributes,verbatim"] ---- @@ -90,14 +98,14 @@ spec: template: metadata: annotations: - inject.istio.io/templates: gateway <1> + inject.istio.io/templates: gateway labels: - istio: <2> - sidecar.istio.io/inject: "true" <3> + istio: + sidecar.istio.io/inject: "true" spec: containers: - name: istio-proxy - image: auto <4> + image: auto securityContext: capabilities: drop: @@ -121,13 +129,13 @@ spec: sysctls: - name: net.ipv4.ip_unprivileged_port_start value: "0" - serviceAccountName: secret-reader <5> + serviceAccountName: secret-reader ---- -<1> Indicates that the {istio} control plane uses the gateway injection template instead of the default sidecar template. -<2> Ensure that a unique label is set for the gateway deployment. A unique label is required so that {istio} `Gateway` resources can select gateway workloads. -<3> Enables gateway injection by setting the `sidecar.istio.io/inject` label to `true`. If the name of the {istio} resource is not `default` you must use the `istio.io/rev: ` label instead, where the revision represents the active revision of the {istio} resource. -<4> Sets the image field to `auto` so that the image automatically updates each time the pod starts. -<5> Sets the `serviceAccountName` to the name of the `ServiceAccount` created previously. +* `spec.template.annotations.inject.istio.io/templates` indicates that the {istio} control plane uses the gateway injection template instead of the default sidecar template. +* `spec.template.labels.istio` ensures that you set a unique label for the gateway deployment. {istio} `Gateway` resources require a unique label to select gateway workloads. +* `spec.template.labels.sidecar.istio.io/inject` enables gateway injection by setting this label to `true`. If the name of the {istio} resource is not `default` you must use the `istio.io/rev: ` label instead, where the revision represents the active revision of the {istio} resource. +* `spec.template.spec.containers.image` sets the image field to `auto` so that the image automatically updates each time the pod starts. +* `spec.template.spec.serviceAccountName` sets the `serviceAccountName` to the name of the `ServiceAccount` created previously. . Apply the YAML file by running the following command: + @@ -143,16 +151,15 @@ $ oc apply -f gateway-deployment.yml $ oc rollout status deployment/ -n ---- + -You should see output similar to the following: +You should see output similar to the following example: + -.Example output [source,terminal] ---- Waiting for deployment "" rollout to finish: 0 of 1 updated replicas are available... deployment "" successfully rolled out ---- -. Create a YAML file named `gateway-service.yml` that contains the Kubernetes `Service` object for the gateway. +. Create a YAML file named `gateway-service.yml` that has the {k8s} `Service` object for the gateway. + [source,yaml,subs="attributes,verbatim"] ---- @@ -179,8 +186,8 @@ spec: protocol: TCP targetPort: 443 ---- -<1> When you set `spec.type` to `ClusterIP` the gateway `Service` object can be accessed only from within the cluster. If the gateway has to handle ingress traffic from outside the cluster, set `spec.type` to `LoadBalancer`. Alternatively, you can use OpenShift Routes. -<2> Set the `selector` to the unique label or set of labels specified in the pod template of the gateway deployment that you previously created. +* `spec.type` sets the type of the gateway `Service` object. Setting `spec.type` to `ClusterIP` restricts gateway Service access to the internal cluster network. If the gateway has to handle ingress traffic from outside the cluster, set `spec.type` to `LoadBalancer`. Or, you can use OpenShift Routes. +* `spec.selector` sets the `selector` to the unique label or set of labels specified in the pod template of the gateway deployment that you created previously. . Apply the YAML file by running the following command: + @@ -198,14 +205,15 @@ $ oc get endpoints -n + You should see output similar to the following example: + -.Example output +*Example output:* ++ [source,terminal] ---- NAME ENDPOINTS AGE 10.131.0.181:8080,10.131.0.181:8443 1m ---- -. Optional: Create a YAML file named `gateway-hpa.yml` that defines a horizontal pod autoscaler for the gateway. The following example sets the minimum replicas to `2` and the maximum replicas to `5` and scales the replicas up when average CPU utilization exceeds 80% of the CPU resource limit. This limit is specified in the pod template of the deployment for the gateway. +. Optional: Create a YAML file named `gateway-hpa.yml` that defines a horizontal pod autoscaler for the gateway. The following example sets the minimum replicas to `2` and the maximum replicas to `5` and scales the replicas up when average CPU usage exceeds 80% of the CPU resource limit. The gateway deployment's pod template specifies this limit. + [source,yaml,subs="attributes,verbatim"] ---- @@ -227,9 +235,9 @@ spec: scaleTargetRef: apiVersion: apps/v1 kind: Deployment - name: <1> + name: ---- -<1> Set `spec.scaleTargetRef.name` to the name of the gateway deployment previously created. +* `spec.scaleTargetRef.name` specifies the name of the gateway deployment created previously. . Optional: Apply the YAML file by running the following command: + @@ -238,7 +246,7 @@ spec: $ oc apply -f gateway-hpa.yml ---- -. Optional: Create a YAML file named `gateway-pdb.yml` that defines a pod disruption budget for the gateway. The following example allows gateway pods to be evicted only when at least 1 healthy gateway pod will remain on the cluster after the eviction. +. Optional: Create a YAML file named `gateway-pdb.yml` that defines a pod disruption budget for the gateway. The following example allows gateway pods eviction only when at least 1 healthy gateway pod will remain on the cluster after the eviction: + [source,yaml,subs="attributes,verbatim"] ---- @@ -251,9 +259,9 @@ spec: minAvailable: 1 selector: matchLabels: - istio: <1> + istio: ---- -<1> Set the `spec.selector.matchLabels` to the unique label or set of labels specified in the pod template of the gateway deployment previously created. +* `spec.selector.matchLabels` specifies the unique label or set of labels specified in the pod template of the gateway deployment created previously. . Optional: Apply the YAML file by running the following command: + diff --git a/modules/ossm-installing-istio-ambient-mode.adoc b/modules/ossm-installing-istio-ambient-mode.adoc index 3234edfac2c..a7ea84fb0a4 100644 --- a/modules/ossm-installing-istio-ambient-mode.adoc +++ b/modules/ossm-installing-istio-ambient-mode.adoc @@ -1,21 +1,24 @@ // Module included in the following assemblies: - +// // * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc :_mod-docs-content-type: PROCEDURE [id="ossm-installing-istio-ambient-mode_{context}"] -= Installing Istio ambient mode += Deploy ambient mode using the CLI [role="_abstract"] -You can install {istio} ambient mode on {ocp-product-title} 4.19 or later and {SMProductName} 3.1.0 or later with the required Gateway API custom resource definitions (CRDs). +You can deploy {istio} in ambient mode by using the OpenShift CLI (`oc`) to create the `Istio`, `IstioCNI`, and `ZTunnel` resources. .Prerequisites * You have deployed a cluster on {ocp-product-title} 4.19 or later. + * You have installed the {SMProduct} Operator 3.1.0 or later in the {ocp-product-title} cluster. -* You are logged in to the {ocp-product-title} cluster either through the web console as a user with the `cluster-admin` role, or with the `oc login` command, depending on the installation method. -* You have configured the OVN-Kubernetes Container Network Interface (CNI) to use local gateway mode by setting the `routingViaHost` field as `true` in the `gatewayConfig` specification for the Cluster Network Operator. For more information, see "Configuring gateway mode". + +* You have logged in to the {ocp-product-title} cluster either through the web console as a user with the `cluster-admin` role, or with the `oc login` command, depending on the installation method. + +* You have configured the OVN-Kubernetes Container Network Interface (CNI) to use local gateway mode by setting the `routingViaHost` field as `true` in the `gatewayConfig` specification for the Cluster Network Operator. For more information, see "Configuring gateway mode" in the {ocp-product-title} documentation. .Procedure @@ -30,7 +33,13 @@ $ oc create namespace istio-system .. Create an `{istio}` resource named `istio.yaml` similar to the following example: + -.Example configuration +You can see the following example configuration for reference: ++ +[NOTE] +==== +If your cluster includes {op-system-base-full} 10 or {op-system-first} 10 nodes, you must enable native `nftables` support by setting the `nativeNftables` field to `true` within the `spec.values.global` section. +==== ++ [source,yaml] ---- apiVersion: sailoperator.io/v1 @@ -41,13 +50,15 @@ spec: namespace: istio-system profile: ambient values: + global: + nativeNftables: true # Add this line if deploying on RHEL 10 or RHCOS 10 nodes pilot: trustedZtunnelNamespace: ztunnel ---- + [IMPORTANT] ==== -You must set the `profile` field to `ambient`, and configure the `.spec.values.pilot.trustedZtunnelNamespace` value to match the namespace where the `ZTunnel` resource will be installed. +You must set the `profile` field to `ambient` and configure the `.spec.values.pilot.trustedZtunnelNamespace` value to match the namespace where you install the `ZTunnel` resource. ==== .. Apply the `{istio}` custom resource (CR) by running the following command: @@ -75,7 +86,13 @@ $ oc create namespace istio-cni .. Create the `IstioCNI` resource named `istio-cni.yaml` similar to the following example: + -.Example configuration +You can see the following example configuration for reference: ++ +[NOTE] +==== +If your cluster includes {op-system-base-full} 10 or {op-system-first} 10 nodes, you must enable native `nftables` support by setting the `nativeNftables` field to `true` within the `spec.values.global` section. +==== ++ [source,yaml] ---- apiVersion: sailoperator.io/v1 @@ -85,6 +102,9 @@ metadata: spec: namespace: istio-cni profile: ambient + values: + global: + nativeNftables: true # Add this line if deploying on RHEL 10 or RHCOS 10 nodes ---- + Set the `profile` field to `ambient`. @@ -100,7 +120,7 @@ $ oc apply -f istio-cni.yaml + [source,terminal] ---- -$ oc wait --for=condition=Ready istios/default --timeout=3m +$ oc wait --for=condition=Ready IstioCNI/default --timeout=3m ---- . Install the Ztunnel proxy: @@ -116,7 +136,8 @@ The namespace name for `ztunnel` project must match the `trustedZtunnelNamespace .. Create the `Ztunnel` resource named `ztunnel.yaml` similar to the following example: + -.Example configuration +You can see the following example configuration for reference: ++ [source,yaml] ---- apiVersion: sailoperator.io/v1alpha1 diff --git a/modules/ossm-installing-istio-with-inplace-strategy.adoc b/modules/ossm-installing-istio-with-inplace-strategy.adoc index a4682a0abfc..23bbb0434f1 100644 --- a/modules/ossm-installing-istio-with-inplace-strategy.adoc +++ b/modules/ossm-installing-istio-with-inplace-strategy.adoc @@ -1,13 +1,14 @@ // Module included in the following assemblies: +// // update/ossm-updating-openshift-service-mesh.adoc :_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"] -You can install the {istio} control plane, {istio} CNI, and the Bookinfo demo application using the `Inplace` update strategy. +You can install the {istio} control plane, {istio} CNI, and the Bookinfo demo application by using the `Inplace` update strategy. [NOTE] ==== @@ -69,7 +70,7 @@ spec: type: InPlace ---- -. Install the {istio} CNI plugin with the desired version. The following example configuration creates an `IstioCNI` resource named `default` in the `istio-cni` namespace: +. Install the {istio} CNI plugin with the required version. The following example configuration creates an `IstioCNI` resource named `default` in the `istio-cni` namespace: + [source,yaml] ---- @@ -112,7 +113,7 @@ $ oc apply -f https://raw.githubusercontent.com/openshift-service-mesh/istio/rel $ oc get istio -n istio-system ---- + -.Example output +*Example output:* + [source,terminal] ---- diff --git a/modules/ossm-installing-istio-with-revisionbased-strategy-istiorevisiontag.adoc b/modules/ossm-installing-istio-with-revisionbased-strategy-istiorevisiontag.adoc index 6e78f194325..4ba69426fba 100644 --- a/modules/ossm-installing-istio-with-revisionbased-strategy-istiorevisiontag.adoc +++ b/modules/ossm-installing-istio-with-revisionbased-strategy-istiorevisiontag.adoc @@ -1,14 +1,14 @@ // Module included in the following assemblies: - +// // update/ossm-updating-openshift-service-mesh.adoc :_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"] -You can install the {istio} control plane, `IstioRevisionTag` resource, {istio} CNI, and the Bookinfo demo application using the `RevisionBased` update strategy. +You can install the {istio} control plane, `IstioRevisionTag` resource, {istio} CNI, and the Bookinfo demo application by using the `RevisionBased` update strategy. [NOTE] ==== @@ -26,7 +26,8 @@ $ oc create ns istio-system . Deploy the {istio} control plane using the `RevisionBased` update strategy. The following example configuration creates an `{istio}` resource named `default` in the `istio-system` namespace: + -.Example configuration +You can see the following example configuration for reference: ++ [source,yaml] ---- apiVersion: sailoperator.io/v1 @@ -42,7 +43,8 @@ spec: . Create an `IstioRevisionTag` resource. The following example configuration creates an `IstioRevisionTag` resource named `default`: + -.Example configuration +You can see the following example configuration for reference: ++ [source,yaml] ---- apiVersion: sailoperator.io/v1 @@ -55,7 +57,7 @@ spec: name: default ---- + -Verify that the `targetRef` field points to the desired `{istio}` resource. In the example above, the `IstioRevisionTag` references the `{istio}` resource named `default`. +Verify that the `targetRef` field points to the required `{istio}` resource. In the example above, the `IstioRevisionTag` references the `{istio}` resource named `default`. . Create the `istio-cni` namespace by running the following command: + @@ -64,9 +66,10 @@ Verify that the `targetRef` field points to the desired `{istio}` resource. In t $ oc create ns istion-cni ---- -. Install the {istio} CNI plugin with the desired version. The following example configuration creates an `IstioCNI` resource named `default` in the `istio-cni` namespace: +. Install the {istio} CNI plugin with the required version. The following example configuration creates an `IstioCNI` resource named `default` in the `istio-cni` namespace: ++ +You can see the following example configuration for reference: + -.Example configuration [source,yaml] ---- apiVersion: sailoperator.io/v1 @@ -108,7 +111,7 @@ $ oc apply -f https://raw.githubusercontent.com/openshift-service-mesh/istio/rel $ oc get istiorevisiontag ---- + -.Example output +You should see output similar to the following example: + [source,terminal] ---- @@ -127,7 +130,7 @@ $ istioctl proxy-status + The `VERSION` column should match the control plane version. + -.Example output +You should see output similar to the following example: + [source,terminal] ---- diff --git a/modules/ossm-installing-istio-with-revisionbased-strategy.adoc b/modules/ossm-installing-istio-with-revisionbased-strategy.adoc index b0001674c80..25727a8c6e9 100644 --- a/modules/ossm-installing-istio-with-revisionbased-strategy.adoc +++ b/modules/ossm-installing-istio-with-revisionbased-strategy.adoc @@ -1,14 +1,14 @@ // Module included in the following assemblies: - +// // update/ossm-updating-openshift-service-mesh.adoc :_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"] -You can install the {istio} control plane, {istio} CNI, and the Bookinfo demo application using the `RevisionBased` update strategy. +You can install the {istio} control plane, {istio} CNI, and the Bookinfo demo application by using the `RevisionBased` update strategy. [NOTE] ==== @@ -26,7 +26,8 @@ $ oc create ns istio-system . Deploy the {istio} control plane using the `RevisionBased` update strategy. The following example configuration creates an `{istio}` resource named `default` in the `istio-system` namespace: + -.Example configuration +You can see the following example configuration for reference: ++ [source,yaml] ---- apiVersion: sailoperator.io/v1 @@ -40,9 +41,10 @@ spec: type: RevisionBased ---- -. Install the {istio} CNI plugin with the desired version. The following example configuration creates an `IstioCNI` resource named `default` in the `istio-cni` namespace: +. Install the {istio} CNI plugin with the required version. The following example configuration creates an `IstioCNI` resource named `default` in the `istio-cni` namespace: ++ +You can see the following example configuration for reference: + -.Example configuration [source,yaml] ---- apiVersion: sailoperator.io/v1 @@ -61,7 +63,8 @@ spec: $ oc get istiorevision -n istio-system ---- + -.Example output +You should see output similar to the following example: ++ [source,terminal] ---- NAME TYPE READY STATUS IN USE VERSION AGE @@ -100,7 +103,7 @@ $ oc apply -f https://raw.githubusercontent.com/openshift-service-mesh/istio/rel $ oc get istio -n istio-system ---- + -.Example output +You should see output similar to the following example: + [source,terminal] ---- @@ -119,7 +122,7 @@ $ istioctl proxy-status + The `VERSION` column should match the control plane version. + -.Example output +You should see output similar to the following example: + [source,terminal] ---- diff --git a/modules/ossm-installing-kiali-multi-cluster-mesh.adoc b/modules/ossm-installing-kiali-multi-cluster-mesh.adoc index 4ff1e099ce0..deca8ea0558 100644 --- a/modules/ossm-installing-kiali-multi-cluster-mesh.adoc +++ b/modules/ossm-installing-kiali-multi-cluster-mesh.adoc @@ -1,9 +1,10 @@ // This procedure is used in the following assembly: +// // * install/ossm-multi-cluster-topologies.adoc :_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"] @@ -20,13 +21,13 @@ You can adapt these instructions for a mesh spanning more than two clusters. * You have installed the latest Kiali Operator on each cluster. -* Istio installed in a multi-cluster configuration on each cluster. +* You have {istio} installed in a multi-cluster configuration on each cluster. * You have `istioctl` installed on the laptop you can use to run these instructions. -* You are logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role. +* You have logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role. -* You have configured a metrics store so that Kiali can query metrics from all the clusters. Kiali queries metrics and traces from their respective endpoints. +* You have configured a metrics store so that Kiali can query metrics from all the clusters. Kiali queries metrics and traces from their required endpoints. .Procedure @@ -34,7 +35,8 @@ You can adapt these instructions for a mesh spanning more than two clusters. .. Create a YAML file named `kiali.yaml` that creates a namespace for the Kiali deployment. + -.Example configuration +You can see the following example configuration for reference: ++ [source,yaml,subs="attributes,verbatim"] ---- apiVersion: kiali.io/v1alpha1 @@ -66,7 +68,7 @@ The endpoint for this example uses OpenShift Monitoring to configure metrics. Fo $ oc --context cluster1 apply -f kiali.yaml ---- + -.Example output +You should see output similar to the following example: + [source,terminal] ---- @@ -80,7 +82,7 @@ kiali-istio-system.apps.example.com $ oc wait --context cluster1 --for=condition=Successful kialis/kiali -n istio-system --timeout=3m ---- + -.Example output +You should see output similar to the following example: + [source,terminal] ---- @@ -96,7 +98,8 @@ $ oc --context cluster1 get route kiali -n istio-system -o jsonpath='{.spec.host . Create a Kiali CR on the West cluster. + -.Example configuration +You can see the following example configuration for reference: ++ [source,yaml,subs="attributes,verbatim"] ---- apiVersion: kiali.io/v1alpha1 @@ -135,7 +138,8 @@ $ oc wait --context cluster2 --for=condition=Successful kialis/kiali -n istio-sy .. Create a long lived API token bound to the kiali-service-account in the West cluster. Kiali uses this token to authenticate to the West cluster. + -.Example configuration +You can see the following example configuration for reference: ++ [source,yaml,subs="attributes,verbatim"] ---- apiVersion: v1 @@ -155,7 +159,7 @@ type: kubernetes.io/service-account-token $ oc --context cluster2 apply -f kiali-svc-account-token.yaml ---- -.. Create a `kubeconfig` file and save it as a secret in the namespace on the East cluster where the Kiali deployment resides. +.. Create a `kubeconfig` file and save it as a secret in the namespace on the East cluster where the Kiali deployment is present. + To simplify this process, use the `kiali-prepare-remote-cluster.sh` script to generate the `kubeconfig` file by running the following `curl` command: + @@ -164,14 +168,14 @@ To simplify this process, use the `kiali-prepare-remote-cluster.sh` script to ge $ curl -L -o kiali-prepare-remote-cluster.sh https://raw.githubusercontent.com/kiali/kiali/master/hack/istio/multicluster/kiali-prepare-remote-cluster.sh ---- -.. Modify the script to make it executeable by running the following command: +.. Change the script to make it executeable by running the following command: + [source,terminal] ---- chmod +x kiali-prepare-remote-cluster.sh ---- -.. Execute the script so that it passes the East and West cluster contexts to the `kubeconfig` file by running the following command: +.. Enter the script so that it passes the East and West cluster contexts to the `kubeconfig` file by running the following command: + [source,terminal] ---- @@ -183,7 +187,7 @@ $ ./kiali-prepare-remote-cluster.sh --kiali-cluster-context cluster1 --remote-cl Use the `--help` option to display additional details about how to use the script. ==== -. Trigger the reconciliation loop so that the Kiali Operator registers the remote secret that the CR contains by running the following command: +. Trigger the reconciliation loop so that the Kiali Operator registers the remote secret that the CR has, by running the following command: + [source,terminal] ---- @@ -206,7 +210,7 @@ oc --context cluster1 rollout status deployments/kiali -n istio-system . Log in to Kiali. -.. When you first access Kiali, log in to the cluster that contains the Kiali deployment. In this example, access the `East` cluster. +.. When you first access Kiali, log in to the cluster that has the Kiali deployment. In this example, access the `East` cluster. .. Display the hostname of the Kiali route by running the following command: + @@ -219,11 +223,11 @@ oc --context cluster1 get route kiali -n istio-system -o jsonpath='{.spec.host}' . Log in to the West cluster through Kiali. + -In order to see other clusters in the Kiali UI, you must first login as a user to those clusters through Kiali. +To see other clusters in the Kiali UI, you must first login as a user to those clusters through Kiali. -.. Click on the user profile dropdown in the top right hand menu. +.. Click the user profile dropdown in the top right hand menu. -.. Select *Login to West*. You are redirected to an OpenShift login page and prompted for credentials for the West cluster. +.. Select *Login to West*. The {ocp-short-name} login page appears and requires your West cluster credentials to continue. . Verify that Kiali shows information from both clusters. diff --git a/modules/ossm-installing-kiali-operator-on-remote-clusters.adoc b/modules/ossm-installing-kiali-operator-on-remote-clusters.adoc index dfaa99084f7..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"] @@ -12,7 +12,7 @@ In an external deployment, you must install the Kiali Operator on all clusters, .Prerequisites -* You are logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role. +* You have logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role. * You have {istio} installed in a multi-cluster configuration on each cluster. @@ -22,11 +22,11 @@ In an external deployment, you must install the Kiali Operator on all clusters, * You have set the `clustering.ignore_home_cluster` field to `true` in the `Kiali` custom reource (CR). -* You have given a unique cluster name for the Kiali home cluster in `.spec.kubernetes_config.cluster_name` specification. In an external deployment, you must manually set this name because there is no colocated {istio} control plane to provide it. +* You have given a unique cluster name for the Kiali home cluster in `.spec.kubernetes_config.cluster_name` specification. In an external deployment, you must manually set this name because there is no colocated {istio} control plane to offer it. .Procedure -. Deploy the Kiali Operator on all clusters using the procedure link:https://docs.redhat.com/en/documentation/red_hat_openshift_service_mesh/latest/html/installing/ossm-multi-cluster-topologies#ossm-installing-kiali-multi-cluster-mesh_ossm-multi-cluster-topologies[Installing Kiali in a multi-cluster mesh]. +. Deploy the Kiali Operator on all clusters using the procedure "Installing Kiali in a multi-cluster mesh". . For clusters where Kiali is not deployed, configure the `Kiali` CR to create only the remote cluster resources by setting the `spec.deployment.remote_cluster_resources_only` field to `true`, similar to the following example: + diff --git a/modules/ossm-installing-multi-primary-multi-network-mesh-ambient.adoc b/modules/ossm-installing-multi-primary-multi-network-mesh-ambient.adoc new file mode 100644 index 00000000000..b266662b601 --- /dev/null +++ b/modules/ossm-installing-multi-primary-multi-network-mesh-ambient.adoc @@ -0,0 +1,303 @@ +// This procedure is used in the following assembly: +// +// * install/ossm-multi-cluster-topologies.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ossm-installing-multi-primary-multi-network-mesh-ambient_{context}"] += 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. + +[NOTE] +==== +In this procedure, `CLUSTER1` is the East cluster and `CLUSTER2` is the West cluster. +==== + +You can adapt these instructions for a mesh spanning more than two clusters. + +.Prerequisites + +* You have {istio} version 1.29.2 or later. + +* You have installed the {SMProduct} 3 Operator on all of the clusters that include the mesh. + +* You have created an {istio} Container Network Interface (CNI) resource as described in the "Installing {istio} ambient mode" section of this guide. + +* You have created certificates for the multi-cluster mesh. + +* You have applied certificates to the multi-cluster topology. + +* You have `istioctl` installed. + +* You have installed and configured the MetalLB Operator *if* your environment is on-premise. ++ +In on-site environments, such as those running on bare metal, {ocp-product-title} clusters often do not include a native load-balancer capability. As a result, a service of type `LoadBalancer`, such as the `istio-eastwestgateway`, does not automatically assign an external IP address. To ensure the required external IP assignment for cross-cluster communication, cluster administrators must install and configure the MetalLB Operator. ++ +Once deployed, MetalLB provides a platform-native load balancer. For more information, see link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/networking_operators/metallb-operator[MetalLB Operator]. + +[NOTE] +==== +In addition to bare metal, the MetalLB Operator can offer load balancing for installations on other infrastructures that might lack native load-balancer capability, including: + +* VMware vSphere + +* {ibm-z-title}® and IBM® LinuxONE + +* {ibm-z-title}® and IBM® LinuxONE for Red Hat Enterprise Linux (RHEL) KVM + +* {ibm-power-title}® +==== + +.Procedure + +. Create an `ISTIO_VERSION` environment variable that defines the {istio} version to install, as shown in the following example: ++ +[source,terminal] +---- +$ export ISTIO_VERSION=1.29.2 +---- + +. Install {istio} on the East cluster: + +.. Create an `{istio}` resource on the East cluster by running the following command: ++ +[source,terminal] +---- +$ cat < *OperatorHub* page. +. In the {ocp-product-title} web console, navigate to the *Ecosystem* -> *Software Catalog* page. . Search for the {SMProductName} 3 Operator. diff --git a/modules/ossm-installing-primary-remote-multi-network-mesh.adoc b/modules/ossm-installing-primary-remote-multi-network-mesh.adoc index 67e6c50a630..ceff10fa06a 100644 --- a/modules/ossm-installing-primary-remote-multi-network-mesh.adoc +++ b/modules/ossm-installing-primary-remote-multi-network-mesh.adoc @@ -1,9 +1,10 @@ // This procedure is used in the following assembly: +// // * install/ossm-multi-cluster-topologies.adoc :_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"] @@ -18,7 +19,7 @@ You can adapt these instructions for a mesh spanning more than two clusters. .Prerequisites -* You have installed the {SMProduct} 3 Operator on all of the clusters that comprise the mesh. +* You have installed the {SMProduct} 3 Operator on all of the clusters that include the mesh. * You have completed "Creating certificates for a multi-cluster mesh". @@ -64,10 +65,10 @@ spec: multiCluster: clusterName: cluster1 network: network1 - externalIstiod: true <1> + externalIstiod: true EOF ---- -<1> This enables the control plane installed on the East cluster to serve as an external control plane for other remote clusters. +* `spec.values.global.externalIstiod: true` This enables the control plane installed on the East cluster to serve as an external control plane for other remote clusters. .. Wait for the control plane to return the "Ready" status condition by running the following command: + @@ -129,7 +130,7 @@ spec: EOF ---- -.. Annotate the `istio-system` namespace in the West cluster so that it is managed by the control plane in the East cluster by running the following command: +.. Annotate the `istio-system` namespace in the West cluster so that the East cluster's control plane manages it by running the following command: + [source,terminal] ---- @@ -153,7 +154,7 @@ $ istioctl create-remote-secret \ oc --context="${CTX_CLUSTER1}" apply -f - ---- -.. Wait for the `Istio` resource to return the "Ready" status condition by running the following command: +.. Wait for the `{istio}` resource to return the "Ready" status condition by running the following command: + [source,terminal] ---- @@ -169,5 +170,5 @@ $ oc --context "${CTX_CLUSTER2}" apply -f https://raw.githubusercontent.com/isti + [NOTE] ==== -Since the West cluster is installed with a remote profile, exposing the application services on the East cluster exposes them on the East-West gateways of both clusters. +Because you installed the West cluster with a remote profile, exposing application services on the East cluster also reveals them on the East-West gateways of both clusters. ==== \ No newline at end of file diff --git a/modules/ossm-installing-the-istioctl-tool.adoc b/modules/ossm-installing-the-istioctl-tool.adoc index 4e4dcd005e4..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"] @@ -14,34 +14,24 @@ Install the `istioctl` command-line utility to debug and diagnose {istio} servic * You have access to the {ocp-product-title} web console. -* The {SMProduct} 3 Operator is installed and running. +* You have installed the {SMProduct} 3 Operator. -* You have created at least one `Istio` resource. +* You have created at least one `{istio}` resource. .Procedure -. Confirm which version of the `Istio` resource runs on the installation by running the following command: +. Confirm which version of the `{istio}` resource runs on the installation by running the following command: + [source,terminal] ---- $ oc get istio -ojsonpath="{range .items[*]}{.spec.version}{'\n'}{end}" | sed s/^v// | sort ---- + -If there are multiple `Istio` resources with different versions, choose the latest version. The latest version is displayed last. +If there are many `{istio}` resources with different versions, select the latest version. The latest version is displayed last. . In the {ocp-product-title} web console, click the *Help* icon and select *Command Line Tools*. . Click *Download istioctl*. Choose the version and architecture that matches your system. - -* link:https://mirror.openshift.com/pub/cgw/servicemesh/latest/istioctl-1.24.4-linux-amd64.tar.gz[Linux (x86_64, amd64)] - -* link:https://mirror.openshift.com/pub/cgw/servicemesh/latest/istioctl-1.24.4-linux-arm64.tar.gz[Linux on ARM (aarch64, arm64)] - -* link:https://mirror.openshift.com/pub/cgw/servicemesh/latest/istioctl-1.24.4-darwin-amd64.tar.gz[MacOS (x86_64, amd64)] - -* link:https://mirror.openshift.com/pub/cgw/servicemesh/latest/istioctl-1.24.4-darwin-arm64.tar.gz[MacOS on ARM (aarch64, arm64)] - -* link:https://mirror.openshift.com/pub/cgw/servicemesh/latest/istioctl-1.24.4-windows-amd64.zip[Windows (x86_64, amd64)] . Extract the `istioctl` binary file. @@ -77,7 +67,8 @@ $ export PATH=$PWD:$PATH $ istioctl version ---- + -.Sample output: +You should see output similar to the following example: ++ [source,terminal] ---- client version: 1.20.0 diff --git a/modules/ossm-integrating-kiali-otel.adoc b/modules/ossm-integrating-kiali-otel.adoc index 19c7f504ff9..e102d59d4c0 100644 --- a/modules/ossm-integrating-kiali-otel.adoc +++ b/modules/ossm-integrating-kiali-otel.adoc @@ -4,13 +4,16 @@ :_mod-docs-content-type: CONCEPT [id="ossm-integrating-kiali-otel_{context}"] -= Integrating {DTProductName} with {KialiProduct} += Distributed tracing integration for Kiali [role="_abstract"] You can integrate {DTProductName} with {KialiProduct}, which enables the following features: * Display trace overlays and details on the graph. + * Display scatterplot charts and in-depth trace/span information on detail pages. + * Integrated span information in logs and metric charts. + * Offer links to the external tracing UI. \ No newline at end of file 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 a4ee5a9fb9b..90cd63da42e 100644 --- a/modules/ossm-kiali-about.adoc +++ b/modules/ossm-kiali-about.adoc @@ -4,14 +4,48 @@ :_mod-docs-content-type: CONCEPT [id="ossm-kiali-about_{context}"] -= About Kiali += Kiali for {SMProductName} [role="_abstract"] -// there is only 1 attribute for Kiali at this time -You can use {KialiProduct} to view configurations, monitor traffic, and analyze traces in a single console. It is based on the open source link:https://www.kiali.io/[Kiali] project. +{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. -{KialiProduct} is the management console for {SMProductName}. It provides dashboards, observability, and robust configuration and validation capabilities. It shows the structure of your service mesh by inferring traffic topology and displays the health of your mesh. Kiali provides detailed metrics, powerful validation, access to Grafana, and strong integration with the {TempoName}. +[id="kiali-architecture_{context}"] +== Kiali architecture -// This is OSSM 3.0 TP 1 content -// Content may change, file names may change, directories may change, the order of directories may change, everything may change. \ No newline at end of file +{KialiProduct} consists of the following components: + +Kiali Operator:: Installs and manages the Kiali Server and the {SMPlugin}. + +Kiali Server (back end):: Runs in the container application platform and communicates with the service mesh components, retrieves and processes data, and exposes this data to the console. The Kiali Server does not need storage. When deploying the Server to a cluster, you set configurations in config maps and secrets. + +Kiali console (front end):: A web application that queries the Kiali Server for data to present it to the user. + +Kiali depends on the following external services and components: + +{istio} control plane:: A deployed {istio} control plane (`istiod`) is a Kiali requirement. Kiali retrieves service mesh data and configurations from the control plane, which are exposed through Prometheus and the {product-title} cluster API. + +Prometheus:: Kiali requires Prometheus metrics to determine the mesh topology, display metrics, calculate health, and show possible problems. {ocp-short-name} monitoring provides Prometheus by default. + +{ocp-product-title} API:: Kiali uses the {ocp-product-title} API to fetch and resolve service mesh configurations, including namespaces, services, deployments, pods, and {istio} resources such as virtual services, destination rules, and gateways. + +Tracing:: Tracing is optional. When you install {DTProductName} and configure Kiali, the Kiali console includes a tab to display {DTShortName} data and tracing integration on the graph. + +Grafana:: Grafana is optional. When available, the metrics pages of Kiali display links to the same metric in Grafana for advanced queries. + +[id="kiali-features_{context}"] +== Kiali features + +{KialiProduct} provides the following capabilities: + +Health:: Quickly identify issues with applications, services, or workloads. + +Topology:: Visualize how your applications, services, or workloads communicate through the Kiali graph. + +Metrics:: Chart service mesh and application performance with predefined metrics dashboards, or create your own custom dashboards. + +Tracing:: Follow the path of a request through various microservices that make up an application by using {TempoName} integration. + +Validations:: Perform advanced validations on the most common {istio} objects, such as destination rules, service entries, and virtual services. + +Configuration:: Create, update, and delete {istio} routing configuration by using wizards or directly in the YAML editor in the Kiali console. \ No newline at end of file diff --git a/modules/ossm-kiali-ambient-mode.adoc b/modules/ossm-kiali-ambient-mode.adoc index 3ac2d0c3148..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"] @@ -13,23 +13,23 @@ When running in {istio} ambient mode, Kiali introduces new behaviors and visuali Access requirements:: Kiali requires access to the `ztunnel` namespace to detect whether ambient mode is enabled. Without this access, Kiali does not display ambient-related features. Visualizations and features:: -With ambient badges, Kiali displays badges for namespaces and workloads that are enrolled in the ambient mesh, allowing quick identification. +Kiali displays ambient badges for namespaces and workloads you enrolled in the ambient mesh, enabling quick identification. Traffic graph adjustments:: -Ambient mode introduces new telemetry sources. Kiali collects and displays metrics from both ztunnel and waypoint proxies to provide complete visibility into mesh traffic. New filters and selectors in Kiali allow users to focus on ambient-specific traffic sources. Kiali provides a display option for visualizing waypoint nodes in the traffic graph. +Ambient mode introduces new telemetry sources. Kiali collects and displays metrics from both ztunnel and waypoint proxies to give complete visibility into mesh traffic. You can focus on ambient-specific traffic sources by using new filters and selectors in Kiali. Kiali provides a display option for visualizing waypoint nodes in the traffic graph. + The traffic graph changes based on the ambient enrollment: * Without waypoint proxies, the traffic graph displays only Layer 4 (L4) traffic. -* With waypoint proxies, the graph includes Layer 7 (L7) traffic and may also include L4 traffic. +* With waypoint proxies, the graph includes Layer 7 (L7) traffic and might also include L4 traffic. Workload proxy logs:: Kiali aggregates and filters logs from both ztunnel and waypoint proxies. This unified view simplifies troubleshooting by showing only the relevant log entries for each workload. -Distributed tracing:: Tracing data is available only when waypoint proxies are deployed, because traces are generated by waypoint services. Kiali automatically correlates workload traces with their associated waypoint proxies. +Distributed tracing:: Tracing data is available only after you deploy waypoint proxies, because waypoint services generate the traces. Kiali automatically correlates workload traces with their associated waypoint proxies. Dedicated pages for ambient components:: -The dedicated pages allow users to analyze ambient components separately from workloads and services: +Analyze ambient components separately from workloads and services on the following dedicated pages: * Waypoint pages display detailed information about captured workloads. diff --git a/modules/ossm-kiali-planning.adoc b/modules/ossm-kiali-planning.adoc new file mode 100644 index 00000000000..cbd8e4b08e9 --- /dev/null +++ b/modules/ossm-kiali-planning.adoc @@ -0,0 +1,38 @@ +// Module included in the following assemblies: +// +// * TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-kiali-planning_{context}"] += Kiali as the mesh observability console + +[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 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. + +== What Kiali provides + +Kiali gives you visibility into your mesh from a single console: + +Service topology:: +Kiali infers traffic topology from mesh telemetry and displays a real-time graph of how services communicate. +You can see traffic flow, identify failing connections, and spot unexpected dependencies. + +Health monitoring:: +Kiali shows the health of services, workloads, and applications based on error rates, latency, and request volume. + +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 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 and data plane modes + +Kiali works with both sidecar and ambient modes. +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-mesh-security-planning.adoc b/modules/ossm-mesh-security-planning.adoc new file mode 100644 index 00000000000..7639ea44d1f --- /dev/null +++ b/modules/ossm-mesh-security-planning.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-mesh-security-planning_{context}"] += Plan mesh security + +[role="_abstract"] + +{SMProductShortName} automatically encrypts and authenticates traffic between services by using mutual TLS (mTLS). +This baseline security is active as soon as services are enrolled in the mesh, with no changes to application code. + +Beyond the baseline, you can extend mesh security based on your organization's requirements: + +* *Certificate management:* By default, the mesh uses a built-in certificate authority to issue mTLS certificates. If your organization requires certificates from a specific CA or centralized certificate lifecycle management, you can integrate cert-manager with external PKI. + +* *Attested workload identity:* By default, the mesh issues certificates based on {k8s} service account identity. For environments that require stronger assurance, you can deploy the SPIFFE Runtime Environment (SPIRE) to verify workload identity through platform and runtime attestation before certificates are issued. + +* *Post-quantum cryptography:* Standard mTLS encryption could be vulnerable to future quantum computing attacks. You can enable quantum-resistant key exchange mechanisms to strengthen mesh communications while maintaining compatibility with existing infrastructure. + +These decisions build on each other: mTLS is the foundation, cert-manager changes how certificates are managed, SPIRE changes how workload identity is verified, and post-quantum cryptography strengthens the encryption itself. + diff --git a/modules/ossm-migrating-2-and-3-differences.adoc b/modules/ossm-migrating-2-and-3-differences.adoc index 72849a17ebe..788403575fa 100644 --- a/modules/ossm-migrating-2-and-3-differences.adoc +++ b/modules/ossm-migrating-2-and-3-differences.adoc @@ -2,19 +2,16 @@ // // * service-mesh-docs-main/about/ossm-migrating-assembly.adoc -//Start of an overall Migrating section. -//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. - :_mod-docs-content-type: CONCEPT [id="ossm-2-and-3-differences_{context}"] = Differences between OpenShift Service Mesh 2 and OpenShift Service Mesh 3 [role="_abstract"] -If you are a current {SMProductName} user, there are a number of important differences you need to understand between {SMProduct} 2 and {SMProduct} 3 before you migrate, including the following: +If you are a current {SMProductName} user, there are several important differences you need to understand between {SMProduct} 2 and {SMProduct} 3 before you migrate, including the following: * A new Operator -* Integrations like Observability and Kiali are installed separately +* Integrations such as Observability and Kiali are installed separately * New resources: `Istio` and `IstioCNI` * Scoping of a mesh with `discoverySelectors` and labels * New considerations for sidecar injection @@ -26,5 +23,6 @@ If you are a current {SMProductName} user, there are a number of important diffe * Support for Istioctl * Change to Kubernetes network policy management * Transport layer security (TLS) configuration change +* DNS capture configuration for `ServiceEntry` resources You must be using {SMProduct} 2.6 to migrate to {SMProduct} 3. \ No newline at end of file diff --git a/modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label.adoc b/modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label.adoc index 283e7901a66..34b98d856bc 100644 --- a/modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label.adoc +++ b/modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label.adoc @@ -11,20 +11,21 @@ endif::[] :_mod-docs-content-type: PROCEDURE [id="ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label_{context}"] -//= Migrating a cluster-wide deployment by using the Istio injection label ifdef::ossm-cluster-wide-istio-injection[= Migrating a cluster-wide deployment by using the Istio injection label] ifdef::ossm-cert-manager-istio-injection[= Migrating a cluster-wide deployment by using the Istio injection label with cert-manager] +[role="_abstract"] + You can perform a canary upgrade with the gradual migration of data plane namespaces for a cluster-wide deployment by using the `istio-injection=enabled` label and the `default` revision tag. You must re-label all of the data plane namespaces. However, it is safe to restart any of the workloads at any point during the migration process. -The `bookinfo` application is used as an example for the `Istio` resource. For more information about configuration differences between the {SMProduct} 2 `ServiceMeshControlPlane` resource and the {SMProduct} 3 `Istio` resource, see "ServiceMeshControlPlane resource to Istio resource fields mapping". +The `bookinfo` application is used as an example for the `{istio}` resource. For more information about configuration differences between the {SMProduct} 2 `ServiceMeshControlPlane` resource and the {SMProduct} 3 `{istio}` resource, see "ServiceMeshControlPlane resource to Istio resource fields mapping". .Prerequisites * You have deployed {ocp-product-title} 4.14 or later. -* You are logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role. +* You have logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role. * You have completed the premigration checklists. * You have the {SMProduct} {SMv2Version} Operator installed. * You have the {SMProduct} 3 Operator installed. @@ -44,7 +45,8 @@ endif::[] ifdef::ossm-cert-manager-istio-injection[] . Confirm that your {SMProduct} 2 `ServiceMeshControlPlane` resource is configured with the cert-manager tool. + -.Example `ServiceMeshControlPlane` cert-manager configuration +You can see the following example configuration for reference: ++ [source,yaml] ---- apiVersion: maistra.io/v2 @@ -75,10 +77,12 @@ spec: --reuse-values \ --namespace istio-system \ --wait \ - --set "app.istio.revisions={basic,ossm-3-v1-24-3}" <1> + --set "app.istio.revisions={basic,ossm-3-v1-24-3}" ---- + -<1> The `app.istio.revisions` field must include your {SMProduct} 3.0 control plane revision _before_ you create your `Istio` resource so that proxies can properly communicate with the {SMProduct} 3.0 control plane. +where: ++ +`app.istio.revisions`:: This field must include your {SMProduct} 3.0 control plane revision _before_ you create your `{istio}` resource so that proxies can properly communicate with the {SMProduct} 3.0 control plane. endif::[] . Identify the namespaces that contain a 2.6 control plane by running the following command: @@ -88,7 +92,8 @@ endif::[] $ oc get smcp -A ---- + -.Example output +*Example output:* ++ [source,terminal] ---- NAMESPACE NAME READY STATUS PROFILES VERSION AGE @@ -102,21 +107,22 @@ istio-system install-istio-system 6/6 ComponentsReady ["default"] 2. In the following example configuration, the {istio} control plane has access to all namespaces on the cluster. If you want to limit the namespaces the control plan has access to, you must define discovery selectors. You must match all the data plane namespaces that you plan to migrate from version 2.6. ==== + -.Example `Istio` resource +You can see the following example configuration for reference: ++ [source,yaml,subs="attributes,verbatim"] ---- apiVersion: sailoperator.io/v1 kind: Istio metadata: - name: ossm-3 # <1> + name: ossm-3 spec: updateStrategy: type: RevisionBased - namespace: istio-system # <2> + namespace: istio-system version: v1.24.3 values: meshConfig: - extensionProviders: # <3> + extensionProviders: - name: prometheus prometheus: {} - name: otel @@ -124,13 +130,13 @@ spec: port: 4317 service: otel-collector.opentelemetrycollector-3.svc.cluster.local ---- -<1> The `name`, `updateStrategy` and `version` fields specify how the `IstioRevision` resource name is created. For more information, see "Identifying the revision name". -<2> The 3.0 and 2.6 control planes must run in the same namespace. -<3> Optional: If you are migrating metrics and tracing, update the `extensionProviders` fields according to your tracing and metrics configurations. +* `metadata.name` specifies the name of the `IstioRevision` resource. The `updateStrategy` and `version` fields specify how the resource is updated. For more information, see "Identifying the revision name". +* `spec.namespace` specifies the namespace where the 3.0 and 2.6 control planes must run. +* `spec.values` specifies the configuration values for the 3.0 control plane. If you are migrating metrics and tracing, update the `extensionProviders` fields according to your tracing and metrics configurations. + [NOTE] ==== -To prevent the {SMProduct} 3.0 control plane from injecting proxies in the namespaces that have the `istio-injection=enabled` label applied and are still managed by {SMProduct} 2.6 control plane, do not use use the `default` name for the {istio} resource, and do not create the `default` revision tag in the following steps. You create the `default` revision tag later in this procedure. +To prevent the {SMProduct} 3.0 control plane from injecting proxies in the namespaces that have the `istio-injection=enabled` label applied and are still managed by {SMProduct} 2.6 control plane, do not use the `default` name for the {istio} resource, and do not create the `default` revision tag in the following steps. You create the `default` revision tag later in this procedure. ==== . Apply the YAML file by running the following command: @@ -149,7 +155,8 @@ $ oc apply -f ossm-3.yaml $ oc logs deployments/istiod-ossm-3-v1-24-3 -n istio-system | grep 'Load signing key and cert from existing secret' ---- + -.Example output +*Example output:* ++ [source,terminal] ---- 2024-12-18T08:13:53.788959Z info pkica Load signing key and cert from existing secret istio-system/istio-ca-secret diff --git a/modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label.adoc b/modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label.adoc index 657b70d1b0b..76c579b9f7c 100644 --- a/modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label.adoc +++ b/modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label.adoc @@ -14,6 +14,8 @@ endif::[] ifdef::ossm-cluster-wide-istio-revision[= Migrating a cluster-wide deployment by using the Istio revision label] ifdef::ossm-cert-manager-istio-revision[= Migrating a cluster-wide deployment by using the Istio revision label with cert-manager] +[role="_abstract"] + You can perform a canary upgrade with the gradual migration of data plane namespaces for a cluster-wide deployment by using the `istio.io/rev` label. The `bookinfo` example application is being used for demonstration purposes with a minimal example for the `Istio` resource. For more information on configuration differences between the {SMProduct} 2 `ServiceMeshControlPlane` resource and the {SMProduct} 3 `Istio` resource, see "Configuration fields mapping between Service Mesh 2 and Service Mesh 3". @@ -43,7 +45,8 @@ endif::[] ifdef::ossm-cert-manager-istio-revision[] . Confirm that your {SMProduct} 2 `ServiceMeshControlPlane` resource is configured with the cert-manager tool. + -.Example `ServiceMeshControlPlane` cert-manager configuration +You can see the following example configuration for reference: ++ [source,yaml] ---- apiVersion: maistra.io/v2 @@ -74,10 +77,12 @@ spec: --reuse-values \ --namespace istio-system \ --wait \ - --set "app.istio.revisions={basic,ossm-3-v1-24-3}" <1> + --set "app.istio.revisions={basic,ossm-3-v1-24-3}" ---- + -<1> The `app.istio.revisions` field must include your {SMProduct} 3.0 control plane revision _before_ you create your `Istio` resource so that proxies can properly communicate with the {SMProduct} 3.0 control plane. +where: ++ +`app.istio.revisions`:: This field must include your {SMProduct} 3.0 control plane revision _before_ you create your `Istio` resource so that proxies can properly communicate with the {SMProduct} 3.0 control plane. endif::[] . Identify the namespaces that contain a 2.6 control plane by running the following command: @@ -87,7 +92,8 @@ endif::[] $ oc get smcp -A ---- + -.Example output +*Example output:* ++ [source,terminal] ---- NAMESPACE NAME READY STATUS PROFILES VERSION AGE @@ -101,19 +107,20 @@ istio-system install-istio-system 6/6 ComponentsReady ["default"] 2. In the following example configuration, the {istio} control plane has access to all namespaces on the cluster. If you want limit the namespaces the control plan has access to, you must define discovery selectors. All data plane namespaces that you plan to migrate from version 2.6 must be matched. ==== + -.Example `Istio` resource +You can see the following example configuration for reference: ++ [source,yaml,subs="attributes,verbatim"] ---- apiVersion: sailoperator.io/v1 kind: Istio metadata: - name: ossm-3 <1> + name: ossm-3 spec: updateStrategy: type: RevisionBased - namespace: istio-system <2> + namespace: istio-system version: v{istio-latest} - values: <3> + values: meshConfig: extensionProviders: - name: prometheus @@ -123,9 +130,9 @@ spec: port: 4317 service: otel-collector.opentelemetrycollector-3.svc.cluster.local ---- -<1> The `name`, `updateStrategy` and `version` fields specify how the `IstioRevision` resource name is created. For more information, see "Identifying the revision name". -<2> The 3.0 and 2.6 control planes must run in the same namespace. -<3> If you are migrating metrics and tracing, update the `extensionProviders` fields according to your tracing and metrics configurations. +* `metadata.name` The `name`, `updateStrategy` and `version` fields specify how the `IstioRevision` resource name is created. For more information, see "Identifying the revision name". +* `spec.namespace` The 3.0 and 2.6 control planes must run in the same namespace. +* `spec.values` If you are migrating metrics and tracing, update the `extensionProviders` fields according to your tracing and metrics configurations. . Apply the YAML file by running the following command: + @@ -141,7 +148,8 @@ $ oc apply -f ossm-3.yaml $ oc logs deployments/istiod-ossm-3-v1-24-3 -n istio-system | grep 'Load signing key and cert from existing secret' ---- + -.Example output +*Example output:* ++ [source,terminal] ---- 2024-12-18T08:13:53.788959Z info pkica Load signing key and cert from existing secret istio-system/istio-ca-secret diff --git a/modules/ossm-migrating-a-cluster-wide-deployment-using-the-simple-migration-method.adoc b/modules/ossm-migrating-a-cluster-wide-deployment-using-the-simple-migration-method.adoc index f8313600860..ae068eeccc1 100644 --- a/modules/ossm-migrating-a-cluster-wide-deployment-using-the-simple-migration-method.adoc +++ b/modules/ossm-migrating-a-cluster-wide-deployment-using-the-simple-migration-method.adoc @@ -17,12 +17,12 @@ The simple migration method should not be used in production environments. Using the simple migration method to migrate from {SMProduct} 2 to {SMProduct} 3 might result in traffic disruption to the services running on a mesh. There are two methods to perform the cluster-wide migration without disrupting traffic. See "Migrating a cluster-wide deployment by using the istio injection label" or "Migrating a cluster-wide deployment by using the Istio revision label" for more information. ==== -The `bookinfo` application is used as an example for the `Istio` resource. For more information about configuration differences between the {SMProduct} 2 `ServiceMeshControlPlane` resource and the {SMProduct} 3 `Istio` resource, see "ServiceMeshControlPlane resource to Istio resource fields mapping." +The `bookinfo` application is used as an example for the `{istio}` resource. For more information about configuration differences between the {SMProduct} 2 `ServiceMeshControlPlane` resource and the {SMProduct} 3 `{istio}` resource, see "ServiceMeshControlPlane resource to Istio resource fields mapping." .Prerequisites * You have deployed {ocp-product-title} 4.14 or later. -* You are logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role. +* You have logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role. * You have completed the premigration checklists. * You have the {SMProduct} {SMv2Version} Operator installed. * You have the {SMProduct} 3 Operator installed. @@ -40,7 +40,8 @@ The `bookinfo` application is used as an example for the `Istio` resource. For m $ oc get smcp -A ---- + -.Example output +*Example output:* ++ [source,terminal] ---- NAMESPACE NAME READY STATUS PROFILES VERSION AGE @@ -54,21 +55,22 @@ istio-system install-istio-system 6/6 ComponentsReady ["default"] 2. In the following example configuration, the {istio} control plane has access to all namespaces on the cluster. If you want to limit the namespaces the control plane has access to, you must define discovery selectors. You must match all the data plane namespaces that you plan to migrate from version 2.6. ==== + -.Example `Istio` resource +You can see the following example configuration for reference: ++ [source,yaml,subs="attributes,verbatim"] ---- apiVersion: sailoperator.io/v1 kind: Istio metadata: - name: default # <1> + name: default spec: updateStrategy: type: InPlace - namespace: istio-system # <2> + namespace: istio-system version: v1.24.3 values: meshConfig: - extensionProviders: # <3> + extensionProviders: - name: prometheus prometheus: {} - name: otel @@ -76,9 +78,9 @@ spec: port: 4317 service: otel-collector.opentelemetrycollector-3.svc.cluster.local ---- -<1> The `name`, `updateStrategy` and `version` fields specify how the `IstioRevision` resource name is created. For more information, see "Identifying the revision name." -<2> The 3.0 and 2.6 control planes must run in the same namespace. -<3> If you are migrating metrics and tracing, update the `extensionProviders` fields according to your tracing and metrics configurations. +* `metadata.name` specifies the `name`, `updateStrategy` and `version` fields specify how the `IstioRevision` resource name is created. For more information, see "Identifying the revision name." +* `spec.namespace` specifies the namespace in which the 3.0 and 2.6 control planes must run. +* `spec.values` specifies the values for the {istio} resource. If you are migrating metrics and tracing, update the `extensionProviders` fields according to your tracing and metrics configurations. + [NOTE] ==== @@ -106,7 +108,8 @@ After you apply the YAML file, any time the workloads are restarted, both the {S $ oc logs deployments/istiod -n istio-system | grep 'Load signing key and cert from existing secret' ---- + -.Example output +*Example output:* ++ [source,terminal] ---- 2024-12-18T08:13:53.788959Z info pkica Load signing key and cert from existing secret istio-system/istio-ca-secret diff --git a/modules/ossm-migrating-a-multitenant-deployment.adoc b/modules/ossm-migrating-a-multitenant-deployment.adoc index ac06180551c..b76dfc358b1 100644 --- a/modules/ossm-migrating-a-multitenant-deployment.adoc +++ b/modules/ossm-migrating-a-multitenant-deployment.adoc @@ -3,19 +3,17 @@ // * service-mesh-docs-main/migrating/checklists/ossm-migrating-multitenant.adoc :_mod-docs-content-type: PROCEDURE -[id="migrating-a-multitenant-deployment_{context}""] +[id="migrating-a-multitenant-deployment_{context}"] = Migrating a multitenant deployment [role="_abstract"] -The `bookinfo` example application is being used for demonstration purposes with a minimal example for the `Istio` resource. For more information on configuration differences between the {SMProduct} 2 `ServiceMeshControlPlane` resource and the {SMProduct} 3 `Istio` resource, see "ServiceMeshControlPlane resource to Istio resource fields mapping". - -You can follow these same steps with your own workloads. +This example with the `bookinfo` application demonstrates how to configure a tenant in the `{istio}` resource. You can follow the same steps with your own workloads. .Prerequisites * You have deployed {ocp-product-title} 4.14 or later. -* You are logged in to the {ocp-product-title} web console as a user with the cluster-admin role. +* You have logged in to the {ocp-product-title} web console as a user with the cluster-admin role. * You have completed the premigration checklists. * You have the {SMProduct} {SMv2Version} Operator installed. * You have the {SMProduct} 3 Operator installed. @@ -26,9 +24,7 @@ You can follow these same steps with your own workloads. .Procedure -. Create your `Istio` resource. -+ -.Example `Istio` resource +. Create your `Istio` resource based on the following example: + [source,yaml] ---- @@ -37,14 +33,14 @@ kind: Istio metadata: name: istio-tenant-a spec: - namespace: istio-system-tenant-a <1> + namespace: istio-system-tenant-a version: v1.24.3 values: meshConfig: - discoverySelectors: <2> + discoverySelectors: - matchLabels: tenant: tenant-a - extensionProviders: <3> + extensionProviders: - name: prometheus prometheus: {} - name: otel @@ -52,19 +48,21 @@ spec: port: 4317 service: otel-collector.opentelemetrycollector-3.svc.cluster.local ---- + +* `spec.namespace` specifies the field in your `{istio}` resource. It must be the same namespace as your `ServiceMeshControlPlane` resource. If you set the `spec.namespace` field in your `Istio` resource to a different namespace, the migration does not complete successfully. ++ +[WARNING] +==== +Adding _new_ namespaces to the mesh during the migration is not recommended and requires extra caution. In multitenant mode, a control plane only interacts with namespaces that are part of its mesh. When you install the 3.0 control plane in the same namespace as the 2.6 control plane, leader election determines which one manages the `istio-ca-root-cert` `ConfigMap`. If the 2.6 control plane becomes the leader, it does not distribute this `ConfigMap` to new namespaces managed by the 3.0 control plane. As a result, sidecar injection fails because the required root certificate is missing. +==== +* `spec.values.meshConfig.discoverySelectors` specifies the labels that the control plane uses to identify the namespaces it should manage. By default, control planes watch the entire cluster. When managing multiple control planes on a single cluster, you must narrow the scope of each control plane by setting `discoverySelectors` fields. + -<1> The `spec.namespace` field in your `Istio` resource must be the same namespace as your `ServiceMeshControlPlane` resource. If you set the `spec.namespace` field in your `Istio` resource to a different namespace than your `ServiceMeshControlPlane` resource, the migration does not complete successfully. -<2> By default, control planes watch the entire cluster. When managing multiple control planes on a single cluster, you must narrow the scope of each control plane by setting `discoverySelectors` fields. In this example, the label `tenant-a` is used, but you can use any label or combination of labels. -<3> Optional: If you are migrating metrics and tracing, update the `extensionProviders` fields according to your tracing and metrics configurations. +This example uses the label `tenant-a`, but you can use any label or combination of labels. The labels must match your `discoverySelectors` fields. +* `spec.values.meshConfig.extensionProviders` specifies the metrics and tracing configurations for the control plane. Optional: If you are migrating metrics and tracing, update the `extensionProviders` fields according to your tracing and metrics configurations. -. Add your `tenant` label to each one of your dataplane namespaces by running the following command for each dataplane namespace: +. Add your `tenant` label to each one of your data plane namespaces by running the following command for each data plane namespace: + [source,terminal] ---- $ oc label ns bookinfo tenant=tenant-a ---- -+ -[NOTE] -==== -With {SMProduct} 2.6, namespaces were enrolled into the mesh by adding them to the `ServiceMeshMemberRoll` resource. In {SMProduct} 3, you must label each one of your dataplane namespaces to match your `discoverySelectors` fields. -==== \ No newline at end of file diff --git a/modules/ossm-migrating-a-multitenant-deployment.html b/modules/ossm-migrating-a-multitenant-deployment.html new file mode 100644 index 00000000000..de8e1118cb7 --- /dev/null +++ b/modules/ossm-migrating-a-multitenant-deployment.html @@ -0,0 +1,553 @@ + + + + + + + +Migrating a multitenant deployment + + + + + +
+
+

This example with the bookinfo application demonstrates how to configure a tenant in the {istio} resource. You can follow the same steps with your own workloads.

+
+
+
Prerequisites
+
    +
  • +

    You have deployed {ocp-product-title} 4.14 or later.

    +
    • +
  • +

    You have logged in to the {ocp-product-title} web console as a user with the cluster-admin role.

    +
    • +
  • +

    You have completed the premigration checklists.

    +
    • +
  • +

    You have the {SMProduct} {SMv2Version} Operator installed.

    +
    • +
  • +

    You have the {SMProduct} 3 Operator installed.

    +
    • +
  • +

    You created an IstioCNI resource.

    +
    • +
  • +

    You have the istioctl tool installed.

    +
    • +
  • +

    You are running a MultiTenant ServiceMeshControlPlane.

    +
    • +
  • +

    You have installed the bookinfo application.

    +
    • +
+
+
+
Procedure
+
    +
  1. +

    Create your Istio resource based on the following example:

    +
    +
    +
    apiVersion: sailoperator.io/v1
+kind: Istio
+metadata:
+  name: istio-tenant-a
+spec:
+  namespace: istio-system-tenant-a
+  version: v1.24.3
+  values:
+    meshConfig:
+      discoverySelectors:
+        - matchLabels:
+            tenant: tenant-a
+      extensionProviders:
+        - name: prometheus
+          prometheus: {}
+        - name: otel
+          opentelemetry:
+            port: 4317
+            service: otel-collector.opentelemetrycollector-3.svc.cluster.local
    +
    +
    +
    +
      +
    • +

      spec.namespace specifies the field in your {istio} resource. It must be the same namespace as your ServiceMeshControlPlane resource. If you set the spec.namespace field in your Istio resource to a different namespace, the migration does not complete successfully.

      +
      + + + + + +
      +
      Warning
      +      		 +
      +

      Adding new namespaces to the mesh during the migration is not recommended and requires extra caution. In multitenant mode, a control plane only interacts with namespaces that are part of its mesh. When you install the 3.0 control plane in the same namespace as the 2.6 control plane, leader election determines which one manages the istio-ca-root-cert ConfigMap. If the 2.6 control plane becomes the leader, it does not distribute this ConfigMap to new namespaces managed by the 3.0 control plane. As a result, sidecar injection fails because the required root certificate is missing.

      +
      +
      +
      +
      • +
    • +

      spec.values.meshConfig.discoverySelectors specifies the labels that the control plane uses to identify the namespaces it should manage. By default, control planes watch the entire cluster. When managing multiple control planes on a single cluster, you must narrow the scope of each control plane by setting discoverySelectors fields.

      +
      +

      This example uses the label tenant-a, but you can use any label or combination of labels. The labels must match your discoverySelectors fields.

      +
      +
      • +
    • +

      spec.values.meshConfig.extensionProviders specifies the metrics and tracing configurations for the control plane. Optional: If you are migrating metrics and tracing, update the extensionProviders fields according to your tracing and metrics configurations.

      +
      • +
    +
    +
    2. +
  2. +

    Add your tenant label to each one of your data plane namespaces by running the following command for each data plane namespace:

    +
    +
    +
    $ oc label ns bookinfo tenant=tenant-a
    +
    +
    +
    3. +
+
+
+ + + \ No newline at end of file diff --git a/modules/ossm-migrating-about-kiali-differences.adoc b/modules/ossm-migrating-about-kiali-differences.adoc new file mode 100644 index 00000000000..a00d280b11a --- /dev/null +++ b/modules/ossm-migrating-about-kiali-differences.adoc @@ -0,0 +1,52 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/checklists/ossm-migrating-kiali-differences.adoc + +:_mod-docs-content-type: CONCEPT +[id="ossm-migrating-about-kiali-differences_{context}"] += About migrating Kiali differences + +[role="_abstract"] + +{kialiproduct} with {SMProductName} 3 introduces the following changes: + +New topology graphs:: + +The **Traffic Page Graph** page has been reorganized and built using Patternfly topology with a new topology view showcasing the mesh infrastructure. + +Deprecated configuration settings:: + +To control which namespaces are accessible or visible to users in {smproduct} 3, Kiali relies on `discoverySelectors`. ++ +By default, `deployment.cluster_wide_access=true` is enabled, granting Kiali cluster-wide access to all namespaces in the local cluster. If you are migrating a cluster-wide deployment with Kiali, you must remove the following deprecated and unavailable configuration settings from your Kiali custom resource (CR): + +* `spec.deployment.accessible_namespaces` +* `api.namespaces.exclude` +* `api.namespaces.include` +* `api.namespaces.label_selector_exclude` +* `api.namespaces.label_selector_include` ++ +If you are are using discovery selectors in Istio to restrict the namespaces that `Istiod` watches, then those must match the discovery selectors in your Kiali CR. + +Renamed configuration settings:: + +The following configuration settings have been renamed: ++ +[cols="1,1"] +|=== +|Old configuration |New configuration + +|`external_service.grafana.in_cluster_url` +|`external_service.grafana.internal_url` + +|`external_service.grafana.url` +|`external_service.grafana.external_url` + +|`external_service.tracing.in_cluster_url` +|`external_service.tracing.internal_url` + +|`external_service.tracing.url` +|`external_service.tracing.external_url` +|=== + +These changes reflect evolving capabilities and configuration standards of Kiali within {SMProduct} 3. \ No newline at end of file diff --git a/modules/ossm-migrating-about.adoc b/modules/ossm-migrating-about.adoc new file mode 100644 index 00000000000..32e4a1b5509 --- /dev/null +++ b/modules/ossm-migrating-about.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/ossm-migrating-from-2-to-3-assembly.adoc + +:_mod-docs-content-type: REFERENCE +[id="ossm-migrating-about_{context}"] += About migrating from Service Mesh 2 to Service Mesh 3 + +[role="_abstract"] + +The content in this migration section applies only in the following cases: + +* You are an existing {SMProductName} user running {SMProduct} {SMv2Version}. +* You want to move to {SMProduct} 3.0. + +[IMPORTANT] +==== +If you are not running {SMProduct} {smv2version}, you must update before you can continue. For more information, see "Upgrading Service Mesh". +==== + +During the migration process, you might need to reference, or you might be directed to {SMProduct} 2.x content. It can be beneficial to open "OpenShift Service Mesh 2.x" in a new tab or window for easier reference. This can be especially helpful when you move between {SMProduct} 2 `ServiceMeshControlPlane` resource content and {SMProduct} 3 `{istio}` resource content. \ No newline at end of file diff --git a/modules/ossm-migrating-based-on-your-deployment-model.adoc b/modules/ossm-migrating-based-on-your-deployment-model.adoc new file mode 100644 index 00000000000..238998e01ac --- /dev/null +++ b/modules/ossm-migrating-based-on-your-deployment-model.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/checklists/ossm-migrating-premigration-checklists.adoc + +:_mod-docs-content-type: REFERENCE +[id="ossm-migrating-based-on-your-deployment-model_{context}"] += Find your deployment model + +[role="_abstract"] + +If you are not using the cert-manager tool with your deployment, you are ready to migrate your deployment. Refer to the following migration guides based on your deployment model: + +* "Multitenant migration guide" + +* "Cluster-wide migration guide" + +If you are unsure, you can check if you are using the cert-manager tool with your deployment. \ No newline at end of file diff --git a/modules/ossm-migrating-complete-remove-2-6-control-plane.adoc b/modules/ossm-migrating-complete-remove-2-6-control-plane.adoc index cd28f1c053a..4c452a60e7d 100644 --- a/modules/ossm-migrating-complete-remove-2-6-control-plane.adoc +++ b/modules/ossm-migrating-complete-remove-2-6-control-plane.adoc @@ -14,7 +14,7 @@ After you have migrated all your workloads and gateways, you can remove the {SMp * You have completed migrating your workloads. * You have completed migrating your gateways. -* You are logged in to the {ocp-product-title} web console as a user with the cluster-admin role. +* You have logged in to the {ocp-product-title} web console as a user with the cluster-admin role. [NOTE] ==== @@ -58,7 +58,8 @@ $ oc delete smm --all -A $ oc get smcp,smm,smmr -A ---- + -.Example output +*Example output:* ++ ---- No resources found ---- diff --git a/modules/ossm-migrating-complete-remove-2-6-operator-crds.adoc b/modules/ossm-migrating-complete-remove-2-6-operator-crds.adoc index 301d091dbdc..cef3cdc9302 100644 --- a/modules/ossm-migrating-complete-remove-2-6-operator-crds.adoc +++ b/modules/ossm-migrating-complete-remove-2-6-operator-crds.adoc @@ -16,7 +16,7 @@ After you remove the {SMProductName} 2 `ServiceMeshControlplane` resource, and a * You have completed migrating your gateways. * You have removed the {SMProduct} 2 `ServiceMeshControlPlane` resource. * You have removed all other {SMProduct} 2 resources. -* You are logged in to the {ocp-product-title} web console as a user with the cluster-admin role. +* You have logged in to the {ocp-product-title} web console as a user with the cluster-admin role. .Procedure @@ -27,28 +27,29 @@ After you remove the {SMProductName} 2 `ServiceMeshControlplane` resource, and a $ oc get smcp,smm,smmr -A ---- + -.Example output +*Example output:* ++ ---- No resources found ---- -. Remove the Operator by running the following commands: +. Remove the Operator: -.. Find the Operator subscription: +.. Find the Operator subscription by running the following command: + [source,terminal] ---- csv=$(oc get subscription servicemeshoperator -n openshift-operators -o yaml | grep currentCSV | cut -f 2 -d ':') ---- -.. Delete the subscription: +.. Delete the subscription by running the following command: + [source,terminal] ---- $ oc delete subscription servicemeshoperator -n openshift-operators ---- -.. Delete the `clusterserviceversion` CSV: +.. Delete the `clusterserviceversion` CSV by running the following command: + [source,terminal] ---- diff --git a/modules/ossm-migrating-complete-remove-maistra-labels.adoc b/modules/ossm-migrating-complete-remove-maistra-labels.adoc index 1c32694f979..9b0275770e8 100644 --- a/modules/ossm-migrating-complete-remove-maistra-labels.adoc +++ b/modules/ossm-migrating-complete-remove-maistra-labels.adoc @@ -8,7 +8,7 @@ [role="_abstract"] -After you have removed all {SMProduct} 2 resources, removed the {SMProduct} 2 Operator, and {SMProduct} 2 custom resource definitions (CRDs), you can choose to remove namespace labels created during the migration. +After you have removed all {SMProduct} 2 resources, removed the {SMProduct} 2 Operator, and {SMProduct} 2 custom resource definitions (CRDs), you can remove namespace labels created during the migration. .Prerequisites @@ -18,7 +18,7 @@ After you have removed all {SMProduct} 2 resources, removed the {SMProduct} 2 Op * You have removed all other {SMProduct} 2 resources. * You have removed the {SMProduct} 2 Operator. * You have removed the {SMProduct} 2 CRDs. -* You are logged in to the {ocp-product-title} web console as a user with the cluster-admin role. +* You have logged in to the {ocp-product-title} web console as a user with the cluster-admin role. .Procedure @@ -29,7 +29,8 @@ After you have removed all {SMProduct} 2 resources, removed the {SMProduct} 2 Op $ oc get smcp,smm,smmr -A ---- + -.Example output +*Example output:* ++ ---- No resources found ---- @@ -41,7 +42,8 @@ No resources found $ oc get namespace -l maistra.io/ignore-namespace="true" ---- + -.Example output +*Example output:* ++ ---- NAME STATUS AGE bookinfo Active 127m @@ -54,7 +56,8 @@ bookinfo Active 127m $ oc label namespace bookinfo maistra.io/ignore-namespace- ---- + -.Example output +*Example output:* ++ ---- namespace/bookinfo unlabeled ---- \ No newline at end of file diff --git a/modules/ossm-migrating-disable-add-ons-and-reconfigure-replacements.adoc b/modules/ossm-migrating-disable-add-ons-and-reconfigure-replacements.adoc new file mode 100644 index 00000000000..2035e09ce73 --- /dev/null +++ b/modules/ossm-migrating-disable-add-ons-and-reconfigure-replacements.adoc @@ -0,0 +1,49 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/checklists/ossm-migrating-premigration-checklists.adoc + +:_mod-docs-content-type: REFERENCE +[id="ossm-migrating-disable-add-ons-and-reconfigure-replacements_{context}"] += Disable add-ons and reconfigure replacements + +[role="_abstract"] + +To prepare for your migration to {SMProduct} 3, you must disable legacy add-ons in your {SMProduct} 2 `ServiceMeshControlPlane` resource and reconfigure replacements for the features that those add-ons provided. + +* [ ] Disable Prometheus in your `ServiceMeshControlPlane` resource: `spec.addons.prometheus.enabled=false` + +** [ ] Configure the `ServiceMeshControlPlane` with OpenShift Monitoring as the replacement. These instructions also include installing a standalone `Kiali` resource. Both can be done at the same time. For more information, see "Integration with user-workload monitoring". + +** [ ] If you are not using OpenShift monitoring, see: "Integration with external Prometheus installation". + +* [ ] Disable tracing in your `ServiceMeshControlPlane` resource: `spec.tracing.type=None` + +** [ ] Configure the `ServiceMeshControlPlane` with OpenShift Distributed Tracing as the replacement. For more information, see "Configuring {TempoName} and the Red{nbsp}Hat build of OpenTelemetry". + +* [ ] Disable Kiali in your `ServiceMeshControlPlane` resource: `spec.addons.kiali.enabled=false` + +** [ ] If you did not create a standalone `Kiali` resource as part of Prometheus or tracing, see: "Using {KialiProduct}". + +[WARNING] +==== +{SMProductName} 3 fails to install if outdated `ServiceEntry` custom resources are present in the cluster. The upstream {istio} version 1.24 introduced schema changes that cause installation failures for `ServiceEntry` resources that miss port numbers or exceed 256 hostnames. You can check for affected resources by running the following commands: + +* For `ServiceEntry` with hostnames over 256, run the following command: ++ +[source,terminal] +---- +$ oc get serviceentries -A -o json | jq -r '.items[] | select(.spec.hosts | length > 256) | "\(.metadata.namespace)/\(.metadata.name): \(.spec.hosts | length) hosts"' +---- + +* For `ServiceEntry` with missing port numbers, run the following command: ++ +[source,terminal] +---- +$ oc get serviceentries -A -o json | jq -r '.items[] | select(.spec.ports == null or (.spec.ports | length == 0)) | "\(.metadata.namespace)/\(.metadata.name)"' +---- + +To ensure a seamless migration to {SMProductName} 3, perform the following corrective actions before installing the OSSM 3 operator: + +* Split `ServiceEntry` resources: You must split any `ServiceEntry` containing more than 256 hosts into multiple smaller resources. +* Validate port configurations: You must ensure that all the `ServiceEntry` definitions include the required port specifications. +==== \ No newline at end of file diff --git a/modules/ossm-migrating-disable-grafana-in-service-mesh-2.adoc b/modules/ossm-migrating-disable-grafana-in-service-mesh-2.adoc new file mode 100644 index 00000000000..0925c588bd0 --- /dev/null +++ b/modules/ossm-migrating-disable-grafana-in-service-mesh-2.adoc @@ -0,0 +1,14 @@ + +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/checklists/ossm-migrating-premigration-checklists.adoc + +:_mod-docs-content-type: REFERENCE +[id="ossm-migrating-disable-grafana-in-service-mesh-2_{context}"] += Disable Grafana in {SMProduct} 2 + +[role="_abstract"] + +Grafana is not supported in {SMProduct} 3, and must be disabled in your {SMProduct} 2 `ServiceMeshControlPlane`. + + * [ ] Disable Grafana in your {SMProduct} 2 `ServiceMeshControlPlane`: `spec.addons.grafana.enabled=false`. \ No newline at end of file diff --git a/modules/ossm-migrating-disable-network-policy-management.adoc b/modules/ossm-migrating-disable-network-policy-management.adoc new file mode 100644 index 00000000000..ba1e5c90c15 --- /dev/null +++ b/modules/ossm-migrating-disable-network-policy-management.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/checklists/ossm-migrating-premigration-checklists.adoc + +:_mod-docs-content-type: REFERENCE +[id="ossm-migrating-disable-network-policy-management_{context}"] += Disable network policy management + +[role="_abstract"] + +If you do not want your network policies in place during your migration: + +* [ ] Disable network policy management in the {SMProduct} 2 `ServiceMeshControlPlane` resource: `spec.security.manageNetworkPolicy=false`. + +* [ ] Complete the rest of the checklists. + +* [ ] Migrate your deployment and workloads. + +* [ ] Manually recreate your network policies after you have migrated your workloads. + +If you want your network policies in place during your migration: + +* [ ] Manually set up network policies to use during migration. For more information, see "Migrating network policies from Service Mesh 2 to Service Mesh 3". + +* [ ] Disable network policy management in the {SMProduct} 2 `ServiceMeshControlPlane` resource: `spec.security.manageNetworkPolicy=false`. + +* [ ] Complete the rest of the checklists. + +* [ ] Migrate your deployment and workloads. \ No newline at end of file diff --git a/modules/ossm-migrating-done-network-policies.adoc b/modules/ossm-migrating-done-network-policies.adoc index 46b77a553bd..7b7fa3c6494 100644 --- a/modules/ossm-migrating-done-network-policies.adoc +++ b/modules/ossm-migrating-done-network-policies.adoc @@ -17,9 +17,9 @@ If you did not re-create your network policies before you migrated your deployme .Procedure -. Recreate necessary network policies in the new {SMProduct} 3 control plane namespace. +. Re-create necessary network policies in the new {SMProduct} 3 control plane namespace. -. Recreate network policies for each namespace that was part of the {SMProduct} 2 mesh. +. Re-create network policies for each namespace that was part of the {SMProduct} 2 mesh. . Update labels. + diff --git a/modules/ossm-migrating-find-your-deployment-model.adoc b/modules/ossm-migrating-find-your-deployment-model.adoc new file mode 100644 index 00000000000..254ba63e724 --- /dev/null +++ b/modules/ossm-migrating-find-your-deployment-model.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/checklists/ossm-migrating-premigration-checklists.adoc + +:_mod-docs-content-type: REFERENCE +[id="ossm-migrating-find-your-deployment-model_{context}"] += Find your deployment model + +[role="_abstract"] + +Run the following command to find your deployment model: + +[source,terminal] +---- +oc get smcp -n -o jsonpath='{.spec.mode}' +---- + +[NOTE] +==== +If you did not set a value for the `.spec.mode` parameter in your `ServiceMeshControlPlane` resource, your deployment is multitenant. +==== \ No newline at end of file diff --git a/modules/ossm-migrating-gateways-canary.adoc b/modules/ossm-migrating-gateways-canary.adoc index 50300de0698..f57769f8074 100644 --- a/modules/ossm-migrating-gateways-canary.adoc +++ b/modules/ossm-migrating-gateways-canary.adoc @@ -29,33 +29,32 @@ $ oc label namespace istio.io/rev= mais . Deploy a canary gateway by using the following example: + -.Example YAML for canary gateway [source,yaml] ---- apiVersion: apps/v1 kind: Deployment metadata: name: istio-ingressgateway-canary - namespace: istio-ingress <1> + namespace: istio-ingress spec: selector: matchLabels: - istio: ingressgateway <2> + istio: ingressgateway template: metadata: annotations: inject.istio.io/templates: gateway labels: istio: ingressgateway - istio.io/rev: canary <3> + istio.io/rev: canary spec: containers: - name: istio-proxy image: auto ---- -<1> Your `Deployment` resource must be in in the same namespace as your existing gateway. -<2> Your `spec.selector.matchlabels.istio` parameter must match your existing gateway service selector. -<3> Set your {SMProduct} 3.0 control plane revision as the value of the `istio.io/rev` label. +* `metadata.namespace` specifies the namespace for your `Deployment` resource must be in the same namespace as your existing gateway. +* `spec.selector.matchLabels.istio` specifies the label selector for your `Deployment` resource that must match your existing gateway service selector. +* `spec.template.metadata.labels.istio.io/rev` sets your {SMProduct} 3.0 control plane revision as the value of the `istio.io/rev` label. . Ensure that the new gateway deployment is running with the new revision and is handling requests: + diff --git a/modules/ossm-migrating-gateways-in-place.adoc b/modules/ossm-migrating-gateways-in-place.adoc index e3938a0f1fe..1b4598993bb 100644 --- a/modules/ossm-migrating-gateways-in-place.adoc +++ b/modules/ossm-migrating-gateways-in-place.adoc @@ -8,7 +8,7 @@ [role="_abstract"] -If you need less detailed control over your gateway migration, you can perform gateway in place migration. This method applies to namespaces with dedicated gateways and to environments using a centralized gateway shared across multiple namespaces. +If you need less detailed control over your gateway migration, you can perform gateway in place migration. This method applies to namespaces with dedicated gateways and to environments by using a centralized gateway shared across multiple namespaces. [NOTE] ==== diff --git a/modules/ossm-migrating-hub-completing-your-migration.adoc b/modules/ossm-migrating-hub-completing-your-migration.adoc index b632790bf9e..f39f88b3ecb 100644 --- a/modules/ossm-migrating-hub-completing-your-migration.adoc +++ b/modules/ossm-migrating-hub-completing-your-migration.adoc @@ -10,4 +10,4 @@ Depending on your deployment model, you might need to take extra steps to complete the migration. For example, when you migrate with the cert-manager tool, you need to take additional steps before you can remove {SMProduct} 2 resources. -After you complete your migration, you can add new workloads, re-create network policies, and remove {SMProduct} 2 resources. +After you complete your migration, you can add new workloads, re-create network policies, and remove {SMProduct} 2 resources. \ No newline at end of file diff --git a/modules/ossm-migrating-hub-how-to-use-migration-guides.adoc b/modules/ossm-migrating-hub-how-to-use-migration-guides.adoc index f1499afdaab..d88dabcc035 100644 --- a/modules/ossm-migrating-hub-how-to-use-migration-guides.adoc +++ b/modules/ossm-migrating-hub-how-to-use-migration-guides.adoc @@ -4,7 +4,9 @@ :_mod-docs-content-type: REFERENCE [id="ossm-migrating-hub-using-migration-guides_{context}"] -== Using the migration guides += Using the migration guides + +[role="_abstract"] The migration guides are designed to help you move from {SMProduct} {SMv2Version} to {SMProduct} 3.0, based on your deployment model: diff --git a/modules/ossm-migrating-hub-premigration-checklists.adoc b/modules/ossm-migrating-hub-premigration-checklists.adoc index acdf3f3eb10..27c796e5b05 100644 --- a/modules/ossm-migrating-hub-premigration-checklists.adoc +++ b/modules/ossm-migrating-hub-premigration-checklists.adoc @@ -10,6 +10,4 @@ Before you can begin your migration, complete the premigration checklists. -These checklists include steps for managing your network policies and configuration updates to set up add ons such as {kialiproduct} and {temposhortname}. - -//exrefs handled by OSSM-8852 \ No newline at end of file +These checklists include steps for managing your network policies and configuration updates to set up add ons such as {kialiproduct} and {temposhortname}. \ No newline at end of file diff --git a/modules/ossm-migrating-hub-recommendations-for-migrating.adoc b/modules/ossm-migrating-hub-recommendations-for-migrating.adoc index 94fa373ec4e..dd71aa68a07 100644 --- a/modules/ossm-migrating-hub-recommendations-for-migrating.adoc +++ b/modules/ossm-migrating-hub-recommendations-for-migrating.adoc @@ -16,7 +16,7 @@ Consider the following recommendations to limit the risk of misconfigurations or [NOTE] ==== -If you need to add a new workload namespace during the migration, it must be managed by the {SMProduct} 3 control plane and labeled with `maistra.io/ignore-namespace: "true"` to avoid conflicts between the {SMProduct} 3 control plane and the {SMProduct} 2 `ServiceMeshControlPlane` resource. +If you need to add a new workload namespace during the migration, it must be managed by the {SMProduct} 3 control plane and labeled with `maistra.io/ignore-namespace: "true"` to avoid conflicts between the {SMProduct} 3 control plane and the {SMProduct} 2 `ServiceMeshControlPlane` resource. In multitenant mode, adding new namespaces during migration is even more complicated. See the "Multitenant migration guide" section of this document. ==== * Finish the migration without unnecessary delays. \ No newline at end of file diff --git a/modules/ossm-migrating-multitenant-with-cert-manager.adoc b/modules/ossm-migrating-multitenant-with-cert-manager.adoc index a3bd7bb2daf..c43f2e37e70 100644 --- a/modules/ossm-migrating-multitenant-with-cert-manager.adoc +++ b/modules/ossm-migrating-multitenant-with-cert-manager.adoc @@ -9,28 +9,28 @@ [role="_abstract"] -The `bookinfo` example application is being used for demonstration purposes with a minimal example for the `Istio` resource. For more information on configuration differences between the {SMProduct} 2 `ServiceMeshControlPlane` resource and the {SMProduct} 3 `Istio` resource, see "ServiceMeshControlPlane resource to Istio resource fields mapping". +The `bookinfo` example application is used for demonstration purposes with a minimal example for the `{istio}` resource. For more information on configuration differences between the {SMProduct} 2 `ServiceMeshControlPlane` resource and the {SMProduct} 3 `{istio}` resource, see "ServiceMeshControlPlane resource to `{istio}` resource fields mapping". You can follow these same steps with your own workloads. .Prerequisites * You have deployed {ocp-product-title} 4.14 or later. -* You are logged in to the {ocp-product-title} web console as a user with the cluster-admin role. +* You have logged in to the {ocp-product-title} web console as a user with the cluster-admin role. * You have completed the premigration checklists. * You have the {SMProduct} {SMv2Version} Operator installed. * You have the {SMProduct} 3 Operator installed. * You created an `IstioCNI` resource. * You have the `istioctl` tool installed. * You are using the cert-manager and istio-csr tools in a multitenant deployment. -//change to "You are using the cert-manager and istio-csr tools in a cluster-wide deployment" for the cluster-wide procedure * Your {SMProduct} 2 `ServiceMeshControlPlane` is configured with the cert-manager tool. .Procedure . Check that your {SMProduct} 2 `ServiceMeshControlPlane` is configured with the cert-manager-tool: + -.Example `ServiceMeshControlPlane` cert-manager configuration +You can see the following example configuration for reference: ++ [source,yaml] ---- apiVersion: maistra.io/v2 @@ -61,14 +61,16 @@ spec: --reuse-values \ --namespace istio-system \ --wait \ - --set "app.istio.revisions={basic,istio-tenant-a}" <1> + --set "app.istio.revisions={basic,istio-tenant-a}" ---- + -<1> The `app.istio.revisions` field needs to include your {SMProduct} 3.0 control plane revision _before_ you create your `Istio` resource so that proxies can properly communicate with the {SMProduct} 3.0 control plane. +where: ++ +`app.istio.revisions`:: This field needs to include your {SMProduct} 3.0 control plane revision _before_ you create your `Istio` resource so that proxies can properly communicate with the {SMProduct} 3.0 control plane. . Create your `Istio` resource. + -.Example `Istio` resource with cert-manager +You can see the following example configuration for reference: + [source,yaml] ---- @@ -77,14 +79,14 @@ kind: Istio metadata: name: istio-tenant-a spec: - namespace: istio-system-tenant-a <1> + namespace: istio-system-tenant-a version: v1.24.3 values: meshConfig: - discoverySelectors: <2> + discoverySelectors: - matchLabels: tenant: tenant-a - extensionProviders: <3> + extensionProviders: - name: prometheus prometheus: {} - name: otel @@ -98,9 +100,9 @@ spec: ENABLE_CA_SERVER: "false" ---- + -<1> The `spec.namespace` field in your `Istio` resource must be the _same_ namespace as your `ServiceMeshControlPlane` resource. If you set the `spec.namespace` field in your `Istio` resource to a different namespace than your `ServiceMeshControlPlane` resource, the migration will not work properly. -<2> By default, control planes watch the entire cluster. When managing multiple control planes on a single cluster, you must narrow the scope of each control plane by setting `discoverySelectors` fields. In this example, the label `tenant-a` is used, but you can use any label or combination of labels. -<3> Optional: If you are migrating metrics and tracing, update the `extensionProviders` fields according to your tracing and metrics configurations. +* `spec.namespace` specifies the namespace for your `{istio}` resource must be the _same_ namespace as your `ServiceMeshControlPlane` resource. If you set the `spec.namespace` field in your `{istio}` resource to a different namespace than your `ServiceMeshControlPlane` resource, the migration will not work properly. +* `spec.values.meshConfig.discoverySelectors` specifies the label selector for your `{istio}` resource. By default, control planes watch the entire cluster. When managing multiple control planes on a single cluster, you must narrow the scope of each control plane by setting `discoverySelectors` fields. In this example, the label `tenant-a` is used, but you can use any label or combination of labels. +* `spec.values.meshConfig.extensionProviders` is an optional field. If you are migrating metrics and tracing, update the `extensionProviders` fields according to your tracing and metrics configurations. . Add your `tenant` label to each one of your dataplane namespaces by running the following command for each dataplane namespace: + diff --git a/modules/ossm-migrating-multitenant-workloads-with-cert-manager.adoc b/modules/ossm-migrating-multitenant-workloads-with-cert-manager.adoc index 6e15787191c..f0704194bf1 100644 --- a/modules/ossm-migrating-multitenant-workloads-with-cert-manager.adoc +++ b/modules/ossm-migrating-multitenant-workloads-with-cert-manager.adoc @@ -24,7 +24,7 @@ You can migrate workloads and gateways separately, and in any order. For more in $ oc get istios istio-tenant-a ---- + -.Example output +*Example output:* + [source,terminal] ---- @@ -61,7 +61,6 @@ Once you apply the `maistra.io/ignore-namespace` label, any new pod that gets cr + .. To restart all the workloads at once so that the new pods are injected with the {SMProduct} 3.0 proxy, run the following command: + -.Example command for `bookinfo` application [source,terminal] ---- $ oc rollout restart deployments -n bookinfo @@ -69,7 +68,6 @@ $ oc rollout restart deployments -n bookinfo .. To restart each workload individually, run the following command for each workload: + -.Example command with `bookinfo` application [source,terminal] ---- $ oc rollout restart deployments productpage-v1 -n bookinfo @@ -93,9 +91,7 @@ $ oc rollout status deployment productpage-v1 -n bookinfo $ istioctl ps --istioNamespace istio-system-tenant-a --revision basic ---- + -In this example, `basic` is the name of your `ServiceMeshControlPlane`: -+ -.Example output +In the following example, `basic` is the name of your `ServiceMeshControlPlane`: + [source,terminal] ---- @@ -114,7 +110,7 @@ In this example, `basic` is the name of your `ServiceMeshControlPlane`: $ istioctl ps --istioNamespace istio-system-tenant-a --revision istio-tenant-a ---- + -.Example output +*Example output:* + [source, terminal] ---- @@ -127,4 +123,9 @@ productpage-v1-7745c5cc94-wpvth.bookinfo Kubernetes SYNCED SYNCED [source,terminal] ---- $ oc exec -it -n bookinfo deployments/productpage-v1 -c istio-proxy -- curl localhost:9080/productpage ----- \ No newline at end of file +---- + +[NOTE] +==== +If you are using gateways, you must migrate them before you complete the migration process for your deployment and workloads. After you have migrated your gateways, you must update the `app.controller.configmapNamespaceSelector` field in your `istio-csr` deployment. If you are not using gateways, you can complete your migration with cert-manager. +==== \ No newline at end of file diff --git a/modules/ossm-migrating-multitenant-workloads.adoc b/modules/ossm-migrating-multitenant-workloads.adoc index 2d45d42cc3d..6d35b4a7561 100644 --- a/modules/ossm-migrating-multitenant-workloads.adoc +++ b/modules/ossm-migrating-multitenant-workloads.adoc @@ -24,7 +24,7 @@ You can migrate workloads and gateways separately, and in any order. For more in $ oc get istios istio-tenant-a ---- + -.Example output +*Example output:* + [source,terminal] ---- @@ -61,7 +61,6 @@ Once you apply the `maistra.io/ignore-namespace` label, any new pod that gets cr + .. To restart all the workloads at once so that the new pods are injected with the {SMProduct} 3.0 proxy, run the following command: + -.Example command for `bookinfo` application [source,terminal] ---- $ oc rollout restart deployments -n bookinfo @@ -69,7 +68,6 @@ $ oc rollout restart deployments -n bookinfo .. To restart each workload individually, run the following command for each workload: + -.Example command with `bookinfo` application [source,terminal] ---- $ oc rollout restart deployments productpage-v1 -n bookinfo @@ -93,9 +91,7 @@ $ oc rollout status deployment productpage-v1 -n bookinfo $ istioctl ps --istioNamespace istio-system-tenant-a --revision basic ---- + -In this example, `basic` is the name of your `ServiceMeshControlPlane`: -+ -.Example output +In the following example, `basic` is the name of your `ServiceMeshControlPlane`: + [source,terminal] ---- @@ -114,7 +110,7 @@ In this example, `basic` is the name of your `ServiceMeshControlPlane`: $ istioctl ps --istioNamespace istio-system-tenant-a --revision istio-tenant-a ---- + -.Example output +*Example output:* + [source, terminal] ---- @@ -127,4 +123,9 @@ productpage-v1-7745c5cc94-wpvth.bookinfo Kubernetes SYNCED SYNCED [source,terminal] ---- $ oc exec -it -n bookinfo deployments/productpage-v1 -c istio-proxy -- curl localhost:9080/productpage ----- \ No newline at end of file +---- + +[NOTE] +==== +If you are using gateways, you must migrate them before you complete the migration process for your deployment and workloads. If you are not using gateways, and have verified your mulitenant migration, you can proceed to complete the migration and remove {SMProduct} 2 resources. +==== \ No newline at end of file diff --git a/modules/ossm-migrating-network-policies-setup-during-migration.adoc b/modules/ossm-migrating-network-policies-setup-during-migration.adoc index 122377afa26..ff728c5372e 100644 --- a/modules/ossm-migrating-network-policies-setup-during-migration.adoc +++ b/modules/ossm-migrating-network-policies-setup-during-migration.adoc @@ -10,6 +10,11 @@ You can set up network policies to use during your migration. +[NOTE] +==== +It is recommended to re-create your network policies after you have migrated your deployment and workloads. However, if your security policies require you to keep your network policies, you must re-create them first, and then set the `spec.security.manageNetworkPolicy` field to `false` as outlined in the migration checklists. +==== + [IMPORTANT] ==== * During the recreation of network policies from {SMProduct} 2 to {SMProduct} 3, both control planes must have access to all workloads and all workloads must have access to control planes. @@ -20,7 +25,7 @@ You can set up network policies to use during your migration. .Prerequisites * You have deployed {ocp-product-title} 4.14 or later. -* You are logged in to the {ocp-product-title} web console as a user with the cluster-admin role. +* You have logged in to the {ocp-product-title} web console as a user with the cluster-admin role. * You have the {SMProduct} {SMv2Version} Operator installed. * You have the `ServiceMeshControlPlane` 2.6 resource installed. * In {SMProduct} 2, you have set `spec.security.manageNetworkPolicy=true` in your `ServiceMeshControlPlane` resource. @@ -42,7 +47,8 @@ Use a label scoped specifically to your mesh that you can reuse for discovery se . Create your network policies by using the following `NetworkPolicy` example configurations: + -.Example of an Istiod network policy in a mesh namespace +You can see the following example configuration for Istiod network policy in a mesh namespace: ++ [source,yaml] -- apiVersion: networking.k8s.io/v1 @@ -61,7 +67,8 @@ spec: - Ingress -- + -.Example of an expose route policy in a mesh namespace +You can see the following example configuration for an expose route policy in a mesh namespace: ++ [source,yaml] -- apiVersion: networking.k8s.io/v1 @@ -82,7 +89,8 @@ spec: - Ingress -- + -.Example of a default mesh network policy in a mesh namespace +You can see the following example configuration for a default mesh network policy in a mesh namespace: ++ [source,yaml] ---- apiVersion: networking.k8s.io/v1 @@ -101,7 +109,8 @@ spec: - Ingress ---- + -.Example expose route network policy in the `bookinfo` namespace +You can see the following example configuration for an expose route network policy in the `bookinfo` namespace: ++ [source,yaml] -- apiVersion: networking.k8s.io/v1 @@ -122,7 +131,8 @@ spec: - Ingress -- + -.Example mesh network policy in the `bookinfo` namespace +You can see the following example configuration for mesh network policy in the `bookinfo` namespace: ++ [source,yaml] -- apiVersion: networking.k8s.io/v1 @@ -141,7 +151,8 @@ spec: - Ingress -- + -.Example expose route network policy in the `bookinfo2` namespace +You can see the following example configuration for an expose route network policy in the `bookinfo2` namespace: ++ [source,yaml] -- apiVersion: networking.k8s.io/v1 @@ -162,7 +173,8 @@ spec: -- + -.Example mesh network policy in the `bookinfo2` namespace +You can see the following example configuration for mesh network policy in the `bookinfo2` namespace: ++ [source,yaml] -- apiVersion: networking.k8s.io/v1 @@ -195,7 +207,8 @@ Setting the `spec.security.manageNetworkPolicy` field to `false` in your `Servic $ oc get istios ---- + -.Example output +*Example output:* ++ [source,terminal] ---- NAME REVISIONS READY IN USE ACTIVE REVISION STATUS VERSION AGE @@ -206,8 +219,6 @@ istio-tenant-a 1 1 0 istio-tenant-a Healthy v1.24. . Create a second Istiod network policy for {SMProduct} 3 by using the following `NetworkPolicy` example configuration: + -.Sample policy -+ [source,yaml] ---- apiVersion: networking.k8s.io/v1 @@ -225,6 +236,12 @@ spec: policyTypes: - Ingress ---- -<1> Must match your current active revision name. ++ +[NOTE] +==== +You must match your current active revision name through the `istio.io/rev` label in your second Istiod network policy. +==== +.Next steps +* In {SMProduct} 2, set the `spec.security.manageNetworkPolicy` field to `false` in your `ServiceMeshControlPlane` resource, and continue with the migration checklists. \ No newline at end of file diff --git a/modules/ossm-migrating-premigration-before-you-begin.adoc b/modules/ossm-migrating-premigration-before-you-begin.adoc new file mode 100644 index 00000000000..06f316bb24d --- /dev/null +++ b/modules/ossm-migrating-premigration-before-you-begin.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/checklists/ossm-migrating-premigration-checklists.adoc + +:_mod-docs-content-type: REFERENCE +[id="ossm-migrating-premigration-before-you-begin_{context}"] += Before you begin + +[role="_abstract"] + +Verify that your environment meets the following requirements, version dependencies, and operator installations necessary to begin the migration from {SMProduct} 2 to {SMProduct} 3. + +* You have read "Migrating from Service Mesh 2 to Service Mesh 3". + +* You have read and understand the "Differences between OpenShift Service Mesh 2 and OpenShift Service Mesh 3" section. + +* You have reviewed the "Migrating references" section. + +* You want to migrate from {SMProduct} 2 to {SMProduct} 3. + +* You are running {SMProduct} {SMv2Version}. + +* You have upgraded your `ServiceMeshControlPlane` resource to the latest version. + +* If you are using the {KialiProduct}, you are running the latest version. + +* You have installed the {SMProduct} Operator 3. To install the {SMProduct} 3 Operator, see "Installing OpenShift Service Mesh". + +[IMPORTANT] +==== +You must complete the following checklists before you can begin migrating your deployment and workloads. +==== \ No newline at end of file diff --git a/modules/ossm-migrating-premigration-checklists-resource-files.adoc b/modules/ossm-migrating-premigration-checklists-resource-files.adoc index 8af477816c5..46f0ba17fbb 100644 --- a/modules/ossm-migrating-premigration-checklists-resource-files.adoc +++ b/modules/ossm-migrating-premigration-checklists-resource-files.adoc @@ -13,7 +13,7 @@ After you have completed the premigration procedures, your {SMProduct} 2 resourc [id="service-mesh-control-plane-resource-file_{context}"] == The ServiceMeshControlPlane resource file -.Example `ServiceMeshControlPlane` resource +You can see the following example configuration for `ServiceMeshControlPlane` resource: [source, yaml] ---- @@ -23,17 +23,17 @@ metadata: name: basic namespace: istio-system spec: - version: v2.6 <1> - security: <2> + version: v2.6 + security: manageNetworkPolicy: false - addons: <3> + addons: grafana: enabled: false kiali: enabled: false prometheus: enabled: false - meshConfig: <4> + meshConfig: extensionProviders: - name: prometheus prometheus: {} @@ -41,28 +41,28 @@ spec: opentelemetry: port: 4317 service: otel-collector.istio-system.svc.cluster.local - gateways: <5> + gateways: enabled: false openshiftRoute: enabled: false - mode: MultiTenant <6> - tracing: <7> + mode: MultiTenant + tracing: type: None ---- -<1> Update your `ServiceMeshControlPlane` resource to the latest {SMProduct} version. -<2> Disable network policy management. -<3> Disable all resources in the `addons` stanza. -<4> Your `ServiceMeshControlPlane` resource is configured to use external metrics and tracing providers. -<5> Disable managed gateways. -<6> Set to either `MultiTenant` or `ClusterWide`. -<7> Disable tracing. +* `spec.version` specifies the version of {SMProduct} to use. +* `spec.security.manageNetworkPolicy` specifies how to manage network policies. +* `spec.addons` specifies the addons to enable or disable. +* `spec.meshConfig` specifies the mesh configuration. +* `spec.gateways` specifies the gateways configuration. +* `spec.mode` specifies the mode of operation. +* `spec.tracing` specifies the tracing configuration. [id="telemetry-resource-file_{context}"] == Telemetry resource file The `Telemetry` resource file is located in your root namespace. The following example uses `istio-system` as the root namespace. -.Example `Telemetry` resource +You can see the following example configuration for `Telemetry` resource: [source,yaml] ---- @@ -72,20 +72,20 @@ metadata: name: mesh-default namespace: istio-system spec: - metrics: <1> + metrics: - providers: - name: prometheus - tracing: <2> + tracing: - providers: - name: otel ---- -<1> Specify your metrics provider. The `name` field must match what is specified in your `ServiceMeshControlPlane` resource in the `spec.meshConfig.extensionProviders` field. -<2> Specify yur tracing provider. The `name` field must match what is specified in your `ServiceMeshControlPlane` resource in the `spec.meshConfig.extensionProviders` field. +* `spec.metrics` specify your metrics provider. The `name` field must match what is specified in your `ServiceMeshControlPlane` resource in the `spec.meshConfig.extensionProviders` field. +* `spec.tracing` specify your tracing provider. The `name` field must match what is specified in your `ServiceMeshControlPlane` resource in the `spec.meshConfig.extensionProviders` field. [id="kiali-resource-file_{context}"] == Kiali resource file -.Example `Kiali` resource +You can see the following example configuration for `Kiali` resource: [source,yaml] ---- @@ -95,25 +95,25 @@ metadata: name: kiali namespace: istio-system spec: - version: default <1> + version: default external_services: - prometheus: <2> + prometheus: auth: type: bearer use_kiali_token: true thanos_proxy: enabled: true url: https://thanos-querier.openshift-monitoring.svc.cluster.local:9091 - tracing: <3> + tracing: enabled: true provider: tempo use_grpc: false internal_url: http://tempo-sample-query-frontend.tempo:3200 external_url: https://tempo-sample-query-frontend-tempo.apps-crc.testing - grafana: <4> + grafana: enabled: false ---- -<1> You can use the `default` value of the version parameter if you install {SMProduct} 3 before updating Kiali. The default version is compatible with both 2.6 and 3.0 control planes. -<2> Configure Kiali to use external Prometheus. -<3> Configure Kiali to use the external tracing store. -<4> Disable the Grafana configuration. Grafana is not supported with {SMProduct} 3.0. \ No newline at end of file +* `spec.version` specifies the version of Kiali to use. You can use the `default` value of the version parameter if you install {SMProduct} 3 before updating Kiali. The default version is compatible with both 2.6 and 3.0 control planes. +* `spec.external_services.prometheus` specifies the configuration for the external Prometheus service. +* `spec.external_services.tracing` specifies the configuration for the external tracing store. +* `spec.external_services.grafana` disables the Grafana configuration. Grafana is not supported with {SMProduct} 3.0. \ No newline at end of file diff --git a/modules/ossm-migrating-premigration-checklists-using-the-cert-manager-tool-with-your-deployment.adoc b/modules/ossm-migrating-premigration-checklists-using-the-cert-manager-tool-with-your-deployment.adoc index 4c8c4977d3a..37b9fb24abc 100644 --- a/modules/ossm-migrating-premigration-checklists-using-the-cert-manager-tool-with-your-deployment.adoc +++ b/modules/ossm-migrating-premigration-checklists-using-the-cert-manager-tool-with-your-deployment.adoc @@ -44,9 +44,17 @@ spec: oc get smcp -n -o jsonpath='{.spec.security.certificateAuthority.type}' ---- + -.Example output - +*Example output:* ++ [source,yaml] ---- cert-manager ----- \ No newline at end of file +---- + +Next steps for migrating with the cert-manager tool:: ++ +There are some configurations you must complete first before you can start migrating your deployments: + +* "Migrating a multitenant deployment with the cert-manager tool" + +* "Cluster-wide migration methods" \ No newline at end of file diff --git a/modules/ossm-migrating-read-me-dns-capture-configuration.adoc b/modules/ossm-migrating-read-me-dns-capture-configuration.adoc new file mode 100644 index 00000000000..12db190707f --- /dev/null +++ b/modules/ossm-migrating-read-me-dns-capture-configuration.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/checklists/ossm-migrating-read-me.adoc + +:_mod-docs-content-type: CONCEPT +[id="ossm-migrating-read-me-dns-capture-configuration_{context}"] += DNS capture configuration for ServiceEntry resources + +[role="_abstract"] + +To maintain access to external services when migrating to {SMProductName} 3.0, you must explicitly enable DNS capture in the proxy metadata settings. + +This is required for any `ServiceEntry` resources that rely on DNS resolution. Failure to enable this feature will result in application errors such as `Name or service not known`. + +{SMProduct} 2.6 enabled DNS capture by default to support federation, which did not align with the upstream {istio} project. {SMProduct} 3.0 removes this default configuration and aligns with the upstream project's multicluster topologies. + +To configure DNS capture in {SMProduct} 3.0, set the `ISTIO_META_DNS_AUTO_ALLOCATE` and `ISTIO_META_DNS_CAPTURE` fields to `true` in the `spec.values.meshConfig.defaultConfig.proxyMetadata` path of your `{istio}` resource. + +[NOTE] +==== +The equivalent of `spec.values.meshConfig.defaultConfig.proxyMetadata` in {SMProduct} 2.6 was `spec.proxy.runtime.container.env`. +==== diff --git a/modules/ossm-migrating-read-me-explicitly-create-openshift-routes.adoc b/modules/ossm-migrating-read-me-explicitly-create-openshift-routes.adoc index b8e9639c7b4..09b0ba56427 100644 --- a/modules/ossm-migrating-read-me-explicitly-create-openshift-routes.adoc +++ b/modules/ossm-migrating-read-me-explicitly-create-openshift-routes.adoc @@ -2,18 +2,14 @@ // // * service-mesh-docs-main/about/ossm-migrating-assembly.adoc -//Start of an overall Migrating section. -//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. - :_mod-docs-content-type: CONCEPT [id="explicitly-create-openshift-routes_{context}"] = Explicitly create OpenShift Routes [role="_abstract"] -//In the ocp-docs repo, there is no attribute for OpenShift Container Platform Ingress Operator so followed https://docs.openshift.com/container-platform/4.17/networking/ingress-operator.html -An OpenShift `Route` resource allows an application to be exposed with a public URL using {ocp-product-title} Ingress Operator for managing HAProxy based Ingress controllers. +An OpenShift `Route` resource allows an application to be exposed with a public URL by using {ocp-product-title} Ingress Operator for managing HAProxy based Ingress controllers. -{SMProductName} 2 used Istio OpenShift Routing (IOR) that automatically created and managed OpenShift routes for Istio gateways. While this was convenient, as the Operator managed these routes for you, it also caused confusion around ownership as many `Route` resources are managed by administrators. Istio OpenShift Routing also lacked the ability to configure an independent `Route` resource, created unnecessary routes, and exhibited unpredictable behavior during updates. +{SMProductName} 2 used {istio} OpenShift Routing (IOR) that automatically created and managed OpenShift routes for {istio} gateways. While this was convenient, as the Operator managed these routes for you, it also caused confusion around ownership as many `Route` resources are managed by administrators. {istio} OpenShift Routing also lacked the ability to configure an independent `Route` resource, created unnecessary routes, and exhibited unpredictable behavior during updates. -Thus, in {SMProduct} 3, when a `Route` is desired to expose an Istio gateway, you must create and manage it manually. You can also expose an Istio gateway through a Kubernetes service of type `LoadBalancer` if a route is not desired. \ No newline at end of file +Thus, in {SMProduct} 3, when a `Route` is required to expose an {istio} gateway, you must create and manage it manually. You can also expose an {istio} gateway through a Kubernetes service of type `LoadBalancer` if a route is not required. \ No newline at end of file diff --git a/modules/ossm-migrating-read-me-independently-managed-gateways.adoc b/modules/ossm-migrating-read-me-independently-managed-gateways.adoc index c12f7fa0936..23cc418b375 100644 --- a/modules/ossm-migrating-read-me-independently-managed-gateways.adoc +++ b/modules/ossm-migrating-read-me-independently-managed-gateways.adoc @@ -2,28 +2,26 @@ // // * service-mesh-docs-main/about/ossm-migrating-assembly.adoc -//Start of an overall Migrating section. -//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. - :_mod-docs-content-type: CONCEPT [id="ossm-migrating-read-me-independently-managed-istio-gateways_{context}"] = Independently managed Istio gateways [role="_abstract"] -In Istio, gateways are used to manage traffic entering (ingress) and exiting (egress) the mesh. {SMProductName} 2 deployed and managed an ingress gateway and an egress gateway with the Service Mesh control plane. Both an ingress gateway and an egress gateway were configured using the `ServiceMeshControlPlane` resource. +In {istio}, gateways are used to manage traffic entering (ingress) and exiting (egress) the mesh. {SMProductName} 2 deployed and managed an ingress gateway and an egress gateway with the Service Mesh control plane. Both an ingress gateway and an egress gateway were configured using the `ServiceMeshControlPlane` resource. The {SMProduct} 3 Operator does not create or manage gateways. -Instead, gateways in {SMProduct} 3 are created and managed independent of the Operator and control plane using gateway injection or the Kubernetes Gateway API. This provides greater flexibility and ensures that gateways can be fully customized and managed as part of a Red Hat OpenShift GitOps pipeline. This allows the gateways to be deployed and managed alongside their applications with the same lifecycle. - -//Note to add GitOps attributes to common-attributes file. Adding attributes is being handled by a different Jira issue, and is outside the scope of this PR. +Instead, gateways in {SMProduct} 3 are created and managed independent of the Operator and control plane by using gateway injection or the Kubernetes Gateway API. This provides greater flexibility and ensures that gateways can be fully customized and managed as part of a {gitops-title} pipeline. This allows the gateways to be deployed and managed alongside their applications with the same lifecycle. This change was made for two reasons: * To start with a gateway configuration that can expand over time to meet the more robust needs of a production environment. * Gateways are better managed together with their corresponding workloads. -Gateways may continue to be deployed onto nodes or namespaces independent of applications. For example, a centralized gateway node. Istio gateways also remain eligible to be deployed on {ocp-product-title} infrastructure nodes. +Gateways might continue to be deployed onto nodes or namespaces independent of applications. For example, a centralized gateway node. Istio gateways also remain eligible to be deployed on {ocp-product-title} infrastructure nodes. -//Note to check if OpenShift Container Platform Infrastructure Nodes (or maybe OpenShift Infrastructure Nodes) has an attribute, and if it does, add it to service-mesh-docs-main _attributes file, which is being handled by a separate Jira and running spreadsheet. \ No newline at end of file +[NOTE] +==== +If you are using {SMProduct} 2.6, and have not migrated from `ServiceMeshControlPlane` defined gateways to gateway injection, then you must follow the {SMProduct} 2.x gateway migration procedure before you can move to {SMProduct} 3. +==== diff --git a/modules/ossm-migrating-read-me-introducing-canary-updates.adoc b/modules/ossm-migrating-read-me-introducing-canary-updates.adoc index 1b6b7975395..a7cc08d09cd 100644 --- a/modules/ossm-migrating-read-me-introducing-canary-updates.adoc +++ b/modules/ossm-migrating-read-me-introducing-canary-updates.adoc @@ -8,12 +8,17 @@ [role="_abstract"] -{SMProductName} 2 supported only in-place style updates, which created risk for large meshes where, after the control plane was updated, all workloads must update to the new control plane version without a simple way to roll back if something goes wrong. +{SMProductName} 3 addresses the risks of traditional in-place updates by providing revision-based update strategies that allow for incremental workload transitions and simplified rollbacks. -{SMProduct} 3 retains support for simple in-place style updates, and adds support for canary-style updates of the Istio control plane using Istio's revision feature. +{SMProduct} 3 retains support for simple in-place style updates, and adds support for canary-style updates of the {istio} control plane by using {istio}'s revision feature. -The `Istio` resource manages Istio revision labels using the `IstioRevision` resource. When the `Istio` resource's `updateStrategy` type is set to `RevisionBased`, it creates Istio revision labels using the `Istio` resource's name combined with the Istio version, for example `mymesh-v1-21-2`. +The `{istio}` resource manages {istio} revision labels by using the `IstioRevision` resource. When the `{istio}` resource's `updateStrategy` type is set to `RevisionBased`, it creates {istio} revision labels by using the `{istio}` resource's name combined with the {istio} version, for example `mymesh-v1-21-2`. -During an updates, a new `IstioRevision` deploys the new Istio control plane with an updated revision label, for example `mymesh-v1-22-0`. Workloads can then be migrated between control planes using the revision label on namespaces or workloads, for example `istio.io/rev=mymesh-v1-22-0`. +During an updates, a new `IstioRevision` deploys the new {istio} control plane with an updated revision label, for example `mymesh-v1-22-0`. Workloads can then be migrated between control planes by using the revision label on namespaces or workloads, for example `istio.io/rev=mymesh-v1-22-0`. -Setting your `updateStrategy` to `RevisionBased` also has implications for integrations, such as the cert-manager tool, and gateways. \ No newline at end of file +Setting your `updateStrategy` to `RevisionBased` also has implications for integrations, such as the cert-manager tool, and gateways. + +[NOTE] +==== +You can set `updateStrategy` to `RevisionBased` to use canary updates. Be aware that setting the `updateStrategy` to `RevisionBased` also has implications for some integrations with {SMProduct}, such as the cert-manager tool integration. +==== \ No newline at end of file diff --git a/modules/ossm-migrating-read-me-kubernetes-network-policy-management.adoc b/modules/ossm-migrating-read-me-kubernetes-network-policy-management.adoc index 7387d72ed56..7c715dd1b07 100644 --- a/modules/ossm-migrating-read-me-kubernetes-network-policy-management.adoc +++ b/modules/ossm-migrating-read-me-kubernetes-network-policy-management.adoc @@ -2,9 +2,6 @@ // // * service-mesh-docs-main/about/ossm-migrating-assembly.adoc -//Start of an overall Migrating section. -//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. - :_mod-docs-content-type: CONCEPT [id="ossm-migrating-read-me-kubernetes-network-policy-management_{context}"] = Kubernetes network policy management @@ -16,4 +13,4 @@ By default, {SMProductName} 2 created Kubernetes `NetworkPolicy` resources with * Ensured network applications and the control plane could communicate with each other. * Restricted ingress for mesh applications to only member projects. -{SMProduct} 3 does not create these policies. Instead, you must configure the level of isolation required for your environment. Istio provides fine grained access control of service mesh workloads through Authorization Policies. For more information, see "Authorization Policies". \ No newline at end of file +{SMProduct} 3 does not create these policies. Instead, you must configure the level of isolation required for your environment. {istio} provides fine grained access control of service mesh workloads through Authorization Policies. For more information, see "Authorization Policies". \ No newline at end of file diff --git a/modules/ossm-migrating-read-me-new-operator.adoc b/modules/ossm-migrating-read-me-new-operator.adoc index 698472be5b6..554e795e84d 100644 --- a/modules/ossm-migrating-read-me-new-operator.adoc +++ b/modules/ossm-migrating-read-me-new-operator.adoc @@ -2,25 +2,22 @@ // // * service-mesh-docs-main/about/ossm-migrating-read-me.adoc -//Start of an overall Migrating section. -//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. - :_mod-docs-content-type: CONCEPT [id="ossm-migrating-read-me-new-operator_{context}"] = New Operator: The {SMProductName} 3 Operator [role="_abstract"] -{SMProductName} 3 is a major update with a feature set closer to the link:https://istio.io/[Istio project]. Whereas {SMProduct} 2 was based on the midstream Maistra project, {SMProduct} 3 is based directly on Istio. This means {SMProduct} 3 is managed using a different, simplified Operator and provides greater support for the latest stable features of Istio. +{SMProductName} 3 is a major update with a feature set closer to the "{istio} project". Whereas {SMProduct} 2 was based on the midstream Maistra project, {SMProduct} 3 is based directly on {istio}. This means {SMProduct} 3 is managed using a different, simplified Operator and provides greater support for the latest stable features of {istio}. -This alignment with the Istio project along with lessons learned in the first two major releases of {SMProduct} have resulted in the following changes: +This alignment with the {istio} project along with lessons learned in the first two major releases of {SMProduct} have resulted in the following changes: [id="ossm-maistra-to-istio_{context}"] == From Maistra to Istio -{SMProduct} 1 and 2 were based on Istio, and included additional functionality that was maintained as part of the midstream Maistra project, but not part of the upstream Istio project. While this provided extra features to {SMProduct} users, the effort to maintain Maistra meant that {SMProduct} 2 was usually several releases behind Istio, and did not support major features like multi-cluster deployment. Since the release of {SMProduct} 1 and 2, Istio has matured to cover most of the use cases addressed by Maistra. +{SMProduct} 1 and 2 were based on {istio}, and included additional functionality that was maintained as part of the midstream Maistra project, but not part of the upstream {istio} project. While this provided extra features to {SMProduct} users, the effort to support Maistra meant that {SMProduct} 2 was usually several releases behind {istio}, and did not support major features such as multi-cluster deployment. Since the release of {SMProduct} 1 and 2, {istio} has matured to cover most of the use cases addressed by Maistra. -Basing {SMProduct} 3 directly on Istio ensures that {SMProduct} 3 supports users on the latest stable Istio features while Red{nbsp}Hat contributes directly to the Istio community on behalf of its customers. +Basing {SMProduct} 3 directly on {istio} ensures that {SMProduct} 3 supports users on the latest stable {istio} features while Red{nbsp}Hat contributes directly to the {istio} community on behalf of its customers. [id="ossm-service-mesh-3-operator_{context}"] == {SMProduct} 3 Operator @@ -36,7 +33,7 @@ Basing {SMProduct} 3 directly on Istio ensures that {SMProduct} 3 supports users All {product-title} Operators use versioning and manage at least one underlying component (operand), which is often versioned independently through a custom resource definition (CRD). -In {SMProduct} 2, the `ServiceMeshControlPlane` resource managed multiple operands, including {istio}, Kiali, and Jaeger. Each component maintained its own version containing the following three levels of versioning: +In {SMProduct} 2, the `ServiceMeshControlPlane` resource managed many operands, including {istio}, Kiali, and Jaeger. Each component maintained its own version containing the following three levels of versioning: * The Operator version * The `ServiceMeshControlPlane` version @@ -46,7 +43,4 @@ For example, the {SMProduct} 2.6 Operator managed the 2.6 version of the control {SMProduct} 3 simplifies versioning by limiting Operator management to the {istio} resource. The {istio} resource is responsible only for the {istio} component and does not manage Kiali or other components. So, the {istio} resource specifies only the {istio} component version. -Each {SMProduct} release supports the latest available {istio} version for that Operator version. For example, {SMProduct} 3.0.0 supports {istio} 1.24.0. While the Operator might contain other {istio} versions to support upgrades, product support, including patches for Common Vulnerabilities and Exposures (CVEs), covers only the latest {istio} version in a given Operator release. For each Operator release, update to the most recent {istio} version available. - -//Note for later: update "Red{nbsp}Hate OpenShift Observability" with appropriate attribute when that attribute has been added to the Service Mesh stand alone _attributes file. -//Note that as of 11/18/2024, no attributes in OCP main _attributes file use Red{nbsp}Hat. OCP main _attributes are not in line with current style. \ No newline at end of file +Each {SMProduct} release supports the latest available {istio} version for that Operator version. For example, {SMProduct} 3.0.0 supports {istio} 1.24.0. While the Operator might contain other {istio} versions to support upgrades, product support, including patches for Common Vulnerabilities and Exposures (CVEs), covers only the latest {istio} version in a given Operator release. For each Operator release, update to the most recent {istio} version available. \ No newline at end of file diff --git a/modules/ossm-migrating-read-me-new-resources.adoc b/modules/ossm-migrating-read-me-new-resources.adoc index c60b184e931..39124d819c5 100644 --- a/modules/ossm-migrating-read-me-new-resources.adoc +++ b/modules/ossm-migrating-read-me-new-resources.adoc @@ -2,9 +2,6 @@ // // * service-mesh-docs-main/about/ossm-migrating-assembly.adoc -//Start of an overall Migrating section. -//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. - :_mod-docs-content-type: CONCEPT [id="ossm-migrating-read-me-new-resources_{context}"] = New resources in {SMProduct} 3 diff --git a/modules/ossm-migrating-read-me-observability-integrations.adoc b/modules/ossm-migrating-read-me-observability-integrations.adoc index 0af8049ee96..0c27bb806cb 100644 --- a/modules/ossm-migrating-read-me-observability-integrations.adoc +++ b/modules/ossm-migrating-read-me-observability-integrations.adoc @@ -2,9 +2,6 @@ // // * service-mesh-docs-main/about/ossm-migrating-assembly.adoc -//Start of an overall Migrating section. -//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. - :_mod-docs-content-type: CONCEPT [id="ossm-migrating-read-me-observability-integrations_{context}"] = Independent Red{nbsp}Hat OpenShift Observability component integrations and configurations @@ -15,8 +12,6 @@ A significant change in {SMProductName} 3 is that the Operator no longer install The {SMProduct} 3 Operator limits its scope to Istio-related resources, with observability components supported and managed by the independent Operators that make up Red{nbsp}Hat OpenShift Observability, such as the following: -//Note to add Observability attributes. Adding attributes is being handled by a different Jira issue, and is outside the scope of this PR. - * Logging * User workload monitoring * {DTProductName} diff --git a/modules/ossm-migrating-read-me-scoping-discovery-selectors.adoc b/modules/ossm-migrating-read-me-scoping-discovery-selectors.adoc index ba95159f666..56931b0177d 100644 --- a/modules/ossm-migrating-read-me-scoping-discovery-selectors.adoc +++ b/modules/ossm-migrating-read-me-scoping-discovery-selectors.adoc @@ -2,15 +2,14 @@ // // * service-mesh-docs-main/about/ossm-migrating-assembly.adoc -//Start of an overall Migrating section. -//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. - :_mod-docs-content-type: CONCEPT [id="ossm-migrating-read-me-scoping-discovery-selectors_{context}"] = Scoping of the mesh with discoverySelectors and labels [role="_abstract"] -In {SMProduct} 2.4, a _cluster-wide_ mode was introduced to allow a mesh to be cluster-scoped, with the option to limit the mesh using an Istio feature called `discoverySelectors`. Using `discoverySelectors` limits the Istio control plane's visibility to a set of namespaces defined with a label selector. This aligned with how community Istio worked, and allowed Istio to manage cluster-level resources. For more information, see "Labels and Selectors". +In {SMProduct} 2.4, a _cluster-wide_ mode was introduced to allow a mesh to be cluster-scoped, with the option to limit the mesh by using an {istio} feature called `discoverySelectors`. + +Using `discoverySelectors` limits the {istio} control plane's visibility to a set of namespaces defined with a label selector. This aligned with how community {istio} worked, and allowed {istio} to manage cluster-level resources. For more information, see "Labels and Selectors". -{SMProduct} 3 makes all meshes cluster-wide by default. This change means that Istio control planes are all cluster-scoped resources and the resources `ServiceMeshMemberRoll` and `ServiceMeshMember` are no longer present, with control planes watching, or _discovering_, the entire cluster by default. The control plane's discovery of namespaces can be limited using the `discoverySelectors` feature. +{SMProduct} 3 makes all meshes cluster-wide by default. This change means that {istio} control planes are all cluster-scoped resources and the resources `ServiceMeshMemberRoll` and `ServiceMeshMember` are no longer present, with control planes watching, or _discovering_, the entire cluster by default. The control plane's discovery of namespaces can be limited using the `discoverySelectors` feature. diff --git a/modules/ossm-migrating-read-me-sidecar-injection-considerations.adoc b/modules/ossm-migrating-read-me-sidecar-injection-considerations.adoc index 75e49982cfe..5ba66bf7a42 100644 --- a/modules/ossm-migrating-read-me-sidecar-injection-considerations.adoc +++ b/modules/ossm-migrating-read-me-sidecar-injection-considerations.adoc @@ -2,9 +2,6 @@ // // * service-mesh-docs-main/about/ossm-migrating-assembly.adoc -//Start of an overall Migrating section. -//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. - :_mod-docs-content-type: CONCEPT [id="ossm-migrating-read-me-sidecar-injection-considerations_{context}"] = New considerations for sidecar injection @@ -13,16 +10,16 @@ {SMProductName} 2 supported using pod annotations and labels to configure sidecar injection and there was no need to indicate which control plane a workload belonged to. -With {SMProduct} 3, even though the Istio control plane discovers a namespace, the workloads present in that namespace still require sidecar proxies to be included as workloads in the service mesh, and to be able to use Istio's many features. +With {SMProduct} 3, even though the {istio} control plane discovers a namespace, the workloads present in that namespace still require sidecar proxies to be included as workloads in the service mesh, and to be able to use Istio's many features. In {SMProduct} 3, sidecar injection works the same way as it does for Istio, with pod or namespace labels used to trigger sidecar injection. However, it might be necessary to include a label that indicates which control plane the workload belongs to. [NOTE] ==== -The Istio Project has deprecated pod annotations in favor of labels for sidecar injection. +The {istio} Project has deprecated pod annotations in favor of labels for sidecar injection. ==== -When an `Istio` resource has the name `default` and `InPlace` upgrades are used, there is a single `IstioRevision` with the name `default` and the label `istio-injection=enabled` for sidecar injection. +When an `{istio}` resource has the name `default` and `InPlace` upgrades are used, there is a single `IstioRevision` with the name `default` and the label `istio-injection=enabled` for sidecar injection. However, an `IstioRevision` resource is required to have a different name in the following cases: diff --git a/modules/ossm-migrating-read-me-support-for-istioctl.adoc b/modules/ossm-migrating-read-me-support-for-istioctl.adoc index 225e28b1f68..c58ae3509fa 100644 --- a/modules/ossm-migrating-read-me-support-for-istioctl.adoc +++ b/modules/ossm-migrating-read-me-support-for-istioctl.adoc @@ -2,9 +2,6 @@ // // * service-mesh-docs-main/about/ossm-migrating-assembly.adoc -//Start of an overall Migrating section. -//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. - :_mod-docs-content-type: CONCEPT [id="ossm-migrating-read-me-support-for-istioctl_{context}"] = Support for Istioctl @@ -13,7 +10,8 @@ {SMProductName} 1 and 2 did not include support for Istioctl, the command line utility for the Istio project that includes many diagnostic and debugging utilities. {SMProduct} 3 introduces support for Istioctl for select commands. -.Supported Istioctl commands +The following commands are supported in {SMProduct} 3: + [cols="1,1"] |=== |Command |Description @@ -27,11 +25,9 @@ |`proxy-status`, `ps` | Retrieve the synchronization status of each Envoy in the mesh |`remote-clusters` | List the remote clusters each `istiod` instance is connected to |`validate`, `v` | Validate the {istio} policy and rules files -|`version` | Print out build version information +|`version` | Print build version information |`waypoint` | Manage the waypoint configuration |`ztunnel-config` | Update or retrieve the current Ztunnel configuration. |=== -//table for supported commands may need to be included in prod doc instructions for Istioctl, if Istioctl procedure content is to be included in prod docs. As of 11/11/2024, there is no additional prod doc content for Istioctl. It is upstream https://github.com/openshift-service-mesh/sail-operator/blob/55e26da369c897583a578b6a622b70c9ff67beb9/docs/ossm/istioctl/README.md#supported-commands but that may change for GA. - Installation and management of Istio is only supported by the {SMProduct} 3 Operator. \ No newline at end of file diff --git a/modules/ossm-migrating-read-me-support-for-multiple-control-planes.adoc b/modules/ossm-migrating-read-me-support-for-multiple-control-planes.adoc index d287074cf8a..ee05e8736ff 100644 --- a/modules/ossm-migrating-read-me-support-for-multiple-control-planes.adoc +++ b/modules/ossm-migrating-read-me-support-for-multiple-control-planes.adoc @@ -2,17 +2,14 @@ // // * service-mesh-docs-main/about/ossm-migrating-assembly.adoc -//Start of an overall Migrating section. -//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. - :_mod-docs-content-type: CONCEPT [id="ossm-migrating-read-me-support-multiple-control-planes_{context}"] = Support for multiple control planes [role="_abstract"] -{SMProductName} 3 supports multiple service meshes in the same cluster, but in a different manner than in {SMProduct} 2. A cluster administrator must create multiple `Istio` instances and then configure `discoverySelectors` appropriately to ensure that there is no overlap between mesh namespaces. +{SMProductName} 3 supports multiple service meshes in the same cluster, but in a different manner than in {SMProduct} 2. A cluster administrator must create multiple `{istio}` instances and then configure `discoverySelectors` appropriately to ensure that there is no overlap between mesh namespaces. -As `Istio` resources are cluster-scoped, they must have unique names to represent unique meshes within the same cluster. The {SMProduct} 3 Operator uses this unique name to create a resource called `IstioRevision` with a name in the format of `{Istio name}` or `{Istio name}-{Istio version}`. +As `{istio}` resources are cluster-scoped, they must have unique names to represent unique meshes within the same cluster. The {SMProduct} 3 Operator uses this unique name to create a resource called `IstioRevision` with a name in the format of `{Istio name}` or `{Istio name}-{Istio version}`. -Each instance of `IstioRevision` is responsible for managing a single control plane. Workloads are assigned to a specific control plane using Istio's revision labels of the format `istio.io/rev={IstioRevision name}`. The name with the version identifier becomes important to support canary-style control plane upgrades. \ No newline at end of file +Each instance of `IstioRevision` is responsible for managing a single control plane. Workloads are assigned to a specific control plane by using {istio}'s revision labels of the format `istio.io/rev={IstioRevision name}`. The name with the version identifier becomes important to support canary-style control plane upgrades. \ No newline at end of file diff --git a/modules/ossm-migrating-read-me-supported-multi-cluster-topologies.adoc b/modules/ossm-migrating-read-me-supported-multi-cluster-topologies.adoc index cc627a460d8..e8495346b04 100644 --- a/modules/ossm-migrating-read-me-supported-multi-cluster-topologies.adoc +++ b/modules/ossm-migrating-read-me-supported-multi-cluster-topologies.adoc @@ -2,9 +2,6 @@ // // * service-mesh-docs-main/about/ossm-migrating-assembly.adoc -//Start of an overall Migrating section. -//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. - :_mod-docs-content-type: CONCEPT [id="ossm-migrating-read-me-supported-multi-cluster-topologies_{context}"] = Supported multi-cluster topologies @@ -13,14 +10,12 @@ {SMProductName} 2 supported one form of multi-cluster, _federation_, which was introduced in {SMProduct} 2.1. Each cluster maintained its own independent control plane in this topology, with services only shared between those meshes on an as-needed basis. -Communication between federated meshes is through Istio gateways, so there was no need for Service Mesh control planes to watch remote Kubernetes control planes, as is the case with Istio's multi-cluster service mesh topologies. Federation is ideal where service meshes are loosely coupled, such as those managed by different administrative teams. +Communication between federated meshes is through {istio} gateways, so there was no need for Service Mesh control planes to watch remote Kubernetes control planes, as is the case with {istio}'s multi-cluster service mesh topologies. Federation is ideal where service meshes are loosely coupled, such as those managed by different administrative teams. -{SMProduct} 3 introduces support for the following Istio multi-cluster topologies as well: +{SMProduct} 3 introduces support for the following {istio} multi-cluster topologies as well: * Multi-Primary * Primary-Remote * External control planes -These topologies effectively stretch a single, unified service mesh across multiple clusters, which is ideal when all clusters involved are managed by the same administrative team. Istio's multi-cluster topologies are also ideal for implementing high-availability or failover use cases across a commonly managed set of applications. - -//Note that this section may need to be updated when federation is supported in OSSM 3. As of 11/12/2024: federation topology is not supported in OSSM 3. \ No newline at end of file +These topologies effectively stretch a single, unified service mesh across multiple clusters, which is ideal when all clusters involved are managed by the same administrative team. {istio}'s multi-cluster topologies are also ideal for implementing high-availability or failover use cases across a commonly managed set of applications. \ No newline at end of file diff --git a/modules/ossm-migrating-read-me-tls-configuration-change.adoc b/modules/ossm-migrating-read-me-tls-configuration-change.adoc index 8da3af2eda7..4cae2f6f412 100644 --- a/modules/ossm-migrating-read-me-tls-configuration-change.adoc +++ b/modules/ossm-migrating-read-me-tls-configuration-change.adoc @@ -3,9 +3,6 @@ // // * service-mesh-docs-main/about/ossm-migrating-assembly.adoc -//Start of an overall Migrating section. -//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. - :_mod-docs-content-type: CONCEPT [id="ossm-migrating-read-me-transport-layer-security-configuration-change_{context}"] = Transport layer security (TLS) configuration change @@ -18,8 +15,8 @@ You were able to set the minimum and maximum TLS protocol versions by setting th In {SMProduct} 3, the `Istio` resource replaces the `ServiceMeshControlPlane` resource and does not include these settings. -To enable enable mTLS strict mode in {SMProduct} 3, you must apply the corresponding `PeerAuthentication` and `DestinationRule` resources. +To enable mTLS strict mode in {SMProduct} 3, you must apply the corresponding `PeerAuthentication` and `DestinationRule` resources. -In {SMProduct} 3, you can enable the minimum TLS protocol by setting `spec.meshConfig.tlsDefaults.minProtocolVersion` in your `Istio` resource. For more information, see "Istio Workload Minimum TLS Version Configuration". +In {SMProduct} 3, you can enable the minimum TLS protocol by setting `spec.meshConfig.tlsDefaults.minProtocolVersion` in your `Istio` resource. For more information, see "Istio Workload Minimum TLS Version Configuration". In {SMProduct} 2 and {SMProduct} 3, `auto mTLS` remains enabled by default. \ No newline at end of file diff --git a/modules/ossm-migrating-reference-smcp-configurations.adoc b/modules/ossm-migrating-reference-smcp-configurations.adoc index 876d6bc13df..db0cbda35a4 100644 --- a/modules/ossm-migrating-reference-smcp-configurations.adoc +++ b/modules/ossm-migrating-reference-smcp-configurations.adoc @@ -8,9 +8,9 @@ [role="_abstract"] -Many of the `spec` fields in the {SMProduct} 2 `ServiceMeshControlPlane` can be configured in the the {SMProduct} 3 `Istio` resource. +Many of the `spec` fields in the {SMProduct} 2 `ServiceMeshControlPlane` can be configured in the {SMProduct} 3 `Istio` resource. -The following tables provide guidance for configuring your `Istio` resource in {SMProduct} 3. +The following tables offer guidance for configuring your `Istio` resource in {SMProduct} 3. [id="cluster-configurations_{context}"] == Cluster configurations @@ -82,7 +82,7 @@ The mode configurations in the {SMProduct} 2 `ServiceMeshControlPlane` resource In {SMProduct} 3, the mode is not configured by using a single field in the `Istio` resource. -By default, the {SMProduct} 3 control plane has access to all namespaces which is equivalent to cluster-wide mode in {SMProduct} 2. For a similar configuration to `MultiTenant` mode in {SMProduct} 2 in {SMProduct} 3, you must use the `discoverySelectors` field. For more information, see "Deploying multiple service meshes on a single cluster". +By default, the {SMProduct} 3 control plane has access to all namespaces, which is equal to cluster-wide mode in {SMProduct} 2. For a similar configuration to `MultiTenant` mode in {SMProduct} 2 in {SMProduct} 3, you must use the `discoverySelectors` field. For more information, see "Deploying multiple service meshes on a single cluster". [id="profile-configurations_{context}"] == Profile configurations @@ -101,8 +101,7 @@ The profile configuration options for {SMProduct} 3 are: [id="proxy-congifurations_{context}"] == Proxy configurations -[id="access-logging-configuration-fields_{context}"] -=== Access logging configuration fields +Access logging configuration fields:: [cols="1,1"] |=== @@ -130,8 +129,7 @@ The profile configuration options for {SMProduct} 3 are: | spec.values.meshConfig.accessLogFile |=== -[id="basic-proxy-configuration-fields_{context}"] -=== Basic proxy configuration fields +Basic proxy configuration fields:: [cols="1,1"] |=== @@ -143,8 +141,7 @@ The profile configuration options for {SMProduct} 3 are: | spec.values.meshConfig.defaultConfig.concurrency |=== -[id="envoy-metrics-service-fields_{context}"] -=== Envoy metrics service fields +Envoy metrics service fields:: [cols="1,1"] |=== @@ -160,8 +157,7 @@ The profile configuration options for {SMProduct} 3 are: | spec.values.meshConfig.defaultConfig.envoyMetricsService.tlsSettings |=== -[id="injection-configuration-fields_{context}"] -=== Injection configuration fields +Injection configuration fields:: [cols="1,1"] |=== @@ -177,8 +173,7 @@ The profile configuration options for {SMProduct} 3 are: | spec.values.global.proxy.autoInject |=== -[id="proxy-logging-configuration-fields_{context}"] -=== Proxy logging configuration fields +Proxy logging configuration fields:: [cols="1,1"] |=== @@ -190,8 +185,7 @@ The profile configuration options for {SMProduct} 3 are: | spec.values.global.logging.level |=== -[id="proxy-networking-configuration-fields_{context}"] -=== Proxy networking configuration fields +Proxy networking configuration fields:: [cols="1,1"] |=== @@ -223,8 +217,7 @@ The profile configuration options for {SMProduct} 3 are: | spec.values.meshConfig.protocolDetectionTimeout |=== -[id="traffic-control-configuration-fields_{context}"] -=== Traffic control configuration fields +Traffic control configuration fields:: [cols="1,1"] |=== @@ -246,8 +239,7 @@ The profile configuration options for {SMProduct} 3 are: | spec.values.meshConfig.outboundTrafficPolicy.mode |=== -[id="proxy-runtime-configuration-fields_{context}"] -=== Proxy runtime configuration fields +Proxy runtime configuration fields:: [cols="1,1"] |=== @@ -282,8 +274,7 @@ The profile configuration options for {SMProduct} 3 are: [id="runtime-configurations_{context}"] == Runtime configurations -[id="container-configuration-fields_{context}"] -=== Container configuration fields +Container configuration fields:: [cols="1,1"] |=== @@ -305,8 +296,7 @@ The profile configuration options for {SMProduct} 3 are: | spec.values.pilot.resources |=== -[id="deployment-configuration-fields_{context}"] -=== Deployment configuration fields +Deployment configuration fields:: [cols="1,1"] |=== @@ -328,8 +318,7 @@ The profile configuration options for {SMProduct} 3 are: | spec.values.pilot.rollingMaxUnavailable |=== -[id="pod-configuration-fields_{context}"] -=== Pod configuration fields +Pod configuration fields:: [cols="1,1"] |=== @@ -353,8 +342,7 @@ The profile configuration options for {SMProduct} 3 are: | spec.values.pilot.tolerations |=== -[id="defaults-configuration-fields_{context}"] -=== Defaults configuration fields +Defaults configuration fields:: [cols="1,1"] |=== @@ -381,8 +369,7 @@ The profile configuration options for {SMProduct} 3 are: [id="security-configurations_{context}"] == Security configurations -[id="certificate-authority-fields_{context}"] -=== Certificate Authority (CA) fields +Certificate Authority (CA) fields:: [cols="1,1"] |=== @@ -396,8 +383,7 @@ The profile configuration options for {SMProduct} 3 are: | spec.values.meshConfig.ca.address |=== -[id="istiod-ca-fields_{context}"] -=== Istiod CA fields +Istiod CA fields:: [cols="1,1"] |=== @@ -407,8 +393,7 @@ The profile configuration options for {SMProduct} 3 are: | spec.values.global.pilotCertProvider |=== -[id="control-plane-security-fields_{context}"] -=== Control plane security fields +Control plane security fields:: [cols="1,1"] |=== @@ -426,8 +411,7 @@ The profile configuration options for {SMProduct} 3 are: | spec.values.meshConfig.tlsDefaults.minProtocolVersion |=== -[id="data-plane-security-fields_{context}"] -=== Data plane security fields +Data plane security fields:: [cols="1,1"] |=== @@ -439,8 +423,7 @@ The profile configuration options for {SMProduct} 3 are: | spec.values.meshConfig.meshMTLS |=== -[id="identity-configuration-fields_{context}"] -=== Identity configuration fields +Identity configuration fields:: [cols="1,1"] |=== @@ -450,8 +433,7 @@ The profile configuration options for {SMProduct} 3 are: | spec.values.global.sds.token.aud |=== -[id="other-security-fields_{context}"] -=== Other security fields +Other security fields:: [cols="1,1"] |=== diff --git a/modules/ossm-migrating-reference-unsupported-configurations.adoc b/modules/ossm-migrating-reference-unsupported-configurations.adoc index 33e15e82be2..ce6e640e45e 100644 --- a/modules/ossm-migrating-reference-unsupported-configurations.adoc +++ b/modules/ossm-migrating-reference-unsupported-configurations.adoc @@ -51,8 +51,7 @@ Gateways are managed separately in {SMProduct} 3. [id="unsupported-proxy-configurations_{context}"] == Unsupported Proxy configurations -[id="unsupported-proxy-networking-configuration-fields_{context}"] -=== Unsupported Proxy networking configuration fields +Unsupported Proxy networking configuration fields:: [cols="1"] |=== @@ -66,16 +65,14 @@ Gateways are managed separately in {SMProduct} 3. [id="unsupported-runtime-configurations_{context}"] == Unsupported runtime configurations -[id="unsupported-deployment-configuration-fields_{context}"] -=== Unsupported deployment configuration fields +Unsupported deployment configuration fields:: [cols="1"] |=== | spec.runtime.components.deployment.strategy.type |=== -[id="unsupported-defaults-configuration-fields_{context}"] -=== Unsupported defaults configuration fields +Unsupported defaults configuration fields:: [cols="1"] |=== @@ -86,8 +83,7 @@ Gateways are managed separately in {SMProduct} 3. [id="unsupported-security-configurations_{context}"] == Unsupported security configurations -[id="unsupported-certificate-authority-fields_{context}"] -=== Unsupported certificate Authority (CA) fields +Unsupported certificate Authority (CA) fields:: [cols="1"] |=== @@ -95,8 +91,7 @@ Gateways are managed separately in {SMProduct} 3. | spec.security.certificateAuthority.cert-manager.rootCAConfigMapName |=== -[id="unsupported-istiod-ca-fields_{context}"] -=== Unsupported Istiod CA fields +Unsupported Istiod CA fields:: [cols="1"] |=== @@ -109,16 +104,14 @@ Gateways are managed separately in {SMProduct} 3. | spec.security.certificateAuthority.istiod.workloadCertTTLMax |=== -[id="unsupported-control-plane-security-fields_{context}"] -=== Unsupported control plane security fields +Unsupported control plane security fields:: [cols="1"] |=== | spec.security.controlPlane.tls.maxProtocolVersion |=== -[id="unsupported-identity-configuration-fields__{context}"] -=== Unsupported identity configuration fields +Unsupported identity configuration fields:: [cols="1"] |=== diff --git a/modules/ossm-migrating-to-explicitly-managed-routes.adoc b/modules/ossm-migrating-to-explicitly-managed-routes.adoc new file mode 100644 index 00000000000..c9a7b9502eb --- /dev/null +++ b/modules/ossm-migrating-to-explicitly-managed-routes.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/checklists/ossm-migrating-premigration-checklists.adoc + +:_mod-docs-content-type: REFERENCE +[id="ossm-migrating-to-explicitly-managed-routes_{context}"] += Migrate to explicitly managed routes + +[role="_abstract"] + +Automatic route creation, also known as {istio} OpenShift Routing (IOR), is a deprecated feature that is disabled by default for any `ServiceMeshControlPlane` resource created using {SMProduct} 2.5 and later. + +To move from {SMProduct} 2 to {SMProduct} 3, you need to migrate from IOR to explicitly-managed routes. + +If you already moved to explicitly-managed routes in {SMProduct} 2, then continue to gateway injection. + +* [ ] Migrate from {istio} OpenShift Routing (IOR) to to explicitly-managed routes. For more information, see "Service Mesh route migration". \ No newline at end of file diff --git a/modules/ossm-migrating-to-gateway-injection.adoc b/modules/ossm-migrating-to-gateway-injection.adoc new file mode 100644 index 00000000000..19a6b954aec --- /dev/null +++ b/modules/ossm-migrating-to-gateway-injection.adoc @@ -0,0 +1,13 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/checklists/ossm-migrating-premigration-checklists.adoc + +:_mod-docs-content-type: REFERENCE +[id="ossm-migrating-to-gateway-injection_{context}"] += Migrate to gateway injection + +[role="_abstract"] + +Gateways were controlled by the `ServiceMeshControlPlane` (SMCP) resource in {SMProduct} 2. The {SMProduct} 3 control plane does not manage gateways so you must migrate from SMCP-Defined gateways to gateway injection. + +* [ ] Migrate to gateway injection. For more information, see "Service Mesh gateway migration". \ No newline at end of file diff --git a/modules/ossm-migrating-workloads-using-the-istio-injection-label.adoc b/modules/ossm-migrating-workloads-using-the-istio-injection-label.adoc index ba74461eda2..62cea6e4af2 100644 --- a/modules/ossm-migrating-workloads-using-the-istio-injection-label.adoc +++ b/modules/ossm-migrating-workloads-using-the-istio-injection-label.adoc @@ -14,6 +14,8 @@ endif::[] ifdef::ossm-cluster-wide-istio-injection[= Migrating workloads by using the Istio injection label] ifdef::ossm-cert-manager-istio-injection[= Migrating workloads by using the Istio injection label with cert-manager] +[role="_abstract"] + Now you can migrate your workloads from the {SMProduct} 2.6 control plane to the {SMproduct} 3.0 control plane. [NOTE] @@ -30,7 +32,7 @@ You can migrate workloads and gateways separately, and in any order. For more in $ oc get istios ---- + -.Example output +*Example output:* + [source,terminal] ---- @@ -69,7 +71,6 @@ After you apply the `maistra.io/ignore-namespace` label, any new pod that gets c + .. To restart all the workloads at the same time so that the new pods are injected with the {SMProduct} 3.0 proxy, run the following command: + -.Example command for `bookinfo` application [source,terminal] ---- $ oc rollout restart deployments -n bookinfo @@ -77,7 +78,6 @@ $ oc rollout restart deployments -n bookinfo .. To restart each workload individually, run the following command for each workload: + -.Example command for `bookinfo` application [source,terminal] ---- $ oc rollout restart deployments productpage-v1 -n bookinfo @@ -92,14 +92,15 @@ $ oc rollout status deployment productpage-v1 -n bookinfo .Verification -. Verify that the the new control plane manages the expected workloads by running the following command: +. Verify that the new control plane manages the expected workloads by running the following command: + [source,terminal] ---- $ istioctl ps -n bookinfo ---- + -.Example output: +*Example output:* ++ [source,terminal] ---- NAME CLUSTER CDS LDS EDS RDS ECDS ISTIOD VERSION @@ -113,7 +114,7 @@ reviews-v3-5c5d764c9b-rrx8w.bookinfo Kubernetes SYNCED SYN + The output shows that the `productpage-v1` deployment is the only deployment that has been restarted and was injected with the 3.0 proxy. Even if there are different versions of the proxies, communication between the services still works. -. If the 2.6 installation contains additional namespaces, migrate the next namespace now. +. If the 2.6 installation has additional namespaces, migrate the next namespace now. + [NOTE] ==== @@ -125,4 +126,12 @@ ifeval::["{context}" == "cw-injection"] endif::[] ifeval::["{context}" == "cw-injection-cm"] :!ossm-cert-manager-istio-injection: -endif::[] \ No newline at end of file +endif::[] + +.Next steps + +If you are using gateways, you must migrate them before you complete the migration process. + +* See: "Migrating gateways" + +If you are not using gateways, and have verified your cluster-wide migration, create a default revision tag and relabel namespaces. diff --git a/modules/ossm-migrating-workloads-using-the-istio-revision-label.adoc b/modules/ossm-migrating-workloads-using-the-istio-revision-label.adoc index 7dfd806bf9b..8b1f2535e3e 100644 --- a/modules/ossm-migrating-workloads-using-the-istio-revision-label.adoc +++ b/modules/ossm-migrating-workloads-using-the-istio-revision-label.adoc @@ -14,6 +14,8 @@ endif::[] ifdef::ossm-cluster-wide-istio-revision[= Migrating workloads by using the Istio revision label] ifdef::ossm-cert-manager-istio-revision[= Migrating workloads by using the Istio revision label with cert-manager] +[role="_abstract"] + Now you can migrate your workloads from the {SMProduct} 2.6 control plane to the {SMproduct} 3.0 control plane. Revision tags are not used in this example for simplicity. When migrating large meshes, you can use revision tags to avoid re-labeling all namespaces during future version 3 updates. @@ -32,7 +34,7 @@ You can migrate workloads and gateways separately, and in any order. For more in $ oc get istios ---- + -.Example output +*Example output:* + [source,terminal] ---- @@ -71,7 +73,6 @@ Once you apply the `maistra.io/ignore-namespace` label, any new pod that gets cr + .. To restart all the workloads at once so that the new pods are injected with the {SMProduct} 3.0 proxy, run the following command: + -.Example command for `bookinfo` application [source,terminal] ---- $ oc rollout restart deployments -n bookinfo @@ -79,7 +80,6 @@ $ oc rollout restart deployments -n bookinfo .. To restart each workload individually, run the following command for each workload: + -.Example command with `bookinfo` application [source,terminal] ---- $ oc rollout restart deployments productpage-v1 -n bookinfo @@ -101,7 +101,8 @@ $ oc rollout status deployment productpage-v1 -n bookinfo $ istioctl ps -n bookinfo ---- + -.Example output +*Example output:* ++ [source,terminal] ---- $ istioctl ps -n bookinfo @@ -116,7 +117,7 @@ reviews-v3-5c5d764c9b-rrx8w.bookinfo Kubernetes SYNCED SYN + The previous output shows that the `productpage-v1` deployment is the only deployment that restarted and was injected with the 3.0 proxy. Even if there are different versions of the proxies, communication between services still works. -. If the 2.6 installation contains additional data plane namespaces, migrate the next namespace now. +. If the 2.6 installation has additional data plane namespaces, migrate the next namespace now. + [NOTE] ==== @@ -128,4 +129,14 @@ ifeval::["{context}" == "cw-revision"] endif::[] ifeval::["{context}" == "cw-revision-cm"] :!ossm-cert-manager-istio-revision: -endif::[] \ No newline at end of file +endif::[] + +.Next steps + +If you are using gateways, you must migrate them before you complete the migration process. + +* See: "Migrating gateways" + +If you are not using gateways, and have verified your cluster-wide migration, you can proceed to complete the migration and remove {SMProduct} 2 resources. + +* See: "Completing the Migration" diff --git a/modules/ossm-migrating-workloads-using-the-simple-migration-method.adoc b/modules/ossm-migrating-workloads-using-the-simple-migration-method.adoc index 3b96e725bad..fc46480ca2f 100644 --- a/modules/ossm-migrating-workloads-using-the-simple-migration-method.adoc +++ b/modules/ossm-migrating-workloads-using-the-simple-migration-method.adoc @@ -35,7 +35,6 @@ After you apply the `maistra.io/ignore-namespace` label, any new pod that gets c + .. To restart all the workloads at the same time so that the new pods are injected with the {SMProduct} 3.0 proxy, run the following command: + -.Example command for `bookinfo` application [source,terminal] ---- $ oc rollout restart deployments -n bookinfo @@ -43,7 +42,6 @@ $ oc rollout restart deployments -n bookinfo .. To restart each workload individually, run the following command for each workload: + -.Example command for `bookinfo` application [source,terminal] ---- $ oc rollout restart deployments productpage-v1 -n bookinfo @@ -58,14 +56,15 @@ $ oc rollout status deployment productpage-v1 -n bookinfo .Verification -. Verify that the the new control plane manages the expected workloads by running the following command: +. Verify that the new control plane manages the expected workloads by running the following command: + [source,terminal] ---- $ istioctl ps -n bookinfo ---- + -.Example output: +*Example output:* ++ [source,terminal] ---- NAME CLUSTER CDS LDS EDS RDS ECDS ISTIOD VERSION @@ -79,9 +78,19 @@ reviews-v3-5c5d764c9b-rrx8w.bookinfo Kubernetes SYNCED SYN + The output shows that the `productpage-v1` deployment is the only deployment that has been restarted and was injected with the 3.0 proxy. Even if there are different versions of the proxies, communication between the services still works. -. If the 2.6 installation contains additional namespaces, migrate the next namespace now. +. If the 2.6 installation has additional namespaces, migrate the next namespace now. + [NOTE] ==== Remove the `maistra.io/ignore-namespace="true"` label only after the 2.6 control plane has been uninstalled. -==== \ No newline at end of file +==== + +.Next steps + +If you are using gateways, you must migrate them before you complete the migration process. + +* See: "Migrating gateways" + +If you are not using gateways, you can complete your migration. + +* See: "Completing the Migration" 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-multi-cluster-configuration-overview.adoc b/modules/ossm-multi-cluster-configuration-overview.adoc index 1ed9e906539..421e4b34bdc 100644 --- a/modules/ossm-multi-cluster-configuration-overview.adoc +++ b/modules/ossm-multi-cluster-configuration-overview.adoc @@ -1,10 +1,10 @@ // This module is used in the following assemblies: - +// // * install/ossm-multi-cluster-topologies.adoc :_mod-docs-content-type: CONCEPT [id="ossm-multi-cluster-configuration-overview_{context}"] -= Multi-Cluster configuration overview += Multi-cluster configuration overview [role="_abstract"] diff --git a/modules/ossm-multiple-control-planes-single-cluster.adoc b/modules/ossm-multiple-control-planes-single-cluster.adoc index ace9cc00314..8590025d6d9 100644 --- a/modules/ossm-multiple-control-planes-single-cluster.adoc +++ b/modules/ossm-multiple-control-planes-single-cluster.adoc @@ -1,4 +1,5 @@ // Module included in the following assemblies: +// // install/ossm-deploying-multiple-service-meshes-on-single-cluster.adoc :_mod-docs-content-type: CONCEPT @@ -7,4 +8,6 @@ [role="_abstract"] -You can use discovery selectors to limit the visibility of an {istio} control plane to specific namespaces in a cluster. By combining discovery selectors with control plane revisions, you can deploy multiple control planes in a single cluster, ensuring that each control plane manages only its assigned namespaces. This approach avoids conflicts between control planes and enables soft multi-tenancy for service meshes. \ No newline at end of file +You can use discovery selectors to limit the visibility of an {istio} control plane to specific namespaces in a cluster. + +By combining discovery selectors with control plane revisions, you can deploy multiple control planes in a single cluster, ensuring that each control plane manages only its assigned namespaces. This approach avoids conflicts between control planes and enables soft multi-tenancy for service meshes. \ No newline at end of file diff --git a/modules/ossm-nftables-migration-ambient.adoc b/modules/ossm-nftables-migration-ambient.adoc new file mode 100644 index 00000000000..e35e37b21f8 --- /dev/null +++ b/modules/ossm-nftables-migration-ambient.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// update/ossm-updating-openshift-service-mesh-in-ambient-mode.adoc + +:_mod-docs-content-type: CONCEPT +[id="ossm-nftables-migration-ambient_{context}"] += Nftables migration in ambient mode + +[role="_abstract"] +When you enable support for the `nftables` network backend, which is required for clusters that use {op-system-base-full} 10 nodes, the {istio} CNI initialization process manages existing networking artifacts. In ambient mode, existing `iptables` rules on the host determine the migration behavior. + +== Enabling `nftables` support +To enable `nftables` support, set the `spec.values.global.nativeNftables` field to `true` in both the `{istio}` and `IstioCNI` resources. This configuration is compatible with earlier versions of {op-system-base-full} and allows for mixed-version clusters during migration. + +== How {SMProductShortName} initializes with `nftables` enabled +The {istio} CNI agent checks for existing `iptables` artifacts on the host during startup. The result of this check determines the networking backend configuration based on environment: + +* **Clean environments:** On nodes with no existing `iptables` artifacts, such as new {op-system-base-full} 10 hosts, the CNI agent automatically uses the `nftables` backend. +* **Existing environments:** On nodes where `iptables` was active, the CNI agent might detect existing artifacts. To prevent networking conflicts, the agent overrides the `nftables` setting and continues to use the `iptables` backend. + +== Final migration step for existing nodes +To migrate existing nodes from `iptables` to `nftables`, reboot the nodes to ensure a clean networking state. + +[NOTE] +==== +If the CNI agent detects existing artifacts and reverts to `iptables`, it logs a message indicating that a node reboot is required to complete the migration to the `nftables` backend. +==== \ No newline at end of file diff --git a/modules/ossm-plan-mesh-observability.adoc b/modules/ossm-plan-mesh-observability.adoc new file mode 100644 index 00000000000..18716a39265 --- /dev/null +++ b/modules/ossm-plan-mesh-observability.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-plan-mesh-observability_{context}"] += Plan observability to monitor mesh health + +[role="_abstract"] + +A service mesh generates telemetry for every connection between services. +With the right tools in place, you can use this telemetry to see how traffic flows through your mesh, identify failing or slow services before users are affected, and trace a single request across multiple services to pinpoint where problems occur. + +{SMProductShortName} builds on the monitoring stack already included in {ocp-product-title} and integrates with Kiali for mesh-specific visualization and management. + 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 new file mode 100644 index 00000000000..204fc2c07e6 --- /dev/null +++ b/modules/ossm-plan-upgrade-strategy.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-plan-upgrade-strategy_{context}"] += Plan your upgrade strategy + +[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. + +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. + +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-protect-services-from-failures.adoc b/modules/ossm-protect-services-from-failures.adoc new file mode 100644 index 00000000000..3c5052930ea --- /dev/null +++ b/modules/ossm-protect-services-from-failures.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-protect-services-from-failures_{context}"] += Protect services from failures and overload + +[role="_abstract"] + +After you deploy the mesh, configure it to maintain service availability and manage risk when rolling out application changes. + +High availability for the control plane prevents single points of failure by running multiple `istiod` instances. You can set a static replica count or enable autoscaling based on resource usage. + +Traffic routing lets you shift a percentage of traffic between application versions, so you can test new releases with a subset of users before a full rollout. In sidecar mode, you configure traffic splits with `VirtualService` and `DestinationRule` resources. In ambient mode, you use `HTTPRoute` resources routed through waypoint proxies. diff --git a/modules/ossm-release-3-0-TP-1.adoc b/modules/ossm-release-3-0-TP-1.adoc deleted file mode 100644 index f45303f3af8..00000000000 --- a/modules/ossm-release-3-0-TP-1.adoc +++ /dev/null @@ -1,113 +0,0 @@ -//// -Module included in the following assemblies: -* service-mesh-docs-main/ossm-release-notes-assembly.adoc -//// - -:_mod-docs-content-type: REFERENCE -[id="ossm-release-3-0-TP-1_{context}"] -= {SMProductName} 3.0 Technology Preview - -This release of {SMProductName} is Technology Preview. - -// Simple table to help clarify for users the component versions they can use with OSSM 3.0 TP1. Likely a more complicated table will be needed for GA. OSSM 3.0 separates all the Operators such as OCP, Istio, Envoy, Kiali, OTEL/Tempo, etc. This is only what is known to work with OSSM 3.0 TP1 and TP2, as of 12/09/2024. - -[id="ossm-release-3-0-TP1-component-versions-2_{context}"] -== Supported component versions for Technology Preview 2 - -|=== -|Component |Version - -|{ocp-product-title} -|4.14 and later - -|Istio -|1.24.1 - -|Envoy Proxy -|1.32 - -|Kiali Operator -|2.1 - -|Kiali Server -|2.1 -|=== - -[IMPORTANT] -==== -* You need to remove the Kiali custom resources (CR) from Technology Preview 1 before you update to {KialiProduct} 2.1. - -* {KialiProduct} 2.1 is available in the `candidates` channel. -+ -The `candidate` channel offers unsupported early access to releases as soon as they are built. Releases present only in candidate channels might not contain the full feature set of eventual GA releases, or features might be removed before GA. Additionally, these releases have not been subject to full Red{nbsp}Hat Quality Assurance and might not offer update paths to later GA releases. Given these caveats, the candidate channel is suitable only for testing purposes where deleting and re-creating a cluster is acceptable. -==== -//copied from https://docs.openshift.com/container-platform/4.17/updating/understanding_updates/understanding-update-channels-release.html#candidate-version-channel_understanding-update-channels-releases - -[id="ossm-release-3-0-TP1-unavailable-features-2_{context}"] -== Unavailable features in Technology Preview 2 - -The following features are not supported in the Technology Preview 2 release: - -* Ambient mode in Istio -* Virtual Machine support in Istio - -[id="ossm-release-3-0-TP1-unavailable-clusters-2_{context}"] -== Unavailable clusters in Technology Preview 2 - -The following clusters are not supported in the Technology Preview 2 release: - -* Production clusters - -[id="ossm-release-3-0-TP1-component-versions_{context}"] -== Supported component versions for Technology Preview 1 - -|=== -|Component |Version - -|{ocp-product-title} -|4.14+ - -|Istio -|1.23.0 - -|Envoy Proxy -|1.31 - -|Kiali Operator -|1.89 - -|Kiali Server -|1.89 -|=== - -[id="ossm-release-3-0-TP1-unavailable-features_{context}"] -== Unavailable features in Technology Preview 1 - -The following features are not supported in the Technology Preview 1 release: - -* {SMPlugin} -* Ambient mode in Istio -* Virtual Machine support in Istio - -[id="ossm-release-3-0-TP1-unavailable-clusters_{context}"] -== Unavailable clusters in Technology Preview 1 - -The following clusters are not supported in the Technology Preview 1 release: - -* Production clusters - -// 12/10/2024: TP2 content from this file will need to be moved to its own file set for the stand alone format prior to GA in order to keep versioning dropdown options consistent. All notes will be removed for GA. - -// 12/09/2024: Per Dev, IBM Power® and IBM Z® platforms are not supported on TP2, only TP1. No new doc branch, so had to add new section, and update titles to denote TP1 vs TP2 unsupported features and unavailable clusters. - -// 12/02/2024: Per PM, no TP2 doc branch. Just update existing file to remove "IBM Power® and IBM Z® platforms" from "Unsupported features" and remove "Clusters with Service Mesh 2.x" from "Unavailable clusters". - -// 09/12/2024: IBM Power and 390x platforms added to unavailable features per https://issues.redhat.com/browse/OSSM-8068 - -// 08/22/2024: Possible more items may be added in the next week. -// Per Jira description from PM: "A bare bones release notes page to capture known features that are not currently available. As nothing is technically supported yet, "unsupported" doesn't really carry weight and the focus will be on features that are either unavailable of have not been tested yet in any manner." -// TP1 content. TP banner is persistent and was handled by a different PR from Tim O'Keefe. See https://docs.openshift.com/service-mesh/3.0.0tp1/about/ossm-about-openshift-service-mesh.html -// Possible file name may change -// Possible assembly file may change -// Assemblies, topic map info needs to be worked out still for 3.0. -// Noting for future reference: Rel notes for GA will have new features, bug fixes, etc. in addition to a Component table. Component table may be its own file as there are more components to update, including supported OCP versions since stand alone format removes the connection to the OCP version. Service Mesh docs are versioned now instead of OCP docs since stand alone moves Service Mesh docs up a level. \ No newline at end of file diff --git a/modules/ossm-release-notes-3-0-1.adoc b/modules/ossm-release-notes-3-0-1.adoc deleted file mode 100644 index 71024e8b1b7..00000000000 --- a/modules/ossm-release-notes-3-0-1.adoc +++ /dev/null @@ -1,9 +0,0 @@ -// 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-0-1_{context}"] -= {SMProductName} version 3.0.1 - -This release of {SMProductName} is included with the {SMProductName} Operator 3.0.1 and is supported on {ocp-product-title} 4.14 and later. This release addresses Common Vulnerabilities and Exposures (CVEs) and is supported on {ocp-product-title} 4.14 and later. For supported component versions for 3.0.1, see "Service Mesh version support tables". \ No newline at end of file diff --git a/modules/ossm-release-notes-3-0-2.adoc b/modules/ossm-release-notes-3-0-2.adoc deleted file mode 100644 index d48efd8e426..00000000000 --- a/modules/ossm-release-notes-3-0-2.adoc +++ /dev/null @@ -1,9 +0,0 @@ -// 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-0-2_{context}"] -= {SMProductName} version 3.0.2 - -This release of {SMProductName} is included with the {SMProductName} Operator 3.0.2 and is supported on {ocp-product-title} 4.14 and later. This release addresses Common Vulnerabilities and Exposures (CVEs) and is supported on {ocp-product-title} 4.14 and later. For supported component versions for 3.0.2, see "Service Mesh version support tables". \ No newline at end of file diff --git a/modules/ossm-release-notes-3-0-3.adoc b/modules/ossm-release-notes-3-0-3.adoc deleted file mode 100644 index 8a49223ad9a..00000000000 --- a/modules/ossm-release-notes-3-0-3.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// 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-0-3_{context}"] -= {SMProductName} version 3.0.3 - -This release of {SMProductName} is included with the {SMProductName} Operator 3.0.3 and is supported on {ocp-product-title} 4.14 and later. This release addresses Common Vulnerabilities and Exposures (CVEs) and is supported on {ocp-product-title} 4.14 and later. For supported component versions for 3.0.3, see "Service Mesh version support tables". - -[id="ossm-enhancements-3-0-3_{context}"] -== Enhancements - -* This enhancement updates {istio} to version 1.24.6. For more information, see link:https://issues.redhat.com/browse/OSSM-9758[OSSM-9758] - -* This enhancement updates Kiali operator to version 2.4.7. - -[id="ossm-bug-fixes-3-0-3_{context}"] -== Bug fixes - -* Previously, the {KialiProduct} used the `k8s_cluster_info` Ansible module from the `kubernetes.core` collection, which could fail in some environments with a result code of `-9`. This failure occurred during the `Get api version information from the cluster` Ansible task and prevented the Operator from reconciling Kiali custom resources (CRs). Now, the fix removes the use of the `k8s_cluster_info` Ansible module to prevent this error. (link:https://issues.redhat.com/browse/OSSM-9659[OSSM-9659]) \ No newline at end of file diff --git a/modules/ossm-release-notes-3-0-deprecated-removed-features.adoc b/modules/ossm-release-notes-3-0-deprecated-removed-features.adoc deleted file mode 100644 index ef7c55b47e7..00000000000 --- a/modules/ossm-release-notes-3-0-deprecated-removed-features.adoc +++ /dev/null @@ -1,26 +0,0 @@ -//// -Module included in the following assemblies: -* service-mesh-docs-main/ossm-release-notes.adoc -//// - -:_mod-docs-content-type: REFERENCE -[id="ossm-release-3-0-deprecated-removed-features_{context}"] -= {SMProduct} 3.0 deprecated and removed features - -Some features available in previous releases have been deprecated or removed. - -Deprecated functionality is still included in {ocp-product-title} and continues to be supported; however, it will be removed in a future release of {SMProductName} 3 and is not recommended for new deployments. - -Removed functionality no longer exists in the product. - -[id="istio-openhisft-routes-ior_{context}"] -== Istio OpenShift routes (IOR) - -This release removes the Istio OpenShift Route (IOR) for automatically creating and managing OpenShift Route resources with Istio Gateway resources. Istio Gateways are managed independent of the Istio control plane using either Gateway injection or Kubernetes Gateway API. - -[id="metrics-and-tracing-integrations_{context}"] -== Metrics and tracing integrations - -{SMProduct} 3.0 no longer includes Prometheus and Grafana, and it does not manage the configuration of Jaeger and Elasticsearch. Both Jaeger and Elasticsearch are deprecated and will be removed in a future release. - -Supported integrations are provided with {ObservabilityLongName}, including user-workload monitoring and distributed tracing. For more information, see "{observabilitylongname} and {smproductshortname}". Support is also provided for the {KialiProduct}. For more information, see "Using {KialiProduct}". \ No newline at end of file diff --git a/modules/ossm-release-notes-3-0-known-issues.adoc b/modules/ossm-release-notes-3-0-known-issues.adoc deleted file mode 100644 index d8ba5c38cc3..00000000000 --- a/modules/ossm-release-notes-3-0-known-issues.adoc +++ /dev/null @@ -1,9 +0,0 @@ -// Module included in the following assemblies: -// -// * service-mesh-docs-main/ossm-release-notes.adoc - -:_mod-docs-content-type: REFERENCE -[id="ossm-release-3-0-known-issues_{context}"] -= {SMProductName} 3.0 known issues - -* link:https://issues.redhat.com/browse/OSSM-8878[OSSM-8878] In {SMProductName} 3.0, {ocp-product-title} builder pods fail to create in namespaces with injection enabled. As a workaround, add injection labels to workloads instead of the namespace when creating the `BuildConfigs` resource. \ No newline at end of file diff --git a/modules/ossm-release-notes-3-0-new-features.adoc b/modules/ossm-release-notes-3-0-new-features.adoc deleted file mode 100644 index c44ad26a97f..00000000000 --- a/modules/ossm-release-notes-3-0-new-features.adoc +++ /dev/null @@ -1,115 +0,0 @@ -//// -Module included in the following assemblies: -* service-mesh-docs-main/ossm-release-notes.adoc -//// - -:_mod-docs-content-type: REFERENCE -[id="ossm-release-3-0-new-features-enhancements_{context}"] -= {SMProduct} 3.0 new features and enhancements - -This release makes {SMProductName} 3.0 generally available, adds new features, addresses Common Vulnerabilities and Exposures (CVEs), and is supported on {ocp-product-title} 4.14 and later. - -For a list of supported component versions and support features, see "Service Mesh 3.0 feature support tables". - -For a complete list of changes between {SMProduct} 2 and {SMProduct} 3, see "Important information to know if you are migrating from OpenShift Service Mesh 2.6". - -[id="migration-guides_{context}"] -== Migration guides - -This release adds a set of checklists and migration guides to help you migrate from {SMProduct} 2 to {SMProduct} 3.0. - -You must complete the checklists first. The checklists help you set up and configure {SMProduct} 2 and the `ServiceMeshControlPlane` resource to migrate to {SMProduct} 3.0 and the `Istio` control plane resource. - -Your migration depends on your deployment model: - -* Multitenant -* Multitenant with cert-manager -* Cluster-wide -* Cluster-wide with cert-manager - -You can also migrate gateways. For more information, see "Migrating from {smproductshortname} 2 to {smproductshortname} 3". - -[id="new-istio-distribution-and-operator_{context}"] -== New Istio distribution and operator - -{SMProduct} 3.0 is based on a Red{nbsp}Hat distribution of the link:https://istio.io/[Istio project] and is deployed with a new Operator for Istio based on the Sail Operator project that is part of the **istio-ecosystem** organization on GitHub. The Sail Operator includes a new set of custom resource definitions (CRDs) for managing Istio. For example, the `Istio` CRD replaces the `ServiceMeshControlPlane` CRD in previous releases of {SMProduct}. - -[id="support-for-istoctl-for-select-platforms-and-commands_{context}"] -== Support for Istioctl for select platforms and commands - -This release adds support for select platforms and commands for Istioctl, the command line utility for the Istio project that includes many diagnostic and debugging utilities. For more information, see "Support for Istioctl". - -[IMPORTANT] -==== -Installing Istio using the `istioctl` utility is not supported. -==== - -[id="support-for-multi-cluster-deployment-models_{context}"] -== Support for multi-cluster deployment models - -This release introduces support for the following Istio multi-cluster deployment models: - -* Multi-primary -* Primary-remote -* An external control plane - -The federation feature introduced in {SMProduct} 2.1 is not available in {SMProduct} 3.0. - -[id="multiple-control-planes-in-a-single-cluster_{context}"] -== Multiple control planes in a single cluster - -This release adds support for the Istio feature of multiple control planes in a single cluster. This replaces the `MultiTenant` deployment model (mode) in {SMProduct} 2. - -[id="revision-based-updates_{context}"] -== Revision based updates - -This release adds support for canary-style updates of the Istio control plane using the Istio revision feature. This enables a new Istio control plane to be created alongside the existing Istio control plane so that workloads can be migrated incrementally. The update strategy is configured using the `spec.updateStrategy` parameter of the `Istio` resource. - -For more information, see "About RevisionBased strategy". - -[id="istiocni-custom-resource-definition_{context}"] -== IstioCNI custom resource definition - -This release introduces the `IstioCNI` custom resource definition (CRD), which is used to manage the lifecycle of the Istio Container Network Interface (CNI) daemon set. A single instance of this resource must be created per cluster to configure traffic redirection for pods in the mesh. The Istio CNI lifecycle is independent of the Istio control plane or planes. - -[id="dual-stack-ipv4-ipv6_{context}"] -== IPv4/IPv6 dual-stack (Technology Preview) -:FeatureName: IPv4/IPv6 dual-stack -include::snippets/technology-preview.adoc[] - -This release includes IPv4/IPv6 dual-stack support as a technology preview feature. This aligns with the Alpha status of the Istio upstream project, and is feature-complete for Istio when using sidecars. Dual-stack helps organizations smoothly transition to IPv6, while still maintaining compatibility with their existing IPv4 setup. - -In {SMProduct} 3.0, dual-stack is disabled by default in the `Istio` resource. You can enable it with specific configuration changes, such as the one shown in the following example: - -.Example YAML configuration for IPv4/IPv6 dual stack -[source,yaml] ----- -apiVersion: sailoperator.io/v1 -kind: Istio -metadata: - name: default -spec: - values: - meshConfig: - defaultConfig: - proxyMetadata: - ISTIO_DUAL_STACK: "true" - pilot: - ipFamilyPolicy: RequireDualStack - env: - ISTIO_DUAL_STACK: "true" - namespace: istio-system ----- - -[id="istio-ambient-mode_{context}"] -== Istio Ambient mode (Developer Preview) -:FeatureName: Istio Ambient mode -include::snippets/developer-preview.adoc[] - -Istio Ambient mode provides a sidecarless service mesh architecture that reduces resource overhead, simplifies operations, and allows incremental adoption without application changes. It maintains security and observability through a layered security model with mTLS and authorization. The {SMProduct} 3 Operator includes deploying the Ambient profile as a developer preview feature using the community Ztunnel image. However, the Ambient profile should not be used on clusters with production workloads or for multi-control plane use cases. - -The community Ztunnel image is unavailable on the following platforms: - -* {ibm-power-name} -* {ibm-z-name} -* {ocp-product-title} clusters in `FIPS` mode \ No newline at end of file diff --git a/modules/ossm-release-notes-3-1-1.adoc b/modules/ossm-release-notes-3-1-1.adoc deleted file mode 100644 index 565349313d9..00000000000 --- a/modules/ossm-release-notes-3-1-1.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// 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-1-1_{context}"] -= {SMProductName} version 3.1.1 - -This release of {SMProductName} is included with the {SMProductName} Operator 3.1.1 and is supported on {ocp-product-title} 4.16 and later. This release addresses enhancements, fixed issues, and Common Vulnerabilities and Exposures (CVEs). - -For supported component versions for 3.1.1, see "Service Mesh version support tables". - -[id="ossm-enhancements-3-1-1_{context}"] -== Enhancements - -* This enhancement updates {istio} to version 1.26.3. - -* This enhancement updates Kiali operator to version 2.11.2. - -[id="ossm-bug-fixes-3-1-1_{context}"] -== Fixed issues - -* Before this update, enabling `NetworkPolicy` field globally in the `{istio}` custom resource (CR) failed to create the corresponding `NetworkPolicy` resource due to incorrect resource handling. This issue prevented users from applying network policies when {istio} was enabled globally. With this update, `NetworkPolicy` resource creation is enabled upon `{istio}` CR update, allowing end users to consistently apply network policy rules in {istio}. (link:https://issues.redhat.com/browse/OSSM-10595[OSSM-10595]) - -* Before this update, creating a `PodDisruptionBudget` for a single `istiod` pod with a `minAvailable` value of `1` caused an upgrade to fail, preventing node restart during upgrade. As a consequence, the upgrade was unsuccessful. With this update, the {istio} Operator disables the default `podDisruptionBudget` for the single `istiod` pod in the {istio} 1.24.3 configuration. As a result, the node can now restart during an upgrade without being prevented by the single `istiod` pod. (link:https://issues.redhat.com/browse/OSSM-9392[OSSM-9392]) - - diff --git a/modules/ossm-release-notes-3-1-deprecated-features.adoc b/modules/ossm-release-notes-3-1-deprecated-features.adoc deleted file mode 100644 index 75a2c509aac..00000000000 --- a/modules/ossm-release-notes-3-1-deprecated-features.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// 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-1-deprecated-features_{context}"] -= {SMProductName} version 3.1 deprecated features - -Some features available in previous releases have been deprecated or removed. - -Deprecated functionality is still included in {ocp-product-title} and continues to be supported; however, it will be removed in a future release of {SMProductName} 3 and is not recommended for new deployments. - -Removed functionality no longer exists in the product. - -[id="dns-auto-auto-allocation-proxymetadata_{context}"] -== DNS auto-allocation in ProxyMetadata - -This release removes the use of `ISTIO_META_DNS_AUTO_ALLOCATE` option in the `proxyMetadata` configuration. You can use the DNS auto-allocation label in the `ServiceEntry` resource instead. A future release will remove support for the `ISTIO_META_DNS_AUTO_ALLOCATE` option. - -For more information about using the DNS auto-allocation label in the `ServiceEntry` resource, see the "Address auto-collection" section in the {istio} documentation. \ No newline at end of file diff --git a/modules/ossm-release-notes-3-1-fixed-issues.adoc b/modules/ossm-release-notes-3-1-fixed-issues.adoc deleted file mode 100644 index 6bfbc784b82..00000000000 --- a/modules/ossm-release-notes-3-1-fixed-issues.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// 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-1-fixed-issues_{context}"] -= {SMProductName} version 3.1 fixed issues - -[id="kiali-fixed-issue_{context}"] -== Kiali fixed issue - -* Before this update, the {KialiProduct} used the `k8s_cluster_info` Ansible module from the `kubernetes.core` collection, which caused failures in certain environments during the `Get API version information from the cluster` task. As a result, Kiali deployment failure occurred, affecting service visibility and management. With this update, the {KialiProduct} avoids the `k8s_cluster_info` module, resolving the issue and ensuring smooth Kiali installation for users. (link:https://issues.redhat.com/browse/OSSM-9659[OSSM-9659]) \ No newline at end of file diff --git a/modules/ossm-release-notes-3-1-known-issues.adoc b/modules/ossm-release-notes-3-1-known-issues.adoc deleted file mode 100644 index 74187bc6d52..00000000000 --- a/modules/ossm-release-notes-3-1-known-issues.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// * service-mesh-docs-main/ossm-release-notes.adoc - -:_mod-docs-content-type: REFERENCE -[id="ossm-release-3-1-known-issues_{context}"] -= {SMProductName} 3.1 known issues - -[id="podDisruptionBudget-object-prevents-nodes-from-upgrading_{context}"] -== `podDisruptionBudget` object that prevents nodes from upgrading - -There is currently a known issue that prevents {ocp-product-title} nodes from upgrading. The `podDisruptionBudget` resource prevents the draining of the node where the `istiod` pod is running, unless there are multiple replicas of the `istiod` pod. - -Workaround: Set the `.spec.values.global.defaultPodDisruptionBudget.enabled` field in the {istio} CR to `false`. Alternatively, you can temporarily increase the number of replicas for the `istiod` deployment. link:https://issues.redhat.com/browse/OSSM-9392[OSSM-9392] \ No newline at end of file diff --git a/modules/ossm-release-notes-3-1-new-features-enhancements.adoc b/modules/ossm-release-notes-3-1-new-features-enhancements.adoc deleted file mode 100644 index 39b497dd6c4..00000000000 --- a/modules/ossm-release-notes-3-1-new-features-enhancements.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// 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-1-new-features-enhancements_{context}"] -= {SMProductName} version 3.1 new features and enhancements - -This release makes {SMProductName} 3.1 generally available, adds new features, addresses Common Vulnerabilities and Exposures (CVEs), and is supported on {ocp-product-title} 4.16 and later. - -For a list of supported component versions and support features, see "Service Mesh 3.0 feature support tables". - -When upgrading from {SMProduct} 2.x, first you must migrate to version 3.0. Then, you can upgrade to version 3.1. For more information see, "Migrating from Service Mesh 2 to Service Mesh 3". - -[id="support-for-kubernetes-gateway-api_{context}"] -== Support for Kubernetes Gateway API - -This release introduces support for {k8s} Gateway API custom resource definitions (CRDs). You can now use these CRDs to configure {SMProduct} with the {k8s} Gateway API. This feature is available with {product-title} 4.19. - -[id="support-for-ossm-on-x86-dual-stack-clusters_{context}"] -== Support for OpenShift Service Mesh on x86 dual-stack clusters - -This release introduces support for {SMProduct} on x86 dual-stack clusters. This feature remains a technology preview on all other platforms. - -[id="kubernetes-traffic-distribution-support_{context}"] -== Kubernetes Traffic Distribution Support - -This release introduces support for the {k8s} traffic distribution feature, part of the {k8s} Service API, within {SMProduct}. As of {product-title} 4.19, this is a Beta feature and requires enabling the `ServiceTrafficDistribution` parameter in the {istio} Custom Resources (CRs). - -[id="developer-preview-kubernetes-clustertrustbundle_{context}"] -== Developer Preview for Kubernetes ClusterTrustBundle - -This release introduces developer preview support for the experimental {k8s} `ClusterTrustBundle` feature. This feature provides a new way of distributing X.509 trust anchors (root certificates) to workloads within the cluster. As of {product-title} 4.19, this is an Alpha feature and requires enabling the `ClusterTrustBundle` feature. - -[id="ubi-micro-base-containers_{context}"] -== UBI-micro base containers - -This release updates {SMProduct} to use UBI-micro base containers for most container images. The UBI-micro image is the smallest possible Universal Base Image (UBI), which excludes a package manager and all of its dependencies normally included in a container image. This change minimizes the attack surface of container images that use the UBI-micro base. \ No newline at end of file diff --git a/modules/ossm-release-notes-3-1-technology-preview-features.adoc b/modules/ossm-release-notes-3-1-technology-preview-features.adoc deleted file mode 100644 index b741474cfaa..00000000000 --- a/modules/ossm-release-notes-3-1-technology-preview-features.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// 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-1-technology-preview-features_{context}"] -= {SMProductName} version 3.1 Technology Preview features - -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]. - -[id="istio-ambient-mode-rn_{context}"] -== Istio ambient mode - -This release updates the status of {istio} ambient mode to Technology Preview. {istio} ambient mode provides a sidecar-less alternative data plane to the traditional sidecar-based data plane. By default, ambient mode splits the data plane into node-level L4 ZTunnels and namespace-scoped L7 Waypoint proxies. - -{istio} ambient mode requires {k8s} Gateway API custom resource definitions (CRDs). Use OpenShift Service Mesh 4.19 or later, which includes the CRDs by default. - -To avoid potential conflicts, you must install {istio} ambient mode only on clusters that do not have an existing {SMProductName} installation. {istio} ambient mode is not compatible with clusters that use {SMProductName} 2.6 or earlier. - -When you use {istio} ambient mode, pods that rely on `liveness` or `readiness` probes require you to set the OVN-Kubernetes gateway mode to `local` instead of the default `shared` mode. In local mode, traffic routes through the host and the host processes it using the routing table, ensuring that probes function correctly. For more information, see the "Configuring gateway mode" section in the OVN-Kubernetes documentation. - -To start using {istio} ambient mode, see the "Istio ambient mode" section in the {SMProduct} 3 installation documentation. - -[id="kubernetes-gateway-api-inference-extensions_{context}"] -== Kubernetes Gateway API Inference Extensions - -This release provides technology preview support for {k8s} Gateway API Inference Extensions. These extensions build on Kubernetes Gateway API to provide inference-specific routing capabilities that optimize for self-hosted generative-AI workloads. This implementation was backported to {SMProduct} 3.1 from {istio} 1.27. \ No newline at end of file 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-3-1-2.adoc b/modules/ossm-release-notes-3-X-X.adoc similarity index 50% rename from modules/ossm-release-notes-3-1-2.adoc rename to modules/ossm-release-notes-3-X-X.adoc index c9b2dcc05ac..2c27eeb581f 100644 --- a/modules/ossm-release-notes-3-1-2.adoc +++ b/modules/ossm-release-notes-3-X-X.adoc @@ -3,16 +3,18 @@ // * service-mesh-docs-main/ossm-release-notes/ossm-release-notes.adoc :_mod-docs-content-type: REFERENCE -[id="ossm-release-3-1-2_{context}"] -= {SMProductName} version 3.1.2 +[id="ossm-release-3-X-X_{context}"] += {SMProductName} version 3.X.X -This release of {SMProductName} is included with the {SMProductName} Operator 3.1.2 and is supported on {ocp-product-title} 4.16 and later. This release addresses enhancements, fixed issues, and Common Vulnerabilities and Exposures (CVEs). +[role="_abstract"] -For supported component versions for 3.1.2, see "Service Mesh version support tables". +This release of {SMProductName} is included with the {SMProductName} Operator 3.X.X and is supported on {ocp-product-title} 4.18 and later. This release addresses enhancements, fixed issues, and Common Vulnerabilities and Exposures (CVEs). -[id="ossm-enhancements-3-1-2_{context}"] +For supported component versions for 3.X.X, see "Service Mesh version support tables". + +[id="ossm-enhancements-3-X-X_{context}"] == Enhancements -* This enhancement updates {istio} to version 1.26.4. -* This enhancement updates Kiali operator and Kiali server to version 2.11.3. \ No newline at end of file +[id="ossm-bug-fixes-3-X-X_{context}"] +== Fixed issues \ No newline at end of file diff --git a/modules/ossm-release-notes-3-X-deprecated-features.adoc b/modules/ossm-release-notes-3-X-deprecated-features.adoc new file mode 100644 index 00000000000..5914ac1455e --- /dev/null +++ b/modules/ossm-release-notes-3-X-deprecated-features.adoc @@ -0,0 +1,15 @@ +// 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-deprecated-features_{context}"] += {SMProductName} version 3.X deprecated features + +[role="_abstract"] + +Some features available in previous releases have been deprecated or removed. + +Deprecated functionality is still included in {ocp-product-title} and continues to be supported; however, it will be removed in a future release of {SMProductName} 3 and is not recommended for new deployments. + +Removed functionality no longer exists in the product. \ No newline at end of file diff --git a/modules/ossm-release-notes-3-X-fixed-issues.adoc b/modules/ossm-release-notes-3-X-fixed-issues.adoc new file mode 100644 index 00000000000..8e5ae751998 --- /dev/null +++ b/modules/ossm-release-notes-3-X-fixed-issues.adoc @@ -0,0 +1,11 @@ +// 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.X fixed issues + +[role="_abstract"] + +This release addresses the following fixed issues: \ No newline at end of file diff --git a/modules/ossm-release-notes-3-X-known-issues.adoc b/modules/ossm-release-notes-3-X-known-issues.adoc new file mode 100644 index 00000000000..d501e621be7 --- /dev/null +++ b/modules/ossm-release-notes-3-X-known-issues.adoc @@ -0,0 +1,12 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/ossm-release-notes.adoc + +:_mod-docs-content-type: REFERENCE +[id="ossm-release-3-X-known-issues_{context}"] += {SMProductName} 3.X known issues + + +[role="_abstract"] + +This release has the following known issues: \ No newline at end of file diff --git a/modules/ossm-release-notes-3-X-new-features-enhancements.adoc b/modules/ossm-release-notes-3-X-new-features-enhancements.adoc new file mode 100644 index 00000000000..a69988c88f9 --- /dev/null +++ b/modules/ossm-release-notes-3-X-new-features-enhancements.adoc @@ -0,0 +1,15 @@ +// 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-new-features-enhancements_{context}"] += {SMProductName} version 3.X new features and enhancements + +[role="_abstract"] + +This release makes {SMProductName} 3.X generally available, adds new features, addresses Common Vulnerabilities and Exposures (CVEs), and is supported on {ocp-product-title} 4.18 and later. + +For a list of supported component versions and support features, see "Service Mesh feature support tables". + +When upgrading from {SMProduct} 2.x, first you must migrate to version 3.0. Then, you can upgrade to version 3.1. For more information see, "Migrating from Service Mesh 2 to Service Mesh 3". \ No newline at end of file diff --git a/modules/ossm-release-notes-3-X-technology-preview-features.adoc b/modules/ossm-release-notes-3-X-technology-preview-features.adoc new file mode 100644 index 00000000000..52ceea005b0 --- /dev/null +++ b/modules/ossm-release-notes-3-X-technology-preview-features.adoc @@ -0,0 +1,13 @@ +// 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-technology-preview-features_{context}"] += {SMProductName} version 3.X 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]. \ No newline at end of file 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-release-notes-consoles-and-dashboards.adoc b/modules/ossm-release-notes-consoles-and-dashboards.adoc index 9de11226cf6..afa35e5fe5a 100644 --- a/modules/ossm-release-notes-consoles-and-dashboards.adoc +++ b/modules/ossm-release-notes-consoles-and-dashboards.adoc @@ -1,7 +1,6 @@ -//// -Module included in the following assemblies: -* service-mesh-docs-main/ossm-release-notes-support-tables.adoc -//// +// Module included in the following assemblies: +// +// * service-mesh-docs-main/ossm-release-notes-support-tables.adoc :_mod-docs-content-type: REFERENCE [id="consoles-and-dashboards_{context}"] diff --git a/modules/ossm-release-notes-definitions.adoc b/modules/ossm-release-notes-definitions.adoc index 06a77afe941..14481d81202 100644 --- a/modules/ossm-release-notes-definitions.adoc +++ b/modules/ossm-release-notes-definitions.adoc @@ -2,7 +2,7 @@ // // service-mesh-docs-main/ossm-release-notes-support-tables.adoc -:_mod-docs-content-type: CONCEPT +:_mod-docs-content-type: REFERENCE [id="release-notes-definitions_{context}"] = Release notes definitions diff --git a/modules/ossm-release-notes-extensibility-features.adoc b/modules/ossm-release-notes-extensibility-features.adoc index 43d8ac8182d..161dde2f343 100644 --- a/modules/ossm-release-notes-extensibility-features.adoc +++ b/modules/ossm-release-notes-extensibility-features.adoc @@ -1,7 +1,6 @@ -//// -Module included in the following assemblies: -* service-mesh-docs-main/ossm-release-notes-support-tables.adoc -//// +// Module included in the following assemblies: +// +// * service-mesh-docs-main/ossm-release-notes-support-tables.adoc :_mod-docs-content-type: REFERENCE [id="extensibility-features_{context}"] diff --git a/modules/ossm-release-notes-istio-ambient-mode.adoc b/modules/ossm-release-notes-istio-ambient-mode.adoc index 5a6ca06d43b..194b52be422 100644 --- a/modules/ossm-release-notes-istio-ambient-mode.adoc +++ b/modules/ossm-release-notes-istio-ambient-mode.adoc @@ -1,7 +1,6 @@ -//// -Module included in the following assemblies: -* service-mesh-docs-main/ossm-release-notes-support-tables.adoc -//// +// Module included in the following assemblies: +// +// * service-mesh-docs-main/ossm-release-notes-support-tables.adoc :_mod-docs-content-type: REFERENCE [id="istio-ambient-mode_{context}"] @@ -56,7 +55,7 @@ Module included in the following assemblies: | NA | Multi-Cluster - Multi-primary topology -| DP +| TP | Multi-Cluster - Other topologies | NA diff --git a/modules/ossm-release-notes-istio-deployment-lifecycle.adoc b/modules/ossm-release-notes-istio-deployment-lifecycle.adoc index 16e83c668a7..a4b6d5d2334 100644 --- a/modules/ossm-release-notes-istio-deployment-lifecycle.adoc +++ b/modules/ossm-release-notes-istio-deployment-lifecycle.adoc @@ -1,7 +1,7 @@ -//// -Module included in the following assemblies: -* service-mesh-docs-main/ossm-release-notes-support-tables.adoc -//// +// Module included in the following assemblies: +// +// * service-mesh-docs-main/ossm-release-notes-support-tables.adoc + :_mod-docs-content-type: REFERENCE [id="istio-deployment-and-lifecycle_{context}"] @@ -41,7 +41,7 @@ Module included in the following assemblies: | GA ^[4]^ | Virtual machine (non-OpenShift) workload integration -| NA +| DP | Istioctl for select commands | GA ^[1]^ @@ -51,9 +51,14 @@ Module included in the following assemblies: | ProxyConfig | GA ^[3]^ + +|Native `nftables` support +|GA ^[5]^ + |=== . For more information, see "Support for Istioctl". . Installation is only supported by using the {SMProduct} 3 Operator, which uses the Istio Helm chart values for managing configuration. . The `ProxyConfig` API is supported with the exception of the image field, which is not supported. -. Dual-Stack IPv4/IPv6 is supported on x86 environments only. On non-x86 environments, this feature remains a Technology Preview. \ No newline at end of file +. Dual-Stack IPv4/IPv6 is supported on x86 environments only. On non-x86 environments, this feature remains a Technology Preview. +. To deploy {SMProduct} on nodes running {op-system-base-full} 10 or {op-system-first} 10, you must enable native `nftables` support. In the {istio} resource, set the `spec.values.global.nativeNftables` parameter to `true`. \ No newline at end of file diff --git a/modules/ossm-release-notes-istio-traffic-management.adoc b/modules/ossm-release-notes-istio-traffic-management.adoc index 7ed7c2e0053..baf12f93294 100644 --- a/modules/ossm-release-notes-istio-traffic-management.adoc +++ b/modules/ossm-release-notes-istio-traffic-management.adoc @@ -1,9 +1,6 @@ -//// -Module included in the following assemblies: -* service-mesh-docs-main/ossm-release-notes-support-tables.adoc -//// - -//Post GA: might be worth considering putting tables into their own modules. Might easier to maintain. Warrants further discussion post GA. +// Module included in the following assemblies: +// +// * service-mesh-docs-main/ossm-release-notes-support-tables.adoc :_mod-docs-content-type: REFERENCE [id="istio-traffic-management_{context}"] diff --git a/modules/ossm-release-notes-kubernetes-gateway-api.adoc b/modules/ossm-release-notes-kubernetes-gateway-api.adoc index c629915a709..cef5614d68e 100644 --- a/modules/ossm-release-notes-kubernetes-gateway-api.adoc +++ b/modules/ossm-release-notes-kubernetes-gateway-api.adoc @@ -1,7 +1,6 @@ -//// -Module included in the following assemblies: -* service-mesh-docs-main/ossm-release-notes-support-tables.adoc -//// +// Module included in the following assemblies: +// +// * service-mesh-docs-main/ossm-release-notes-support-tables.adoc :_mod-docs-content-type: REFERENCE [id="kubernetes-gateway-api_{context}"] diff --git a/modules/ossm-release-notes-observability-features.adoc b/modules/ossm-release-notes-observability-features.adoc index 8fe9d115de2..323ed654c90 100644 --- a/modules/ossm-release-notes-observability-features.adoc +++ b/modules/ossm-release-notes-observability-features.adoc @@ -1,7 +1,6 @@ -//// -Module included in the following assemblies: -* service-mesh-docs-main/ossm-release-notes-support-tables.adoc -//// +// Module included in the following assemblies: +// +// * service-mesh-docs-main/ossm-release-notes-support-tables.adoc :_mod-docs-content-type: REFERENCE [id="observability-features_{context}"] diff --git a/modules/ossm-release-notes-sail-operator-apis.adoc b/modules/ossm-release-notes-sail-operator-apis.adoc index e1c82a99345..2dedf14102a 100644 --- a/modules/ossm-release-notes-sail-operator-apis.adoc +++ b/modules/ossm-release-notes-sail-operator-apis.adoc @@ -1,9 +1,6 @@ -//// -Module included in the following assemblies: -* service-mesh-docs-main/ossm-release-notes-support-tables.adoc -//// - -//Post GA: might be worth considering putting tables into their own modules. Might easier to maintain. Warrants further discussion post GA. +// Module included in the following assemblies: +// +// * service-mesh-docs-main/ossm-release-notes-support-tables.adoc :_mod-docs-content-type: REFERENCE [id="sail-operator-apis_{context}"] @@ -28,5 +25,5 @@ Module included in the following assemblies: | GA | ZTunnel -| TP +| GA |=== \ No newline at end of file diff --git a/modules/ossm-release-notes-security-features.adoc b/modules/ossm-release-notes-security-features.adoc index f7acc6fe5c2..21c87d9c679 100644 --- a/modules/ossm-release-notes-security-features.adoc +++ b/modules/ossm-release-notes-security-features.adoc @@ -1,7 +1,6 @@ -//// -Module included in the following assemblies: -* service-mesh-docs-main/ossm-release-notes-support-tables.adoc -//// +// Module included in the following assemblies: +// +// * service-mesh-docs-main/ossm-release-notes-support-tables.adoc :_mod-docs-content-type: REFERENCE [id="security-features_{context}"] diff --git a/modules/ossm-release-notes-supported-versions.adoc b/modules/ossm-release-notes-supported-versions.adoc index 99e590c92b7..d4b25428c4d 100644 --- a/modules/ossm-release-notes-supported-versions.adoc +++ b/modules/ossm-release-notes-supported-versions.adoc @@ -8,193 +8,33 @@ [role="_abstract"] -See the following table for information about {SMProduct} 3.1.2 supported versions. +See the following table for information about {SMProduct} 3.X supported versions. -== {SMProduct} 3.1.2 supported versions +== {SMProduct} 3.X.X supported versions [cols="1,1"] |=== | Feature | Supported versions |{SMProduct} 3 Operator -|3.1.2 +|3.X.X |{SMProduct} `Istio` control plane resource -|1.26.4 +|1.2X.X |{ocp-product-title} -|4.16 and later +|4.18 and later | Envoy proxy -| 1.34.6 +| 1.3X.X | `IstioCNI` resource -| 1.26.4 +| 1.2X.X |Kiali Operator -|2.11.3 +|2.XX.X |Kiali control plane resource -|2.11.3 +|2.XX.X -|=== - -See the following table for information about {SMProduct} 3.1.1 supported versions. - -== {SMProduct} 3.1.1 supported versions - -[cols="1,1"] -|=== -| Feature | Supported versions - -|{SMProduct} 3 Operator -|3.1.1 - -|{SMProduct} `Istio` control plane resource -|1.26.3 - -|{ocp-product-title} -|4.16 and later - -| Envoy proxy -| 1.34.3 - -| `IstioCNI` resource -| 1.26.3 - -|Kiali Operator -|2.11.2 - -|=== - -See the following table for information about {SMProduct} 3.1.0 supported versions. - -== {SMProduct} 3.1.0 supported versions - -[cols="1,1"] -|=== -| Feature | Supported versions - -|{SMProduct} 3 Operator -|3.1.0 - -|{SMProduct} `Istio` control plane resource -|1.26.2 - -|{ocp-product-title} -|4.16 and later - -| Envoy proxy -| 1.34.2 - -| `IstioCNI` resource -| 1.26.2 - -|Kiali Operator -|2.11.1 - -|=== - -See the following table for information about {SMProduct} 3.0.3 supported versions. - -== {SMProduct} 3.0.3 supported versions - -[cols="1,1"] -|=== -| Feature | Supported versions - -|{SMProduct} 3 Operator -|3.0.3 - -|{SMProduct} `Istio` control plane resource -|1.24.6 - -|{ocp-product-title} -|4.14 and later - -| Envoy proxy -| 1.32.6 - -| `IstioCNI` resource -| 1.24.6 ^[1]^ - -|Kiali Operator -|2.4.7 - -|=== - -. The `Istio` control plane and `IstioCNI` resources can be upgraded in any order, as long as their version difference is within one minor version. - -See the following table for information about {SMProduct} 3.0.2 supported versions. - -== {SMProduct} 3.0.2 supported versions - -[cols="1,1"] -|=== -| Feature | Supported versions - -|{SMProduct} 3 Operator -|3.0.2 - -|{SMProduct} `Istio` control plane resource -|1.24.5 - -|{ocp-product-title} -|4.14 and later - -| Envoy proxy -| 1.32.6 - -| `IstioCNI` resource -| 1.24.5 ^[1]^ -|=== - -See the following table for information about {SMProduct} 3.0.1 supported versions. - -== {SMProduct} 3.0.1 supported versions - -[cols="1,1"] -|=== -| Feature | Supported versions - -|{SMProduct} 3 Operator -|3.0.1 - -|{SMProduct} `Istio` control plane resource -|1.24.4 - -|{ocp-product-title} -|4.14 and later - -| Envoy proxy -| 1.32.4 - -| `IstioCNI` resource -| 1.24.4 ^[1]^ -|=== - -See the following table for information about {SMProduct} 3.0.0 supported versions. - -== {SMProduct} 3.0.0 supported versions - -[cols="1,1"] -|=== -| Feature | Supported versions - -|{SMProduct} 3 Operator -|3.0.0 - -|{SMProduct} `Istio` control plane resource -|1.24.3 - -|{ocp-product-title} -|4.14 and later - -| Envoy proxy -| 1.32.4 - -| `IstioCNI` resource -| 1.24.3 ^[1]^ -|=== - -//note to self for post GA: might be worth having Envoy proxy and IstioCNI attributes. \ No newline at end of file +|=== \ No newline at end of file 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 a65a780c873..cdc17b52723 100644 --- a/modules/ossm-removing-multi-cluster-installation-from-development-environment.adoc +++ b/modules/ossm-removing-multi-cluster-installation-from-development-environment.adoc @@ -1,9 +1,10 @@ // This procedure is used in the following assembly: +// // * install/ossm-multi-cluster-topologies.adoc :_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"] @@ -27,9 +28,25 @@ In this procedure, `CLUSTER1` is the East cluster and `CLUSTER2` is the West clu $ oc --context="${CTX_CLUSTER1}" delete istio/default ns/istio-system ns/sample ns/istio-cni ---- -. Remove {istio} and the sample applications from the West cluster of development environment by running the following command: +. Remove {istio} and the sample applications from the West cluster of the development environment by running the following command: + [source,terminal] ---- $ oc --context="${CTX_CLUSTER2}" delete istio/default ns/istio-system ns/sample ns/istio-cni +---- + +. If you used {SMProductShortName} in ambient mode, remove the ztunnel resources: + +.. Remove the resources from the East cluster with the following command: ++ +[source,terminal] +---- +$ oc --context="${CTX_CLUSTER1}" delete ns/ztunnel +---- + +.. Remove them from the West cluster with the following command: ++ +[source,terminal] +---- +$ oc --context="${CTX_CLUSTER2}" delete ns/ztunnel ---- \ No newline at end of file diff --git a/modules/ossm-routing-traffic-using-virtualservice.adoc b/modules/ossm-routing-traffic-using-virtualservice.adoc new file mode 100644 index 00000000000..b6404381271 --- /dev/null +++ b/modules/ossm-routing-traffic-using-virtualservice.adoc @@ -0,0 +1,89 @@ +// Module included in the following assemblies: +// +// * TBD + +:_mod-docs-content-type: PROCEDURE +[id="ossm-routing-traffic-using-virtualservice_{context}"] += Route traffic in a sidecar mesh + +[role="_abstract"] + +You can use a `VirtualService` and `DestinationRule` to split traffic between different versions of the Bookinfo `reviews` service for feature testing or A/B testing. + +.Prerequisites + +* You have deployed {istio} in sidecar mode. +* You have deployed the Bookinfo application with sidecar injection enabled. + +.Procedure + +. Create a `DestinationRule` to define the available versions of the `reviews` service. Create a file named `reviews-destination-rule.yaml` similar to the following example: ++ +[source,yaml] +---- +apiVersion: networking.istio.io/v1 +kind: DestinationRule +metadata: + name: reviews + namespace: bookinfo +spec: + host: reviews + subsets: + - name: v1 + labels: + version: v1 + - name: v2 + labels: + version: v2 +---- + +. Apply the `DestinationRule` by running the following command: ++ +[source,terminal] +---- +$ oc apply -f reviews-destination-rule.yaml +---- + +. Create a `VirtualService` to split traffic between versions. Create a file named `reviews-virtual-service.yaml` similar to the following example: ++ +[source,yaml] +---- +apiVersion: networking.istio.io/v1 +kind: VirtualService +metadata: + name: reviews + namespace: bookinfo +spec: + hosts: + - reviews + http: + - route: + - destination: + host: reviews + subset: v1 + weight: 90 + - destination: + host: reviews + subset: v2 + weight: 10 +---- + +. Apply the `VirtualService` by running the following command: ++ +[source,terminal] +---- +$ oc apply -f reviews-virtual-service.yaml +---- + +.Verification + +* Access the `productpage` service from within the ratings pod by running the following command: ++ +[source,terminal] +---- +$ oc exec "$(oc get pod -l app=ratings -n bookinfo \ +-o jsonpath='{.items[0].metadata.name}')" -c ratings -n bookinfo \ +-- curl -sS productpage:9080/productpage | grep -om1 'reviews-v[12]' +---- ++ +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 6ae801219ef..1c6dcf81b43 100644 --- a/modules/ossm-routing-traffic-using-waypoint-proxies.adoc +++ b/modules/ossm-routing-traffic-using-waypoint-proxies.adoc @@ -1,10 +1,10 @@ // Module included in the following assemblies: - +// // * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc :_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"] @@ -14,7 +14,8 @@ You can use a deployed waypoint proxy to split traffic between different version . Create the traffic routing configuration similar to the following example: + -.Example configuration +You can see the following example configuration for reference: ++ [source,yaml] ---- apiVersion: gateway.networking.k8s.io/v1 @@ -56,4 +57,4 @@ $ oc exec "$(oc get pod -l app=ratings -n bookinfo \ -- curl -sS productpage:9080/productpage | grep -om1 'reviews-v[12]' ---- + -Most responses (90%) will contain `reviews-v1` output, while a smaller portion (10%) will contain `reviews-v2` output. \ No newline at end of file +Most responses (90%) will contain `reviews-v1` output, while a smaller part (10%) will contain `reviews-v2` output. \ No newline at end of file diff --git a/modules/ossm-scoping-service-mesh-with-discoveryselectors.adoc b/modules/ossm-scoping-service-mesh-with-discoveryselectors.adoc index 974de294ac5..e976e8261b6 100644 --- a/modules/ossm-scoping-service-mesh-with-discoveryselectors.adoc +++ b/modules/ossm-scoping-service-mesh-with-discoveryselectors.adoc @@ -1,20 +1,13 @@ // Module included in the following assemblies: +// // install/ossm-installing-openshift-service-mesh.adoc :_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 multiple 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. \ No newline at end of file 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 816fab86f01..125dba9e08b 100644 --- a/modules/ossm-scoping-sm-discovery-selectors-istio-ambient-mode.adoc +++ b/modules/ossm-scoping-sm-discovery-selectors-istio-ambient-mode.adoc @@ -1,10 +1,10 @@ // Module included in the following assemblies: - +// // * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc :_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"] @@ -13,8 +13,11 @@ To limit the scope of the {SMProduct} in {istio} ambient mode, you can configure .Prerequisites * You have deployed a cluster on {ocp-product-title} 4.19 or later. + * You have created an `Istio` control plane resource. + * You have created an `IstioCNI` resource. + * You have created a `Ztunnel` resource. .Procedure @@ -40,11 +43,12 @@ $ oc label namespace istio-cni istio-discovery=enabled $ oc label namespace ztunnel istio-discovery=enabled ---- -. Modify the `{istio}` control plane resource to include a `discoverySelectors` section with the same label: +. Change the `{istio}` control plane resource to include a `discoverySelectors` section with the same label: .. Create a YAML file with the name `istio-discovery-selectors.yaml` similar to the following example: + -.Example configuration +You can see the following example configuration for reference: ++ [source,yaml] ---- apiVersion: sailoperator.io/v1 diff --git a/modules/ossm-selecting-inplace-strategy.adoc b/modules/ossm-selecting-inplace-strategy.adoc index c26ed1184c0..4f9e511f6cd 100644 --- a/modules/ossm-selecting-inplace-strategy.adoc +++ b/modules/ossm-selecting-inplace-strategy.adoc @@ -1,15 +1,17 @@ // Module included in the following assemblies: +// // update/ossm-updating-openshift-service-mesh.adoc :_mod-docs-content-type: CONCEPT [id="selecting-inplace-strategy_{context}"] -= Selecting InPlace strategy += When to use the InPlace strategy [role="_abstract"] To select the `InPlace` strategy, set the `spec.updateStrategy.type` value in the {istio} resource to `InPlace`. -.Example specification to select InPlace update strategy +You can see the following example configuration for reference: + [source,yaml, subs="attributes,verbatim"] ---- kind: Istio @@ -20,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 29f12d2392b..fe6dbd93e01 100644 --- a/modules/ossm-selecting-revisionbased-strategy.adoc +++ b/modules/ossm-selecting-revisionbased-strategy.adoc @@ -1,15 +1,17 @@ // Module included in the following assemblies: +// // update/ossm-updating-openshift-service-mesh.adoc :_mod-docs-content-type: CONCEPT [id="selecting-revision-based-strategy_{context}"] -= Selecting RevisionBased strategy += When to use the RevisionBased strategy [role="_abstract"] To deploy {istio} with the `RevisionBased` strategy, create the `{istio}` resource with the following `spec.updateStrategy` value: -.Example specification to select `RevisionBased` strategy +You can see the following example configuration for reference: + [source,yaml, subs="attributes,verbatim"] ---- kind: Istio diff --git a/modules/ossm-service-mesh-deployment-resources.adoc b/modules/ossm-service-mesh-deployment-resources.adoc new file mode 100644 index 00000000000..5277c43aafc --- /dev/null +++ b/modules/ossm-service-mesh-deployment-resources.adoc @@ -0,0 +1,135 @@ +// Module included in the following assemblies: +// +// install/ossm-installing-openshift-service-mesh.adoc + +:_mod-docs-content-type: CONCEPT +[id="ossm-service-mesh-deployment-resources_{context}"] += Custom resources overview + +[role="_abstract"] + +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] +==== +Ambient mode deployments also require a `ZTunnel` resource. For more information, see "Installing {istio} ambient mode". +==== + +The following sections provide an overview of each resource. For deployment steps, see the sidecar mode or ambient mode installation procedures. + +== The {istio} resource + +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. + +[NOTE] +==== +The `spec.namespace` field is immutable: to move a control plane to another namespace, you must remove the `{istio}` resource and re-create it with a different `spec.namespace`. +==== + +You can access all `{istio}` CRD options through `spec.values` fields similar to the following example: + +[source,yaml] +---- +apiVersion: sailoperator.io/v1 +kind: Istio +metadata: + name: default +spec: + version: v1.22.3 + namespace: istio-system + updateStrategy: + type: InPlace + values: + pilot: + resources: + requests: + cpu: 100m + memory: 1024Mi +---- + +You can run the following command to see all the customization options: + +[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. + +== The IstioCNI resource + +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: + +[source,yaml] +---- +apiVersion: sailoperator.io/v1 +kind: IstioCNI +metadata: + name: default +spec: + version: v1.22.3 + namespace: istio-cni + values: + cni: + cniConfDir: /etc/cni/net.d + excludeNamespaces: + - kube-system +---- + +You can run the following command to see all the customization options: + +[source, terminal] +---- +$ oc explain istiocnis.spec.values +---- + +== 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. + +Each `IstioRevision` represents an instance of {istio} with a specific version and revision name. The naming depends on the `spec.updateStrategy.type` setting in the `{istio}` resource: + +* `InPlace`: The revision shares the `{istio}` resource name. +* `RevisionBased`: The revision name follows the format `-v`. + +During a `RevisionBased` upgrade, multiple `IstioRevision` resources can exist, each representing a distinct control plane instance. + +To see available revisions, run the following command: + +[source, terminal] +---- +$ oc get istiorevisions +---- + +== 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. + +The `IstioRevisionTag` has one field in its `spec:` field, `targetRef`, which can reference an `{istio}` or `IstioRevision` resource: + +[source,yaml] +---- +apiVersion: sailoperator.io/v1 +kind: IstioRevisionTag +metadata: + name: default +spec: + targetRef: + kind: Istio + name: prod +---- + +`spec.targetRef.kind`:: The kind of resource the tag references. The value can be either `{istio}` or `IstioRevision`. + +`spec.targetRef.name`:: The name of the resource the tag references. + +When using an `{istio}` resource as the target, the Operator automatically updates the revision tag when the underlying `IstioRevision` changes during a control plane update. + +[IMPORTANT] +==== +You can only use the `istio-injection` label for revisions and revision tags that have the name `default`. +==== diff --git a/modules/ossm-service-mesh-overview.adoc b/modules/ossm-service-mesh-overview.adoc index 330fd79b9eb..ea5b04595b6 100644 --- a/modules/ossm-service-mesh-overview.adoc +++ b/modules/ossm-service-mesh-overview.adoc @@ -1,7 +1,6 @@ -//// -Module included in the following assemblies: -* about/ossm-about-openshift-service-mesh.adoc -//// +// Module included in the following assemblies: +// +//* about/ossm-about-openshift-service-mesh.adoc :_mod-docs-content-type: CONCEPT [id="ossm-servicemesh-overview_{context}"] @@ -9,6 +8,27 @@ Module included in the following assemblies: [role="_abstract"] -{SMProductName} adds a transparent layer on existing distributed applications without requiring any changes to the application code. The mesh introduces an easy way to create a network of deployed services that provides discovery, load balancing, service-to-service authentication, failure recovery, metrics, and monitoring. A service mesh also provides more complex operational functionality, including A/B testing, canary releases, access control, and end-to-end authentication. +{SMProductName} is a service mesh based on the {istio} project. It adds a transparent layer on existing distributed applications without requiring any changes to the application code. -Microservice architectures split the work of enterprise applications into modular services, which can make scaling and maintenance easier. However, as an enterprise application built on a microservice architecture grows in size and complexity, it becomes difficult to understand and manage. {SMProductShortName} can address those architecture problems by capturing or intercepting traffic between services and can modify, redirect, or create new requests to other services. \ No newline at end of file +The mesh creates a network of your deployed services and manages how they discover and communicate with each other. It adds capabilities such as secure connectivity, traffic management, and observability without changes to your services. {SMProductShortName} works by intercepting the traffic between services, where it can redirect, modify, or create requests to other services. + +[id="ossm-core-features2_{context}"] +== Core features + +{SMProductShortName} provides several key capabilities uniformly across a network of services: + +* *Zero-trust security* - Automatically encrypt and authenticate all service-to-service communication with mutual TLS (mTLS). Every service receives a cryptographic identity, and authorization policies control which services can communicate with each other. You can also integrate external security solutions to extend the zero-trust model with enterprise certificate management and attested workload identity. +* *Traffic management* - Control the flow of traffic and API calls between services, make calls more reliable, and make the network more robust in the face of adverse conditions. +* *Policy enforcement* - Apply organizational policies to service interactions without changing application code. The mesh enforces access controls and distributes resources fairly among consumers. +* *Telemetry* - See how services depend on each other, monitor traffic flow, and identify issues quickly with automatically generated metrics and distributed tracing. + +[id="ossm-based-on-istio_{context}"] +== Based on the {istio} project + +{istio} is a widely adopted open source service mesh project that provides the core mesh functionality. {SMProductShortName} builds on {istio} by adding enterprise features, hardening, and integration with {ocp-product-title}. + +Building on {istio} means that you get the following benefits: + +* A mesh implementation that is based on a mature, community-driven project and open standards. +* Additional components and tools that Red Hat tests, packages, and supports. +* Lifecycle management through Operators, along with integration with the {ocp-product-title} monitoring stack, web console, and security infrastructure. \ No newline at end of file diff --git a/modules/ossm-setup-observability-console.adoc b/modules/ossm-setup-observability-console.adoc new file mode 100644 index 00000000000..b48998b57c6 --- /dev/null +++ b/modules/ossm-setup-observability-console.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-setup-observability-console_{context}"] += Set up a mesh observability console + +[role="_abstract"] + +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. + +[NOTE] +==== +Kiali requires {ocp-short-name} monitoring integration for metrics collection. +==== diff --git a/modules/ossm-sidecar-ambient-deployment-modes-comparison.adoc b/modules/ossm-sidecar-ambient-deployment-modes-comparison.adoc new file mode 100644 index 00000000000..6db7ca0df1c --- /dev/null +++ b/modules/ossm-sidecar-ambient-deployment-modes-comparison.adoc @@ -0,0 +1,74 @@ +// Module included in the following assemblies: +// +// + +:_mod-docs-content-type: CONCEPT +[id="ossm-sidecar-ambient-deployment-modes_{context}"] += Comparison of sidecar and ambient deployment modes + +[role="_abstract"] + +{SMProductName} 3 supports two data plane architectures: sidecar mode and ambient mode. Choose the deployment model that best aligns with your workload performance, security isolation, and resource constraints. + +[NOTE] +==== +Sidecar and ambient modes can coexist in the same mesh. +==== + +[id="ossm-sidecar-mode-per-pod-proxies_{context}"] +== Sidecar mode, which uses per-pod proxies + +In sidecar mode, {SMProductName} injects an Envoy proxy container directly into each application pod. All network traffic entering or leaving the pod passes through its local Envoy sidecar proxy. + +* The sidecar proxy enforces both network transport security (mTLS) and application protocol rules (HTTP, gRPC) locally inside the pod. +* Security boundaries match pod boundaries and prevent noisy-neighbor proxy performance issues. +* Sidecar mode is best used for environments requiring strict pod-level security isolation, complex legacy configurations, or workloads relying only on classic {istio} APIs (`VirtualService`, `DestinationRule`). + +[id="ossm-ambient-mode-sidecarless_{context}"] +== Ambient mode, which is sidecarless + +In ambient mode, application pods run without injected proxy sidecars. Instead, ambient mode splits networking responsibilities into two separate operational layers: + +. *Layer 4 Secure Transport (`ztunnel`):* A shared, high-performance node agent (`ztunnel`) handles zero-trust mutual TLS, workload identity, and L4 transport encryption for all pods on the node. +. *Layer 7 Policy Enforcement (`waypoint proxy`):* An optional, dedicated Envoy-based proxy deployed per-namespace or per-service that handles HTTP routing, header manipulation, L7 authorization, and telemetry. + +Some benefits of ambient mode include the following: + +* *Zero application restarts.* Add applications to the mesh by labeling the namespace; no pod restarts or sidecar container injection required. +* *Lower resource consumption.* Eliminates the memory and CPU reserved for idle sidecar proxies in large deployments. + +Ambient mode is best used for standard microservice workloads, environments with high pod density, applications where container injection causes operational friction, or modern deployments that use the Kubernetes Gateway API. + +[id="ossm-data-plane-decision-matrix_{context}"] +== Data plane decision matrix + +[cols="1,1,1", options="header"] +|=== +| Capability and requirements +| Sidecar mode +| Ambient mode + +| *Application Onboarding* +| Requires sidecar container injection and pod restarts +| Uses namespace label application with zero pod restarts + +| *Proxy Deployment Scope* +| Needs a dedicated proxy per pod +| Uses a shared L4 node agent (`ztunnel`) and an optional per-service L7 proxy (`waypoint`) + +| *Resource Footprint* +| Needs more CPU and memory reserved per pod +| Needs lower CPU and memory + +| *Security Isolation Boundary* +| Uses pod-level proxy boundary +| Uses a node-level L4 boundary, as well as namespace and service L7 boundaries + +| *Primary Configuration API* +| Uses {istio} classic APIs or Gateway API +| Primarily uses Kubernetes Gateway API + +| *L7 Processing Default* +| Is enabled for all sidecar-injected workloads +| Enabled only when a waypoint proxy is deployed +|=== diff --git a/modules/ossm-support-for-istioctl.adoc b/modules/ossm-support-for-istioctl.adoc index cca753fef11..d7d7567b340 100644 --- a/modules/ossm-support-for-istioctl.adoc +++ b/modules/ossm-support-for-istioctl.adoc @@ -4,13 +4,14 @@ :_mod-docs-content-type: REFERENCE [id="ossm-support-for-istioctl_{context}"] -= Support for Istioctl += Supported Istioctl commands [role="_abstract"] {SMProduct} 3 supports a selection of Istioctl commands. -.Supported Istioctl commands +Supported Istioctl commands:: + [cols="1,1"] |=== |Command |Description @@ -20,12 +21,16 @@ |`completion` | Generate the autocompletion script for the specified shell |`create-remote-secret` | Create a secret with credentials to allow {istio} to access remote Kubernetes API servers |`help` | Display help about any command -|`proxy-config`, `pc` | Retrieve information about the proxy configuration from Envoy (Kubernetes only) +|`proxy-config`, `pc` | Retrieve information about the proxy configuration from Envoy ({k8s} only) |`proxy-status`, `ps` | Retrieve the synchronization status of each Envoy in the mesh -|`remote-clusters` | List the remote clusters each `istiod` instance is connected to +|`remote-clusters` | List the remote clusters each `istiod` instance connects to |`validate`, `v` | Validate the {istio} policy and rules files -|`version` | Print out the build version information +|`version` | Print the build version information |`waypoint` | Manage the waypoint configuration |`ztunnel-config` | Update or retrieve the current Ztunnel configuration. |=== +[NOTE] +==== +Any other commands display the _WARNING: Not supported in OpenShift Service Mesh context_ message. Do not use these commands in production environments. +==== \ No newline at end of file diff --git a/modules/ossm-supported-configurations-kiali.adoc b/modules/ossm-supported-configurations-kiali.adoc index 9628b0e4bc9..c6cfb705ca5 100644 --- a/modules/ossm-supported-configurations-kiali.adoc +++ b/modules/ossm-supported-configurations-kiali.adoc @@ -4,9 +4,12 @@ :_mod-docs-content-type: REFERENCE [id="ossm-supported-configurations-kiali_{context}"] -== Supported configurations for Kiali += Supported configurations for Kiali [role="_abstract"] +Access the Kiali console through supported web browsers by using the mandatory {ocp-short-name} authentication strategy, which leverages cluster role-based access control (RBAC) to manage user permissions. + * The Kiali console is supported on Google Chrome, Microsoft Edge, Mozilla Firefox, or Apple Safari browsers. -* The `openshift` authentication strategy is the only supported authentication configuration when Kiali is deployed with {SMProductName} (OSSM). The `openshift` strategy controls access based on the user's role-based access control (RBAC) roles of the {ocp-product-title}. \ No newline at end of file + +* {SMProductName} (OSSM) supports only the `openshift` authentication strategy when you deploy Kiali. The `openshift` strategy controls access based on the user's role-based access control (RBAC) roles of the {ocp-product-title}. \ No newline at end of file diff --git a/modules/ossm-supported-configurations-networks.adoc b/modules/ossm-supported-configurations-networks.adoc index 34b8c2ead90..a2004bcbaf4 100644 --- a/modules/ossm-supported-configurations-networks.adoc +++ b/modules/ossm-supported-configurations-networks.adoc @@ -11,5 +11,7 @@ You can use the following OpenShift networking plugins for the {SMProductName}: * OpenShift-SDN. -* OVN-Kubernetes. See link:https://docs.redhat.com/en/documentation/openshift_dedicated/latest/html/networking/ovn-kubernetes-network-plugin#about-ovn-kubernetes[About the OVN-Kubernetes network plugin] for more information. -* Third-Party Container Network Interface (CNI) plugins that have been certified on {ocp-product-title} and passed {SMProductShortName} conformance testing. See link:https://access.redhat.com/articles/5436171[Certified OpenShift CNI Plug-ins] for more information. \ No newline at end of file + +* OVN-Kubernetes. See "About the OVN-Kubernetes network plugin" for more information. + +* Third-party CNI plugins that {ocp-product-title} certifies and {SMProductShortName} validates through conformance testing. See "Certified OpenShift CNI plugins" for more information. \ No newline at end of file diff --git a/modules/ossm-supported-configurations-sm.adoc b/modules/ossm-supported-configurations-sm.adoc index 4dbb983571f..8f4434f2ce2 100644 --- a/modules/ossm-supported-configurations-sm.adoc +++ b/modules/ossm-supported-configurations-sm.adoc @@ -16,7 +16,7 @@ endif::openshift-rosa,openshift-rosa-hcp[] ifdef::openshift-rosa,openshift-rosa-hcp[] * This release of {SMProductName} is supported on {ocp-product-title} x86_64. endif::openshift-rosa,openshift-rosa-hcp[] -* Configurations where all {SMProductShortName} components are contained within a single {ocp-product-title} cluster. +* A single {ocp-product-title} cluster has all {SMProductShortName} components. * Configurations that do not integrate external services such as virtual machines. [NOTE] diff --git a/modules/ossm-supported-platforms.adoc b/modules/ossm-supported-platforms.adoc index 3d7be77d6b4..d4dad032e2c 100644 --- a/modules/ossm-supported-platforms.adoc +++ b/modules/ossm-supported-platforms.adoc @@ -20,8 +20,8 @@ endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] * Azure Red Hat OpenShift (ARO) version 4 * Red Hat OpenShift Service on AWS (ROSA) -The {SMProductName} Operator supports multiple versions of `Istio`. +The {SMProductName} Operator supports many versions of `{istio}`. -If you are installing {SMProductName} on a link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/installation_overview/installing-preparing#supported-installation-methods-for-different-platforms[restricted network], follow the instructions for your chosen {ocp-product-title} infrastructure. +If you are installing {SMProductName} on a "Restricted network", follow the instructions for your chosen {ocp-product-title} infrastructure. -For additional information about {SMProductName} lifecycle and supported platforms, refer to the link:https://access.redhat.com/support/policy/updates/openshift_operators[Support Policy]. \ No newline at end of file +For additional information about {SMProductName} lifecycle and supported platforms, see the "Support Policy". \ No newline at end of file diff --git a/modules/ossm-tls-gateways.adoc b/modules/ossm-tls-gateways.adoc new file mode 100644 index 00000000000..c2ce0cb50ea --- /dev/null +++ b/modules/ossm-tls-gateways.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-tls-gateways_{context}"] += Configure TLS for gateways + +[role="_abstract"] + +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-gateways.adoc b/modules/ossm-understanding-gateways.adoc new file mode 100644 index 00000000000..974fb473eec --- /dev/null +++ b/modules/ossm-understanding-gateways.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// gateways/ossm-about-gateways.adoc + +:_mod-docs-content-type: CONCEPT +[id="ossm-understanding-gateways_{context}"] += Gateways in a service mesh + +[role="_abstract"] + +A gateway consists of a standalone Envoy proxy deployment and an associated {k8s} service operating at the edge of a service mesh. You can configure a gateway to give fine-grained control over the traffic that enters or leaves the mesh. + +{SMProductName} supports different gateway deployment methods based on your data plane mode: + +* *Sidecar mode:* You can deploy gateways through injection, and then configure the flow of traffic with {istio} Gateway and `VirtualService` resources. Alternatively, you can use {k8s} Gateway API resources for both deployment and configuration. +* *Ambient mode:* Deploy gateways by using {k8s} Gateway API resources. \ No newline at end of file diff --git a/modules/ossm-understanding-operator-updates-and-channels.adoc b/modules/ossm-understanding-operator-updates-and-channels.adoc index aa5aa519c01..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"] @@ -14,7 +14,7 @@ To ensure that your {SMProduct} stays current with the latest security patches, OLM provides the following channels for the {SMProduct} Operator: -* *Stable* channel: tracks the most recent version of the {SMProduct} 3 Operator and the latest supported version of {istio}. This channel enables upgrades to new operator versions and corresponding {istio} updates as soon as they are released. Use the stable channel to stay current with the latest features, bug fixes, and security updates. +* *Stable* channel: tracks the most recent version of the {SMProduct} 3 Operator and the latest supported version of {istio}. This channel enables upgrades to new operator versions and {istio} updates immediately following their release. Use the stable channel to stay current with the latest features, bug fixes, and security updates. * *Versioned* channel: restricts updates to patch-level releases within a specific minor version. For example, `stable-3.0` provides access to the latest `{SMProductVersion}` patch version. When a new patch release becomes available, you can upgrade the Operator to the newer patch version. To move to a newer minor release, you must manually switch to a different channel. You can use a versioned channel to maintain a consistent minor version while applying only patch updates. diff --git a/modules/ossm-understanding-sm-istio-versions.adoc b/modules/ossm-understanding-sm-istio-versions.adoc index 6279ccd4249..6fcdb8108f6 100644 --- a/modules/ossm-understanding-sm-istio-versions.adoc +++ b/modules/ossm-understanding-sm-istio-versions.adoc @@ -4,8 +4,10 @@ :_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"] -The most current {SMProduct} Operator version is {SMProductVersion}. This version supports the features listed in the "{SMProductShortName} {SMProductVersion} feature support tables". The {SMProduct} Operator includes additional {istio} releases for upgrades but supports only the latest {istio} version available for each Operator version. See the "{SMProductShortName} version support tables" to identify the supported {istio} version for each Operator release. \ No newline at end of file +The most current {SMProduct} Operator version is {SMProductVersion}. This version supports the features listed in the "{SMProductShortName} {SMProductVersion} feature support tables". + +The {SMProduct} Operator includes additional {istio} releases for upgrades but supports only the latest {istio} version available for each Operator version. See the "{SMProductShortName} version support tables" to identify the supported {istio} version for each Operator release. \ No newline at end of file diff --git a/modules/ossm-uninstall-console-plugin-ocp-cli.adoc b/modules/ossm-uninstall-console-plugin-ocp-cli.adoc index 30a1d82ce61..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"] @@ -21,7 +21,7 @@ $ oc delete ossmconsoles -n .Verification -* Verify all the CRs are deleted from all namespaces by running the following command: +* Verify that you deleted all the CRs from all namespaces by running the following command: + [source,terminal] ---- 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 eac8a80fcf1..7eb472c7fd9 100644 --- a/modules/ossm-uninstalling-cert-manager.adoc +++ b/modules/ossm-uninstalling-cert-manager.adoc @@ -4,11 +4,11 @@ :_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"] -You can uninstall the cert-manager Operator with {SMProduct} by completing the following procedure. Before you remove the following resources, verify that no {SMProductName} or {istio} components reference the `Istio-CSR` agent or the certificates it issued. Removing these resources while they are still in use might disrupt mesh functionality. +Uninstall the cert-manager Operator and the `istio-csr` agent from {SMProduct} after verifying that no mesh components depend on the agent or its issued certificates to avoid service disruption. .Procedure diff --git a/modules/ossm-uninstalling-delete-istio-crds.adoc b/modules/ossm-uninstalling-delete-istio-crds.adoc index 2ce2d419fbc..cda862bad05 100644 --- a/modules/ossm-uninstalling-delete-istio-crds.adoc +++ b/modules/ossm-uninstalling-delete-istio-crds.adoc @@ -8,12 +8,12 @@ [role="_abstract"] -Deleting Istio custom resource definitions (CRDs) are optional. +Deleting {istio} custom resource definitions (CRDs) are optional. .Procedure -. To delete the Istio CRDs, run the following command: - +* To delete the {istio} CRDs, run the following command: ++ [source,terminal] ---- $ oc get crds -oname | grep -e istio.io -e sailoperator.io | xargs kubectl delete diff --git a/modules/ossm-uninstalling-service-mesh-operator-control-plane-cli.adoc b/modules/ossm-uninstalling-service-mesh-operator-control-plane-cli.adoc index bea8827136f..245669fb2b5 100644 --- a/modules/ossm-uninstalling-service-mesh-operator-control-plane-cli.adoc +++ b/modules/ossm-uninstalling-service-mesh-operator-control-plane-cli.adoc @@ -8,23 +8,23 @@ [role="_abstract"] -Uninstalling {SMProductName} Operator 3 and the {Istio} control plane from an existing {ocp-product-title} instance requires removing the following: +Uninstalling {SMProductName} Operator 3 and the {istio} control plane from an existing {ocp-product-title} instance requires removing the following: -* `Istio` resource +* `{istio}` resource * `IstioCNI` resource * {SMProductName} Operator 3 * `istio-system` project * `istio-cni` project -Optionally, you can remove the Istio custom resource definitions (CRDs). +Optionally, you can remove the {istio} custom resource definitions (CRDs). You can uninstall the {SMProductName} Operator 3 either by using the {ocp-product-title} command line interface (CLI). .Procedure -. Delete the `Istio` resource: +. Delete the `{istio}` resource: -.. Retrieve the `Istio` resource name by running the following command: +.. Retrieve the `{istio}` resource name by running the following command: + [source,terminal] ---- @@ -79,7 +79,8 @@ $ oc delete ns istio-cni $ oc delete subscription servicemeshoperator3 -n openshift-operators ---- + -.Example output +You should see output similar to the following example: ++ [source,terminal] ---- output: subscription.operators.coreos.com "servicemeshoperator3" deleted @@ -92,7 +93,8 @@ output: subscription.operators.coreos.com "servicemeshoperator3" deleted $ oc get clusterserviceversion -n openshift-operators | grep servicemeshoperator3 | awk '{print $1}' ---- + -.Example output +You should see output similar to the following example: ++ [source,terminal] ---- output: currentCSV: servicemeshoperator3.v3.0.0 @@ -105,7 +107,7 @@ output: currentCSV: servicemeshoperator3.v3.0.0 $ oc delete clusterserviceversion servicemeshoperator3.v3.0.0 -n openshift-operators ---- + -.Example output +You should see output similar to the following example: + [source,terminal] ---- diff --git a/modules/ossm-uninstalling-service-mesh-operator-control-plane-web-console.adoc b/modules/ossm-uninstalling-service-mesh-operator-control-plane-web-console.adoc index 2299e1c1f75..f43bba2d2ac 100644 --- a/modules/ossm-uninstalling-service-mesh-operator-control-plane-web-console.adoc +++ b/modules/ossm-uninstalling-service-mesh-operator-control-plane-web-console.adoc @@ -8,9 +8,6 @@ [role="_abstract"] -//TP1 content. 3 may be removed for GA. Using now to help users distinguish between OSSM 2.x and OSSM 3 as the uninstall instructions for each Operator are different. -//Possible uninstall procedures for Kiali, OpenShift Service Mesh Console (OSSMC), and other integrations may be added, or linked to, for GA. - Uninstalling {SMProductName} Operator 3 and the {Istio} control plane from an existing {ocp-product-title} instance requires removing the following: * `Istio` resource @@ -19,41 +16,64 @@ Uninstalling {SMProductName} Operator 3 and the {Istio} control plane from an ex * `istio-system` project * `istio-cni` project -Optionally, you can remove the Istio custom resource definitions (CRDs). +Optionally, you can remove the {istio} custom resource definitions (CRDs). You can uninstall the {SMProductName} Operator 3 either by using the {ocp-product-title} web console. .Procedure -. Delete the `Istio` resource: +. Delete the `{istio}` resource: + .. In the {ocp-short-name} web console, click *Operators* -> *Installed Operators*. + .. Click *Istio* in the *Provided APIs* column. -.. Click the *Options* menu -> *Delete Istio*. + +.. Click the *Options* menu -> *Delete {istio}*. + .. At the prompt to confirm the action, click *Delete*. . Delete the `IstioCNI` resource: + .. In the {ocp-short-name} web console, click *Operators* -> *Installed Operators*. + .. Click *IstioCNI* in the *Provided APIs* column. + .. Click the *Options* menu -> *Delete IstioCNI*. + .. At the prompt to confirm the action, click *Delete*. . Uninstall {SMProductName} 3 Operator: + .. In the {ocp-short-name} web console, click *Operators* -> *Installed Operators*. + .. Locate {SMProductName} 3 Operator. + .. Click the *Options* menu -> *Uninstall Operator*. -.. At the prompt to confirm the action, select the *Delete all operand instances for this operator* checkbox. + +.. At the prompt to confirm the action, select the *Delete all operand instances for this operator* checkbox. + .. Click *Uninstall*. . Delete the `istio-system` project: + .. In the {ocp-short-name} web console, click *Home* -> *Projects*. + .. Locate the name of the `istio-system` project. + .. Click the *Options* menu -> *Delete Project*. + .. At the prompt to confirm the action, enter the name of the project. + .. Click *Delete*. . Delete the `istio-cni` project: + .. In the {ocp-short-name} web console, click *Home* -> *Projects*. + .. Locate the name of the `istio-cni` project. + .. Click the *Options* menu -> *Delete Project*. + .. At the prompt to confirm the action, enter the name of the project. + .. Click *Delete*. 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 b2d3b835d85..c0e0613c620 100644 --- a/modules/ossm-updating-cross-namespace-waypoint.adoc +++ b/modules/ossm-updating-cross-namespace-waypoint.adoc @@ -1,14 +1,17 @@ // Module included in the following assemblies: +// // update/ossm-updating-openshift-service-mesh-in-ambient-mode.adoc :_mod-docs-content-type: PROCEDURE [id="ossm-updating-cross-namespace-waypoint_{context}"] -= Updating cross-namespace waypoint += Update cross-namespace waypoints [role="_abstract"] If you are using cross-namespace waypoints, verify that the `istio.io/use-waypoint-namespace` and `istio.io/use-waypoint` labels are correctly applied to the relevant namespaces before updating. +.Procedure + . Verify the namespace with any of the waypoint labels by running the following command: + [source,terminal] diff --git a/modules/ossm-updating-istio-cni-resource-version.adoc b/modules/ossm-updating-istio-cni-resource-version.adoc index 59fc9e4cf54..c1db4304066 100644 --- a/modules/ossm-updating-istio-cni-resource-version.adoc +++ b/modules/ossm-updating-istio-cni-resource-version.adoc @@ -1,20 +1,23 @@ // Module included in the following assemblies: - +// // update/ossm-updating-openshift-service-mesh.adoc :_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"] -You can update the {istio} Container Network Interface (CNI) resource version by changing the version in the resource. Then, the {SMProductShortName} Operator deploys a new version of the CNI plugin that replaces the old version of the CNI plugin. The `istio-cni-node` pods automatically reconnect to the new CNI plugin. +Update the {istio} CNI plugin by modifying the version in the resource, triggering the {SMProductShortName} Operator to deploy new plugin versions and automatically reconnect the node pods. .Prerequisites -* You are logged in to {ocp-product-title} as a user with the `cluster-admin` role. +* You have logged in to {ocp-product-title} as a user with the `cluster-admin` role. + * You have installed the {SMProductName} Operator and deployed {istio}. -* You have installed the {istio} CNI plugin with the required version. In the following example, the `IstioCNI` resource named `default` is deployed in the `istio-cni` namespace. + +* You have installed the {istio} CNI plugin with the required version. In the following example, the deployment of the `IstioCNI` resource named `default` is in the `istio-cni` namespace. + * You have either updated the {istio} control plane to the required version (for `Inplace` strategy) or created a new control plane revision (for `RevisionBased` strategy). .Procedure @@ -64,7 +67,7 @@ istio-cni-node-abc12 1/1 Running 0 3m istio-cni-node-def34 1/1 Running 0 3m istio-cni-node-ghi56 1/1 Running 0 3m ---- - ++ [NOTE] ==== When you use the `RevisionBased` strategy, the {istio} CNI component remains compatible with many control plane versions. It continues to manage traffic redirection for both the old and the new control planes throughout the migration. The {istio} CNI is compatible with a control plane running the same minor version or one minor version higher. diff --git a/modules/ossm-updating-istio-control-plane-with-inplace.adoc b/modules/ossm-updating-istio-control-plane-with-inplace.adoc index 18900ff66bd..802ddbbaefd 100644 --- a/modules/ossm-updating-istio-control-plane-with-inplace.adoc +++ b/modules/ossm-updating-istio-control-plane-with-inplace.adoc @@ -1,4 +1,5 @@ // Module included in the following assemblies: +// // update/ossm-updating-openshift-service-mesh.adoc :_mod-docs-content-type: PROCEDURE @@ -7,16 +8,27 @@ [role="_abstract"] -When updating {istio} using the `InPlace` strategy, you can increment the version by only one minor release at a time. To update by more than one minor version, you must increment the version and restart the workloads after each update. Restarting workloads ensures compatibility between the sidecar and control plane versions. The update process is complete after restarting all workloads. +When updating {istio} using the `InPlace` strategy, you can increment the version by only one minor release at a time. To update by more than one minor version, you must increment the version and restart the workloads after each update. + +[NOTE] +==== +Restarting workloads ensures compatibility between the sidecar and control plane versions. The update process is complete after restarting all workloads. +==== .Prerequisites -* You are logged in to {ocp-product-title} as a user with the `cluster-admin` role. +* You have logged in to {ocp-product-title} as a user with the `cluster-admin` role. + * You have installed the {SMProductName} Operator, and deployed {istio}. + * You have installed `istioctl` on your local machine. + * You have configured the {istio} control plane to use the `InPlace` update strategy. In this example, the `{istio}` resource named `default` is deployed in the `istio-system` namespace. -* You have installed the {istio} CNI plugin with the desired version. In this example, the `IstioCNI` resource named `default` is deployed in the `istio-cni` namespace. + +* You have installed the {istio} CNI plugin with the required version. In this example, the `IstioCNI` resource named `default` is deployed in the `istio-cni` namespace. + * You have labeled the `bookinfo` namespace to enable sidecar injection. + * You have application workloads running in the cluster. In this example, the `bookinfo` application is deployed in the `bookinfo` namespace. .Procedure @@ -28,7 +40,7 @@ When updating {istio} using the `InPlace` strategy, you can increment the versio $ oc patch istio default --type='merge' -p '{"spec":{"version":"v1.24.4"}}' ---- + -.Version update in {istio} CR +You can see the following example configuration for reference: + [source,yaml] ---- @@ -48,7 +60,7 @@ The {SMProductShortName} Operator deploys a new version of the control plane tha $ oc get istio ---- + -.Example output +You should see output similar to the following example: + [source,terminal] ---- @@ -72,7 +84,7 @@ $ oc rollout restart deployment -n bookinfo $ istioctl proxy-status ---- + -.Example output +You should see output similar to the following example: + [source,terminal] ---- 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 a8c1926af82..049cf69cd0f 100644 --- a/modules/ossm-updating-istio-control-plane-with-revisionbased-istiorevisiontag.adoc +++ b/modules/ossm-updating-istio-control-plane-with-revisionbased-istiorevisiontag.adoc @@ -1,10 +1,10 @@ // Module included in the following assemblies: - +// // update/ossm-updating-openshift-service-mesh.adoc :_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"] @@ -12,14 +12,21 @@ When updating {istio} using the `RevisionBased` strategy, you can create an `Ist .Prerequisites -* You are logged in to {ocp-product-title} as a user with the `cluster-admin` role. +* You have logged in to {ocp-product-title} as a user with the `cluster-admin` role. + * You have installed the {SMProductName} Operator 3, and deployed {istio} with the `RevisionBased` strategy. In this example, the `{istio}` resource named `default` is deployed in the `istio-system` namespace. -* You have created an `IstioRevisionTag` resource and the `targetRef` field is referencing the desired `{istio}` resource. -* You have installed the {istio} CNI plugin with the desired version. + +* You have created an `IstioRevisionTag` resource and the `targetRef` field is referencing the required `{istio}` resource. + +* You have installed the {istio} CNI plugin with the required version. + * You have labeled the `bookinfo` namespace to enable sidecar injection. + * You have application workloads running in the cluster. In this example, the `bookinfo` application is deployed in the `bookinfo` namespace. + * You have installed `istioctl` on your local machine. -* You have confirmed that the `InUse` field in the `IstioRevisionTag` resource is set to `true`. + +* You have set the `InUse` field in the `IstioRevisionTag` resource to `true`. .Procedure @@ -30,7 +37,7 @@ When updating {istio} using the `RevisionBased` strategy, you can create an `Ist $ oc patch istio default --type='merge' -p '{"spec":{"version":"v1.24.4"}}' ---- + -.Version Update in {istio} CR +You can see the following example configuration for reference: + [source,yaml] ---- @@ -52,7 +59,7 @@ The {SMProductShortName} Operator deploys a new version of the control plane alo $ oc get istio ---- + -.Example output +You should see output similar to the following example: + [source,terminal] ---- @@ -67,7 +74,7 @@ default 2 2 1 default-v1-24-3 Healthy v1.24.3 9m2 $ oc get istiorevision ---- + -.Example output +You should see output similar to the following example: + [source,terminal] ---- @@ -83,7 +90,7 @@ default-v1-24-4 Local True Healthy True v1.24.4 66s $ oc get istiorevisiontag ---- + -.Example output +You should see output similar to the following example: + [source,terminal] ---- @@ -98,7 +105,7 @@ default Healthy True default-v1-24-4 10m44s $ oc get pods -n istio-system ---- + -.Example output +You should see output similar to the following example: + [source,terminal] ---- @@ -114,7 +121,7 @@ istiod-default-v1-24-4-7495cdc7bf-v8t4g 1/1 Running 0 113s $ istioctl proxy-status ---- + -.Example output +You should see output similar to the following example: + [source,terminal] ---- @@ -172,4 +179,4 @@ $ oc get istiorevision The {SMProduct} Operator deletes the old `IstioRevision` resource and the associated control plane after the grace period defined in the `spec.updateStrategy.inactiveRevisionDeletionGracePeriodSeconds` field expires. The default grace period is 30 seconds. -You can increase the grace period to allow sufficient time to test the new control plane before removing the previous revision. Set a higher value during canary upgrades to ensure workload stability before fully transitioning. \ No newline at end of file +You can increase the grace period to allow enough time to test the new control plane before removing the earlier revision. Set a higher value during canary upgrades to ensure workload stability before fully transitioning. \ No newline at end of file diff --git a/modules/ossm-updating-istio-control-plane-with-revisionbased.adoc b/modules/ossm-updating-istio-control-plane-with-revisionbased.adoc index 8265fced3cc..32f735faad7 100644 --- a/modules/ossm-updating-istio-control-plane-with-revisionbased.adoc +++ b/modules/ossm-updating-istio-control-plane-with-revisionbased.adoc @@ -1,9 +1,10 @@ // Module included in the following assemblies: +// // update/ossm-updating-openshift-service-mesh.adoc :_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"] @@ -11,11 +12,16 @@ When updating {istio} using the `RevisionBased` strategy, you can upgrade by mor .Prerequisites -* You are logged in to {ocp-product-title} as a user with the `cluster-admin` role. +* You have logged in to {ocp-product-title} as a user with the `cluster-admin` role. + * You have installed the {SMProductName} Operator 3, and deployed {istio} with the `RevisionBased` strategy. In this example, the `{istio}` resource named `default` is deployed in the `istio-system` namespace. -* You have installed the {istio} CNI plugin with the desired version. In this example, the `IstioCNI` resource named `default` is deployed in the `istio-cni` namespace. + +* You have installed the {istio} CNI plugin with the required version. In this example, the `IstioCNI` resource named `default` is deployed in the `istio-cni` namespace. + * You have labeled the `bookinfo` namespace to enable sidecar injection. + * You have application workloads running in the cluster. In this example, the `bookinfo` application is deployed in the `bookinfo` namespace. + * You have installed `istioctl` on your local machine. .Procedure @@ -27,7 +33,7 @@ When updating {istio} using the `RevisionBased` strategy, you can upgrade by mor $ oc patch istio default --type='merge' -p '{"spec":{"version":"v1.24.4"}}' ---- + -.Version Update in {istio} CR +*Version Update in {istio} CR:* + [source,yaml] ---- @@ -49,7 +55,7 @@ The {SMProductShortName} Operator deploys a new version of the control plane alo $ oc get istio ---- + -.Example output +You should see output similar to the following example: + [source,terminal] ---- @@ -64,7 +70,7 @@ default 2 2 1 default-v1-2-4 Healthy v1.24.4 9m23 $ oc get istiorevision ---- + -.Example output +You should see output similar to the following example: + [source,terminal] ---- @@ -80,7 +86,7 @@ default-v1-24-4 Local True Healthy False v1.24.4 66s $ oc get pods -n istio-system ---- + -.Example output +You should see output similar to the following example: + [source,terminal] ---- @@ -89,14 +95,14 @@ istiod-default-v1-24-3-c98fd9675-r7bfw 1/1 Running 0 10m istiod-default-v1-24-4-7495cdc7bf-v8t4g 1/1 Running 0 113s ---- -. Confirm that the workload sidecars are still connected to the previous control plane by running the following command: +. Confirm that the workload sidecars are still connected to the earlier control plane by running the following command: + [source,terminal] ---- $ istioctl proxy-status ---- + -.Example output +You should see output similar to the following example: + [source,terminal] ---- @@ -161,4 +167,4 @@ $ oc get istiorevision The {SMProduct} Operator deletes the old `IstioRevision` resource and the associated control plane after the grace period defined in the `spec.updateStrategy.inactiveRevisionDeletionGracePeriodSeconds` field expires. The default grace period is 30 seconds. -You can increase the grace period to allow sufficient time to test the new control plane before removing the previous revision. Set a higher value during canary upgrades to ensure workload stability before fully transitioning. \ No newline at end of file +You can increase the grace period to allow enough time to test the new control plane before removing the earlier revision. Set a higher value during canary upgrades to ensure workload stability before fully transitioning. \ No newline at end of file diff --git a/modules/ossm-updating-waypoint-proxies-with-inplace-strategy.adoc b/modules/ossm-updating-waypoint-proxies-with-inplace-strategy.adoc index 3b1676acd98..48c24d894ea 100644 --- a/modules/ossm-updating-waypoint-proxies-with-inplace-strategy.adoc +++ b/modules/ossm-updating-waypoint-proxies-with-inplace-strategy.adoc @@ -1,13 +1,14 @@ // Module included in the following assemblies: +// // update/ossm-updating-openshift-service-mesh-in-ambient-mode.adoc :_mod-docs-content-type: PROCEDURE [id="ossm-updating-waypoint-proxies-with-inplace-strategy_{context}"] -= Updating waypoint proxies with InPlace strategy in ambient mode += Update waypoint proxies with InPlace strategy [role="_abstract"] -During an `InPlace` update in ambient mode, waypoint proxies are going to be updated to the latest control plane version without restarting application workloads because they are deployed and managed as separate Gateway API resources that scale and upgrade independently. +Maintain application uptime during `InPlace` updates by independently upgrading waypoint proxies through the {k8s} Gateway API without restarting associated workloads. .Prerequisites @@ -15,7 +16,7 @@ During an `InPlace` update in ambient mode, waypoint proxies are going to be upd .Procedure -* Confirm that the waypoint proxy was updated proxy version by running the following command: +* Confirm that you updated the waypoint proxy to the latest proxy version by running the following command: + [source,terminal] ---- diff --git a/modules/ossm-updating-waypoint-proxies-with-revisionbased-strategy.adoc b/modules/ossm-updating-waypoint-proxies-with-revisionbased-strategy.adoc index beea9f332f7..1b8c0de102d 100644 --- a/modules/ossm-updating-waypoint-proxies-with-revisionbased-strategy.adoc +++ b/modules/ossm-updating-waypoint-proxies-with-revisionbased-strategy.adoc @@ -1,9 +1,10 @@ // Module included in the following assemblies: +// // update/ossm-updating-openshift-service-mesh-in-ambient-mode.adoc :_mod-docs-content-type: PROCEDURE [id="ossm-updating-waypoint-proxies-with-revisionbased-strategy_{context}"] -= Updating waypoint proxies with RevisionBased strategy in ambient mode += Update waypoint proxies with RevisionBased strategy [role="_abstract"] @@ -11,7 +12,7 @@ In ambient mode, you can update waypoint proxies by using the `RevisionBased` up [NOTE] ==== -Keep waypoint proxies within one minor version of the control plane (same version or `n–1`). This recommendation aligns with the support policy of {istio}, which states that data plane components must not run ahead of the control plane version. Apply the same versioning guidance to {istio} Container Network Interface (CNI) and `Ztunnel` components. For more details, see the "{istio} Supported Releases" documentation. +Keep waypoint proxies within one minor version of the control plane (same version or `n-1`). This recommendation aligns with the support policy of {istio}, which states that data plane components must not run ahead of the control plane version. Apply the same versioning guidance to {istio} Container Network Interface (CNI) and `Ztunnel` components. For more details, see the "{istio} Supported Releases" documentation. ==== .Prerequisites @@ -35,7 +36,7 @@ NAME READY STATUS RESTARTS AGE waypoint-5d9c8b7f9-abc12 1/1 Running 0 5m ---- -. Confirm that the waypoint proxy is updated to the latest version by running the following command: +. Confirm that you updated the waypoint proxy to the latest version by running the following command: + [source,terminal] ---- @@ -49,4 +50,4 @@ You should see an output similar to the following example: waypoint-5d9c8b7f9-abc12.bookinfo SYNCED SYNCED SYNCED SYNCED istiod-1-27-3-7b9f8c5d6-xyz78.istio-system {istio-latest} ---- + -You can run the command to query the {istio} control plane and verify that the waypoint proxy is connected to the new revision. The output lists the revision-specific `istiod` pod (for example, `istiod-1-27-3`) and shows that the waypoint proxy is running the updated version, {istio-latest}. The revision-specific name in the `ISTIOD` column confirms that the waypoint proxy has successfully migrated to the new control plane revision. \ No newline at end of file +You can run the command to query the {istio} control plane and verify that the waypoint proxy connects to the new revision. The output lists the revision-specific `istiod` pod (for example, `istiod-1-27-3`) and shows that the waypoint proxy is running the updated version, {istio-latest}. The revision-specific name in the `ISTIOD` column confirms that the waypoint proxy has successfully migrated to the new control plane revision. \ No newline at end of file diff --git a/modules/ossm-updating-waypoint-proxies.adoc b/modules/ossm-updating-waypoint-proxies.adoc new file mode 100644 index 00000000000..7c1442e43c2 --- /dev/null +++ b/modules/ossm-updating-waypoint-proxies.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-updating-waypoint-proxies_{context}"] += Update waypoint proxies after upgrading an ambient mesh + +[role="_abstract"] + +Update waypoint proxies after upgrading the Istio control plane to ensure that Layer 7 policy enforcement and traffic routing continue to function correctly. Waypoint proxies are deployed using the Kubernetes Gateway API and are managed by the Istio control plane. They update independently from application workloads. + +The update procedure depends on which control plane strategy you used: + +* **InPlace strategy.** Waypoint proxies automatically reconnect to the updated control plane. +* **RevisionBased strategy.** Waypoint proxies migrate to the new control plane revision alongside your workloads. + +After the update completes, verify that L7 traffic routing and authorization policies behave as expected for both strategies. diff --git a/modules/ossm-updating-ztunnel-proxy.adoc b/modules/ossm-updating-ztunnel-proxy.adoc new file mode 100644 index 00000000000..2ab6db6092a --- /dev/null +++ b/modules/ossm-updating-ztunnel-proxy.adoc @@ -0,0 +1,13 @@ +// Module included in the following assemblies: +// +// * TBD + +:_mod-docs-content-type: CONCEPT +[id="ossm-updating-ztunnel-proxy_{context}"] += Update the ztunnel proxy + +[role="_abstract"] + +Update the ztunnel node proxy after upgrading the Istio control plane and CNI plugin. Because ztunnel operates at Layer 4 and cannot seamlessly transfer active socket connection state between instances, upgrading the proxy will briefly disrupt long-lived TCP connections on each node as the process restarts. + +By default, the `ztunnel` `DaemonSet` uses a node-by-node rolling update that replaces the pod on one node at a time. While brief traffic interruptions on a node are minimal, for workloads with long-lived TCP connections that cannot tolerate forced termination, you should cordon and drain nodes before upgrading `ztunnel` on them. 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 250954ac77c..c041958777c 100644 --- a/modules/ossm-using-discoveryselectors-scope-service-mesh.adoc +++ b/modules/ossm-using-discoveryselectors-scope-service-mesh.adoc @@ -1,27 +1,31 @@ // Module included in the following assemblies: +// // install/ossm-installing-openshift-service-mesh.adoc :_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"] -If you know which namespaces to include in the {SMProductShortName}, configure `discoverySelectors` during or after installation by adding the required selectors to the `meshConfig.discoverySelectors` section of the `{istio}` resource. For example, configure {istio} to discover only namespaces labeled `istio-discovery=enabled`. +You can restrict the namespaces that {SMProductShortName} manages by configuring `discoverySelectors` in the `{istio}` resource to include only specific labeled namespaces. .Prerequisites -* The {SMProduct} operator is installed. -* An {istio} CNI resource is created. + +* You have the {SMProduct} operator installed. + +* You have created an {istio} CNI resource. .Procedure -. Add a label to the namespace containing the {istio} control plane, for example, the `istio-system` system namespace. + +. Add a label to the namespace containing the {istio} control plane, for example, the `istio-system` system namespace, by running the following command: + [source,terminal] ---- $ oc label namespace istio-system istio-discovery=enabled ---- -. Modify the `{istio}` control plane resource to include a `discoverySelectors` section with the same label. +. Change the `{istio}` control plane resource to include a `discoverySelectors` section with the same label, similar to the following example: + [source,yaml] ---- @@ -38,7 +42,7 @@ spec: istio-discovery: enabled ---- -. Apply the Istio CR: +. Apply the `{istio}` custom resource (CR) by running the following command: + [source,terminal] ---- @@ -46,9 +50,9 @@ $ oc apply -f istio.yaml ---- . Ensure that all namespaces that will contain workloads that are to be part of the {SMProductShortName} have both the `discoverySelector` label and, if needed, the appropriate {istio} injection label. - ++ [NOTE] ==== -Discovery selectors help restrict the scope of a single {SMProductShortName} and are essential for limiting the control plane scope when you deploy multiple {istio} control planes in a single cluster. +Discovery selectors help restrict the scope of a single {SMProductShortName} and are essential for limiting the control plane scope when you deploy many {istio} control planes in a single cluster. ==== diff --git a/modules/ossm-validating-encryptions-with-kiali.adoc b/modules/ossm-validating-encryptions-with-kiali.adoc index 74823f197fa..a68bf824a42 100644 --- a/modules/ossm-validating-encryptions-with-kiali.adoc +++ b/modules/ossm-validating-encryptions-with-kiali.adoc @@ -1,7 +1,7 @@ // Module included in the following assemblies: +// // install/ossm-enabling-mtls.adoc - :_mod-docs-content-type: CONCEPT [id="ossm-validating-encryptions-with-kiali_{context}"] = Validating encryptions with Kiali @@ -10,4 +10,4 @@ The Kiali console offers several ways to validate whether or not your applications, services, and workloads have Mutual Transport Layer Security (mTLS) encryption enabled. -The *Services Detail Overview* page displays a *Security* icon on the graph edges where at least one request with mTLS enabled is present. Also note that Kiali displays a lock icon in the *Network* section next to ports that are configured for mTLS. \ No newline at end of file +The *Services Detail Overview* page displays a *Security* icon on the graph edges where at least one request with mTLS enabled is present. Also note that Kiali displays a lock icon in the *Network* section next to ports that use mTLS configuration. \ No newline at end of file diff --git a/modules/ossm-verifying-cert-manager-ambient.adoc b/modules/ossm-verifying-cert-manager-ambient.adoc new file mode 100644 index 00000000000..468237c030a --- /dev/null +++ b/modules/ossm-verifying-cert-manager-ambient.adoc @@ -0,0 +1,222 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/install/ossm-cert-manager.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ossm-verifying-cert-manager-ambient_{context}"] += Verify cert-manager in ambient mode + +[role="_abstract"] + +You can use the sample `httpbin` service and `sleep` application to verify traffic between workloads. Check the workload proxy certificate to verify a successful cert-manager Operator installation. + +.Procedure + +. Create the following namespaces: + +.. Create the `apps-1` namespace by running the following command: ++ +[source, terminal] +---- +$ oc new-project apps-1 +---- + +.. Create the `apps-2` namespace by running the following command: ++ +[source, terminal] +---- +$ oc new-project apps-2 +---- + +. Add the `istio-discovered=enabled` label on the namespaces: + +.. Add the `istio-discovered=enabled` label on the `apps-1` namespace by running the following command: ++ +[source, terminal] +---- +$ oc label namespaces apps-1 istio-discovery=enabled +---- + +.. Add the `istio-discovered=enabled` label on the `apps-2` namespace by running the following command: ++ +[source, terminal] +---- +$ oc label namespaces apps-2 istio-discovery=enabled +---- + +. Deploy the `httpbin` app in the namespaces: + +.. Deploy the `httpbin` app in the `apps-1` namespace by running the following command: ++ +[source, terminal] +---- +$ oc apply -n apps-1 -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.24/samples/httpbin/httpbin.yaml +---- + +.. Deploy the `httpbin` app in the `apps-2` namespace by running the following command: ++ +[source, terminal] +---- +$ oc apply -n apps-2 -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.24/samples/httpbin/httpbin.yaml +---- + +. Deploy the `sleep` app in the namespaces: + +.. Deploy the `sleep` app in the `apps-1` namespace by running the following command: ++ +[source, terminal] +---- +$ oc apply -n apps-1 -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.24/samples/sleep/sleep.yaml +---- + +.. Deploy the `sleep` app in the `apps-2` namespace by running the following command: ++ +[source, terminal] +---- +$ oc apply -n apps-2 -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.24/samples/sleep/sleep.yaml +---- + +. Add the `apps-1` and `apps-2` applications to the mesh in ambient mode: + +.. Apply the `istio.io/dataplane-mode=ambient` label to the `apps-1` namespace as follows: ++ +[source, terminal] +---- +$ oc label namespace apps-1 `istio.io/dataplane-mode=ambient` +---- + +.. Apply the `istio.io/dataplane-mode=ambient` label to the `apps-2` namespace as follows: ++ +[source, terminal] +---- +$ oc label namespace apps-2 `istio.io/dataplane-mode=ambient` +---- ++ +[NOTE] +==== +You can also add the label to individual pods to include only individual workloads. +==== + +. Confirm that `ztunnel` successfully opened listening sockets inside the pod network namespace, as shown in the following example: ++ +[source, terminal] +---- +$ istioctl ztunnel-config workloads --namespace ztunnel +---- ++ +You will get an output similar to the following example: ++ +[source, terminal] +---- +# NAMESPACE POD NAME ADDRESS NODE WAYPOINT PROTOCOL +apps-1 httpbin-5c6c796d88-mt864 10.131.0.28 user-rhos-d-2-7qxgk-worker-0-9s7rf None HBONE +apps-1 sleep-fb964478b-qq4cs 10.131.0.30 user-rhos-d-2-7qxgk-worker-0-9s7rf None HBONE +apps-2 httpbin-5c6c796d88-jvt52 10.131.0.29 user-rhos-d-2-7qxgk-worker-0-9s7rf None HBONE +apps-2 sleep-fb964478b-xr9qw 10.131.0.31 user-rhos-d-2-7qxgk-worker-0-9s7rf None HBONE +istio-cni istio-cni-node-4xvkv 10.128.2.79 user-rhos-d-2-7qxgk-worker-0-jztd5 None TCP +istio-cni istio-cni-node-czhkx 10.129.1.40 user-rhos-d-2-7qxgk-master-1 None TCP +istio-cni istio-cni-node-kpnmr 10.128.0.18 user-rhos-d-2-7qxgk-master-0 None TCP +istio-cni istio-cni-node-nd88z 10.130.0.72 user-rhos-d-2-7qxgk-master-2 None TCP +istio-cni istio-cni-node-tmx5l 10.131.0.26 user-rhos-d-2-7qxgk-worker-0-9s7rf None TCP +istio-system istiod-58f9796ddd-pdnh2 10.128.2.77 user-rhos-d-2-7qxgk-worker-0-jztd5 None TCP +ztunnel ztunnel-64vqw 10.129.1.39 user-rhos-d-2-7qxgk-master-1 None TCP +ztunnel ztunnel-bnbgh 10.128.2.78 user-rhos-d-2-7qxgk-worker-0-jztd5 None TCP +ztunnel ztunnel-jkzbl 10.130.0.71 user-rhos-d-2-7qxgk-master-2 None TCP +ztunnel ztunnel-p6pdf 10.128.0.17 user-rhos-d-2-7qxgk-master-0 None TCP +ztunnel ztunnel-xbpx2 10.131.0.25 user-rhos-d-2-7qxgk-worker-0-9s7rf None TCP +---- + +. Create a mesh-wide strict mutual Transport Layer Security (mTLS) policy similar to the following example: ++ +[NOTE] +==== +Enabling `PeerAuthentication` in strict mTLS mode verifies correct certificate distribution and functional mTLS communication between workloads. +==== ++ +[source, yaml] +---- +apiVersion: security.istio.io/v1beta1 +kind: PeerAuthentication +metadata: + name: default + namespace: istio-system +spec: + mtls: + mode: STRICT +---- + +. Apply the mTLS policy by running the following command: ++ +[source, terminal] +---- +$ oc apply -f peer_auth.yaml +---- + +. Verify that the `apps-1/sleep` app can access the `apps-2/httpbin` service by running the following command: ++ +[source, terminal] +---- +$ oc -n apps-1 exec "$(oc -n apps-1 get pod \ + -l app=sleep -o jsonpath={.items..metadata.name})" \ + -c sleep -- curl -sIL http://httpbin.apps-2.svc.cluster.local:8000 +---- ++ +You will get an output similar to the following example: ++ +[source, terminal] +---- +HTTP/1.1 200 OK +access-control-allow-credentials: true +access-control-allow-origin: * +content-security-policy: default-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' camo.githubusercontent.com +content-type: text/html; charset=utf-8 +date: Wed, 18 Jun 2025 09:20:55 GMT +x-envoy-upstream-service-time: 14 +server: envoy +transfer-encoding: chunked +---- + +. Verify that the `apps-2/sleep` app can access the `apps-1/httpbin` service by running the following command: ++ +[source, terminal] +---- +$ oc -n apps-2 exec "$(oc -n apps-1 get pod \ + -l app=sleep -o jsonpath={.items..metadata.name})" \ + -c sleep -- curl -sIL http://httpbin.apps-2.svc.cluster.local:8000 +---- ++ +You will get an output similar to the following example: ++ +[source, terminal] +---- +HTTP/1.1 200 OK +access-control-allow-credentials: true +access-control-allow-origin: * +content-security-policy: default-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' camo.githubusercontent.com +content-type: text/html; charset=utf-8 +date: Wed, 18 Jun 2025 09:21:23 GMT +x-envoy-upstream-service-time: 16 +server: envoy +transfer-encoding: chunked +---- + +. Verify that the `httpbin` workload certificate matches as expected by running the following command: ++ +[source, terminal] +---- +$ istioctl proxy-config secret -n apps-1 \ + $(oc get pods -n apps-1 -o jsonpath='{.items..metadata.name}' --selector app=httpbin) \ + -o json | jq -r '.dynamicActiveSecrets[0].secret.tlsCertificate.certificateChain.inlineBytes' \ + | base64 --decode | openssl x509 -text -noout +---- ++ +You will get an output similar to the following example: ++ +[source, terminal] +---- +... +Issuer: O = cert-manager + O = cluster.local, CN = istio-ca +... +X509v3 Subject Alternative Name: +URI:spiffe://cluster.local/ns/apps-1/sa/httpbin +---- diff --git a/modules/ossm-verifying-cert-manager.adoc b/modules/ossm-verifying-cert-manager.adoc index 963ce4acd18..4c950e9f248 100644 --- a/modules/ossm-verifying-cert-manager.adoc +++ b/modules/ossm-verifying-cert-manager.adoc @@ -4,13 +4,15 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-verifying-cert-manager_{context}"] -= Verifying Service Mesh with the cert-manager Operator using the istio-csr agent += Verify cert-manager in sidecar mode [role="_abstract"] -You can use the sample `httpbin` service and `sleep` application to verify traffic between workloads. Check the workload proxy certificate to verify that the cert-manager Operator is installed correctly. +You can use the sample `httpbin` service and `sleep` application to verify traffic between workloads. Check the workload proxy certificate to verify a successful cert-manager Operator installation. -. Create the namespaces: +.Procedure + +. Create the followingnamespaces: .. Create the `apps-1` namespace by running the following command: + @@ -94,10 +96,9 @@ $ oc get pods -n apps-2 + [NOTE] ==== -Enabling `PeerAuthentication` in strict mTLS mode verifies that certificates are distributed correctly and that mTLS communication functions between workloads. +Enabling `PeerAuthentication` in strict mTLS mode verifies correct certificate distribution and functional mTLS communication between workloads. ==== + -.Example `peer_auth.yaml` file [source, yaml] ---- apiVersion: security.istio.io/v1beta1 @@ -126,7 +127,7 @@ $ oc -n apps-1 exec "$(oc -n apps-1 get pod \ -c sleep -- curl -sIL http://httpbin.apps-2.svc.cluster.local:8000 ---- + -.Example output +You should see output similar to the following example: + [source, terminal] ---- @@ -150,7 +151,7 @@ $ oc -n apps-2 exec "$(oc -n apps-1 get pod \ -c sleep -- curl -sIL http://httpbin.apps-2.svc.cluster.local:8000 ---- + -.Example output +You should see output similar to the following example: + [source, terminal] ---- @@ -175,7 +176,7 @@ $ istioctl proxy-config secret -n apps-1 \ | base64 --decode | openssl x509 -text -noout ---- + -.Example output +You should see output similar to the following example: + [source, terminal] ---- diff --git a/modules/ossm-verifying-l7-features-with-authorization-policies.adoc b/modules/ossm-verifying-l7-features-with-authorization-policies.adoc index 71ffbb0f55c..01bab6e18db 100644 --- a/modules/ossm-verifying-l7-features-with-authorization-policies.adoc +++ b/modules/ossm-verifying-l7-features-with-authorization-policies.adoc @@ -1,13 +1,14 @@ // Module included in the following assemblies: +// // update/ossm-updating-openshift-service-mesh-in-ambient-mode.adoc :_mod-docs-content-type: PROCEDURE [id="ossm-verifying-l7-features-with-authorization-policies_{context}"] -= Verifying Layer 7 (L7) features with authorization policies += Verify L7 authorization policies after waypoint updates [role="_abstract"] -After updating the waypoint proxies, verify that the Layer 7 (L7) authorization policies are enforced correctly. In this example, the `AuthorizationPolicy` resource named `productpage-waypoint` allows only requests from the `default/sa/curl` service account to send `GET` requests to the `productpage` service. +After updating the waypoint proxies, verify that the Layer 7 (L7) authorization policies enforce correctly. In this example, the `AuthorizationPolicy` resource named `productpage-waypoint` allows only requests from the `default/sa/curl` service account to send `GET` requests to the `productpage` service. .Prerequisites @@ -61,7 +62,7 @@ $ oc exec "$( curl -sS productpage:9080/productpage ---- + -The request will be denied because the `ratings` service is not included in the authorization policy’s `allow` list. Only the `curl` pod using the `default/curl` service account can access `productpage` service. +The request will be denied because the `ratings` service is not included in the authorization policy's `allow` list. Only the `curl` pod by using the `default/curl` service account can access `productpage` service. . Verify that the `curl` service can access the `productpage` service with `GET` requests by running the following command: + diff --git a/modules/ossm-verifying-l7-features-with-traffic-routing.adoc b/modules/ossm-verifying-l7-features-with-traffic-routing.adoc index d40a01a4c6e..9d5460ed98b 100644 --- a/modules/ossm-verifying-l7-features-with-traffic-routing.adoc +++ b/modules/ossm-verifying-l7-features-with-traffic-routing.adoc @@ -1,9 +1,10 @@ // Module included in the following assemblies: +// // update/ossm-updating-openshift-service-mesh-in-ambient-mode.adoc :_mod-docs-content-type: PROCEDURE [id="ossm-verifying-l7-features-with-traffic-routing_{context}"] -= Verifying Layer 7 (L7) features with traffic routing += Verify L7 traffic routing after waypoint updates [role="_abstract"] @@ -64,4 +65,4 @@ for i in {1..10}; do done ---- + -The output should reflect the traffic distribution defined in your `HTTPRoute`. For example, with a `90/10` weight split between `reviews-v1` and `reviews-v2`, you should observe about nine requests routed to `reviews-v1` and one request routed to `reviews-v2`. The exact ratio can vary slightly due to load-balancing behavior, but should closely match the configured weights over multiple test runs. +The output should reflect the traffic distribution defined in your `HTTPRoute`. For example, with a `90/10` weight split between `reviews-v1` and `reviews-v2`, you should observe about nine requests routed to `reviews-v1` and one request routed to `reviews-v2`. The exact ratio can vary slightly due to load balancing behavior, but should closely match the configured weights over many test runs. diff --git a/modules/ossm-verifying-metrics-ambient-mode.adoc b/modules/ossm-verifying-metrics-ambient-mode.adoc index 7714137176b..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,13 +12,13 @@ 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 https://docs.redhat.com/en/documentation/red_hat_openshift_service_mesh/3.2/html/installing/ossm-istio-ambient-mode#ossm-deploying-bookinfo-application-istio-ambient-mode_ossm-istio-ambient-mode[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 . On the {ocp-short-name} Console go to *Observe* -> *Targets*. -. Find the status of `Metrics Targets` by searching for targets such as `istiod-monitor`, `istio-ztunnel-monitor`, and `istio-waypoint-monitor`. `istio-waypoint-monitor` is created only when the waypoint proxy is created to use Layer 7 (L7) {SMProduct} features. +. Find the status of `Metrics Targets` by searching for targets such as `istiod-monitor`, `istio-ztunnel-monitor`, and `istio-waypoint-monitor`. You can create `istio-waypoint-monitor` only if you created the waypoint to use Layer 7 (L7) {SMProduct} features. + [NOTE] ==== diff --git a/modules/ossm-verifying-multi-cluster-topology-ambient.adoc b/modules/ossm-verifying-multi-cluster-topology-ambient.adoc new file mode 100644 index 00000000000..d218b3e59d8 --- /dev/null +++ b/modules/ossm-verifying-multi-cluster-topology-ambient.adoc @@ -0,0 +1,188 @@ +// This procedure is used in the following assembly: +// +// * install/ossm-multi-cluster-topologies.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ossm-verifying-multi-cluster-topology-ambient_{context}"] += Verify a multi-primary multi-network mesh in ambient mode + +[role="_abstract"] + +Deploy sample applications and verify traffic across two {ocp-product-title} clusters with {SMProductShortName} in ambient mode. + +[NOTE] +==== +In this procedure, `CLUSTER1` is the East cluster and `CLUSTER2` is the West cluster. +==== + +.Prerequisites + +* You have {istio} version 1.27.3 or later. + +* You have installed the {SMProduct} Operator on all of the clusters that include the mesh. + +* You have completed "Creating certificates for a multi-cluster mesh". + +* You have completed "Applying certificates to a multi-cluster topology". + +* You have created an {istio} Container Network Interface (CNI) resource as described in the "Installing {istio} ambient mode" section of this guide. + +* You have `istioctl` installed on your laptop. + +* You have installed a multi-cluster topology. + +.Procedure + +. Deploy sample applications on the East cluster: + +.. Create a sample application namespace on the East cluster by running the following command: ++ +[source,terminal] +---- +$ oc --context "${CTX_CLUSTER1}" get project sample || oc --context="${CTX_CLUSTER1}" new-project sample +---- + +.. Label the application namespace to support ambient mode by running the following command: ++ +[source,terminal] +---- +$ oc --context="${CTX_CLUSTER1}" label namespace sample istio.io/dataplane-mode=ambient +---- + +.. Deploy the `helloworld` application: + +... Create the `helloworld` service by running the following command: ++ +[source,terminal] +---- +$ oc --context="${CTX_CLUSTER1}" apply \ + -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.27/samples/helloworld/helloworld.yaml \ + -l service=helloworld -n sample +---- + +... Label the `helloworld` service as global so that other clusters in the mesh can access the service: ++ +[source,terminal] +---- +$ oc --context="${CTX_CLUSTER1}" label svc -n sample -l app=helloworld istio.io/global=true +---- + +... Create the `helloworld-v1` deployment by running the following command: ++ +[source,terminal] +---- +$ oc --context="${CTX_CLUSTER1}" apply \ + -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.27/samples/helloworld/helloworld.yaml \ + -l version=v1 -n sample +---- + +.. Deploy the `sleep` application by running the following command: ++ +[source,terminal] +---- +$ oc --context="${CTX_CLUSTER1}" apply \ + -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.27/samples/sleep/sleep.yaml -n sample +---- + +.. Wait for the `helloworld` application on the East cluster to return the `Ready` status condition by running the following command: ++ +[source,terminal] +---- +$ oc --context="${CTX_CLUSTER1}" wait --for condition=available -n sample deployment/helloworld-v1 +---- + +.. Wait for the `sleep` application on the East cluster to return the `Ready` status condition by running the following command: ++ +[source,terminal] +---- +$ oc --context="${CTX_CLUSTER1}" wait --for condition=available -n sample deployment/sleep +---- + +. Deploy the sample applications on the West cluster: + +.. Create a sample application namespace on the West cluster by running the following command: ++ +[source,terminal] +---- +$ oc --context "${CTX_CLUSTER2}" get project sample || oc --context="${CTX_CLUSTER2}" new-project sample +---- + +.. Label the application namespace to support ambient mode by running the following command: ++ +[source,terminal] +---- +$ oc --context="${CTX_CLUSTER2}" label namespace sample istio.io/dataplane-mode=ambient +---- + +.. Deploy the `helloworld` application: + +... Create the `helloworld` service by running the following command: ++ +[source,terminal] +---- +$ oc --context="${CTX_CLUSTER2}" apply \ + -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.27/samples/helloworld/helloworld.yaml \ + -l service=helloworld -n sample +---- + +... Label the `helloworld` service as global so that other clusters in the mesh can access the service: ++ +[source,terminal] +---- +$ oc --context="${CTX_CLUSTER2}" label svc -n sample -l app=helloworld istio.io/global=true +---- + +... Create the `helloworld-v2` deployment by running the following command: ++ +[source,terminal] +---- +$ oc --context="${CTX_CLUSTER2}" apply \ + -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.27/samples/helloworld/helloworld.yaml \ + -l version=v2 -n sample +---- + +.. Deploy the `sleep` application by running the following command: ++ +[source,terminal] +---- +$ oc --context="${CTX_CLUSTER2}" apply \ + -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.27/samples/sleep/sleep.yaml -n sample +---- + +.. Wait for the `helloworld` application on the West cluster to return the `Ready` status condition by running the following command: ++ +[source,terminal] +---- +$ oc --context="${CTX_CLUSTER2}" wait --for condition=available -n sample deployment/helloworld-v2 +---- + +.. Wait for the `sleep` application on the West cluster to return the `Ready` status condition by running the following command: ++ +[source,terminal] +---- +$ oc --context="${CTX_CLUSTER2}" wait --for condition=available -n sample deployment/sleep +---- + +.Verification + +. For the East cluster, send 10 requests to the `helloworld` service by running the following command: ++ +[source,terminal] +---- +$ for i in {0..9}; do \ + oc --context="${CTX_CLUSTER1}" exec -n sample deploy/sleep -c sleep -- curl -sS helloworld.sample:5000/hello; \ +done +---- ++ +Verify that both clusters respond, displaying both version 1 and version 2 of the service. + +. For the West cluster, send 10 requests to the `helloworld` service: ++ +[source,terminal] +---- +$ for i in {0..9}; do \ + oc --context="${CTX_CLUSTER2}" exec -n sample deploy/sleep -c sleep -- curl -sS helloworld.sample:5000/hello; \ +done +---- ++ +Verify that both clusters respond, displaying both version 1 and version 2 of the service. diff --git a/modules/ossm-verifying-multi-cluster-topology.adoc b/modules/ossm-verifying-multi-cluster-topology.adoc index 8dc73f3ea5e..68718cbfb42 100644 --- a/modules/ossm-verifying-multi-cluster-topology.adoc +++ b/modules/ossm-verifying-multi-cluster-topology.adoc @@ -1,9 +1,10 @@ // This procedure is used in the following assembly: +// // * install/ossm-multi-cluster-topologies.adoc :_mod-docs-content-type: PROCEDURE [id="ossm-verifying-multi-cluster-topology_{context}"] -= Verifying a multi-cluster topology += Verify a multi-primary multi-network mesh with sidecar deployment [role="_abstract"] @@ -16,7 +17,7 @@ In this procedure, `CLUSTER1` is the East cluster and `CLUSTER2` is the West clu .Prerequisites -* You have installed the {SMProduct} Operator on all of the clusters that comprise the mesh. +* You have installed the {SMProduct} Operator on all of the clusters that include the mesh. * You have completed "Creating certificates for a multi-cluster mesh". @@ -146,7 +147,7 @@ $ oc --context="${CTX_CLUSTER2}" wait --for condition=available -n sample deploy $ oc --context="${CTX_CLUSTER2}" wait --for condition=available -n sample deployment/sleep ---- -.Verifying traffic flows between clusters +.Verification . For the East cluster, send 10 requests to the `helloworld` service by running the following command: + @@ -157,7 +158,7 @@ $ for i in {0..9}; do \ done ---- + -Verify that you see responses from both clusters. This means version 1 and version 2 of the service can be seen in the responses. +Verify that you see responses from both clusters, displaying both version 1 and version 2 of the service. . For the West cluster, send 10 requests to the `helloworld` service: + @@ -168,4 +169,4 @@ $ for i in {0..9}; do \ done ---- + -Verify that you see responses from both clusters. This means version 1 and version 2 of the service can be seen in the responses. +Verify that you see responses from both clusters, displaying both version 1 and version 2 of the service. diff --git a/modules/ossm-verifying-multiple-control-planes.adoc b/modules/ossm-verifying-multiple-control-planes.adoc index aabb71e1a47..ad7a7e1dd8b 100644 --- a/modules/ossm-verifying-multiple-control-planes.adoc +++ b/modules/ossm-verifying-multiple-control-planes.adoc @@ -1,36 +1,41 @@ // Module included in the following assemblies: +// // install/ossm-deploying-multiple-service-meshes-on-single-cluster.adoc :_mod-docs-content-type: PROCEDURE [id="ossm-verifying-multiple-control-planes_{context}"] -= Verifying multiple control planes += Verify multiple control planes [role="_abstract"] -Verify that both of the {istio} control planes are deployed and running properly. You can validate that the `istiod` pod is successfully running in each {istio} system namespace. +Verify that both {istio} control planes deploy and run as expected. You can validate that the `istiod` pod is successfully running in each {istio} system namespace. -. Verify that the workloads are assigned to the control plane in `istio-system-1` by running the following command: +.Procedure + +. Verify that the control plane in `istio-system-1` manages the workloads by running the following command: + [source,terminal] ---- $ oc get pods -n istio-system-1 ---- + -.Example output +You should see output similar to the following example: ++ [source,terminal] ---- NAME READY STATUS RESTARTS AGE istiod-mesh-1-b69646b6f-kxrwk 1/1 Running 0 4m14s ---- -. Verify that the workloads are assigned to the control plane in `istio-system-2` by running the following command: +. Verify that the control plane in `istio-system-2` manages the workloads by running the following command: + [source,terminal] ---- $ oc get pods -n istio-system-2 ---- + -.Example output +You should see output similar to the following example: ++ [source,terminal] ---- NAME READY STATUS RESTARTS AGE diff --git a/modules/ossm-verifying-quantum-secure-gateway.adoc b/modules/ossm-verifying-quantum-secure-gateway.adoc index fb5c7be8664..067a843aee0 100644 --- a/modules/ossm-verifying-quantum-secure-gateway.adoc +++ b/modules/ossm-verifying-quantum-secure-gateway.adoc @@ -8,7 +8,7 @@ [role="_abstract"] -Verify the post-quantum gateway configuration by testing connections with both {pqc-short}-enabled and standard clients to confirm that only quantum-safe handshakes are accepted. +Verify the post-quantum gateway configuration by testing connections with both {pqc-short}-enabled and standard clients to confirm that the gateway accepts only quantum-safe handshakes. .Procedure diff --git a/modules/ossm-verifying-traces-ambient-mode.adoc b/modules/ossm-verifying-traces-ambient-mode.adoc index aa06d53de96..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 link:https://docs.redhat.com/en/documentation/red_hat_openshift_service_mesh/latest/html/installing/ossm-istio-ambient-mode#ossm-deploying-bookinfo-application-istio-ambient-mode_ossm-istio-ambient-mode[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 link:https://docs.redhat.com/en/documentation/red_hat_openshift_service_mesh/latest/html/installing/ossm-istio-ambient-mode#ossm-deploying-waypoint-proxy_ossm-istio-ambient-mode[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 @@ -38,5 +38,5 @@ $ oc get routes -n tempo tempo-sample-query-frontend + [NOTE] ==== -The route for Tempo dashboard UI can be created from the `TempoStack` custom resource (CR) with `.spec.template.queryFrontend.jaegerQuery.ingress.type: route` field. +The `TempoStack` custom resource (CR) creates the route for the Tempo dashboard UI when you set the .`spec.template.queryFrontend.jaegerQuery.ingress.type` field to `route`. ==== \ No newline at end of file diff --git a/modules/ossm-ztunnel-update-lifecycle.adoc b/modules/ossm-ztunnel-update-lifecycle.adoc index 064394eec7c..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"] @@ -12,14 +12,14 @@ Understand the Ztunnel rolling update process, and how the process affects conne 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. -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: +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 new connections may be handled by either one. +* 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 diff --git a/observability/kiali/ossm-console-plugin.adoc b/observability/kiali/ossm-console-plugin.adoc index caf6e9456ab..ffd31a8643c 100644 --- a/observability/kiali/ossm-console-plugin.adoc +++ b/observability/kiali/ossm-console-plugin.adoc @@ -1,6 +1,6 @@ :_mod-docs-content-type: ASSEMBLY [id="ossm-console-plugin"] -= Using OpenShift Service Mesh Console plugin += OpenShift Service Mesh Console plugin include::_attributes/common-attributes.adoc[] :context: ossm-console-plugin diff --git a/observability/kiali/ossm-kiali.adoc b/observability/kiali/ossm-kiali.adoc index cbf753e69fb..867faa323c8 100644 --- a/observability/kiali/ossm-kiali.adoc +++ b/observability/kiali/ossm-kiali.adoc @@ -27,9 +27,15 @@ include::modules/ossm-external-kiali-deployment-model.adoc[leveloffset=+1] include::modules/ossm-installing-kiali-operator-on-remote-clusters.adoc[leveloffset=+2] [role="_additional-resources"] -[id="ossm-kiali-additional-resource_{context}"] +[id="additional-resources_{context}"] == Additional resources +* link:https://www.kiali.io/[Kiali project] + +* link:https://docs.redhat.com/en/documentation/monitoring_stack_for_red_hat_openshift/latest/html/configuring_user_workload_monitoring/preparing-to-configure-the-monitoring-stack-uwm#enabling-monitoring-for-user-defined-projects-uwm_preparing-to-configure-the-monitoring-stack-uwm[Enabling monitoring for user-defined projects] + * xref:../metrics/ossm-metrics.adoc#ossm-config-openshift-monitoring-only_ossm-metrics[Configuring OpenShift Monitoring with Service Mesh] -* xref:../traces/ossm-distr-tracing.adoc#ossm-config-otel_ossm-traces[Configuring {OTELName} with Service Mesh] \ No newline at end of file +* xref:../traces/ossm-distr-tracing.adoc#ossm-config-otel_ossm-traces[Configuring {OTELName} with Service Mesh] + +* link:https://docs.redhat.com/en/documentation/red_hat_openshift_service_mesh/latest/html/installing/ossm-multi-cluster-topologies#ossm-installing-kiali-multi-cluster-mesh_ossm-multi-cluster-topologies[Installing Kiali in a multi-cluster mesh] \ No newline at end of file diff --git a/observability/metrics/ossm-metrics.adoc b/observability/metrics/ossm-metrics.adoc index 40950f07779..2fe6f06337c 100644 --- a/observability/metrics/ossm-metrics.adoc +++ b/observability/metrics/ossm-metrics.adoc @@ -16,4 +16,12 @@ include::modules/ossm-config-openshift-monitoring-only.adoc[leveloffset=+1] include::modules/ossm-config-openshift-monitoring-ambient-mode.adoc[leveloffset=+1] -include::modules/ossm-verifying-metrics-ambient-mode.adoc[leveloffset=+2] \ No newline at end of file +include::modules/ossm-verifying-metrics-ambient-mode.adoc[leveloffset=+2] + +[role="_additional-resources"] +[id="additional-resources_{context}"] +== Additional resources + +* link:https://docs.redhat.com/en/documentation/monitoring_stack_for_red_hat_openshift/4.21/html/configuring_user_workload_monitoring/index[Configuring user workload monitoring] + +* link:https://docs.redhat.com/en/documentation/red_hat_openshift_service_mesh/3.2/html/installing/ossm-istio-ambient-mode#ossm-deploying-bookinfo-application-istio-ambient-mode_ossm-istio-ambient-mode[Deploying the Bookinfo application in Istio ambient mode] \ No newline at end of file diff --git a/observability/traces/ossm-distr-tracing.adoc b/observability/traces/ossm-distr-tracing.adoc index 1c76636ceb8..a70f7a964e6 100644 --- a/observability/traces/ossm-distr-tracing.adoc +++ b/observability/traces/ossm-distr-tracing.adoc @@ -1,4 +1,4 @@ -:_content-type: ASSEMBLY +:_mod-docs-content-type: ASSEMBLY [id="ossm-distr-tracing"] = Configuring {DTProductName} with Service Mesh include::_attributes/common-attributes.adoc[] @@ -8,7 +8,7 @@ toc::[] [role="_abstract"] -Integrate {DTProductName} with {SMProductName} by using {TempoName} for distributed tracing storage and {OTELName} for standardized telemetry data collection and processing. +Integrate {DTProductName} with {SMProductName} by using {TempoName} for {DTShortName} storage and {OTELName} for standardized telemetry data collection and processing. include::modules/ossm-about-distributed-tracing-and-service-mesh.adoc[leveloffset=+1] @@ -16,4 +16,28 @@ include::modules/ossm-config-otel.adoc[leveloffset=+1] include::modules/ossm-config-dt-ambient-mode.adoc[leveloffset=+1] -include::modules/ossm-verifying-traces-ambient-mode.adoc[leveloffset=+2] \ No newline at end of file +include::modules/ossm-verifying-traces-ambient-mode.adoc[leveloffset=+2] + +[role="_additional-resources"] +[id="additional-resources_{context}"] +== Additional resources + +* link:https://grafana.com/oss/tempo/[Grafana Tempo] + +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/distributed_tracing/distr-tracing-tempo-architecture[{TempoName}] + +* link:https://opentelemetry.io/[OpenTelemetry project] + +* link:https://opentelemetry.io/docs/collector/[OpenTelemetry Collector] + +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/red_hat_build_of_opentelemetry/index[{OTELName}] + +* link:https://docs.redhat.com/en/documentation/red_hat_openshift_distributed_tracing_platform/latest/html/installing_the_distributed_tracing_platform/distr-tracing-tempo-installing#installing-the-tempo-operator_distr-tracing-tempo-installing[Installing the Tempo Operator] + +* link:https://docs.redhat.com/en/documentation/red_hat_build_of_opentelemetry/latest/html/installing_red_hat_build_of_opentelemetry/install-otel[Installing the Red Hat build of OpenTelemetry] + +* link:https://docs.redhat.com/en/documentation/red_hat_openshift_distributed_tracing_platform/latest/html/installing_the_distributed_tracing_platform/distr-tracing-tempo-installing#installing-a-tempostack-instance_distr-tracing-tempo-installing[Installing a TempoStack instance] + +* link:https://docs.redhat.com/en/documentation/red_hat_openshift_service_mesh/latest/html/installing/ossm-istio-ambient-mode#ossm-deploying-bookinfo-application-istio-ambient-mode_ossm-istio-ambient-mode[Deploying the Bookinfo application in Istio ambient mode] + +* link:https://docs.redhat.com/en/documentation/red_hat_openshift_service_mesh/latest/html/installing/ossm-istio-ambient-mode#ossm-deploying-waypoint-proxy_ossm-istio-ambient-mode[Deploying a waypoint proxy] \ No newline at end of file diff --git a/ossm-release-notes/ossm-release-notes-feature-support-tables.adoc b/ossm-release-notes/ossm-release-notes-feature-support-tables.adoc index 3027fcb04b6..0a83553a70c 100644 --- a/ossm-release-notes/ossm-release-notes-feature-support-tables.adoc +++ b/ossm-release-notes/ossm-release-notes-feature-support-tables.adoc @@ -1,9 +1,16 @@ -:_mod-docs_content-type: ASSEMBLY +:_mod-docs-content-type: ASSEMBLY + [id="ossm-release-notes-feature-support-tables"] = {SMProductShortName} feature support tables include::_attributes/common-attributes.adoc[] :context: ossm-release-notes-support-tables +include::_attributes/attributes-microshift.adoc[] +:context: ossm-release-notes-support-tables + +include::_attributes/attributes-openshift-dedicated.adoc[] +:context: ossm-release-notes-support-tables + toc::[] [role="_abstract"] @@ -31,7 +38,7 @@ include::modules/ossm-release-notes-extensibility-features.adoc[leveloffset=+1] include::modules/ossm-release-notes-istio-ambient-mode.adoc[leveloffset=+1] [role="_additional-resources"] -[id="additional-resources-istio-deployment-lifecycle_{context}"] +[id="additional-resources_{context}"] == Additional resources * xref:../install/ossm-istioctl-tool.adoc#ossm-support-for-istioctl_ossm-istioctl-tool[Support for Istioctl] diff --git a/ossm-release-notes/ossm-release-notes-version-support-tables.adoc b/ossm-release-notes/ossm-release-notes-version-support-tables.adoc index 482a7e73666..8ec5c454654 100644 --- a/ossm-release-notes/ossm-release-notes-version-support-tables.adoc +++ b/ossm-release-notes/ossm-release-notes-version-support-tables.adoc @@ -1,4 +1,4 @@ -:_mod-docs_content-type: ASSEMBLY +:_mod-docs-content-type: ASSEMBLY [id="ossm-release-notes-version-support-tables"] = {SMProductShortName} version support tables include::_attributes/common-attributes.adoc[] @@ -13,7 +13,7 @@ toc::[] include::modules/ossm-release-notes-supported-versions.adoc[leveloffset=+1] [role="_additional-resources"] -[id="additional-resources-supported-versions_{context}"] +[id="additional-resources_{context}"] == Additional resources -* xref:../observability/kiali/ossm-console-plugin.adoc#ossm-install-console-plugin_ossm-console-plugin[Installing {SMPlugin}]. \ No newline at end of file +* xref:../observability/kiali/ossm-console-plugin.adoc#ossm-install-console-plugin_ossm-console-plugin[Installing {SMPlugin}] \ No newline at end of file diff --git a/ossm-release-notes/ossm-release-notes.adoc b/ossm-release-notes/ossm-release-notes.adoc index 2d79b576662..aa9f3c0eb0c 100644 --- a/ossm-release-notes/ossm-release-notes.adoc +++ b/ossm-release-notes/ossm-release-notes.adoc @@ -1,4 +1,5 @@ -:_mod-docs_content-type: ASSEMBLY +:_mod-docs-content-type: ASSEMBLY + [id="ossm-release-notes"] = OpenShift Service Mesh release notes include::_attributes/common-attributes.adoc[] @@ -10,22 +11,18 @@ toc::[] Review new features, compatibility updates, fixed issues, and known issues for {SMProductName} to stay informed about changes across different product versions. -include::modules/ossm-release-notes-3-1-2.adoc[leveloffset=+1] - -include::modules/ossm-release-notes-3-1-1.adoc[leveloffset=+1] - -include::modules/ossm-release-notes-3-1-new-features-enhancements.adoc[leveloffset=+1] +include::modules/ossm-release-notes-3-X-new-features-enhancements.adoc[leveloffset=+1] -include::modules/ossm-release-notes-3-1-technology-preview-features.adoc[leveloffset=+1] +include::modules/ossm-release-notes-3-X-technology-preview-features.adoc[leveloffset=+1] -include::modules/ossm-release-notes-3-1-fixed-issues.adoc[leveloffset=+1] +include::modules/ossm-release-notes-3-X-fixed-issues.adoc[leveloffset=+1] -include::modules/ossm-release-notes-3-1-known-issues.adoc[leveloffset=+1] +include::modules/ossm-release-notes-3-X-known-issues.adoc[leveloffset=+1] -include::modules/ossm-release-notes-3-1-deprecated-features.adoc[leveloffset=+1] +include::modules/ossm-release-notes-3-X-deprecated-features.adoc[leveloffset=+1] [role="_additional-resources"] -[id="additional-resources-release-notes_{context}"] +[id="additional-resources_{context}"] == Additional resources * link:https://access.redhat.com/support/policy/updates/openshift_operators[{ocp-short-name} Operator Life Cycles] diff --git a/snippets/ossm-migrate-all-namespaces.adoc b/snippets/ossm-migrate-all-namespaces.adoc new file mode 100644 index 00000000000..56d7d1c0825 --- /dev/null +++ b/snippets/ossm-migrate-all-namespaces.adoc @@ -0,0 +1,9 @@ +// snippet included in the following assembly: +// +// * migrating/cluster-wide/ossm-migrating-cluster-wide.adoc +:_mod-docs-content-type: SNIPPET + +[IMPORTANT] +==== +Before creating a default revision tag and relabelling the namespaces, you must migrate all remaining workload namespaces, including gateways. +==== \ No newline at end of file diff --git a/snippets/technology-preview-SPIRE.adoc b/snippets/technology-preview-SPIRE.adoc new file mode 100644 index 00000000000..b177e22ec73 --- /dev/null +++ b/snippets/technology-preview-SPIRE.adoc @@ -0,0 +1,11 @@ +// snippet included in the following assembly and modules: +// +// * service-mesh-docs-main/install/ossm-SPIRE.adoc +// * service-mesh-docs-main/modules/ossm-SPIRE-install-ZTWIM.adoc + +[IMPORTANT] +==== +SPIRE integration with {SMProduct} is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. + +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]. +==== diff --git a/uninstalling/ossm-uninstalling-openshift-service-mesh.adoc b/uninstalling/ossm-uninstalling-openshift-service-mesh.adoc index b510b5e0c66..32155159631 100644 --- a/uninstalling/ossm-uninstalling-openshift-service-mesh.adoc +++ b/uninstalling/ossm-uninstalling-openshift-service-mesh.adoc @@ -1,4 +1,4 @@ -:_content-type: ASSEMBLY +:_mod-docs-content-type: ASSEMBLY [id="ossm-uninstalling-openshift-service-mesh"] = Uninstalling OpenShift Service Mesh include::_attributes/common-attributes.adoc[] @@ -16,8 +16,8 @@ include::modules/ossm-uninstalling-service-mesh-operator-control-plane-cli.adoc[ include::modules/ossm-uninstalling-delete-istio-crds.adoc[leveloffset=+1] -[id="addition-resources_{context}"] -[id="additional-resources-ossm-uninstalling-openshift-service-mesh_{context}"] +[role="_additional-resources"] +[id="additional-resources_{context}"] == Additional resources * link:https://olm.operatorframework.io/docs/tasks/uninstall-operator/#step-4-deciding-whether-or-not-to-delete-the-crds-and-apiservices[Operator Lifecycle Management] \ No newline at end of file diff --git a/update/ossm-about-updating-openshift-service-mesh.adoc b/update/ossm-about-updating-openshift-service-mesh.adoc index 5d986d310f0..78c5cdb136d 100644 --- a/update/ossm-about-updating-openshift-service-mesh.adoc +++ b/update/ossm-about-updating-openshift-service-mesh.adoc @@ -1,4 +1,4 @@ -:_content-type: ASSEMBLY +:_mod-docs-content-type: ASSEMBLY [id="ossm-about-updating-openshift-service-mesh"] = About updating OpenShift Service Mesh include::_attributes/common-attributes.adoc[] @@ -21,7 +21,7 @@ include::modules/ossm-about-operator-update-process.adoc[leveloffset=+2] include::modules/ossm-about-istio-update-process.adoc[leveloffset=+2] [role="_additional-resources"] -[id="additional-resources-ossm-about-updating-openshift-service-mesh_{context}"] +[id="additional-resources_{context}"] == Additional resources * xref:../update/ossm-updating-openshift-service-mesh-in-ambient-mode.adoc#ossm-updating-openshift-service-mesh-in-ambient-mode[Updating OpenShift Service Mesh in ambient mode] diff --git a/update/ossm-updating-istio-cni.adoc b/update/ossm-updating-istio-cni.adoc index a55982da615..39a16e8b884 100644 --- a/update/ossm-updating-istio-cni.adoc +++ b/update/ossm-updating-istio-cni.adoc @@ -1,4 +1,4 @@ -:_content-type: ASSEMBLY +:_mod-docs-content-type: ASSEMBLY [id="ossm-updating-istio-cni"] = Updating the Istio CNI include::_attributes/common-attributes.adoc[] diff --git a/update/ossm-updating-openshift-service-mesh-in-ambient-mode.adoc b/update/ossm-updating-openshift-service-mesh-in-ambient-mode.adoc index 82e9ca94f08..77be4a587d1 100644 --- a/update/ossm-updating-openshift-service-mesh-in-ambient-mode.adoc +++ b/update/ossm-updating-openshift-service-mesh-in-ambient-mode.adoc @@ -1,9 +1,15 @@ -:_content-type: ASSEMBLY +:_mod-docs-content-type: ASSEMBLY [id="ossm-updating-openshift-service-mesh-in-ambient-mode"] = Updating OpenShift Service Mesh in ambient mode include::_attributes/common-attributes.adoc[] :context: ossm-updating-openshift-service-mesh-in-ambient-mode +include::_attributes/attributes-microshift.adoc[] +:context: ossm-updating-openshift-service-mesh-in-ambient-mode + +include::_attributes/attributes-openshift-dedicated.adoc[] +:context: ossm-updating-openshift-service-mesh-in-ambient-mode + toc::[] [role="_abstract"] @@ -12,6 +18,8 @@ Update {SMProductName} in ambient mode by transitioning the control plane and wa include::modules/ossm-about-update-strategies-in-ambient-mode.adoc[leveloffset=+1] +include::modules/ossm-nftables-migration-ambient.adoc[leveloffset=+1] + include::modules/ossm-updating-waypoint-proxies-with-inplace-strategy.adoc[leveloffset=+1] include::modules/ossm-updating-waypoint-proxies-with-revisionbased-strategy.adoc[leveloffset=+1] @@ -29,7 +37,7 @@ include::modules/ossm-configuring-ztunnel-grace-period.adoc[leveloffset=+2] include::modules/ossm-updating-ztunnel-with-node-draining.adoc[leveloffset=+2] [role="_additional-resources"] -[id="additional-resources-ossm-updating-openshift-service-mesh-in-ambient-mode_{context}"] +[id="additional-resources_{context}"] == Additional resources * xref:../update/ossm-updating-openshift-service-mesh#ossm-updating-openshift-service-mesh[Updating OpenShift Service Mesh] diff --git a/update/ossm-updating-openshift-service-mesh.adoc b/update/ossm-updating-openshift-service-mesh.adoc index 5088e9d42f4..3f6be9ba099 100644 --- a/update/ossm-updating-openshift-service-mesh.adoc +++ b/update/ossm-updating-openshift-service-mesh.adoc @@ -1,4 +1,4 @@ -:_content-type: ASSEMBLY +:_mod-docs-content-type: ASSEMBLY [id="ossm-updating-openshift-service-mesh"] = Updating OpenShift Service Mesh include::_attributes/common-attributes.adoc[] @@ -33,8 +33,8 @@ include::modules/ossm-installing-istio-with-revisionbased-strategy-istiorevision include::modules/ossm-updating-istio-control-plane-with-revisionbased-istiorevisiontag.adoc[leveloffset=+2] [role="_additional-resources"] -[id="additional-resources-ossm-updating-openshift-service-mesh_{context}"] -.Additional resources +[id="additional-resources_{context}"] +== Additional resources * xref:../update/ossm-updating-openshift-service-mesh-in-ambient-mode#ossm-updating-waypoint-proxies-with-inplace-strategy_ossm-updating-openshift-service-mesh-in-ambient-mode[Updating waypoint proxies with InPlace strategy in ambient mode]