docs(tenants): document namespace layout and parent/child derivation#479
docs(tenants): document namespace layout and parent/child derivation#479
Conversation
✅ Deploy Preview for cozystack ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughDocumentation adds a deterministic mapping from tenant hierarchy to Kubernetes workload namespaces, documents RFC 1123 and 63-character limits and failure mode, ties the Helm helper Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the tenant documentation by adding sections on the tenant namespace layout and the recommended method for deriving parent-child relationships using the Tenant custom resource. The feedback suggests highlighting the 63-character limit for Kubernetes namespace names to avoid issues with deep hierarchies and including a kubectl command example to help users list child tenants more easily.
| - Tenants created at any deeper level get a **hierarchical** namespace of | ||
| the form `<parent-workload-namespace>-<name>`. |
There was a problem hiding this comment.
Since the namespace name is constructed hierarchically by appending the tenant name to the parent's workload namespace, it is possible to exceed the Kubernetes limit of 63 characters for namespace names. This is especially relevant for deeply nested hierarchies or long tenant names. It would be beneficial to mention this constraint here to guide users in planning their tenant structure.
There was a problem hiding this comment.
Applied — added a warning callout in the Tenant Namespace Layout section about the 63-character RFC 1123 label limit, how deep hierarchies accumulate the ancestor chain into the namespace name, and practical guidance (short tenant names at deeper levels, shallower trees when long names are unavoidable). Also noted that Kubernetes surfaces the rejection through the containing tenant Helm release as a reconcile failure.
| - To list the direct children of a tenant with workload namespace `N`, list | ||
| `Tenant` CRs whose `metadata.namespace == N`. |
There was a problem hiding this comment.
To make this guide more actionable for administrators and developers, consider providing the specific kubectl command used to list children. For example: kubectl get tenants -n <parent-workload-namespace>. This directly illustrates the relationship between the parent's workload namespace and the children's metadata namespace described in the text.
There was a problem hiding this comment.
Applied — added an explicit kubectl get tenants --namespace <parent-workload-namespace> example inside the Deriving Parent and Child Relationships section, plus a note that the tenants resource is served by the Cozystack aggregated API (apps.cozystack.io/v1alpha1) and requires cozystack-api to be reachable, with kubectl api-resources --api-group apps.cozystack.io suggested as a quick sanity check.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (1)
content/en/docs/v1/guides/tenants/_index.md (1)
94-99: Consider using explicit table separator for consistency.The table uses a simplified header separator (
---) which is valid Markdown, but explicit column separators (| --- | --- |) might improve consistency with other tables in the documentation.📝 Proposed formatting enhancement
| Tenant path | Workload namespace | -| --- | --- | +| ----------------------- | -------------------------- | | `root` | `tenant-root` | | `root/alpha` | `tenant-alpha` | | `root/alpha/beta` | `tenant-alpha-beta` | | `root/alpha/beta/gamma` | `tenant-alpha-beta-gamma` |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@content/en/docs/v1/guides/tenants/_index.md` around lines 94 - 99, The Markdown table header uses a simplified separator; update the header separator row so each column has explicit pipe boundaries (e.g. replace the current `---` row under "Tenant path" and "Workload namespace" with a row that has `| --- | --- |`) to match the other tables and preserve consistent formatting for the table containing the rows `root`, `root/alpha`, `root/alpha/beta`, and `root/alpha/beta/gamma`.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@content/en/docs/v1/guides/tenants/_index.md`:
- Around line 94-99: The Markdown table header uses a simplified separator;
update the header separator row so each column has explicit pipe boundaries
(e.g. replace the current `---` row under "Tenant path" and "Workload namespace"
with a row that has `| --- | --- |`) to match the other tables and preserve
consistent formatting for the table containing the rows `root`, `root/alpha`,
`root/alpha/beta`, and `root/alpha/beta/gamma`.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 683cccc1-44af-476d-9d58-3ae6579d14f1
📒 Files selected for processing (1)
content/en/docs/v1/guides/tenants/_index.md
- Add 63-character RFC 1123 limit warning for deep/long tenant hierarchies and describe how Kubernetes surfaces the rejection through the tenant Helm release (gemini-code-assist bot comment on #479). - Add an explicit kubectl example for listing direct children of a tenant along with a note that the tenants resource is served by the aggregated API and requires cozystack-api to be reachable (gemini-code-assist bot comment on #479). - Rework the Tenant Namespace Layout intro so the hardcoded tenant-root case is called out separately from the two derivation rules, reference the Helm helper and computeTenantNamespace by plain file + function names instead of the non-standard :: notation, and clarify that the Helm helper computes the namespace of the child release being installed. - Rewrite the Deriving Parent and Child Relationships intro: naive string splitting actually works today because tenant names are alphanumeric, so the argument for preferring the Tenant CR is that parsing relies on implementation-detail invariants rather than on a stable contract, not that it is outright broken. - Normalise list bullets (- with one space), drop trailing whitespace and duplicate blank lines across the whole file for markdownlint cleanliness. Assisted-By: Claude <noreply@anthropic.com> Signed-off-by: Aleksei Sviridkin <f@lex.la>
- Add 63-character RFC 1123 limit warning for deep/long tenant hierarchies and describe how Kubernetes surfaces the rejection through the tenant Helm release (gemini-code-assist bot comment on #479). - Add an explicit kubectl example for listing direct children of a tenant along with a note that the tenants resource is served by the aggregated API and requires cozystack-api to be reachable (gemini-code-assist bot comment on #479). - Rework the Tenant Namespace Layout intro so the hardcoded tenant-root case is called out separately from the two derivation rules, reference the Helm helper and computeTenantNamespace by plain file + function names instead of the non-standard :: notation, and clarify that the Helm helper computes the namespace of the child release being installed. - Rewrite the Deriving Parent and Child Relationships intro: naive string splitting actually works today because tenant names are alphanumeric, so the argument for preferring the Tenant CR is that parsing relies on implementation-detail invariants rather than on a stable contract, not that it is outright broken. - Normalise list bullets (- with one space), drop trailing whitespace and duplicate blank lines across the whole file for markdownlint cleanliness. Assisted-By: Claude <noreply@anthropic.com> Signed-off-by: Aleksei Sviridkin <f@lex.la>
lexfrei
force-pushed
the
docs/tenant-namespace-naming-convention
branch
from
60ce6f9 to
886743d
Compare
Two new sections in the v1.2 Tenant System guide: - Tenant Namespace Layout — states the two naming rules (direct child of tenant-root vs. deeper descendant), a lookup table, and links to the source-of-truth helper/function in cozystack. - Deriving Parent and Child Relationships — why string-parsing the workload namespace is unreliable, and how to use metadata.namespace / status.namespace on the Tenant CR to walk the tree reliably. Assisted-By: Claude <noreply@anthropic.com> Signed-off-by: Aleksei Sviridkin <f@lex.la>
lexfrei
force-pushed
the
docs/tenant-namespace-naming-convention
branch
from
886743d to
d37bf26
Compare
2 participants
What
Adds two new sections to the Tenant System guide (
/docs/v1/guides/tenants/) that document how tenant workload namespace names are constructed and how downstream integrations should walk the tenant tree without string-parsing namespace names.Why
Tenant workload namespaces follow two different rules depending on depth: tenants created directly under
tenant-rootget a flat name (tenant-alpha), while tenants created at any deeper level get a hierarchical name (tenant-alpha-beta,tenant-alpha-beta-gamma). This split is not documented anywhere incontent/en/docs/v1/, so anyone building dashboards, audit tooling, cost-allocation jobs, or policy engines on top of Cozystack has to infer it from the chart templates. The natural first attempt —strings.Split(namespace, "-")to derive a parent — is wrong for one of the two cases regardless of which heuristic you pick, and integrations that try it run into silent breakage on root-level or deep-level tenants.The new material:
rootdown toroot/alpha/beta/gamma, and links to the two source-of-truth files (packages/apps/tenant/templates/_helpers.tplandpkg/registry/apps/application/rest.go::computeTenantNamespace) so a reader can audit the claim against the implementation.TenantCR fields that should be used instead:metadata.namespacealways equals the parent's workload namespace,status.namespaceequals the tenant's own workload namespace, and listing children of a tenant with workload namespaceNislist Tenants where metadata.namespace == N. This pattern is stable regardless of whether the tenant is a direct child oftenant-rootor a deeper descendant.No existing content is moved or rewritten; the sections are inserted between Tenant Naming Limitations and Reference, where readers looking for naming details will naturally land.
Verification
hugobuilds cleanly; the tenants guide renders with both new sections.packages/apps/tenant/templates/_helpers.tpl::tenant.namein the current cozystack tree (the helper fails the Helm release if the tenant name itself contains a dash, which is why the "namespace fragments never contain tenant-internal dashes" note is accurate).metadata.namespaceequals the parent's workload namespace" claim matches Kubernetes semantics —TenantCRs are namespace-scoped and stored in the parent's workload namespace by construction.pkg/registry/apps/application/rest.go::computeTenantNamespace) implements the same flat/hierarchical split, sostatus.namespaceon aTenantCR is a reliable mirror of the workload namespace.Summary by CodeRabbit