Skip to content

feat(vcluster): add webhook token authentication guide for vcluster api server #1535

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
Piotr1215 wants to merge 3 commits into
base: main
Choose a base branch
from
Open

feat(vcluster): add webhook token authentication guide for vcluster api server #1535

Piotr1215 wants to merge 3 commits into from

Conversation

@Piotr1215
Copy link
Contributor

@Piotr1215 Piotr1215 commented Jan 5, 2026 •
edited by loft-bot
Loading

Content Description

Preview Link

Internal Reference

Closes DOC-

@netlify /docs

Note

Adds comprehensive documentation for configuring webhook token authentication in vCluster API server.

  • New guide: Explains how to set up webhook token authentication for external identity providers
  • Coverage: Prerequisites, step-by-step configuration, CAPIVC integration, and troubleshooting
  • Distribution: Documents K8s distribution requirement (not available in K3s/K0s)

Generated by Claude for 47647e3

@Piotr1215 Piotr1215 requested a review from a team as a code owner January 5, 2026 08:57
@loft-bot
Copy link
Contributor

loft-bot commented Jan 5, 2026 •
edited
Loading

Claude finished @Piotr1215's task in 2m 44s —— View job

Review Complete

  • Read repository guidelines (CLAUDE.md, CONTRIBUTING.md)
  • Read the changed documentation file
  • Validate vCluster YAML configurations (all 3 configs valid ✓)
  • Verify related links exist (all paths valid ✓)
  • Check documentation quality (links, formatting, style)
  • Provide review feedback
  • Update PR description summary

Summary

This is a well-written documentation guide for configuring webhook token authentication in vCluster. The content is comprehensive, covering prerequisites, step-by-step configuration, CAPIVC integration, and troubleshooting.

What looks good:

  • ✓ All vCluster YAML configurations are valid
  • ✓ Sentence case used for all headings
  • ✓ Active voice and present tense throughout
  • ✓ No forbidden words (easy, simple, obvious)
  • ✓ Correct relative paths for internal links
  • ✓ Note admonition correctly placed outside JSX components
  • ✓ Clear structure with logical flow
  • ✓ Good troubleshooting section

Minor suggestions (optional):

  1. Line 10: Consider adding a brief intro sentence before the link to provide context:

    Current: "This guide shows how to configure the vCluster API server to use webhook token authentication..."

    The opening is good, but you could consider adding context about when users would need this feature.

  2. Line 27: The prerequisite controlPlane.distro.k8s.enabled: true uses inline code formatting which is good - just verify this matches the exact YAML path in vCluster docs.

  3. Consider adding TenancySupport: Other guides in this directory (like configure-custom-coredns.mdx) include the TenancySupport fragment to indicate which tenancy modes support the feature. If webhook token auth is specific to certain modes, consider adding:

    import TenancySupport from '../../../_fragments/tenancy-support.mdx';
<TenancySupport hostNodes="true" />

  4. Line 217: The CAPIVC section uses awk for escaping newlines. This works but could be fragile. Consider noting that users should ensure proper escaping for their shell environment.

Overall: The documentation is ready for merge. The content is technically accurate, follows the style guide, and provides valuable information for users integrating external identity providers with vCluster.

@github-actions
Copy link
Contributor

github-actions bot commented Jan 5, 2026

DOC-815: Configuring vC apiservers to use webhook token

@netlify
Copy link

netlify bot commented Jan 5, 2026 •
edited
Loading

✅ Deploy Preview for vcluster-docs-site ready!

Name Link
🔨 Latest commit aef3399
🔍 Latest deploy log https://app.netlify.com/projects/vcluster-docs-site/deploys/6968eff60a3d920008a4d579
😎 Deploy Preview https://deploy-preview-1535--vcluster-docs-site.netlify.app/docs
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@Piotr1215 Piotr1215 force-pushed the doc-815/webhook-token branch from ed35223 to 6836b5b Compare January 5, 2026 09:17
@loft-bot
Copy link
Contributor

loft-bot commented Jan 5, 2026 •
edited
Loading

Claude finished @Piotr1215's task in 1m 14s —— View job

