Installing Linkerd with Helm

Linkerd can optionally be installed via Helm rather than with the linkerd install command.

Prerequisite: identity certificates

The identity component of Linkerd requires setting up a trust anchorcertificate, and an issuer certificate with its key. These must use the ECDSAP-256 algorithm and need to be provided to Helm by the user (unlike when usingthe linkerd install CLI which can generate these automatically). You canprovide your own, or follow these instructionsto generate new ones.

Adding Linkerd's Helm repository

  1. # To add the repo for Linkerd2 stable releases:
  2. helm repo add linkerd https://helm.linkerd.io/stable
  4. # To add the repo for Linkerd2 edge releases:
  5. helm repo add linkerd-edge https://helm.linkerd.io/edge

The following instructions use the linkerd repo. For installing an edgerelease, just replace with linkerd-edge.

Helm install procedure

  1. # set expiry date one year from now, in Mac:
  2. exp=$(date -v+8760H +"%Y-%m-%dT%H:%M:%SZ")
  3. # in Linux:
  4. exp=$(date -d '+8760 hour' +"%Y-%m-%dT%H:%M:%SZ")
  6. helm install \
  7.   --name=linkerd2 \
  8.   --set-file global.identityTrustAnchorsPEM=ca.crt \
  9.   --set-file identity.issuer.tls.crtPEM=issuer.crt \
  10.   --set-file identity.issuer.tls.keyPEM=issuer.key \
  11.   --set identity.issuer.crtExpiry=$exp \
  12.   linkerd/linkerd2

The chart values will be picked from the chart's values.yaml file.

You can override the values in that file by providing your own values.yamlfile passed with a -f option, or overriding specific values using the family of—set flags like we did above for certificates.

Disabling The Proxy Init Container

If installing with CNI, make sure that you add the —set global.cniEnabled=true flag to your helm install command.

Setting High-Availability

The chart contains a file values-ha.yaml that overrides somedefault values as to set things up under a high-availability scenario, analogousto the —ha option in linkerd install. Values such as higher number ofreplicas, higher memory/cpu limits and affinities are specified in that file.

You can get ahold of values-ha.yaml by fetching the chart files:

  1. helm fetch --untar linkerd/linkerd2

Then use the -f flag to provide the override file, for example:

  1. ## see above on how to set $exp
  2. helm install \
  3.   --name=linkerd2 \
  4.   --set-file global.identityTrustAnchorsPEM=ca.crt \
  5.   --set-file identity.issuer.tls.crtPEM=issuer.crt \
  6.   --set-file identity.issuer.tls.keyPEM=issuer.key \
  7.   --set identity.issuer.crtExpiry=$exp \
  8.   -f linkerd2/values-ha.yaml \
  9.   linkerd/linkerd2

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 theconfig.linkerd.io/admission-webhooks: disabled label. It is required for thecontrol plane to work correctly. This means that the chart won't work withHelm v2's —namespace option. If you're relying on a separate tool to createthe control plane namespace, make sure that:

  • The namespace is labeled with linkerd.io/admission-webhooks: disabled
  • The InstallNamespace is set to false
  • The Namespace variable is overridden with the name of your namespace

NoteIn Helm v3 the —namespace option must be used with an existing namespace.

Helm upgrade procedure

Make sure your local Helm repos are updated:

  1. helm repo update
  3. helm search linkerd2 -v stable-2.7.0
  4. NAME                    CHART VERSION          APP VERSION            DESCRIPTION
  5. linkerd/linkerd2        <chart-semver-version> stable-2.7.0    Linkerd gives you observability, reliability, and securit...

The helm upgrade command has a number of flags that allow you to customizeits behaviour. The ones that special attention should be paid to are—reuse-values and —reset-values and how they behave when charts changefrom version to version and/or overrides are applied through —set and—set-file. To summarize there are the following prominent cases that can beobserved:

  • —reuse-values with no overrides - all values are reused
  • —reuse-values with overrides - all except the values that are overriddenare reused
  • —reset-values with no overrides - no values are reused and all changesfrom provided release are applied during the upgrade
  • —reset-values with overrides - no values are reused and changed fromprovided release are applied together with the overrides
  • no flag and no overrides - —reuse-values will be used by default
  • 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 thevalues 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 customoverrides that you have for your chart. Before upgrade, check whether thereare breaking changes to the chart (i.e. renamed or moved keys, etc). You canconsult the edge or thestable chart docs, depending onwhich one your are upgrading to. If there are, make the corresponding changes toyour values.yaml file. Then you can use:

  1. helm upgrade linkerd2 linkerd/linkerd2 --reset-values -f values.yaml --atomic

The —atomic flag will ensure that all changes are rolled back in case theupgrade operation fails