docs: describe current TLS behavior on the security page - #1187
Conversation
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: thc1006 The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
|
Hi @thc1006. Thanks for your PR. I'm waiting for a etcd-io member to verify that this patch is reasonable to test. If it is, they should reply with Regular contributors should join the org to skip this step. Once the patch is verified, the new status will be reflected by the I understand the commands that are listed here. DetailsInstructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
There was a problem hiding this comment.
Pull request overview
Updates the transport security documentation to describe current etcd TLS/DNS-SRV behavior (instead of a historical changelog), applied consistently across the active doc versions (v3.5–v3.7).
Changes:
- Rewrites “Notes for DNS SRV” to describe current peer
ServerName/SAN requirements when using--discovery-srv. - Replaces the historical TLS-auth section with current-behavior subsections for certificate reload, peer SAN verification flow, and CN/hostname allow-list flags (including mutual exclusivity).
- Removes outdated per-release narration and stale error/details in favor of present-tense descriptions.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| content/en/docs/v3.7/op-guide/security.md | Replaces historical DNS SRV / TLS auth notes with current-behavior explanations and examples. |
| content/en/docs/v3.6/op-guide/security.md | Same doc rewrite for v3.6 security page to match current behavior. |
| content/en/docs/v3.5/op-guide/security.md | Same doc rewrite for v3.5 security page to match current behavior. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ### Certificate reload | ||
|
|
||
| Since [v3.2.0](https://github.com/etcd-io/etcd/blob/main/CHANGELOG/CHANGELOG-3.2.md#v320-2017-06-09), [server denies incoming peer certs with wrong IP `SAN`](https://github.com/etcd-io/etcd/pull/7687). For instance, if peer cert contains any IP addresses in Subject Alternative Name (SAN) field, server authenticates a peer only when the remote IP address matches one of those IP addresses. This is to prevent unauthorized endpoints from joining the cluster. For example, peer B's CSR (with `cfssl`) is: | ||
| etcd reloads its TLS certificates on every new connection, so expiring certificates can be replaced without restarting the server: overwrite the certificate and key files in place, and subsequent connections use the new certificate. Reload also works for certificates whose Subject Alternative Name (SAN) field contains only IP addresses and no domain names. |
| ### Certificate reload | ||
|
|
||
| Since [v3.2.0](https://github.com/etcd-io/etcd/blob/main/CHANGELOG/CHANGELOG-3.2.md#v320-2017-06-09), [server denies incoming peer certs with wrong IP `SAN`](https://github.com/etcd-io/etcd/pull/7687). For instance, if peer cert contains any IP addresses in Subject Alternative Name (SAN) field, server authenticates a peer only when the remote IP address matches one of those IP addresses. This is to prevent unauthorized endpoints from joining the cluster. For example, peer B's CSR (with `cfssl`) is: | ||
| etcd reloads its TLS certificates on every new connection, so expiring certificates can be replaced without restarting the server: overwrite the certificate and key files in place, and subsequent connections use the new certificate. Reload also works for certificates whose Subject Alternative Name (SAN) field contains only IP addresses and no domain names. |
094f657 to
802cd1a
Compare
The transport security page documented TLS SAN matching, CN and hostname authentication, and certificate reload as a version-by-version changelog going back to v3.1, which is not useful to a current reader. Rewrite the "Notes for DNS SRV" and "Notes for TLS authentication" sections to describe what etcd does now: fold the per-release SAN paragraphs into one present-tense description, keep the CN and hostname matching details, and drop the outdated CHANGELOG and PR links. Apply the same rewrite to the active doc versions v3.5, v3.6, and v3.7. Fixes etcd-io#1185 Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>
802cd1a to
075d436
Compare
Summary
The "Notes for DNS SRV" and "Notes for TLS authentication" sections of the transport security
page were written as a version-by-version changelog going back to v3.1 (issue #1185). This
rewrites them to describe current behavior.
match first, then DNS reverse/forward lookup, with wildcard support.
--peer-cert-allowed-cn,--peer-cert-allowed-hostname,--client-cert-allowed-hostname), including the exact-match vsVerifyHostnamedistinction and the peer flags' mutual exclusivity.client certificate authentication failed(notCommonName authentication failed), and the SAN/remote-address check applies to peer connections.Applied to the active doc versions v3.5, v3.6, and v3.7 (48 insertions, 399 deletions).
Verified with
npm run buildandnpm run check-links(htmltest, internal). Technical claimswere checked against the etcd
release-3.6source and against a live etcd v3.6.13 cluster.Fixes #1185