refactor(docs): restructure administrator quickstart and kind setup #6943
+854
−215
Conversation
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
…uide
## Changes Overview
This refactor reorganizes the administrator quickstart to better guide users
through local Kubernetes setup and Camunda 8 installation.
### Structural Changes
1. **Quick Start navigation update**
- "For Administrators" now redirects to: Deploy & Manage > Kubernetes > Install > Quick install
- Added admonition in quick-install pointing to kind guide for local Kubernetes setup
- Quick install remains focused on installation with port-forwarding (default for local dev)
2. **New kind guide location**
- Created: Deploy & Manage > Cloud Providers > Local > kind
- Comprehensive tutorial covering:
- Installing kind, kubectl, and Helm (all OS)
- Creating local Kubernetes cluster
- Optional Ingress setup
- Camunda 8 deployment
- Verification commands (kubectl get nodes, pods, services, etc.)
- Cluster exploration and troubleshooting
3. **Quick install enhancements**
- Added tip admonition with two paths:
* Local development → kind tutorial
* Cloud providers → Amazon EKS, Google GKE, Azure AKS, Red Hat OpenShift
- Simplified prerequisites section
- Maintains focus on port-forwarding for simplicity
4. **Sidebar structure**
```
Quick Start
├── For Developers
│ ├── c8run
│ └── docker-compose
└── For Administrators → (link to quick-install)
Deploy & Manage
└── Kubernetes with Helm
├── Install
│ └── Quick install
└── Cloud Providers
├── Local
│ └── kind
├── Amazon (EKS, ROSA)
├── Google (GKE)
├── Microsoft (AKS)
└── Red Hat OpenShift
```
### Design Decisions
- **Port-forwarding focus**: Quick install explicitly uses port-forwarding as the
primary access method for local development (simpler for first-time users)
- **Ingress as optional**: Ingress setup moved to optional section in kind guide
with link from quick-install for advanced users
- **Progressive complexity**: Basic cluster → Quick install → Optional Ingress
## What's Next / TODO
### Testing Required
- [ ] Test kind installation guide on all OS (macOS, Linux, Windows)
- [ ] Verify all kubectl commands work as documented
- [ ] Test port-forwarding workflow end-to-end
- [ ] Test optional Ingress setup workflow
- [ ] Validate all internal links work correctly
- [ ] Check sidebar navigation renders properly
### Future Work
- [ ] Infra team to maintain automated test of local cluster setup in reference architecture
- [ ] Consider adding link to Ingress setup at end of quick-install for users wanting advanced networking
- [ ] Potentially add "Next steps after installation" section to guide users to relevant tutorials
### Open Questions (resolved in this PR)
- ✅ Move kind to cloud providers → YES, under "Local" category for better discoverability
## Related
- Improves user journey for administrators getting started with Camunda 8 Self-Managed
- Aligns documentation structure with deployment patterns (local dev vs cloud production)
- Maintains backward compatibility with redirect from old administrator-quickstart page
|
👋 🤖 🤔 Hello, @leiicamundi! Did you make your changes in all the right places? These files were changed only in docs/. You might want to duplicate these changes in versioned_docs/version-8.7/.
You may have done this intentionally, but we wanted to point it out in case you didn't. You can read more about the versioning within our docs in our documentation guidelines. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
|
||
| <Tabs groupId="cluster-type" defaultValue="basic" queryString values={[ | ||
| {label: 'Basic cluster (recommended)', value: 'basic'}, | ||
| {label: 'Cluster with Ingress support', value: 'ingress'} |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[all.glossary] Inconsistent spelling detected. Use Ingress instead of ingress. Review the WCoE glossary - https://confluence.camunda.com/x/b5RZBw .
|
|
||
| <Tabs groupId="cluster-type" defaultValue="basic" queryString values={[ | ||
| {label: 'Basic cluster (port-forwarding)', value: 'basic'}, | ||
| {label: 'Cluster with Ingress', value: 'ingress'} |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[all.glossary] Inconsistent spelling detected. Use Ingress instead of ingress. Review the WCoE glossary - https://confluence.camunda.com/x/b5RZBw .
| kubectl get ingress | ||
| ``` | ||
|
|
||
| You should see ingress resources for various Camunda components. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[all.glossary] Inconsistent spelling detected. Use Ingress instead of ingress. Review the WCoE glossary - https://confluence.camunda.com/x/b5RZBw .
leiicamundi
added
deploy
|
🚧 The preview environment for the commit 11665a6 is being built. This usually takes 8-10 minutes. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Description
This refactor reorganizes the administrator quickstart to better guide users through local Kubernetes setup and Camunda 8 installation.
Structural Changes
Quick Start navigation update
New kind guide location
Quick install enhancements
Sidebar structure ``` Quick Start ├── For Developers
│ ├── c8run
│ └── docker-compose
└── For Administrators → (link to quick-install)
Deploy & Manage └── Kubernetes with Helm ├── Install
│ └── Quick install
└── Cloud Providers
├── Local
│ └── kind
├── Amazon (EKS, ROSA)
├── Google (GKE)
├── Microsoft (AKS)
└── Red Hat OpenShift
Design Decisions
What's Next / TODO
Testing Required
Future Work
Open Questions (resolved in this PR)
Related
When should this change go live?
bugorsupportlabel)available & undocumentedlabel)holdlabel)low priolabel)PR Checklist
{type}(scope): {description}commit message(s)/docsdirectory (version 8.8)./versioned_docsdirectory.@camunda/tech-writersunless working with an embedded writer.