Restructure multicluster docs to Diataxis framework#2549
Draft
ctauchen wants to merge 3 commits intotigera:mainfrom
Draft
Restructure multicluster docs to Diataxis framework#2549ctauchen wants to merge 3 commits intotigera:mainfrom
ctauchen wants to merge 3 commits intotigera:mainfrom
Conversation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Reorganize calico-enterprise/multicluster/ from a flat structure into Diataxis categories (explanation, how-to, reference, tutorial, troubleshooting) to separate conceptual, procedural, and reference content that was previously mixed within individual pages. Key changes: - Merge standard + Helm install guides into single pages with tabs - Extract setup, validation, and troubleshooting from 20KB kubeconfig.mdx - Create new explanation pages for architecture and security model - Add reference pages for CRDs, federation annotations, Helm values, and port/service requirements - Rewrite AWS federation example as a learning-oriented tutorial - Update sidebar, 16 cross-references, and 5 Install components - Fix pre-existing broken links in versioned recommended-metrics.mdx Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
✅ Deploy Preview for calico-docs-preview-next ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview succeeded!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
There was a problem hiding this comment.
Pull request overview
This pull request comprehensively restructures the Calico Enterprise multicluster documentation from a flat structure into the Diataxis documentation framework (Explanation, How-to, Reference, Tutorial, Troubleshooting). The changes transform scattered documentation into a well-organized, user-friendly structure that better serves different user needs.
Changes:
- Reorganized
calico-enterprise/multicluster/from flat structure to Diataxis categories (Concepts, How-to guides, Reference, Tutorials, Troubleshooting) - Merged Operator and Helm installation guides into single pages with nested tabs (using different
groupIdvalues to prevent conflicts) - Extracted setup, validation, and troubleshooting content from the monolithic
kubeconfig.mdx(20KB) into focused, task-oriented pages - Created new explanation pages synthesizing scattered architecture and security model content
- Added comprehensive reference pages for CRDs, federation annotations, Helm values, and port/service requirements
- Rewrote AWS federation example as a learning-oriented tutorial following best practices
- Updated sidebar structure, 16 cross-references throughout the codebase, and 5 Install component files
- Fixed 4 pre-existing broken links in versioned
recommended-metrics.mdxfiles - Updated announcement bar to promote Calico 3.30+ Hackathon (unrelated to multicluster docs)
Reviewed changes
Copilot reviewed 49 out of 49 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
sidebars-calico-enterprise.js |
Restructured multicluster sidebar to Diataxis framework with Concepts, How-to guides, Reference, Tutorials, and Troubleshooting categories |
docusaurus.config.js |
Updated announcement bar (unrelated to multicluster changes) |
calico-enterprise_versioned_docs/version-*/operations/monitor/metrics/recommended-metrics.mdx |
Fixed pre-existing broken relative paths to cluster mesh documentation (4 versions) |
calico-enterprise/reference/resources/remoteclusterconfiguration.mdx |
Updated link to cluster mesh overview |
calico-enterprise/reference/resources/managedcluster.mdx |
Updated link to management cluster creation guide |
calico-enterprise/reference/public-cloud/aws.mdx |
Updated 2 links to cluster mesh documentation |
calico-enterprise/reference/component-resources/kube-controllers/configuration.mdx |
Updated link to federated services configuration |
calico-enterprise/operations/monitor/metrics/recommended-metrics.mdx |
Updated 2 links to cluster mesh documentation |
calico-enterprise/operations/comms/certificate-management.mdx |
Updated link to management cluster guide |
calico-enterprise/operations/cnx/roles-and-permissions.mdx |
Updated link to multi-cluster RBAC |
calico-enterprise/multicluster/index.mdx |
Restructured landing page to Diataxis framework with clear categories |
calico-enterprise/multicluster/explanation/index.mdx |
Created category index for conceptual documentation |
calico-enterprise/multicluster/explanation/architecture.mdx |
NEW: Synthesized comprehensive architecture explanation covering topology, components, and communication model |
calico-enterprise/multicluster/explanation/cluster-mesh.mdx |
NEW: Consolidated cluster mesh concepts including federated identity, services, and networking |
calico-enterprise/multicluster/explanation/security-model.mdx |
NEW: Synthesized security model covering authentication, RBAC, and credential management |
calico-enterprise/multicluster/how-to/index.mdx |
Created category index for task-oriented guides |
calico-enterprise/multicluster/how-to/create-a-management-cluster.mdx |
Merged Operator and Helm installation into single page with nested tabs (install-method → service-type groupIds) |
calico-enterprise/multicluster/how-to/create-a-managed-cluster.mdx |
Merged Operator and Helm installation with nested tabs (install-method → platform groupIds) |
calico-enterprise/multicluster/how-to/set-up-cluster-mesh.mdx |
Extracted cluster mesh setup from kubeconfig.mdx into focused how-to guide |
calico-enterprise/multicluster/how-to/validate-multi-cluster-setup.mdx |
Extracted validation procedures into dedicated page |
calico-enterprise/multicluster/how-to/configure-federated-services.mdx |
Moved from federation/services-controller.mdx with updated structure |
calico-enterprise/multicluster/how-to/configure-log-storage.mdx |
Extracted log storage configuration from fine-tune-deployment.mdx |
calico-enterprise/multicluster/how-to/configure-cross-cluster-rbac.mdx |
Extracted RBAC configuration from fine-tune-deployment.mdx |
calico-enterprise/multicluster/how-to/change-cluster-type.mdx |
Updated with new link references |
calico-enterprise/multicluster/reference/index.mdx |
Created category index for reference documentation |
calico-enterprise/multicluster/reference/custom-resources.mdx |
NEW: Quick reference for all multicluster CRDs with usage patterns |
calico-enterprise/multicluster/reference/federation-annotations.mdx |
Extracted annotations reference from services-controller.mdx |
calico-enterprise/multicluster/reference/helm-values.mdx |
NEW: Comprehensive Helm values reference for management and managed clusters |
calico-enterprise/multicluster/reference/port-and-service-requirements.mdx |
Extracted service requirements and network prerequisites |
calico-enterprise/multicluster/tutorial/index.mdx |
Created category index for tutorials |
calico-enterprise/multicluster/tutorial/aws-cluster-mesh.mdx |
Rewrote AWS example as learning-oriented tutorial with clear objectives and steps |
calico-enterprise/multicluster/troubleshooting.mdx |
Extracted troubleshooting content from kubeconfig.mdx into dedicated page |
calico-enterprise/multicluster/set-up-multi-cluster-management/standard-install/create-a-management-cluster.mdx |
DELETED: Content merged into how-to/create-a-management-cluster.mdx |
calico-enterprise/multicluster/set-up-multi-cluster-management/standard-install/create-a-managed-cluster.mdx |
DELETED: Content merged into how-to/create-a-managed-cluster.mdx |
calico-enterprise/multicluster/fine-tune-deployment.mdx |
DELETED: Content extracted to configure-log-storage.mdx and configure-cross-cluster-rbac.mdx |
calico-enterprise/multicluster/federation/overview.mdx |
DELETED: Content moved to explanation/cluster-mesh.mdx |
calico-enterprise/multicluster/federation/kubeconfig.mdx |
DELETED: Content extracted to set-up-cluster-mesh.mdx, validate-multi-cluster-setup.mdx, and troubleshooting.mdx |
calico-enterprise/multicluster/federation/services-controller.mdx |
DELETED: Content moved to how-to/configure-federated-services.mdx and reference/federation-annotations.mdx |
calico-enterprise/multicluster/federation/aws.mdx |
DELETED: Content rewritten as tutorial/aws-cluster-mesh.mdx |
calico-enterprise/_includes/components/Install*.js |
Updated 5 component files with new link to port-and-service-requirements.mdx |
calico-enterprise/getting-started/install-on-clusters/kubernetes/helm.mdx |
Updated 2 links to new how-to guides |
calico-enterprise/about/index.mdx |
Updated 2 links to new explanation and how-to pages |
Comment on lines
+119
to
+120
| id: "calico_hackathon", | ||
| content: '🚀 The <a href="https://www.tigera.io/lp/project-calico-hackathon?utm_source=website&utm_medium=Docs_site&utm_campaign=Hackathon2026">Calico 3.30+ Hackathon</a> is live! Leverage Calico 3.30+ to solve networking challenges and win up to $1,000.', |
There was a problem hiding this comment.
The announcement bar change appears to be unrelated to the multicluster docs restructure. This updates the banner from promoting "Calico Cloud Free" to promoting a "Calico 3.30+ Hackathon" event. Consider whether this change should be in a separate PR focused on marketing content updates.
Comment on lines
+422
to
+430
| items: [ | ||
| 'multicluster/how-to/create-a-management-cluster', | ||
| 'multicluster/how-to/create-a-managed-cluster', | ||
| 'multicluster/how-to/change-cluster-type', | ||
| 'multicluster/how-to/set-up-cluster-mesh', | ||
| 'multicluster/how-to/configure-federated-services', | ||
| 'multicluster/how-to/configure-log-storage', | ||
| 'multicluster/how-to/configure-cross-cluster-rbac', | ||
| 'multicluster/how-to/validate-multi-cluster-setup', |
There was a problem hiding this comment.
The ordering of how-to guides in the sidebar may not reflect the typical workflow. Consider reordering to:
- create-a-management-cluster
- create-a-managed-cluster
- set-up-cluster-mesh
- configure-federated-services
- configure-log-storage
- configure-cross-cluster-rbac
- validate-multi-cluster-setup
- change-cluster-type (as this is less common than the setup workflow)
This would present the guides in a more natural setup-to-configuration order.
- Remove DocCardLink to add-maglev-load-balancing from calico-cloud networking index since the page only exists in the unreleased next version and the component generates URLs without the next prefix - Fix relative path in calico maglev page from ../../../ to ../../ and correct anchor from #try-out-direct-server-return-mode to #enable-direct-server-return-mode to match the calico heading
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.
Summary
calico-enterprise/multicluster/from a flat structure into Diataxis categories: explanation, how-to, reference, tutorial, and troubleshootinggroupId)kubeconfig.mdxinto focused pagesrecommended-metrics.mdxfilesNotes for reviewers
calico-enterprise/directory is modified (plus pre-existing link fixes in versioned docs)architecture.mdx,security-model.mdx) andreference/custom-resources.mdxare synthesized from existing scattered content — please review for technical accuracycalico-cloud/andcalico/(unrelated to this PR) still exist inbuild-nextTest plan
make build-nextcompiles without MDX errors; no new broken links introducedyarn test:components— 6/6 test suites pass🤖 Generated with Claude Code