docs(tenants): document the checkbox-then-edit-CR customization pattern by lexfrei · Pull Request #485 · cozystack/website

lexfrei · 2026-04-11T22:16:54Z

What

Adds a Customizing Tenant Services section to content/en/docs/v1/guides/tenants/_index.md that documents how to configure a tenant-level service (etcd, monitoring, ingress, seaweedfs) beyond the per-tenant boolean flag: flip the flag on, then kubectl edit (or kubectl patch) the downstream apps.cozystack.io/v1alpha1 CR in place. Also calls out two common wrong approaches in a warning callout.

Why

This is one of the most frequent confusions in the community chat. A user turns on seaweedfs: true on a tenant, discovers the default configuration does not fit (e.g. needs storage pools, a MultiZone topology, non-default quotas), and cannot find a place in the tenant manifest to put the service-specific spec. Attempts to preconfigure the service by applying its CR manifest before the tenant is created fail with "namespace not found". Attempts to nest service-specific fields under the Tenant spec are silently ignored because the tenant-level fields are plain booleans — the per-service spec lives on a separate resource.

The working pattern was confirmed in chat by a cozystack maintainer: turn the flag on, then edit the generated application CR in place — manual changes on tenant-service CRs are not overwritten when the tenant reconciles. It already exists as a worked example in operations/services/object-storage/storage-pools, but a reader has no reason to find that page unless they already know to look in object-storage docs for a general tenant-customization pattern.

The new section in the Tenant System guide:

States the two-step workflow explicitly.
Shows both kubectl edit and kubectl patch examples against seaweedfses.apps.cozystack.io.
Links forward to the storage-pools page as a worked end-to-end example.
Adds a warning callout naming the two wrong approaches users actually try.

Verification

Pattern confirmed against packages/apps/tenant/templates/etcd.yaml, seaweedfs.yaml, monitoring.yaml, ingress.yaml at tag release-1.2.1. Each template generates a HelmRelease in the tenant namespace that reads values from the cozystack-values secret (valuesFrom: cozystack-values) and carries apps.cozystack.io/application.* labels, so the aggregated API exposes the corresponding apps.cozystack.io/v1alpha1 resource (Etcd, SeaweedFS, Monitoring, Ingress).
Existing SeaweedFS storage-pools page demonstrates exactly the same workflow for one specific service, so the new section is consistent with existing docs rather than inventing a new pattern.
hugo builds cleanly; the new section renders with the expected code blocks and callout.

Summary by CodeRabbit

Documentation
- Added new "Customizing Tenant Services" guide explaining how to enable services through tenant-level flags and customize individual service configurations
- Includes practical workflow examples and important warnings regarding proper service setup and configuration practices

coderabbitai · 2026-04-11T22:17:01Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1a124701-ea73-4352-9a50-4f7442efb00f

📥 Commits

Reviewing files that changed from the base of the PR and between 95123d6 and 141e925.

📒 Files selected for processing (1)

content/en/docs/v1/guides/tenants/_index.md

📝 Walkthrough

Walkthrough

A new documentation section titled "Customizing Tenant Services" was added to the tenants guide, explaining how tenant-level boolean flags generate default application CRs and how to manually edit these resources after creation. Includes examples and guidance on proper customization workflows.

Changes

Cohort / File(s)	Summary
Tenant Services Documentation `content/en/docs/v1/guides/tenants/_index.md`	Added "Customizing Tenant Services" section describing tenant-level boolean flags (`etcd`, `monitoring`, `ingress`, `seaweedfs`), their default CR generation, persistence of manual edits across reconciliations, and a two-step customization workflow with `kubectl edit` and `kubectl patch` examples. Includes warning alert against applying service CRs before tenant creation and nesting service config under tenant spec.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 With flags so true and services neat,
Our tenants now can customize, sweet!
Edit and patch with a whisker's grace,
Configs persist in their rightful place! 🌟

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs(tenants): document the checkbox-then-edit-CR customization pattern' directly and specifically describes the main change: documenting a customization pattern for tenant services via boolean flags followed by CR edits.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/tenant-service-customization

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

netlify · 2026-04-11T22:17:15Z

✅ Deploy Preview for cozystack ready!

Name	Link
🔨 Latest commit	`4438ea2`
🔍 Latest deploy log	https://app.netlify.com/projects/cozystack/deploys/69df9e589f85b00008f319e8
😎 Deploy Preview	https://deploy-preview-485--cozystack.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

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

gemini-code-assist

Code Review

