diff --git a/modules/ossm-release-notes-3-0-deprecated-removed-features.adoc b/modules/ossm-release-notes-3-0-deprecated-removed-features.adoc new file mode 100644 index 000000000000..2c3bff2a8d72 --- /dev/null +++ b/modules/ossm-release-notes-3-0-deprecated-removed-features.adoc @@ -0,0 +1,26 @@ +//// +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-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-new-features.adoc b/modules/ossm-release-notes-3-0-new-features.adoc new file mode 100644 index 000000000000..78adbfbe68c1 --- /dev/null +++ b/modules/ossm-release-notes-3-0-new-features.adoc @@ -0,0 +1,115 @@ +//// +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-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/ossm-release-notes/snippets b/modules/snippets similarity index 100% rename from ossm-release-notes/snippets rename to modules/snippets diff --git a/ossm-release-notes/ossm-release-notes-assembly.adoc b/ossm-release-notes/ossm-release-notes-assembly.adoc index cdbfe658ca3e..0e3f0d124e7e 100644 --- a/ossm-release-notes/ossm-release-notes-assembly.adoc +++ b/ossm-release-notes/ossm-release-notes-assembly.adoc @@ -6,33 +6,30 @@ include::_attributes/common-attributes.adoc[] toc::[] -// Copied from OCP core file: making-open-source-more-inclusive.adoc -// Will make inclusive statement its own module for OSSM 3.0 GA. -include::modules/ossm-release-notes-making-open-source-inclusive.adoc[leveloffset=+1] +{SMProductName} release notes contain information about new features and enhancements, deprecated features, technology preview features, bug fixes, and known issues. They contain a set of tables for supported component versions and Istio features, and are organized by {SMProduct} version. +[NOTE] +==== +For additional information about the {SMProductName} life cycle and supported platforms, refer to the link:https://access.redhat.com/support/policy/updates/openshift_operators[{ocp-short-name} Operator Life Cycles]. +==== + +include::modules/ossm-release-notes-3-0-new-features.adoc[leveloffset=+1] include::modules/ossm-release-notes-3-0-known-issues.adoc[leveloffset=+1] +include::modules/ossm-release-notes-3-0-deprecated-removed-features.adoc[leveloffset=+1] -//Only GA rel notes should be visible for GA. Revisit post IA GA +//only GA release notes should appear since Service Mesh is versioned. Readdress in IA post GA. //include::snippets/technology-preview.adoc[] + //include::modules/ossm-release-3-0-TP-1.adoc[leveloffset=+1] -// commented out in case it is needed for GA -// [role="_additional-resources"] -// [id="additional-resources_{context}"] -// .Additional resources - -//Notes Oct 25, 2024 -//Troubleshooting Pantheon. All builds are failing and give the same generic error. -//Troubleshooting rel notes first. -//Removed 3.x from title of ossm-release-notes-assembly -//Removed attribute (again) from title -//Considered renaming title and corresponding subtitle in docinfo to: Release notes. Considered doing so for the sake of simplicity, however, Doc Peer Review and Doc Merge Review would likely require the title to be OpenShift Service Mesh release notes per style guidelines. If the other changes fail, will try "Release notes" as title anyway. -//Sentence case for subtitle in docinfo.xml to match sentence case title in ossm-release-notes-assembly -//Update version in docinfo.xml to be 3.0.0tp1 to match what Jenkins seems to be looking for -//The joys of setting something up in Pantheon for the first time. -//These notes will be removed once Pantheon build passes. - - -// This is OSSM 3.0 TP 1 content. Technology Preview banner is persistent and was handled by a separate PR from Tim O'Keefe. It has also been added to rel notes so users will see it twice: once at the top of the page, and again within rel notes. OCP writers suggested it should appear in rel notes, even if it means the user sees it twice. -// NOTE: the banner does not appear in preview. You can see it here: https://docs.openshift.com/service-mesh/3.0.0tp1/about/ossm-about-openshift-service-mesh.html -// Content may change, file names may change, directories may change, the order of directories may change, everything may change for OSSM 3.0 GA. \ No newline at end of file +[role="_additional-resources"] +[id="additional-resources-release-notes_{context}"] +== Additional resources + +* xref:../ossm-release-notes/ossm-release-notes-support-tables-assembly.adoc#ossm-release-notes-support-tables-assembly[Service Mesh 3.0 feature support tables] +* xref:../migrating/ossm-migrating-from-service-mesh-2-to-3-assembly.adoc#ossm-migrating-from-service-mesh-2-to-3[Migrating from {smproductshortname} 2 to {smproductshortname} 3] +* xref:../migrating/checklists/ossm-migrating-read-me-assembly.adoc#ossm-migrating-read-me-assembly[Important information to know if you are migrating from {SMProduct} 2.6] +* xref:../migrating/checklists/ossm-migrating-read-me-assembly.adoc#ossm-migrating-read-me-support-for-istioctl_ossm-migrating-read-me-assembly[Support for Istioctl] +* xref:../update/ossm-updating-openshift-service-mesh.adoc#about-revisionbased-strategy_ossm-performing-inplace-update[About RevisionBased strategy] +* xref:../observability/ossm-observability-service-mesh-assembly.adoc#ossm-observability-service-mesh-assembly[{observabilitylongname} and {smproductshortname}] +* xref:../observability/kiali/ossm-kiali-assembly.adoc#ossm-kiali-assembly[Using {kialiproduct}] \ No newline at end of file diff --git a/ossm-release-notes/snippets/deprecated-feature.adoc b/ossm-release-notes/snippets/deprecated-feature.adoc new file mode 100644 index 000000000000..e30dac75e985 --- /dev/null +++ b/ossm-release-notes/snippets/deprecated-feature.adoc @@ -0,0 +1,14 @@ +// When including this file, ensure that {FeatureName} is set immediately before +// the include. Otherwise it will result in an incorrect replacement. + +[IMPORTANT] +==== +[subs="attributes+"] +{FeatureName} is a deprecated feature. Deprecated functionality is still included in {product-title} and continues to be supported; however, it will be removed in a future release of this product and is not recommended for new deployments. + +ifndef::openshift-rosa,openshift-dedicated[] +For the most recent list of major functionality that has been deprecated or removed within {product-title}, refer to the _Deprecated and removed features_ section of the {product-title} release notes. +endif::openshift-rosa,openshift-dedicated[] +==== +// Undefine {FeatureName} attribute, so that any mistakes are easily spotted +:!FeatureName: diff --git a/ossm-release-notes/snippets/developer-preview.adoc b/ossm-release-notes/snippets/developer-preview.adoc new file mode 100644 index 000000000000..84e70cfd8d7e --- /dev/null +++ b/ossm-release-notes/snippets/developer-preview.adoc @@ -0,0 +1,11 @@ +// DO NOT USE THIS SNIPPET. DEVELOPER PREVIEW FEATURES ARE NOT DOCUMENTED IN CORE OPENSHIFT DOCS. + +// When including this file, ensure that {FeatureName} is set immediately before the include. Otherwise it will result in an incorrect replacement. + +[IMPORTANT] +==== +[subs="attributes+"] +{FeatureName} is a Developer Preview feature only. Developer Preview features are not supported by Red Hat in any way and are not functionally complete or production-ready. Do not use Developer Preview features for production or business-critical workloads. Developer Preview features provide early access to upcoming product features in advance of their possible inclusion in a Red Hat product offering, enabling customers to test functionality and provide feedback during the development process. These features might not have any documentation, are subject to change or removal at any time, and testing is limited. Red Hat might provide ways to submit feedback on Developer Preview features without an associated SLA. +==== +// Undefine {FeatureName} attribute, so that any mistakes are easily spotted +:!FeatureName: diff --git a/ossm-release-notes/snippets/ossm-out-of-support.adoc b/ossm-release-notes/snippets/ossm-out-of-support.adoc new file mode 100644 index 000000000000..3ecfd9fd9c96 --- /dev/null +++ b/ossm-release-notes/snippets/ossm-out-of-support.adoc @@ -0,0 +1,14 @@ +// Text snippet included in all Service Mesh v1 assemblies. +// NOTE: The OpenShift docs standards state that snippets should NOT contain xrefs. https://github.com/openshift/openshift-docs/blob/main/contributing_to_docs/doc_guidelines.adoc#writing-text-snippets +//Because this snippet contains two xrefs it should ONLY be used in the v1 assemblies and never in a module. + +:_mod-docs-content-type: SNIPPET + +[WARNING] +==== +*You are viewing documentation for a {SMProductName} release that is no longer supported.* + +Service Mesh version 1.0 and 1.1 control planes are no longer supported. For information about upgrading your service mesh control plane, see xref:../../service_mesh/v2x/upgrading-ossm.adoc#ossm-versions_ossm-upgrade[Upgrading Service Mesh]. + +For information about the support status of a particular {SMProductName} release, see the https://access.redhat.com/support/policy/updates/openshift#ossm[Product lifecycle page]. +==== diff --git a/ossm-release-notes/snippets/technology-preview.adoc b/ossm-release-notes/snippets/technology-preview.adoc new file mode 100644 index 000000000000..9c1acea0a89b --- /dev/null +++ b/ossm-release-notes/snippets/technology-preview.adoc @@ -0,0 +1,12 @@ +// When including this file, ensure that {FeatureName} is set immediately before +// the include. Otherwise it will result in an incorrect replacement. + +[IMPORTANT] +==== +[subs="attributes+"] +{FeatureName} 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]. +==== +// Undefine {FeatureName} attribute, so that any mistakes are easily spotted +:!FeatureName: