docs: add developer guide for cluster access with kubectl #patch#479
Merged
Conversation
Adds an end-user guide covering kubectl/krew/oidc-login prerequisites, creating the kubeconfig from the cluster-info page, GitHub device-code sign-in, the three access tiers (reader/debugger/operator), and namespace-scoped access with troubleshooting. Adds a CAPTAIN_NAMESPACE sentinel to the swizzled CodeBlock so commands render with the reader's environment namespace (the first label of the Captain Domain), and a CSS rule so an inline CaptainDomain inside a code chip blends into a single monospace token. Supersedes the operator-focused draft in PR #477: the Traefik exposure and RBAC manifests now live in the per-cluster GitOps repos, and the hand-built kubeconfig script is replaced by the cluster-info kubeconfig.
There was a problem hiding this comment.
Pull request overview
Adds a new developer-facing documentation page explaining how to access GlueOps clusters with kubectl via GitHub OIDC, and extends the docs site’s dynamic “Captain Domain” rendering to support a namespace sentinel for copy/paste-ready commands.
Changes:
- Added a new tutorial doc: Access Your Cluster with kubectl (OIDC device-code login, namespace-scoped access, tiers, troubleshooting).
- Extended the swizzled
CodeBlockreplacement to supportCAPTAIN_NAMESPACE(first label of the Captain Domain). - Updated styling so
<CaptainDomain />embedded inside inline<code>renders as a single “token”, and wired the new doc into navigation/next-steps.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| src/theme/CodeBlock/index.tsx | Adds CAPTAIN_NAMESPACE sentinel replacement alongside CAPTAIN_DOMAIN. |
| src/css/custom.css | Adjusts inline domain styling when nested inside <code> to avoid “chip-within-a-chip”. |
| sidebars.js | Adds the new kubectl access doc under the Developers sidebar section. |
| docs/deploy-applications/hello-world.mdx | Links to the new kubectl access guide in “Next steps”. |
| docs/deploy-applications/access-cluster-kubectl.mdx | New tutorial doc describing kubectl access flow, tiers, and troubleshooting. |
| .ai/reference.md | Documents the new sentinel/component patterns for dynamic domain/namespace rendering. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- clarify oidc-login is installed via krew and needs ~/.krew/bin on PATH - soften device-code wording (browser may open automatically) - use 'kubectl oidc-login clean' instead of rm -rf for token cache - note connection may be refused (not only hang) when IP not allowlisted
- correct .ai/reference.md Verify convention: developers now have namespace-scoped kubectl access, so scoped kubectl verification is acceptable (was: 'platform users do not have kubectl access') - cross-link the kubectl access guide from the ExternalSecret tip
- reference.md: drop stale 'three patterns' count (table lists more) - custom.css: fully blend custom-domain token inside code chips (reset border/radius, not just background) - e2e: add CAPTAIN_NAMESPACE coverage on the new access page (default + custom domain), closing the regression gap - e2e: fix pre-existing playwright version mismatch (@playwright/test 1.49.1 vs base image 1.58.2) that broke the entire suite
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a developer-facing guide: Access Your Cluster with kubectl (
docs/deploy-applications/access-cluster-kubectl.mdx), placed under Developers in the sidebar next to Add Secrets.The page covers:
~/.kube/config.Site changes
CAPTAIN_NAMESPACEsentinel in the swizzledCodeBlock— renders the reader's environment namespace (the first label of their Captain Domain), so commands likekubectl get pods -n <ns>are copy-paste ready.<CaptainDomain />inside a<code>chip blends into a single monospace token (used for the team names in the tiers table)..ai/reference.md.Supersedes #477
The original PR mixed operator-side concerns (Traefik
IngressRouteTCPexposure, RBAC manifests, a hand-built kubeconfig script) into a Traefik how-to. Those now live in the per-cluster GitOps repos, and the kubeconfig is served from the cluster-info page — so this is a clean, end-user-only doc on a fresh branch. The accidentalyarn.lockfrom #477 is not included (repo uses npm).Validated with a full
docusaurus build(passesonBrokenLinks: throw).