Add ExternalName migration blog post to the sidebar (#1014)

* add migration blog post to the sidebar

* update intor

* Update docs/user/migration/external-name-alias.md

Co-authored-by: Małgorzata Świeca <[email protected]>

* add Gosia's suggestions

* apply Gosia's suggestions 2

* aff if

* replace the with a

* ExternalName

* add a

---------

Co-authored-by: Małgorzata Świeca <[email protected]>

docs/user/_sidebar.md

@@ -6,6 +6,7 @@
 * [Default Istio Setup](/istio/user/00-40-overview-istio-setup.md)
 * [Resource Configuration](/istio/user/00-50-resource-configuration.md)
 * [Istio Custom Resource](/istio/user/04-00-istio-custom-resource.md)
+* [ExternalName Migration Guide](/istio/user/migration/external-name-alias.md)
 * [Operation Guides](/istio/user/operation-guides/README.md)
   * [Check Istio Sidecar](/istio/user/operation-guides/02-10-check-if-sidecar-injection-is-enabled.md)
   * [Enable Istio Sidecar](/istio/user/operation-guides/02-20-enable-sidecar-injection.md)

docs/user/migration/external-name-alias.md

@@ -1,22 +1,21 @@
-# Migration Guide for External Name Alias's Behavior Change
+# Migration Guide for ExternalName Alias's Behavior Change
 
 ## Context
 
-Istio with 1.21 version has changed the behavior of the Service of type ExternalName.
-With the change, the Service of type ExternalName is treated as an alias of the Service that it points to.
-Istio introduced this change to align the way it handles the Service of type ExternalName with the Kubernetes behavior.
-Since it caused some issues for our users, we introduced a new annotation, **disable-external-name-alias**, to disable this change.
-However, use of this parameter is not recommended and if you are using it, please update your configuration according to the following points.
+To align with Kubernetes behavior, Istio 1.21 changed the behavior of Services of type ExternalName.
+A Service of this type is now treated as an alias of the Service that it points to.
+Since this caused some issues for SAP BTP, Kyma runtime users, the Istio module introduced a new annotation, **disable-external-name-alias**, to disable the change.
+However, this annotation has been deprecated. If you are using it, read this migration guide and update your resources' configuration accordingly.
 
 ## VirtualService
 
-According to [Istio 1.21 Upgrade Notes](https://istio.io/latest/news/releases/1.21.x/announcing-1.21/upgrade-notes/), the destination of a VirtualService cannot point to the Service of type ExternalName.
+According to [Istio 1.21 Upgrade Notes](https://istio.io/latest/news/releases/1.21.x/announcing-1.21/upgrade-notes/), the destination of a VirtualService cannot point to a Service of type ExternalName.
 The limitation exists in the traffic coming from the internal mesh clients.
 Upgrade notes for version 1.21 describe a migration path by creating a ServiceEntry, although in currently released Istio versions it has no effect.
-Routing to the Service of type ExternalName, which aliases another type of Service, will also not work.
-Instead, it has to point to the actual host aliased by the Service of type ExternalName.
+Routing to a Service of type ExternalName, which aliases another type of Service, will also not work.
+Instead, it must point to the actual host aliased by a Service of type ExternalName.
 
-The following configuration will not work:
+The following configuration will **not** work:
 
 ```yaml
 apiVersion: v1
@@ -80,11 +79,11 @@ Remember to test if the new configuration works as expected and fits all your ne
 
 ## DestinationRule
 
-DestinationRule cannot point to the Service of type ExternalName.
+DestinationRule cannot point to a Service of type ExternalName.
 If you have a DestinationRule that points to a Service of type ExternalName, update the DestinationRule to point to the actual host.
 To still have the possibility to apply some of the Istio features in the given situation, you can create a ServiceEntry for the external host.
 
-The following configuration will not work:
+The following configuration will **not** work:
 
 ```yaml
 apiVersion: v1
@@ -143,6 +142,6 @@ Remember to test if the new configuration works as expected and fits all your ne
 
 ## Service ExternalName Ports
 
-In the new behavior, Istio ignores the ports set in the Service of type ExternalName.
-In case you rely on them in any way, you must update your configuration to align with the new behavior.
-Since the solution heavily depends on the use case, it has to be adjusted to the particular case.
+In the new behavior, Istio ignores the ports set in a Service of type ExternalName.
+If you rely on them in any way, you must update your configuration to align with the new behavior.
+Since the solution heavily depends on the use case, it has to be adjusted to the particular case.