apiVersion: release-notes/v2
kind: bug-fix
area: installation
issue:
- 25933

releaseNotes:
- |
  **Added** port 15012 to the default list of ports for the `istio-ingressgateway` Service.
- |
  **Deprecated** installation flags `values.global.meshExpansion.enabled` in favor of user-managed config and `values.gateways.istio-ingressgateway.meshExpansionPorts` in favor of `components.ingressGateways[name=istio-ingressgateway].k8s.service.ports`

upgradeNotes:
- title: Avoid use of mesh expansion installation flags
  content: |
    To ease setup for multicluster and virtual machines while giving more control to users, the `meshExpansion` and `meshExpansionPorts` installation flags have been deprecated, and port 15012 has been added to the default list of ports for the `istio-ingressgateway` Service.

    For users with `values.global.meshExpansion.enabled=true`, perform the following steps before upgrading Istio:

    1. Apply the code sample for exposing Istiod through ingress.

       {{< text bash >}}
       $ kubectl apply -f @samples/istiod-gateway/istiod-gateway.yaml@
       {{< /text >}}

       This removes `operator.istio.io/managed` labels from the associated Istio networking resources so that the Istio installer won't delete them. After this step, you can modify these resources freely.

    1. If `components.ingressGateways[name=istio-ingressgateway].k8s.service.ports` is overridden, add port 15012 to the list of ports:

       {{< text yaml >}}
            - port: 15012
              targetPort: 15012
              name: tcp-istiod
       {{< /text >}}

    1. If `values.gateways.istio-ingressgateway.meshExpansionPorts` is set, move all ports to `components.ingressGateways[name=istio-ingressgateway].k8s.service.ports` if they're not already present. Then, unset this value.

    1. Unset `values.global.meshExpansion.enabled`.
