Helm migration instructions for 2.12 (#1245)

* Helm migration instructions for 2.12 This updates the helm install instructions to account for the new charts as per linkerd/linkerd2#6635 and linkerd/linkerd2#6691 Also this adds a new section for 2.12 in `upgrade.md`, detailing the migration steps needed for the new charts. Co-authored-by: Matei David <matei@buoyant.io>
linkerd · Jan 10, 2022 · 5e56efc · 5e56efc
1 parent f188049
commit 5e56efc
Show file tree

Hide file tree

Showing 2 changed files with 134 additions and 72 deletions.
diff --git a/linkerd.io/content/2.12/tasks/install-helm.md b/linkerd.io/content/2.12/tasks/install-helm.md
@@ -18,118 +18,96 @@ to generate new ones.
 ## Adding Linkerd's Helm repository
 
 ```bash
-# To add the repo for Linkerd2 stable releases:
+# To add the repo for Linkerd stable releases:
 helm repo add linkerd https://helm.linkerd.io/stable
 
-# To add the repo for Linkerd2 edge releases:
+# To add the repo for Linkerd edge releases:
 helm repo add linkerd-edge https://helm.linkerd.io/edge
 ```
 
 The following instructions use the `linkerd` repo. For installing an edge
-release, just replace with `linkerd-edge`.
+release, just replace with `linkerd-edge`, and add the `--devel` flag to all
+commands.
 
 ## Helm install procedure
 
-```bash
-# set expiry date one year from now, in Mac:
-exp=$(date -v+8760H +"%Y-%m-%dT%H:%M:%SZ")
-# in Linux:
-exp=$(date -d '+8760 hour' +"%Y-%m-%dT%H:%M:%SZ")
+You need to install two separate charts in succession: first `linkerd-crds` and
+then `linkerd-control-plane`.
 
-helm install linkerd2 \
-  --set-file identityTrustAnchorsPEM=ca.crt \
-  --set-file identity.issuer.tls.crtPEM=issuer.crt \
-  --set-file identity.issuer.tls.keyPEM=issuer.key \
-  --set identity.issuer.crtExpiry=$exp \
-  linkerd/linkerd2
+### linkerd-crds
+
+The `linkerd-crds` chart sets up the CRDs linkerd requires:
+
+```bash
+helm install linkerd-crds -n linkerd --create-namespace linkerd/linkerd-crds
 ```
 
 {{< note >}}
-For Helm versions < v3, `--name` flag has to specifically be passed.
-In Helm v3, It has been deprecated, and is the first argument as
- specified above.
+This will create the `linkerd` namespace. If it already exists or you're
+creating it beforehand elsewhere in your pipeline, just omit the
+`--create-namespace` flag.
 {{< /note >}}
 
-The chart values will be picked from the chart's `values.yaml` file.
+### linkerd-control-plane
+
+The `linkerd-control-plane` chart sets up all the control plane components:
 
-You can override the values in that file by providing your own `values.yaml`
-file passed with a `-f` option, or overriding specific values using the family of
-`--set` flags like we did above for certificates.
+```bash
+helm install linkerd-control-plane \
+  -n linkerd \
+  --set-file identityTrustAnchorsPEM=ca.crt \
+  --set-file identity.issuer.tls.crtPEM=issuer.crt \
+  --set-file identity.issuer.tls.keyPEM=issuer.key \
+  linkerd/linkerd-control-plane
+```
 
 ## Disabling The Proxy Init Container
 
 If installing with CNI, make sure that you add the `--set
-cniEnabled=true` flag to your `helm install` command.
+cniEnabled=true` flag to your `helm install` command in both charts.
 
 ## Setting High-Availability
 
-The chart contains a file `values-ha.yaml` that overrides some
+`linkerd-control-plane` contains a file `values-ha.yaml` that overrides some
 default values as to set things up under a high-availability scenario, analogous
 to the `--ha` option in `linkerd install`. Values such as higher number of
-replicas, higher memory/cpu limits and affinities are specified in that file.
+replicas, higher memory/cpu limits and affinities are specified in those files.
 
-You can get ahold of `values-ha.yaml` by fetching the chart files:
+You can get ahold of `values-ha.yaml` by fetching the chart file:
 
 ```bash
-helm fetch --untar linkerd/linkerd2
+helm fetch --untar linkerd/linkerd-control-plane
 ```
 
 Then use the `-f` flag to provide the override file, for example:
 
 ```bash
-## see above on how to set $exp
-helm install linkerd2 \
+helm install linkerd-control-plane \
   --set-file identityTrustAnchorsPEM=ca.crt \
   --set-file identity.issuer.tls.crtPEM=issuer.crt \
   --set-file identity.issuer.tls.keyPEM=issuer.key \
-  --set identity.issuer.crtExpiry=$exp \
-  -f linkerd2/values-ha.yaml \
-  linkerd/linkerd2
+  -f linkerd-control-plane/values-ha.yaml \
+  linkerd/linkerd-control-plane
 ```
 
-{{< note >}}
-For Helm versions < v3, `--name` flag has to specifically be passed.
-In Helm v3, It has been deprecated, and is the first argument as
- specified above.
-{{< /note >}}
-
-## Customizing the Namespace
-
-To install Linkerd to a different namespace than the default `linkerd`,
-override the `Namespace` variable.
-
-By default, the chart creates the control plane namespace with the
-`config.linkerd.io/admission-webhooks: disabled` label. It is required for the
-control plane to work correctly. This means that the chart won't work with
-Helm v2's `--namespace` option.  If you're relying on a separate tool to create
-the control plane namespace, make sure that:
-
-1. The namespace is labeled with `config.linkerd.io/admission-webhooks: disabled`
-1. The `installNamespace` is set to `false`
-1. The `namespace` variable is overridden with the name of your namespace
-
-{{< note >}}
-In Helm v3 the `--namespace` option must be used with an existing namespace.
-{{< /note >}}
-
 ## Helm upgrade procedure
 
 Make sure your local Helm repos are updated:
 
 ```bash
 helm repo update
 
-helm search repo linkerd2
-NAME                    CHART VERSION          APP VERSION            DESCRIPTION
-linkerd/linkerd2        <chart-semver-version> {{% latestversion %}}    Linkerd gives you observability, reliability, and securit...
+helm search repo linkerd
+NAME                          CHART VERSION          APP VERSION              DESCRIPTION
+linkerd/linkerd-crds          <chart-semver-version>                          Linkerd gives you observability, reliability, and securit...
+linkerd/linkerd-control-plane <chart-semver-version> {{% latestversion %}}    Linkerd gives you observability, reliability, and securit...
 ```
 
 The `helm upgrade` command has a number of flags that allow you to customize
 its behaviour. The ones that special attention should be paid to are
 `--reuse-values` and `--reset-values` and how they behave when charts change
 from version to version and/or overrides are applied through `--set` and
-`--set-file`. To summarize there are the following prominent cases that can be
-observed:
+`--set-file`. To summarize these are prominent cases that can be observed:
 
 - `--reuse-values` with no overrides - all values are reused
 - `--reuse-values` with overrides - all except the values that are overridden
@@ -142,17 +120,22 @@ provided release are applied together with the overrides
 - no flag and overrides - `--reset-values` will be used by default
 
 Bearing all that in mind, you have to decide whether you want to reuse the
-values in the chart or move to the values specified in the newer chart.
-The advised practice is to use a `values.yaml` file that stores all custom
-overrides that you have for your chart. Before upgrade, check whether there
-are breaking changes to the chart (i.e. renamed or moved keys, etc). You can
-consult the [edge](https://hub.helm.sh/charts/linkerd2-edge/linkerd2) or the
-[stable](https://hub.helm.sh/charts/linkerd2/linkerd2) chart docs, depending on
-which one your are upgrading to. If there are, make the corresponding changes to
-your `values.yaml` file. Then you can use:
+values in the chart or move to the values specified in the newer chart.  The
+advised practice is to use a `values.yaml` file that stores all custom overrides
+that you have for your chart. Before upgrade, check whether there are breaking
+changes to the chart (i.e. renamed or moved keys, etc). You can consult the
+[edge](https://artifacthub.io/packages/helm/linkerd2/linkerd-control-plane#values)
+or the
+[stable](https://artifacthub.io/packages/helm/linkerd2-edge/linkerd-control-plane#values)
+chart docs, depending on which one your are upgrading to. If there are, make the
+corresponding changes to your `values.yaml` file. Then you can use:
 
 ```bash
-helm upgrade linkerd2 linkerd/linkerd2 --reset-values -f values.yaml --atomic
+# the linkerd-crds chart currently doesn't have a values.yaml file
+helm upgrade linkerd-crds linkerd/linkerd-crds
+
+# whereas linkerd-control-plane does
+helm upgrade linkerd-control-plane linkerd/linkerd-control-plane --reset-values -f values.yaml --atomic
 ```
 
 The `--atomic` flag will ensure that all changes are rolled back in case the

diff --git a/linkerd.io/content/2.12/tasks/upgrade.md b/linkerd.io/content/2.12/tasks/upgrade.md
@@ -13,6 +13,7 @@ Before starting, read through the version-specific upgrade notices below, which
 may contain important information you need to be aware of before commencing
 with the upgrade process:
 
+- [Upgrade notice: stable-2.12.0](#upgrade-notice-stable-2-12-0)
 - [Upgrade notice: stable-2.11.0](#upgrade-notice-stable-2-11-0)
 - [Upgrade notice: stable-2.10.0](#upgrade-notice-stable-2-10-0)
 - [Upgrade notice: stable-2.9.4](#upgrade-notice-stable-2-9-4)
@@ -149,8 +150,8 @@ your Kubernetes cluster, it is time to upgrade the data plane. The easiest
 way to do this is to run a rolling deploy on your services, allowing the
 proxy-injector to inject the latest version of the proxy as they come up.
 
-With `kubectl` 1.15+, this can be as simple as using the `kubectl rollout
-restart` command to restart all your meshed services. For example,
+This can be as simple as using the `kubectl rollout restart` command to restart
+all your meshed services. For example,
 
 ```bash
 kubectl -n <namespace> rollout restart deploy
@@ -190,6 +191,84 @@ Congratulation! You have successfully upgraded your Linkerd to the newer
 version. If you have any questions, feel free to raise them at the #linkerd2
 channel in the [Linkerd slack](https://slack.linkerd.io/).
 
+## Upgrade notice: stable-2.12.0
+
+The minimum Kubernetes version supported is `v1.20.0`.
+
+### Breaking changes in core Helm charts
+
+The `linkerd2` chart has been replaced by two charts: `linkerd-crds` and
+`linkerd-control-plane`. Please check the updated [Helm
+instructions](../install-helm/) for details. Also note that support for Helm v2
+has been dropped.
+
+Migrating to these new charts will incur in downtime for linkerd's control plane
+during the process, but as the proxies don't require the control plane to always
+be up, the data plane shouldn't incur in downtime. Just make sure you roll your
+data plane deployments after the control plane is updated, as explained in
+[upgrade the data plane](#upgrade-the-data-plane).
+
+Before proceeding, make sure you retrieve all your chart values customizations,
+in particular your trust root and issuer keys (`identityTrustAnchorsPEM`,
+`identity.issuer.tls.crtPEM` and `identity.issuer.tls.keyPEM`). These values
+will need to be fed again into the `helm install` command below for the
+`linkerd-control-plane` chart.
+
+To start the migration first find the namespace you used to store the previous
+linkerd chart helm config:
+
+```bash
+$ helm ls -A
+NAME    NAMESPACE       REVISION        UPDATED                                 STATUS          CHART           APP VERSION  
+linkerd default         1               2021-11-22 17:14:50.751436374 -0500 -05 deployed        linkerd2-2.11.1 stable-2.11.1
+```
+
+If you did use Helm's `--namespace` flag when you previously installed linkerd,
+then you should see that namespace reflected in the output above, and use it
+instead of `default` when deleting the chart:
+
+```bash
+helm delete -n default linkerd
+```
+
+Then install both new charts, one after the other:
+
+```bash
+# first make sure you update the helm repo
+helm repo up
+
+# now install the linkerd-crds chart
+helm install linkerd-crds -n linkerd --create-namespace linkerd/linkerd-crds
+
+# then install the linkerd-control-plane chart
+helm install linkerd-control-plane \
+  -n linkerd \
+  --set-file identityTrustAnchorsPEM=ca.crt \
+  --set-file identity.issuer.tls.crtPEM=issuer.crt \
+  --set-file identity.issuer.tls.keyPEM=issuer.key \
+  linkerd/linkerd-control-plane
+```
+
+### Breaking changes in extension Helm charts
+
+The main extensions (viz, multicluster, jaeger, linkerd2-cni) were also
+refactored, in that they no longer install their namespaces, leaving that to the
+`helm` command (or to a previous step in your CD pipeline), and they rely on an
+post-install hook to add the required metadata into that namespace. Therefore
+you also need to delete and reinstall them; for example for Linkerd-Viz:
+
+```bash
+# update the helm repo
+helm repo up
+
+# delete your current instance
+# (assuming you didn't use the -n flag when installing)
+helm delete linkerd-viz
+
+# install the new chart version
+helm install linkerd-viz -n linkerd-viz --create-namespace linkerd/linkerd-viz
+```
+
 ## Upgrade notice: stable-2.11.0
 
 The minimum Kubernetes version supported is `v1.17.0`. There are two breaking