Automatically Rotating Webhook TLS Credentials

    By default, when Linkerd is installed with the Linkerd CLI or with the Linkerd Helm chart, TLS credentials are automatically generated for all of the webhooks. If these certificates expire or need to be regenerated for any reason, performing a Linkerd upgrade (using the Linkerd CLI or using Helm) will regenerate them.

    This workflow is suitable for most users. However, if you need these webhook certificates to be rotated automatically on a regular basis, it is possible to use cert-manager to automatically manage them.

    As a first step, and create the namespaces that cert-manager will use to store its webhook-related resources. For simplicity, we suggest using the defaule namespace linkerd uses:

    Save the signing key pair as a Secret

    Next, we will use the tool, to create a signing key pair which will be used to sign each of the webhook certificates:

    1. step certificate create webhook.linkerd.cluster.local ca.crt ca.key \
    2.   --profile root-ca --no-password --insecure --san webhook.linkerd.cluster.local
    4. kubectl create secret tls webhook-issuer-tls --cert=ca.crt --key=ca.key --namespace=linkerd
    6. # ignore if not using the viz extension
    7. kubectl create secret tls webhook-issuer-tls --cert=ca.crt --key=ca.key --namespace=linkerd-viz
    9. # ignore if not using the jaeger extension
    10. kubectl create secret tls webhook-issuer-tls --cert=ca.crt --key=ca.key --namespace=linkerd-jaeger

    Issuing certificates and writing them to secrets

    Finally, we can create cert-manager “Certificate” resources which use the Issuers to generate the desired certificates:

    1. cat <<EOF | kubectl apply -f -
    2. apiVersion: cert-manager.io/v1
    3. kind: Certificate
    4. metadata:
    5.   name: linkerd-proxy-injector
    6.   namespace: linkerd
    7. spec:
    8.   secretName: linkerd-proxy-injector-k8s-tls
    9.   duration: 24h
    10.   renewBefore: 1h
    11.   issuerRef:
    12.     name: webhook-issuer
    13.     kind: Issuer
    14.   commonName: linkerd-proxy-injector.linkerd.svc
    15.   dnsNames:
    16.   - linkerd-proxy-injector.linkerd.svc
    17.   isCA: false
    18.   privateKey:
    19.     algorithm: ECDSA
    20.   usages:
    21.   - server auth
    22. ---
    23. apiVersion: cert-manager.io/v1
    24. kind: Certificate
    25. metadata:
    26.   name: linkerd-sp-validator
    27.   namespace: linkerd
    28.   secretName: linkerd-sp-validator-k8s-tls
    29.   duration: 24h
    30.   renewBefore: 1h
    31.   issuerRef:
    32.     name: webhook-issuer
    34.   commonName: linkerd-sp-validator.linkerd.svc
    35.   dnsNames:
    36.   - linkerd-sp-validator.linkerd.svc
    37.   isCA: false
    38.   privateKey:
    39.     algorithm: ECDSA
    40.   usages:
    41.   - server auth
    42. ---
    43. # ignore if not using the viz extension
    44. apiVersion: cert-manager.io/v1
    45. kind: Certificate
    46. metadata:
    47.   name: tap
    48.   namespace: linkerd-viz
    49. spec:
    50.   secretName: tap-k8s-tls
    51.   duration: 24h
    52.   renewBefore: 1h
    53.   issuerRef:
    54.     name: webhook-issuer
    55.     kind: Issuer
    56.   commonName: tap.linkerd-viz.svc
    57.   dnsNames:
    58.   - tap.linkerd-viz.svc
    59.   isCA: false
    60.   privateKey:
    61.     algorithm: ECDSA
    62.   usages:
    63.   - server auth
    64. ---
    65. # ignore if not using the viz extension
    66. apiVersion: cert-manager.io/v1
    67. kind: Certificate
    68. metadata:
    69.   name: linkerd-tap-injector
    70.   namespace: linkerd-viz
    71.   secretName: tap-injector-k8s-tls
    72.   duration: 24h
    73.   renewBefore: 1h
    74.   issuerRef:
    75.     name: webhook-issuer
    77.   commonName: tap-injector.linkerd-viz.svc
    78.   dnsNames:
    79.   - tap-injector.linkerd-viz.svc
    80.   isCA: false
    81.   privateKey:
    82.     algorithm: ECDSA
    83.   usages:
    84.   - server auth
    85. ---
    86. # ignore if not using the jaeger extension
    87. apiVersion: cert-manager.io/v1
    88. kind: Certificate
    89. metadata:
    90.   name: jaeger-injector
    91.   namespace: linkerd-jaeger
    92. spec:
    93.   secretName: jaeger-injector-k8s-tls
    94.   duration: 24h
    95.   renewBefore: 1h
    96.   issuerRef:
    97.     name: webhook-issuer
    98.     kind: Issuer
    99.   commonName: jaeger-injector.linkerd.svc
    100.   dnsNames:
    101.   - jaeger-injector.linkerd.svc
    102.   isCA: false
    103.   privateKey:
    104.     algorithm: ECDSA
    105.   usages:
    106.   - server auth
    107. EOF

    At this point, cert-manager can now use these Certificate resources to obtain TLS credentials, which are stored in the linkerd-proxy-injector-k8s-tls, linkerd-sp-validator-k8s-tls, tap-k8s-tls, tap-injector-k8s-tls and jaeger-injector-k8s-tls secrets respectively.

    Now we just need to inform Linkerd to consume these credentials.

    To configure Linkerd to use the credentials from cert-manager rather than generating its own, we generate a supplemental config file:

    1. linkerd install --values=config.yml | kubectl apply -f -
    3. # ignore if not using the viz extension
    4. linkerd viz install --values=config-viz.yml | kubectl apply -f -
    6. # ignore if not using the jaeger extension

    Installing with Helm

    For Helm installation, we can configure the Helm values directly:

    Note

    When installing Linkerd with Helm, you must also provide the issuer trust root and issuer credentials as described in Installing Linkerd with Helm.

    Note

    See for details on how to do something similar for control plane credentials.