Update upgrade steps for Istio 1.3

README.md

@@ -98,7 +98,7 @@ name for `istio.git` and `api.git` to point to the release branch. In this case
 1. Switch to the istio/istio.io repo and make sure everything is up to date.
 
 1. In the **master** branch, edit the file `data/args.yml`. Set the `version` and `full_version` fields to have the version
-of the next Istio release. In this case, you would set the fields to "0.8" and "0.8.0" respectively.
+of the next Istio release, and `previous_version` to be the version of the previous release. In this case, you would set the fields to "0.8", "0.8.0", and "0.7" respectively.
 
 1. In the **master** branch, edit the file `.mergify.yml`. Set the `branches` array to the name of the
 new release branch you just created.

content/en/docs/setup/upgrade/steps/index.md

@@ -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
@@ -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
+      --namespace istio-system | kubectl apply -f -
     {{< /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
-    {{< /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.
@@ -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:
@@ -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.

data/args.yml

@@ -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"
+
 # The year to display in copyright notices
 copyright_year: 2019
 

layouts/shortcodes/istio_previous_version.html

@@ -0,0 +1 @@
+{{ .Site.Data.args.previous_version }}