Linkerd Helm docs

Helm.md

Helm chart

The main Linkerd2 chart is located under charts/linkerd2. It depends on the chart under charts/partials. The chart under charts/patch is only used internally for the sidecar proxy injection.

Helm CLI

The charts are installed and managed with the Helm CLI, but we encourage you to use bin/helm which is a wrapper around it; it will download and use a specific version of the CLI with which the official chart has already been tested.

Certificates creation

The identity component of Linkerd requires setting up a trust anchor certificate, and an issuer certificate and key. These need to be provided to Helm by the user (unlike when using linkerd install which can generate these automatically).

You can do this with a tool like openssl or step. We'll provide here instructions for step.

step certificate create identity.linkerd.cluster.local ca.crt ca.key --profile root-ca --no-password --insecure
step certificate create identity.linkerd.cluster.local issuer.crt issuer.key --ca ca.crt --ca-key ca.key --profile intermediate-ca --not-after 2020-10-02T10:00:00Z --no-password --insecure

This will generate the trust root (ca.crt), the issuer certificate (issuer.crt) and the issuer key (issuer.key).

We use --no-password --insecure to avoid encrypting these files with a passphrase. Also note that the expiration time (--not-after) should be in RFC-3339 format.

Setting up the dependencies

Before installing the chart, make sure you update the dependencies:

bin/helm dependency update charts/linkerd2

This creates the file charts/linkerd2/charts/partials-0.1.0.tgz that consolidates the charts/partials chart.

Installing the chart

Then you can install the chart, pointing to the certificates and keys you created above, and using the same expiration time you used to create those certificates:

bin/helm install --set-file Identity.TrustAnchorsPEM=ca.crt --set-file Identity.Issuer.TLS.CrtPEM=issuer.crt --set-file Identity.Issuer.TLS.KeyPEM=issuer.key --set Identity.Issuer.CrtExpiry=2020-10-02T10:00:00Z charts/linkerd2

The chart parameters ("values" in Helm parlance) will be picked from the default values.yaml file located under charts/linkerd2.

You can customize the chart by overriding 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 for certificates.

Setting High-Availability

Also under charts/linkerd2 there's a file values-ha.yaml that overrides some default values as to set things up under a high-availability scenario. Values such as higher number of replicas, higher memory/cpu limits and affinities are specified in that file.

Like explained before, use the -f to provide the override file:

bin/helm install --set-file Identity.TrustAnchorsPEM=ca.crt --set-file Identity.Issuer.TLS.CrtPEM=issuer.crt --set-file Identity.Issuer.TLS.KeyPEM=issuer.key --set Identity.Issuer.CrtExpiry=2020-10-02T10:00:00Z -f charts/linkerd2/values-ha.yaml charts/linkerd2

Making changes to the charts

You can further customize the charts by actually editing their templates (located under the corresponding templates subdirectory). Whenever you make changes make sure you update the dependencies as explained above, and then verify the chart is well formed:

bin/helm lint --set Identity.TrustAnchorsPEM="fake-trust" --set Identity.Issuer.TLS.CrtPEM="fake-cert" --set Identity.Issuer.TLS.KeyPEM="fake-key" --set Identity.Issuer.CrtExpiry="fake-expiry-date" charts/linkerd2

For linting purposes you can use fake values for the certificates.