Overview

This article describes the installation of Linkerd using Helm in conjunction with Flux and Cert-Manager for TLS certificate rotation. The Cert-Manager will manage the default configurations for certificates, while Flux will handle the deployment of Linkerd.

Helm Release Configuration

The following configuration is used to define the Helm release for Linkerd:

apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
  name: linkerd
  namespace: linkerd
spec:
  interval: 5m
  values:
    identity.issuer.scheme: kubernetes.io/tls
    installNamespace: false
  valuesFrom:
  - kind: Secret
    name: linkerd-trust-anchor
    valuesKey: tls.crt
    targetPath: identityTrustAnchorsPEM
  chart:
    spec:
      chart: linkerd2
      version: "2.11.2"
      sourceRef:
        kind: HelmRepository
        name: linkerd
        namespace: linkerd
      interval: 1m

Helm Repository Source

To define the Helm repository from which Linkerd will be installed, use the following configuration:

apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: HelmRepository
metadata:
  name: linkerd
  namespace: linkerd
spec:
  interval: 5m0s
  url: https://helm.linkerd.io/stable

Trust Anchor Secret

Create a Kubernetes secret to hold the trust anchor certificate:

apiVersion: v1
data:
  tls.crt: base64encoded
  tls.key: base64encoded
kind: Secret
metadata:
  name: linkerd-trust-anchor
  namespace: linkerd
type: kubernetes.io/tls

This secret can be generated using the following command:

step certificate create root.linkerd.cluster.local ca.crt ca.key \
  --profile root-ca --no-password --insecure

Issuer and Certificate Configuration

Define the Issuer and Certificate for Linkerd's identity management:

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: linkerd-trust-anchor
  namespace: linkerd
spec:
  ca:
    secretName: linkerd-trust-anchor
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: linkerd-identity-issuer
  namespace: linkerd
spec:
  secretName: linkerd-identity-issuer
  duration: 48h
  renewBefore: 25h
  issuerRef:
    name: linkerd-trust-anchor
    kind: Issuer
  commonName: identity.linkerd.cluster.local
  dnsNames:
  - identity.linkerd.cluster.local
  isCA: true
  privateKey:
    algorithm: ECDSA
  usages:
  - cert sign
  - crl sign
  - server auth
  - client auth

Troubleshooting Common Errors

If you encounter the following error during reconciliation:

Helm install failed: execution error at (linkerd2/templates/identity.yaml:19:21): Please provide the identity issuer certificate

This may indicate that the identity issuer certificate is not being correctly referenced. You can verify the configuration by manually installing Linkerd with:

helm install linkerd2 \
--set-file identityTrustAnchorsPEM=ca.crt \
--set identity.issuer.scheme=kubernetes.io/tls \
--set installNamespace=false linkerd/linkerd2 \
-n linkerd

Alternatively, if you set up the configuration without Cert-Manager, ensure that the secrets are defined correctly:

valuesFrom:
  - kind: Secret
    name: linkerd-trust-anchor
    valuesKey: tls.crt
    targetPath: identityTrustAnchorsPEM
  - kind: Secret
    name: linkerd-identity-issuer-2
    valuesKey: tls.crt
    targetPath: identity.issuer.tls.crtPEM
  - kind: Secret
    name: linkerd-identity-issuer-2
    valuesKey: tls.key
    targetPath: identity.issuer.tls.keyPEM

Conclusion

By following the configurations outlined above, you should be able to successfully deploy Linkerd with automated TLS management using Cert-Manager. If issues persist, ensure that all secrets and configurations are correctly set up and troubleshoot based on the error messages received.