This pull request adds a new section to the documentation titled "Customizing Tenant Services," which explains how to modify the configuration of services like etcd, monitoring, and SeaweedFS after they have been enabled. It details a two-step workflow involving enabling the service flag and then editing the resulting application custom resource. A review comment suggests updating the terminology from "HelmRelease YAML" to "Tenant manifest" to ensure clarity for users working directly with the Tenant resource.

gemini-code-assist · 2026-04-11T22:17:56Z

+1. Turn on the flag on the tenant (checkbox in the Dashboard or `etcd: true` /
+   `seaweedfs: true` / ... in the HelmRelease YAML). Cozystack creates the


The term 'HelmRelease YAML' might be confusing for users who are interacting with the Tenant custom resource directly via kubectl. Since the guide is about the Tenant System and the Tenant resource, it's more accurate to refer to it as the 'Tenant manifest' or 'Tenant YAML'.

Suggested change

1. Turn on the flag on the tenant (checkbox in the Dashboard or `etcd: true` /

`seaweedfs: true` / ... in the HelmRelease YAML). Cozystack creates the

1. Turn on the flag on the tenant (checkbox in the Dashboard or `etcd: true` /

`seaweedfs: true` / ... in the Tenant manifest). Cozystack creates the

Applied, but not as a direct suggestion replace — there is no dedicated Tenant CRD; tenants are created through a HelmRelease pointing at the tenant chart. Reworded to "under spec.values in the Tenant HelmRelease manifest you apply with kubectl", which is the object the reader actually writes and keeps the pointer concrete without pretending there is a separate Tenant YAML form.

…anifest Review comment on #485 flagged that 'HelmRelease YAML' is ambiguous in the context of the Tenant System guide — readers may think it refers to some downstream HelmRelease, not the Tenant object they are actually editing. Spell it out: the field lives under spec.values in the Tenant HelmRelease manifest the user applies with kubectl. Assisted-By: Claude <noreply@anthropic.com> Signed-off-by: Aleksei Sviridkin <f@lex.la>

Adds a Customizing Tenant Services section to the v1.2 Tenant System guide. Documents the two-step pattern for configuring tenant-level services (etcd, monitoring, ingress, seaweedfs) beyond the boolean flag: enable the flag, then kubectl edit / kubectl patch the generated apps.cozystack.io CR in place. Includes a warning callout naming the two common wrong approaches (preconfiguring CRs before the tenant exists, nesting service-specific spec under the Tenant CR). Assisted-By: Claude <noreply@anthropic.com> Signed-off-by: Aleksei Sviridkin <f@lex.la>

kvaps

LGTM

lexfrei requested review from kvaps and lllamnyp as code owners April 11, 2026 22:16

gemini-code-assist Bot reviewed Apr 11, 2026

View reviewed changes

kvaps previously approved these changes Apr 12, 2026

View reviewed changes

lexfrei dismissed kvaps’s stale review via 141e925 April 12, 2026 10:57

lexfrei force-pushed the docs/tenant-service-customization branch from 3c771c8 to 141e925 Compare April 12, 2026 10:57

lexfrei self-assigned this Apr 12, 2026

lexfrei force-pushed the docs/tenant-service-customization branch from 141e925 to 18e66e6 Compare April 15, 2026 13:59

kvaps approved these changes Apr 15, 2026

View reviewed changes

lexfrei enabled auto-merge April 15, 2026 14:18

Merge branch 'main' into docs/tenant-service-customization

4438ea2

lexfrei merged commit f1c640d into main Apr 15, 2026
1 check passed

lexfrei deleted the docs/tenant-service-customization branch April 15, 2026 14:19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(tenants): document the checkbox-then-edit-CR customization pattern#485

docs(tenants): document the checkbox-then-edit-CR customization pattern#485
lexfrei merged 2 commits intomainfrom
docs/tenant-service-customization

lexfrei commented Apr 11, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Apr 11, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

netlify Bot commented Apr 11, 2026 •

edited

Loading

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot Apr 11, 2026

Uh oh!

lexfrei Apr 11, 2026

Uh oh!

kvaps left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		1. Turn on the flag on the tenant (checkbox in the Dashboard or `etcd: true` /
		`seaweedfs: true` / ... in the HelmRelease YAML). Cozystack creates the

Conversation

lexfrei commented Apr 11, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

Verification

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Apr 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

netlify Bot commented Apr 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cozystack ready!

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Apr 11, 2026

Choose a reason for hiding this comment

Uh oh!

lexfrei Apr 11, 2026

Choose a reason for hiding this comment

Uh oh!

kvaps left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

lexfrei commented Apr 11, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Apr 11, 2026 •

edited

Loading

netlify Bot commented Apr 11, 2026 •

edited

Loading