Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update upgrade steps for Istio 1.3 #4890

Merged
merged 2 commits into from Sep 3, 2019
Merged

Update upgrade steps for Istio 1.3 #4890

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d656faa
Update upgrade steps for Istio 1.3
howardjohn Sep 3, 2019
6bdaa6a
updates
howardjohn Sep 3, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
204 changes: 13 additions & 191 deletions content/en/docs/setup/upgrade/steps/index.md
View file
Open in desktop
Expand Up @@ -12,25 +12,16 @@ control plane and the sidecar proxies, to a new release of Istio. The upgrade
process may install new binaries and may change configuration and API schemas.
The upgrade process may result in service downtime. To minimize downtime,
please ensure your Istio control plane components and your applications are
highly available with multiple replicas (as multi-replica Citadel is still
under development, Citadel should be deployed with one replica).

{{< warning >}}
Citadel does not support multiple instances. Running multiple Citadel instances
may introduce race conditions and lead to system outages.
{{< /warning >}}

This flow assumes that the Istio components are installed and upgraded in the
`istio-system` namespace.
highly available with multiple replicas.

{{< warning >}}
Be sure to check out the [upgrade notice](/docs/setup/upgrade/notice)
for a concise list of things you should know before upgrading your deployment to Istio 1.2.
for a concise list of things you should know before upgrading your deployment to Istio {{< istio_version >}}.
{{< /warning >}}

{{< tip >}}
Istio does **NOT** support skip level upgrades. Only upgrades from 1.1 to 1.2
are supported. If you are on an older version, please upgrade to 1.1 first.
Istio does **NOT** support skip level upgrades. Only upgrades from {{< istio_previous_version >}} to {{< istio_version >}}
are supported. If you are on an older version, please upgrade to {{< istio_previous_version >}} first.
{{< /tip >}}

## Upgrade steps
Expand Down Expand Up @@ -58,14 +49,14 @@ This is suitable for cases where `kubectl apply` was used to deploy Istio CNI.
$ NAMESPACE=$(kubectl get pods -l k8s-app=istio-cni-node --all-namespaces --output='jsonpath={.items[0].metadata.namespace}')
{{< /text >}}

1. If `istio-cni` is currently installed in a namespace other than `kube-system`
2. If `istio-cni` is currently installed in a namespace other than `kube-system`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please leave numbered lists with 1. The right numbers will be inserted automatically when the page is generated.

(for example, `istio-system`), delete `istio-cni`:

{{< text bash >}}
$ helm template install/kubernetes/helm/istio-cni --name=istio-cni --namespace=$NAMESPACE | kubectl delete -f -
{{< /text >}}

1. Install or upgrade `istio-cni` in the `kube-system` namespace:
3. Install or upgrade `istio-cni` in the `kube-system` namespace:

{{< text bash >}}
$ helm template install/kubernetes/helm/istio-cni --name=istio-cni --namespace=kube-system | kubectl apply -f -
Expand Down Expand Up @@ -136,34 +127,14 @@ including configurations generated using

1. {{< boilerplate verify-crds >}}

1. Add Istio's core components to a Kubernetes manifest file, for example.
1. Apply the update templates:

{{< text bash >}}
$ helm template install/kubernetes/helm/istio --name istio \
--namespace istio-system > $HOME/istio.yaml
{{< /text >}}

