apiVersion: release-notes/v2
kind: bug-fix
area: traffic-management
issues:
  - 37331
releaseNotes:
  - |
    **Improved** support for `ExternalName` services. See Upgrade Notes for more information.
upgradeNotes:
  - title: "`ExternalName` support changes"
    content: |
      Kubernetes `ExternalName` `Service`s allow users to create new DNS entries. For example, you can create an `example` service
      that points to `example.com`. This is implemented by a DNS `CNAME` redirect.

      In Istio, the implementation of `ExternalName`, historically, was substantially different. Each `ExternalName` represented its own
      service, and traffic matching the service was sent to the configured DNS name.

      This caused a few issues:
      * Ports are required in Istio, but not in Kubernetes. This can result in broken traffic if ports are not configured as Istio expects, despite them working without Istio.
      * Ports not declared as `HTTP` would match *all* traffic on that port, making it easy to accidentally send all traffic on a port to the wrong place.
      * Because the destination DNS name is treated as opaque, we cannot apply Istio policies to it as expected. For example, if I point
        an external name at another in-cluster Service (for example, `example.default.svc.cluster.local`), mTLS would not be used.

      `ExternalName` support has been revamped to fix these problems. `ExternalName`s are now simply treated as aliases.
      Wherever we would match `Host: <concrete service>` we additionally will match `Host: <external name service>`.
      Note that the primary implementation of `ExternalName` -- DNS -- is handled outside of Istio in the Kubernetes DNS implementation, and remains unchanged.

      If you are using `ExternalName` with Istio, please be advised of the following behavioral changes:
      * The `ports` field is no longer needed, matching Kubernetes behavior. If it is set, it will have no impact.
      * `VirtualServices` that route to an `ExternalName` service will no longer work unless the referenced service exists (as a Service or ServiceEntry).
      * `DestinationRule` can no longer apply to `ExternalName` services. Instead, create rules where the `host` references service.

      To opt-out, the `ENABLE_EXTERNAL_NAME_ALIAS=false` environment variable can be set.

      Note: the same change was introduced in the previous release, but off by default. This release turns the flag on by default.
