🤖 docs: rewrite the aggregated API server guide in plain English

[ThomasK33]

Summary

Rewrite docs/how-to/deploy-aggregated-apiserver.md in plain English. The text follows ASD-STE100 (Simplified Technical English) about 80% of the time: short sentences, active voice, simple tenses, conditions before commands, and lists instead of long joined sentences. Kubernetes terms, RBAC names, commands, and code stay as they were.

This is the fourth PR of a plain-English docs series (#164, #165, #166). It stands alone and is based on main.

Background

This page carries the security rules of the aggregated API server: delegated authentication, RBAC that is owner access in Coder, who can read the serving CA key, and how the server manages the APIService caBundle. Many of these rules sit in long sentences with semicolons and parentheses. One fact per sentence makes the rules easier to check and to translate.

Implementation

• Rewrote the prose only. All 14 code blocks and all headings are byte-identical to main (checked with a script). Anchors that other pages use (#how-callers-are-checked, #replace-the-ca, #opt-out, #how-kube-apiserver-trusts-the-server, #option-a-all-in-one-recommended, #option-b-standalone) still work.
• Split the long rules into lists: the two delegated-auth bindings and what happens without them, and the rights that RBAC on these resources gives in Coder. The upgrade warning about old copies of deploy/apiserver-apiservice.yaml is now its own paragraph.
• "may not" (in the sense "is not permitted to") is now "does not have permission to" or "cannot".
• No facts were added or removed. I found no stale claims on this page.

Validation

• make docs-check (strict mkdocs build), markdownlint-cli2 0.18.1, cspell 8.19.4, and lychee pass on the pushed commit.
• A separate read-only auditor compared every changed claim with the original text and the code (cache TTLs, certificate lifetimes and renewal, log rate and backoff, kubeconfig order, opt-out annotation value). It found no meaning changes. I applied its optional fixes: a pronoun that could point to the wrong ServiceAccount, "somewhere in the cluster", "If something fails", and one remaining "would".
• Built the site locally with mkdocs and took screenshots.

Before:

After:

Refs: no issue. Part of a plain-English docs pass.

---

Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: high

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-02T12:36:23.575695Z	7b9f265	PR opened
🔒 Security Review	✅ Completed 2026-10-02T12:47:55.284381Z	7b9f265	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[ThomasK33]

@codex security review

[chatgpt-codex-connector]

🛡️ Codex Security Review

Security review completed. No security issues were found in this pull request.

Reviewed commit: 7b9f265a4c

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.