If you want to enable [global mutual TLS](/docs/concepts/security/#mutual-tls-authentication),
set `global.mtls.enabled` and `global.controlPlaneSecurityEnabled` to `true` for the last command:

{{< text bash >}}
$ helm template install/kubernetes/helm/istio --name istio --namespace istio-system \
--set global.mtls.enabled=true --set global.controlPlaneSecurityEnabled=true > $HOME/istio-auth.yaml
{{< /text >}}

If Istio CNI is installed, enable it by adding the `--set istio_cni.enabled=true` setting.

1. Upgrade the Istio control plane components via the manifest, for example:

{{< text bash >}}
$ kubectl apply -f $HOME/istio.yaml
--namespace istio-system | kubectl apply -f -
{{< /text >}}

or

{{< text bash >}}
$ kubectl apply -f $HOME/istio-auth.yaml
{{< /text >}}
You must pass the same settings as when you first [installed Istio](/docs/setup/install/helm).

The rolling update process will upgrade all deployments and configmaps to the new version.
After this process finishes, your Istio control plane should be updated to the new version.
Expand All @@ -182,9 +153,9 @@ the preferred upgrade option is to let Helm take care of the upgrade.
$ helm upgrade --install --force istio-init install/kubernetes/helm/istio-init --namespace istio-system
{{< /text >}}

1. {{< boilerplate verify-crds >}}
2. {{< boilerplate verify-crds >}}

1. Upgrade the `istio` chart:
3. Upgrade the `istio` chart:

{{< text bash >}}
$ helm upgrade istio install/kubernetes/helm/istio --namespace istio-system
Expand All @@ -202,12 +173,10 @@ still be using an older sidecar. To upgrade the sidecar, you will need to re-inj

If you're using automatic sidecar injection, you can upgrade the sidecar
by doing a rolling update for all the pods, so that the new version of the
sidecar will be automatically re-injected. There are some tricks to reload
all pods. E.g. There is a sample [bash script](https://github.com/truongnh1992/playing-with-istio/blob/master/upgrade-sidecar.sh)
which triggers the rolling update by patching the grace termination period.
sidecar will be automatically re-injected.

{{< text bash >}}
$ ./upgrade-sidecar.sh $namespace
$ kubectl rollout restart deployment --namespace default
{{< /text >}}

If you're using manual injection, you can upgrade the sidecar by executing:
Expand All @@ -225,150 +194,3 @@ $ kubectl apply -f <(istioctl kube-inject \
--injectConfigFile inject-config.yaml \
--filename $ORIGINAL_DEPLOYMENT_YAML)
{{< /text >}}

## Migrating per-service mutual TLS enablement via annotations to authentication policy

If you use service annotations to override global mutual TLS enablement for a service, you need to replace it with
[authentication policy](/docs/concepts/security/#authentication-policies) and [destination rules](/docs/concepts/traffic-management/#destination-rules).

For example, if you install Istio with mutual TLS enabled, and disable it for service `foo` using a service annotation like below:

{{< text yaml >}}
kind: Service
metadata:
name: foo
namespace: bar
annotations:
auth.istio.io/8000: NONE
{{< /text >}}

You need to replace this with this authentication policy and destination rule (deleting the old annotation is optional)

{{< text yaml >}}
apiVersion: "authentication.istio.io/v1alpha1"
kind: "Policy"
metadata:
name: "disable-mTLS-foo"
namespace: bar
spec:
targets:
- name: foo
ports:
- number: 8000
peers:
---
apiVersion: "networking.istio.io/v1alpha3"
kind: "DestinationRule"
metadata:
name: "disable-mTLS-foo"
namespace: "bar"
spec:
host: "foo"
trafficPolicy:
tls:
mode: ISTIO_MUTUAL
portLevelSettings:
- port:
number: 8000
tls:
mode: DISABLE
{{< /text >}}

If you already have destination rules for `foo`, you must edit that rule instead of creating a new one.
When create a new destination rule, make sure to include other settings, i.e `load balancer`, `connection pool` and `outlier detection` if necessary.
Finally, If `foo` doesn't have sidecar, you can skip authentication policy, but still need to add destination rule.

If 8000 is the only port that service `foo` provides (or you want to disable mutual TLS for all ports), the policies can be simplified as:

{{< text yaml >}}
apiVersion: "authentication.istio.io/v1alpha1"
kind: "Policy"
metadata:
name: "disable-mTLS-foo"
namespace: bar
spec:
targets:
- name: foo
peers:
---
apiVersion: "networking.istio.io/v1alpha3"
kind: "DestinationRule"
metadata:
name: "disable-mTLS-foo"
namespace: "bar"
spec:
host: "foo"
trafficPolicy:
tls:
mode: DISABLE
{{< /text >}}

## Migrating the `mtls_excluded_services` configuration to destination rules

If you installed Istio with mutual TLS enabled, and used the mesh configuration option `mtls_excluded_services` to
disable mutual TLS when connecting to these services (e.g Kubernetes API server), you need to replace this by adding a destination rule. For example:

{{< text yaml >}}
apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
name: "kubernetes-master"
namespace: "default"
spec:
host: "kubernetes.default.svc.cluster.local"
trafficPolicy:
tls:
mode: DISABLE
{{< /text >}}

## Migrating from `RbacConfig` to `ClusterRbacConfig`

The `RbacConfig` is deprecated due to a [bug](https://github.com/istio/istio/issues/8825). You must
migrate to `ClusterRbacConfig` if you are currently using `RbacConfig`. The bug reduces the scope of
the object to be namespace-scoped in some cases. The `ClusterRbacConfig` follows the exact same
specification as the `RbacConfig` but with the correct cluster scope implementation.

To automate the migration, we developed the `convert_RbacConfig_to_ClusterRbacConfig.sh` script.
The script is included in the [Istio installation package](/docs/setup/#downloading-the-release).

Download and run the script with the following command:

{{< text bash >}}
$ curl -L {{< github_file >}}/tools/convert_RbacConfig_to_ClusterRbacConfig.sh | sh -
{{< /text >}}

The script automates the following operations:

1. The script creates the cluster RBAC configuration with same specification as the existing RBAC configuration
because Kubernetes doesn't allow the value of `kind:` in a custom resource to change after it's created.

For example, if you have the following RBAC configuration:

{{< text yaml >}}
apiVersion: "rbac.istio.io/v1alpha1"
kind: RbacConfig
metadata:
name: default
spec:
mode: 'ON_WITH_INCLUSION'
inclusion:
namespaces: ["default"]
{{< /text >}}

The script creates the following cluster RBAC configuration:

{{< text yaml >}}
apiVersion: "rbac.istio.io/v1alpha1"
kind: ClusterRbacConfig
metadata:
name: default
spec:
mode: 'ON_WITH_INCLUSION'
inclusion:
namespaces: ["default"]
{{< /text >}}

1. The script applies the configuration and waits for a few seconds to let the configuration to take effect.

1. The script deletes the previous RBAC configuration custom resource after applying the cluster RBAC
configuration successfully.
3 changes: 3 additions & 0 deletions data/args.yml
View file
Open in desktop
Expand Up @@ -4,6 +4,9 @@ version: "1.3"
# The full Istio version identifier the docs describe
full_version: "1.3.0"

# The previous Istio version identifier the docs describe, used for upgrade documentation
previous_version: "1.2"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In order to reference this symbol from markdown files, you need to add a shortcode definition in layouts/shortcodes.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You should also update the release instructions in README.md to indicate this field needs to be updated when creating a new release.


# The year to display in copyright notices
copyright_year: 2019

Expand Down