content/en/news/releases/1.5.x/announcing-1.5/upgrade-notes/index.md
This page describes changes you need to be aware of when upgrading from Istio 1.4.x to 1.5.x. Here, we detail cases where we intentionally broke backwards compatibility. We also mention cases where backwards compatibility was preserved but new behavior was introduced that would be surprising to someone familiar with the use and operation of Istio 1.4.
In Istio 1.5, we have moved towards a new deployment model for the control plane, with many components consolidated. The following describes where various functionality has been moved to.
In Istio 1.5, there will be a new deployment, istiod. This component is the core of the control plane, and will handle configuration and certificate distribution, sidecar injection, and more.
Previously, sidecar injection was handled by a mutating webhook that was processed by a deployment named istio-sidecar-injector. In Istio 1.5, the same mutating webhook remains, but it will now point to the istiod deployment. All injection logic remains the same.
istiod deployment.istio-galley deployment.istio-galley deployment.Previously, Citadel served two functions: writing certificates to secrets in each namespace, and serving secrets to the nodeagent over gRPC when SDS is used. In Istio 1.5, secrets are no longer written to each namespace. Instead, they are only served over gRPC. This functionality has been moved to the istiod deployment.
The nodeagent deployment has been removed. This functionality now exists in the Envoy sidecar.
Previously, the sidecar was able to access certificates in two ways: through secrets mounted as files, or over SDS (through the nodeagent deployment). In Istio 1.5, this has been simplified. All secrets will be served over a locally run SDS server. For most users, these secrets will be fetched from the istiod deployment. For users with a custom CA, file mounted secrets can still be used, however, these will still be served by the local SDS server. This means that certificate rotations will no longer require Envoy to restart.
There have been no changes to the deployment of istio-cni.
The istio-pilot deployment has been removed in favor of the istiod deployment, which contains all functionality that Pilot once had. For backwards compatibility, there are still some references to Pilot.
Mixer, the process behind the istio-telemetry and istio-policy deployments, has been deprecated with the 1.5 release. istio-policy was disabled by default since Istio 1.3 and istio-telemetry is disabled by default in Istio 1.5.
Telemetry is collected using an in-proxy extension mechanism (Telemetry V2) that does not require Mixer.
If you depend on specific Mixer features like out of process adapters, you may re-enable Mixer. Mixer will continue receiving bug fixes and security fixes until Istio 1.7. Many features supported by Mixer have alternatives as specified in the Mixer Deprecation document including the in-proxy extensions based on the WebAssembly sandbox API.
If you rely on a Mixer feature that does not have an equivalent, we encourage you to open issues and discuss in the community.
Please check Mixer Deprecation notice for details.
mtls.In Istio 1.5 proxy configuration for hosts is determined by VirtualService visibility in
addition to that of any relevant ServiceEntry.
If in previous versions you relied on Sidecar resources to
restrict the visibility of hosts (mesh internal or external) to a target set of sidecar proxies, you now also need to
consider the hosts implied by any VirtualService.
Depending on your use of Sidecar resources in your mesh, this may require
you to review the namespaces that your VirtualServices are in to
ensure only the intended workloads can see them.
More details on this change can be found at 24251 and 20408.
Istio 1.5 introduces PeerAuthentication and RequestAuthentication, which are replacing the alpha version of the Authentication API. For more information about how to use the new API, see the authentication policy tutorial.
PeerAuthentication and RequestAuthentication. The new policy will take over the old policy in the scope it is defined. We recommend starting with workload-wide (the most specific scope), then namespace-wide, and finally mesh-wide.{{< text bash >}} $ kubectl delete policies.authentication.istio.io --all-namespaces --all $ kubectl delete meshpolicies.authentication.istio.io --all {{< /text >}}
Automatic mutual TLS is now enabled by default. Traffic between sidecars is automatically configured as mutual TLS. You can disable this explicitly if you worry about the encryption overhead by adding the option -- set values.global.mtls.auto=false during install. For more details, refer to automatic mutual TLS.
As part of the Istiod effort, we have changed how proxies securely communicate with the control plane. In previous versions, proxies would connect to the control plane securely when the setting values.global.controlPlaneSecurityEnabled=true was configured, which was the default for Istio 1.4. Each control plane component ran a sidecar with Citadel certificates, and proxies connected to Pilot over port 15011.
In Istio 1.5, this is no longer the recommended or default way to connect the proxies with the control plane; instead, DNS certificates, which can be signed by Kubernetes or Istiod, will be used to connect to Istiod over port 15012.
Note: despite the naming, in Istio 1.5 when controlPlaneSecurityEnabled is set to false, communication between the control plane will be secure by default.
{{< warning >}} We recommend that you do not upgrade to Istio 1.5.0 if you are using a multicluster setup.
Istio 1.5.0 multicluster setup has several known issues (27102, 21676) that make it unusable in both shared control plane and replicated control plane deployments. These issues will be resolved in Istio 1.5.1. {{< /warning >}}
If you used helm upgrade to update your cluster to newer Istio versions, we recommend you to switch to use istioctl upgrade or follow the helm template steps.