Upgrade Notes

Important changes to consider when upgrading to Istio 1.5.

Mar 5, 2020

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.

Control Plane Restructuring

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.

Istiod

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.

Sidecar injection

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.

Galley

Citadel

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.

SDS Node Agent

The nodeagent deployment has been removed. This functionality now exists in the Envoy sidecar.

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.

CNI

There have been no changes to the deployment of istio-cni.

Pilot

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 deprecation

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.

Feature gaps between Telemetry V2 and Mixer Telemetry

Traffic management resource visibility changes

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.

Authentication policy

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.

$ kubectl delete policies.authentication.istio.io --all-namespaces --all
$ kubectl delete meshpolicies.authentication.istio.io --all

Istio workload key and certificate provisioning

Automatic mutual TLS

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.

Control plane security

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.

Multicluster setup

Helm upgrade

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.