linkerd / linkerd/website

Docs on automatic TLS rotation recommend settings that result in `linkerd check` warnings

Open
#1,502 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
60
Forks
221
Avg merge
4h 32m
Merged PRs (30d)
1

Description

The documentation for automatically rotating [control plane](https://linkerd.io/2.12/tasks/automatically-rotating-control-plane-tls-credentials/) and [webhook](https://linkerd.io/2.12/tasks/automatically-rotating-webhook-tls-credentials/) TLS credentials give recommended settings that result in certificates that are valid for only 48 or 24 hours, respectively.

This is perfectly fine (great, even), because cert manager will automatically manage issuing replacements (that's the whole point). However, it does mean that once you've set this up, `linkerd check` will always issue warning because your certificates have less than 60 days left before they expire, for example:

```
√ issuer cert is within its validity period
‼ issuer cert is valid for at least 60 days
issuer certificate will expire on 2022-09-24T13:35:07Z
see https://linkerd.io/2.12/checks/#l5d-identity-issuer-cert-not-expiring-soon for hints
```

The documentation should probably call out that this will be the case. Optionally, the documentation could instead recommend certificates that are valid for longer (61 days?) and get replaced when they have 60 days remaining, to avoid the warnings.

(I'm aware that the troubleshooting documentation linked in the warning says, "if you do not rely on external certificate management solution such as `cert-manager`..."; I'm referring to the docs about setting up the external certificate management in the first place)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the control-plane and webhook TLS rotation documentation linked in the issue, then review the certificate validity examples and the `linkerd check` warning they produce. Decide whether the pages should explain the expected warning or change the recommendation, and update both pages so the documented setup and its outcome are explicit.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.