In-place Upgrades
The istioctl upgrade
command performs an upgrade of Istio. Before performing the upgrade, it checks that the Istio installation meets the upgrade eligibility criteria. Also, it alerts the user if it detects any changes in the profile default values between Istio versions.
The upgrade command can also perform a downgrade of Istio.
See the istioctl
upgrade reference for all the options provided by the istioctl upgrade
command.
istioctl upgrade
is for in-place upgrade and not compatible with installations done with the --revision
flag. Upgrades of such installations will fail with an error.
Upgrade prerequisites
Before you begin the upgrade process, check the following prerequisites:
The installed Istio version is no more than one minor version less than the upgrade version. For example, 1.6.0 or higher is required before you start the upgrade process to 1.7.x.
Your Istio installation was installed using istioctl.
Upgrade steps
Traffic disruption may occur during the upgrade process. To minimize the disruption, ensure that at least two replicas of each component (except Citadel) are running. Also, ensure that PodDisruptionBudgets
are configured with a minimum availability of 1.
The commands in this section should be run using the new version of istioctl
which can be found in the bin/
subdirectory of the downloaded package.
Download the new Istio release and change directory to the new release directory.
Ensure that your Kubernetes configuration points to the cluster to upgrade:
$ kubectl config view
Begin the upgrade by running this command:
$ istioctl upgrade
If you installed Istio using the
-f
flag, for exampleistioctl install -f <IstioOperator-custom-resource-definition-file>
, then you must provide the same-f
flag value to theistioctl upgrade
command.If you installed Istio using
--set
flags, ensure that you pass the same--set
flags to upgrade, otherwise the customizations done with--set
will be reverted. For production use, the use of a configuration file instead of--set
is recommended.If you omit the
-f
flag, Istio upgrades using the default profile.After performing several checks,
istioctl
will ask you to confirm whether to proceed.istioctl
will in-place upgrade the Istio control plane and gateways to the new version and indicate the completion status.After
istioctl
completes the upgrade, you must manually update the Istio data plane by restarting any pods with Istio sidecars:$ kubectl rollout restart deployment
Downgrade prerequisites
Before you begin the downgrade process, check the following prerequisites:
Your Istio installation was installed using istioctl.
The Istio version you intend to downgrade to is no more than one minor version less than the installed Istio version. For example, you can downgrade to no lower than 1.6.0 from Istio 1.7.x.
Downgrade must be done using the
istioctl
binary version that corresponds to the Istio version that you intend to downgrade to. For example, if you are downgrading from Istio 1.7 to 1.6.5, useistioctl
version 1.6.5.
Steps to downgrade to a lower Istio version
You can use istioctl upgrade
to downgrade to a lower version of Istio. The steps are identical to the upgrade process described in the previous section, only using the istioctl
binary corresponding to the lower version (e.g., 1.6.5). When completed, Istio will be restored to the previously installed version.
Alternatively, istioctl install
can be used to install an older version of the Istio control plane, but is not recommended because it does not perform any checks. For example, default values applied to the cluster for a configuration profile may change without warning.
See also
Upgrade Istio by first running a canary deployment of a new control plane.
Managing Gateways with Multiple Revisions [Experimental]
Configuring and upgrading Istio with gateways (experimental).
Provision and manage DNS certificates in Istio.
A more secure way to manage Istio webhooks.
Demystifying Istio’s Sidecar Injection Model
De-mystify how Istio manages to plugin its data-plane components into an existing deployment.
Requirements of applications deployed in an Istio-enabled cluster.