[DOCS-1442] Self-Managed deployment guide revamp #2113
Conversation
- Create and edit snippets for shared object storage content
- Updates to BYOB page to clarify that it applies to all deployments
- Add a new Requirements page for Self-Managed
- Uses existing snippet imports extensively
- Clear cross-references to reference architecture
- Strong BYOB integration
- Sections:
- Software version requirements
- Hardware requirements
- Kubernetes (with OpenShift mention)
- MySQL database (with config parameters and creation instructions)
- Redis
- Object storage (with BYOB provisioning link and configuration transition)
- Networking (with DNS and load balancer info)
- SSL/TLS
- License
- Next steps (links to cloud, on-prem, airgapped guides)
- Create new directories for details specific to Cloud or on-premise
deployments, will be populated in phases 3 and 4s
- Update navigation
- Move and edit Operator landing page
- Update title
- Use shared BYOB content
- Adjust Before you begin
- Update links for file moves
- Adjust support storage provider list
- Improve cross-references
- Where possible, tabify content for Helm and Terraform to
simplify the giew
- Update navigation
- Create consolidated Terraform guide
- Shared intro, explanation of modules
- Adds a cloud provider selector
- Platform-specific content in tabs
- Prerequisites
- General steps
- Recommendations
- Specific details about Redis, message broker
- Links to more resources
- Update navigation
- Create connected and airgapped on-prem guides - Update requirements - Update navigation This resolves some links that were intentionally left broken after the last phase
Add redirects for files we moved, renamed, or consolidated Temporarily, redirect old Japanese / Korean destinations to English destinations
📚 Mintlify Preview Links🔄 Renamed/Moved (1 total)📄 Pages (1)
✨ Added (8 total)📄 Pages (8)
📝 Changed (4 total)📄 Pages (3)
⚙️ Other (1)
🗑️ Deleted (5 total)View deleted files📄 Pages (5)
🤖 Generated automatically when Mintlify deployment succeeds |
Delete old files we no longer need
mdlinville
force-pushed
the
operator_docs_revamp
branch
from
c56b49d to
d2312a9
Compare
mdlinville
force-pushed
the
operator_docs_revamp
branch
from
7fd62b6 to
cb18bb2
Compare
flamarion
left a comment
flamarion
left a comment
There was a problem hiding this comment.
I haven’t finished reviewing all the content yet, but assuming this was mostly a structural move (rather than content changes), everything looks reasonable so far.
One question I have is around the need to keep both:
Deploy W&B with Kubernetes OperatorDeploy on On-Premises Kubernetes
My suggestion would be to avoid centering this around on-prem and instead treat Kubernetes as a generic deployment method, independent of the environment.
Rationale
Kubernetes itself is fundamentally the same whether it runs on-prem or in the cloud — the core requirements and workflows don’t change. The main differences are usually in naming or managed services, for example:
- MySQL vs. RDS (AWS)
- S3 vs. another object storage
- Managed Redis vs. self-hosted Redis
Those are environment-specific details, but they don’t change the Kubernetes deployment model.
Suggested structure
You already do something similar with Deploy with Terraform on public cloud, which works well. Following that pattern, one option could be to group:
Deploy W&B with Kubernetes OperatorDeploy on Air-Gapped Kubernetes
under a broader section like:
Deploy on Kubernetes
or, if you prefer to keep the on-prem framing:
Deploy on On-Premises Kubernetes
This would reduce duplication, make the mental model clearer, and emphasize Kubernetes as the primary abstraction rather than the underlying environment.
Leave airgapped page separate but maximize content reuse
I just pushed a commit that consolidates the Cloud and on-prem content into a single (main) Operator page, and left the airgapped content on a separate page since it's for a very particular sort of deployment and there is SEO merit here. I have maximized shared content between the main page and the airgapped page where possible, so updating a snippet will update both pages automatically. PTAL and let me know what you think. The redundant redirects the link checker is finding are expected for now. I need to fix the rest of them tomorrow. |
2 participants
Description
This PR completes a comprehensive restructure of the W&B self-managed deployment documentation to address confusion between deployment guides, consolidate shared requirements, improve discoverability, and incorporate enhanced OpenShift/air-gapped deployment guidance.
Key improvements:
The project was accomplished in 6 phases. Each phase is encapsulated into a commit for iterative review. See Changes by Phase.
Benefits
For Users
For Maintenance
For Support
Major Content Improvements
OpenShift Support
Air-Gapped Deployments
User Experience
Related Issues
Closes DOCS-1442
Changes by Phase
Reviewers: This project was completed in 6 phases, each in a separate commit. I suggest loading and scanning through each commit in sequence, before reviewing the HTML output using the Preview comment.
Phase 1: Foundation + Snippets
**Commit:** https://github.com//pull/2113/changes/6567f8668bb8028197611fd92c25279214dc3f8arequirements.mdxpage consolidating prerequisitesPhase 2: Operator Consolidation
**Commit:** https://github.com//pull/2113/changes/19785806b8a73d3ad60c0d3d5e940c17e54373d8operator.mdxtoself-managed/operator.mdxPhase 3: Cloud Terraform Consolidation
**Commit:** https://github.com//pull/2113/changes/90948936bf0ceebc823bd7e9842a9a06bc7a734faws-tf.mdx,gcp-tf.mdx,azure-tf.mdxinto singlecloud-deployments/terraform.mdxPhase 4: On-Premises Guides
**Commit:** https://github.com//pull/2113/changes/ae58ee25e23e7c92c98480c98ca148b131290d34on-premises-deployments/kubernetes.mdx(replaces bare-metal.mdx)on-premises-deployments/kubernetes-airgapped.mdxPhase 5: Redirects
**Commit:** https://github.com//pull/2113/changes/559d904cfda61f22d0442cf2ff491907120853e1Phase 6: Cleanup
**Commit:** https://github.com//pull/2113/changes/d2312a94f3cf2cb40b0d001c5ac8cda254aa7a2bPhase 7: Address feedback
- Consolidated Cloud and on-prem guides into a single page - Left airgapped guide as a separate page - Maximized content reuse and single-sourcing between the twoNew Documentation Structure
Files Removed
- platform/hosting/operator.mdx (moved) - platform/hosting/self-managed/bare-metal.mdx (replaced) - platform/hosting/self-managed/operator-airgapped.mdx (replaced) - platform/hosting/self-managed/aws-tf.mdx (consolidated) - platform/hosting/self-managed/gcp-tf.mdx (consolidated) - platform/hosting/self-managed/azure-tf.mdx (consolidated)Redirects Added
All old URLs redirect to new locations:
English:
/platform/hosting/operator→/platform/hosting/self-managed/operator/platform/hosting/self-managed/bare-metal→/platform/hosting/self-managed/on-premises-deployments/kubernetes/platform/hosting/self-managed/operator-airgapped→/platform/hosting/self-managed/on-premises-deployments/kubernetes-airgapped/platform/hosting/self-managed/aws-tf→/platform/hosting/self-managed/cloud-deployments/terraform/platform/hosting/self-managed/gcp-tf→/platform/hosting/self-managed/cloud-deployments/terraform/platform/hosting/self-managed/azure-tf→/platform/hosting/self-managed/cloud-deployments/terraformLocalized (ja/ and ko/):
Testing Checklist
mint dev,mint validatecat docs.json | python3 -m json.toolFollowup tasks for localization team
Japanese and Korean localized files still exist but redirect to English versions. The localization team should:
Translate new/updated content (5 files):
platform/hosting/self-managed/requirements.mdx(NEW)platform/hosting/self-managed/operator.mdx(enhanced)platform/hosting/self-managed/cloud-deployments/terraform.mdx(NEW)platform/hosting/self-managed/on-premises-deployments/kubernetes.mdx(NEW)platform/hosting/self-managed/on-premises-deployments/kubernetes-airgapped.mdx(NEW)Delete old localized files (6 per language):
ja/platform/hosting/operator.mdxandko/platform/hosting/operator.mdx{ja,ko}/platform/hosting/self-managed/bare-metal.mdx{ja,ko}/platform/hosting/self-managed/operator-airgapped.mdx{ja,ko}/platform/hosting/self-managed/{aws,gcp,azure}-tf.mdxUpdate navigation in
docs.jsonfor ja/ and ko/ sectionsTimeline: No urgency - redirects serve English content until translations ready.
Statistics