Review Complete

  • Read repository guidelines (CLAUDE.md, CONTRIBUTING.md)
  • Read the changed documentation file
  • Validate vCluster YAML configurations (all 3 configs valid ✓)
  • Verify related links exist (all paths valid ✓)
  • Check documentation quality (links, formatting, style)
  • Update PR description summary

Summary

This is a well-written documentation guide for configuring webhook token authentication in vCluster. The content is comprehensive and follows the style guide.

Validation results:

  • ✓ All 3 vCluster YAML configurations are valid
  • ✓ All relative link paths exist in the repository
  • ✓ TenancySupport fragment correctly imported and used
  • ✓ Sentence case used for all headings
  • ✓ Active voice and present tense throughout
  • ✓ No forbidden words (easy, simple, obvious)
  • ✓ Note admonition correctly placed outside JSX Step components
  • ✓ Clear structure with logical flow
  • ✓ Good troubleshooting section

Documentation quality:

  • The guide covers the full workflow from prerequisites to troubleshooting
  • Code examples are well-formatted with appropriate titles
  • The CAPIVC integration section adds value for users of that tooling
  • Network connectivity and certificate troubleshooting tips are helpful

No issues found. The documentation is ready for merge.

@Piotr1215 Piotr1215 changed the title docs: add webhook token authentication guide for vcluster api server feat(vcluster): add webhook token authentication guide for vcluster api server Jan 5, 2026
@Piotr1215
docs: add webhook token authentication guide for vcluster api server
47647e3 
Users integrating vCluster with external identity providers or CAPIVC
need to configure the kube-apiserver to validate tokens via webhook.
No existing documentation covers this use case despite being requested
in DOC-815.

New guide covers:
- Webhook token auth configuration via extraArgs
- Volume mounting for webhook config and TLS certificates
- CAPIVC integration via VCLUSTER_YAML environment variable
- TokenReview API contract for webhook implementers
- Troubleshooting authentication and certificate issues

Placed in learn-how-to/control-plane/container/ alongside similar
advanced configuration guides like custom schedulers and audit logging.
@Piotr1215 Piotr1215 force-pushed the doc-815/webhook-token branch from 6836b5b to 47647e3 Compare January 5, 2026 10:16
@loft-bot
Copy link
Contributor

loft-bot commented Jan 5, 2026 •
edited
Loading

Claude finished @Piotr1215's task in 2m 4s —— View job

Review Complete

  • Read repository guidelines (CLAUDE.md, CONTRIBUTING.md)
  • Read the changed documentation file
  • Validate vCluster YAML configurations (all 3 configs valid ✓)
  • Check documentation quality (links, formatting, style)
  • Update PR description summary

Summary

This is a well-written documentation guide for configuring webhook token authentication in vCluster. The content is comprehensive, covering prerequisites, step-by-step configuration, CAPIVC integration, and troubleshooting.

Validation results:

  • ✓ All 3 vCluster YAML configurations are valid
  • ✓ All relative link paths exist in the repository
  • ✓ TenancySupport fragment correctly imported and used
  • ✓ Sentence case used for all headings
  • ✓ Active voice and present tense throughout
  • ✓ No forbidden words (easy, simple, obvious)
  • ✓ Note admonition correctly placed outside JSX Step components
  • ✓ Clear structure with logical flow
  • ✓ Good troubleshooting section

Documentation quality:

  • The guide covers the full workflow from prerequisites to troubleshooting
  • Code examples are well-formatted with appropriate titles
  • The CAPIVC integration section adds value for users of that tooling
  • Network connectivity and certificate troubleshooting tips are helpful

No issues found. The documentation is ready for merge.

@Piotr1215 @guowenatk
Update vcluster/learn-how-to/control-plane/container/configure-webhoo…
31c39b0 
…k-token-auth.mdx

Co-authored-by: Guowen Huang <guowen.huang@loft.sh>
@Piotr1215
docs(vcluster): add CAPIVC reference link
aef3399 
Reviewer requested reference to CAPIVC project. Added direct
link to the cluster-api-provider-vcluster GitHub repository.
@Piotr1215 Piotr1215 added this to the v0.31 milestone Jan 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@guowenatk guowenatk guowenatk left review comments

@bdecoste bdecoste Awaiting requested review from bdecoste

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

v0.31

Development

Successfully merging this pull request may close these issues.

4 participants

@Piotr1215 @loft-bot @guowenatk