Skip to content

docs(tenants): finish isolated-field removal and document opt-in policy labels#481

Merged
kvaps merged 7 commits intomainfrom
docs/tenant-isolation-and-apiserver-access
Apr 12, 2026
Merged

docs(tenants): finish isolated-field removal and document opt-in policy labels#481
kvaps merged 7 commits intomainfrom
docs/tenant-isolation-and-apiserver-access

Conversation

@lexfrei
Copy link
Copy Markdown
Contributor

@lexfrei lexfrei commented Apr 11, 2026

What

Three-file update that closes out the isolated field removal in the v1 docs and documents the new opt-in network-policy label mechanism that replaced it.

Changed files:

  • content/en/docs/v1/getting-started/create-tenant.md — drop the outdated Dashboard-tab bullet about the isolated checkbox, drop isolated: true from the kubectl YAML example, and add an info callout after the tabs block pointing at the upgrade notes and listing both labels inline so readers of either tab see the same guidance.
  • content/en/docs/v1/operations/upgrades/_index.md — expand the pre-existing "Tenant isolated flag removed" stub with a target/label table, a complete Deployment example that includes spec.selector.matchLabels, and a short prose explanation that the Cilium allow-to-apiserver policy matches via the kube-apiserver entity rather than by hard-coded Service IP.
  • content/en/docs/v1/guides/tenants/_index.md — add a new "Network Isolation Between Tenants" section so operators landing directly on the Tenant System guide learn about the mandatory isolation model and the opt-in labels without having to read the upgrade notes.
  • content/en/docs/v1/operations/stretched/seaweedfs-multidc.md — remove the stale isolated: true from the two v1 Tenant YAML examples and add a short note pointing at the upgrade guide so a reader comparing with an older version of the doc understands why the field disappeared.

Why

Two recurring pain points from the community chat:

  1. Users still see isolated in examples (create-tenant.md, seaweedfs-multidc.md) even though the field was deleted from the tenant chart in Cozystack v1.0. Copy-pasting the old YAML leaves a silently-ignored field in their manifests; in the worst case it breaks validation on stricter admission setups.
  2. With isolation now always on, the next question every time is how do I let my operator reach kube-apiserver from inside a tenant namespace. The answer is the two Cilium-policy-gated pod labels shipped by the tenant chart (policy.cozystack.io/allow-to-apiserver and policy.cozystack.io/allow-to-etcd), but they are documented nowhere outside the chart source — users ended up discovering the labels by reading packages/apps/tenant/templates/networkpolicy.yaml in the upstream repo.

This PR documents both the removal and the replacement in the three places a user is likely to land: the getting-started flow, the Tenant System guide, and the v0→v1 upgrade notes.

Verification

  • hugo builds cleanly; all three affected pages render with the new sections.
  • Label names verified against packages/apps/tenant/templates/networkpolicy.yaml in upstream cozystack/cozystack:
    • policy.cozystack.io/allow-to-apiserver → consumed by CiliumNetworkPolicy allow-to-apiserver (egress to kube-apiserver entity on port 6443).
    • policy.cozystack.io/allow-to-etcd → consumed by CiliumClusterwideNetworkPolicy <tenant>-ingress-etcd.
  • The kube-apiserver Cilium entity claim is verified against Cilium's entity documentation.
  • Hugo auto-generates #tenant-isolated-flag-removed from the heading Tenant \isolated` flag removed(backticks are stripped, spaces become hyphens); the three cross-file{{% ref %}}` links resolve correctly in the built site.
  • grep -rn "isolated:\s*\(true\|false\)" content/en/docs/v1/ after the change only finds the intentional mention in upgrades/_index.md describing the historical isolated: false behaviour — no stale YAML examples remain.

Summary by CodeRabbit

  • Documentation
    • Updated tenant configuration documentation to reflect removal of the isolated field
    • Added details on automatic Cilium-enforced network isolation for all tenants
    • Documented pod label requirements for accessing kube-apiserver and etcd
    • Added upgrade guidance for the isolated flag removal with migration examples

lexfrei added 6 commits April 11, 2026 23:44
…y labels

The isolated field was removed from the Tenant application in v1.0; the
'Tenant isolated flag removed' note in the upgrade guide already
acknowledges this, but users still hit the follow-up question every
week in chat: with isolation always on, how do you let tenant workloads
reach kube-apiserver or the tenant's own etcd? The answer is the opt-in
policy labels shipped by the tenant chart:

  policy.cozystack.io/allow-to-apiserver: "true"
  policy.cozystack.io/allow-to-etcd:      "true"

These labels are consumed by CiliumNetworkPolicies the tenant chart
installs in every tenant namespace (allow-to-apiserver and
allow-to-etcd in packages/apps/tenant/templates/networkpolicy.yaml).
Without the label, the matching policy does not apply and traffic is
blocked.

Changes:
- create-tenant.md: delete the outdated bullet describing the isolated
  checkbox, remove isolated: true from the kubectl example, and add an
  info callout linking to the upgrade note.
- upgrades/_index.md: extend the 'Tenant isolated flag removed' section
  with a table of label-gated targets and a concrete Deployment example
  that shows where the label goes in a pod template.

Assisted-By: Claude <noreply@anthropic.com>
Signed-off-by: Aleksei Sviridkin <f@lex.la>
…ple apply-able

- Drop the 'other cluster services' hedge from the create-tenant alert
  so it lists only what the upgrade notes actually document
  (kube-apiserver and tenant-owned etcd).
- Add spec.selector.matchLabels to the Deployment example in the upgrade
  notes so a reader can kubectl apply it as-is without hitting a
  validation error.

Assisted-By: Claude <noreply@anthropic.com>
Signed-off-by: Aleksei Sviridkin <f@lex.la>
Readers of the Using Dashboard tab never saw the isolation callout
because it lived inside the Using kubectl tab. Move it below the
closing tabs shortcode so both tab audiences see it, and mention that
neither the Dashboard form nor the HelmRelease values field exists
anymore.

Assisted-By: Claude <noreply@anthropic.com>
Signed-off-by: Aleksei Sviridkin <f@lex.la>
…tside upgrades

- Remove the 10.96.0.1:443 example from the upgrade-notes table: that
  address is only the default Service CIDR allocation, and Cozystack
  operators choose the range freely. Point at the 'kubernetes' Service
  in the default namespace instead and show the kubectl lookup so
  readers on a non-default CIDR do not chase a stale IP.
- Rewrite the create-tenant callout so fresh-install readers learn the
  mechanism directly from the getting-started page instead of only
  finding it in the upgrade notes — list both labels inline and keep
  the upgrade-notes link for the full worked example.
- Add a new 'Network Isolation Between Tenants' subsection to the
  Tenant System guide so operators landing there understand the
  mandatory isolation model and the opt-in label contract, with a
  cross-reference to the upgrade notes for the migration context.

Assisted-By: Claude <noreply@anthropic.com>
Signed-off-by: Aleksei Sviridkin <f@lex.la>
…dd etcd qualifier

- Remove isolated: true from the two v1 Tenant YAML examples in the
  SeaweedFS multi-datacentre guide. The field was removed from the
  tenant chart in v1.0; copying these manifests as-is on a modern
  cluster leaves a stale field that is silently ignored at best.
- Qualify the etcd note in the create-tenant callout so it only
  applies to tenants that were actually created with etcd: true,
  matching the wording already on the Tenant System guide page.

Assisted-By: Claude <noreply@anthropic.com>
Signed-off-by: Aleksei Sviridkin <f@lex.la>
…er, note removal in multi-DC guide

- Drop the 'reachable through the kubernetes Service in the default
  namespace' parenthetical from the upgrades table. The Cilium
  allow-to-apiserver policy matches traffic via the kube-apiserver
  Cilium entity, which resolves the real API server endpoints — the
  Service name is a distraction. Restate the same thing plainly
  below the table.
- Add the 'only applicable when the tenant was created with etcd:
  true' qualifier to the Tenant System guide's new Network Isolation
  section so it matches the wording in the create-tenant callout.
- Add a short note to the SeaweedFS multi-DC guide that the isolated
  field was removed in v1.0, with a link back to the upgrade notes.
  Readers who compare the example against older versions can see
  why the field disappeared.

Assisted-By: Claude <noreply@anthropic.com>
Signed-off-by: Aleksei Sviridkin <f@lex.la>
@netlify
Copy link
Copy Markdown

netlify Bot commented Apr 11, 2026

Deploy Preview for cozystack ready!

Name Link
🔨 Latest commit ab91c81
🔍 Latest deploy log https://app.netlify.com/projects/cozystack/deploys/69dac3422bf90a00082d0557
😎 Deploy Preview https://deploy-preview-481--cozystack.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

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

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented Apr 11, 2026

Warning

Rate limit exceeded

@lexfrei has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 8 minutes and 7 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 8 minutes and 7 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 52d7f65d-f9b2-4da2-9cb3-f1f1730b2c7c

📥 Commits

Reviewing files that changed from the base of the PR and between 7ccde63 and ab91c81.

📒 Files selected for processing (1)
  • content/en/docs/v1/operations/upgrades/_index.md
📝 Walkthrough

Walkthrough

This documentation update removes references to the deprecated isolated tenant configuration field and clarifies the new Cilium-based network isolation mechanism that now enforces cross-tenant isolation by default. Pod labels enable explicit opt-in access to control-plane components like kube-apiserver and etcd.

Changes

Cohort / File(s) Summary
Tenant Configuration Examples
content/en/docs/v1/getting-started/create-tenant.md, content/en/docs/v1/operations/stretched/seaweedfs-multidc.md
Removed isolated: true from HelmRelease and Tenant manifest examples; added/updated references to upgrade documentation covering field removal.
Network Isolation Policy Documentation
content/en/docs/v1/guides/tenants/_index.md, content/en/docs/v1/operations/upgrades/_index.md
Added new sections describing Cilium-enforced cross-tenant isolation, default pod restrictions on kube-apiserver and etcd access, and pod label-based opt-in mechanism (policy.cozystack.io/allow-to-apiserver and allow-to-etcd); included YAML examples and target-to-label mappings.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 The isolated flag hops away with grace,
Cilium nets now guard each tenant's space,
Pod labels unlock the paths they need,
Network policies plant the security seed,
Clearer docs bloom for all to read! 🌿

🚥 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 accurately summarizes the main changes: documentation cleanup removing the isolated field and documenting the replacement opt-in policy labels.
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-isolation-and-apiserver-access

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.

Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request updates the documentation to reflect the removal of the isolated flag in Cozystack v1.0, as network isolation via Cilium policies is now mandatory for all tenants. The changes include updated configuration examples and instructions on using specific pod labels to opt-in for access to the Kubernetes API server and tenant-owned etcd. One grammatical correction was identified in the upgrade notes regarding subject-verb agreement.

The `isolated` field has been removed from Tenant configuration. Network isolation via
NetworkPolicy is now always enforced for all tenants. If you previously relied on
`isolated: false` to allow unrestricted traffic between tenants, this is no longer possible.
Cilium network policies is now always enforced for every tenant — there is no
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The sentence 'Cilium network policies is now always enforced' contains a subject-verb agreement error. Since 'policies' is plural, the verb should be 'are' to ensure grammatical correctness.

Suggested change
Cilium network policies is now always enforced for every tenant — there is no
Cilium network policies are now always enforced for every tenant — there is no

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied, but differently than suggested: the subject of is enforced is Network isolation (singular), and via Cilium network policies is a prepositional modifier — the original sentence was grammatical but easy to misread. Reworded to Network isolation is now always enforced for every tenant via Cilium network policies so the subject sits next to the verb.

@lexfrei lexfrei marked this pull request as ready for review April 11, 2026 21:33
@lexfrei lexfrei requested review from kvaps and lllamnyp as code owners April 11, 2026 21:33
…biguity

Move 'via Cilium network policies' after the verb so it's unambiguous
that the subject of 'is now always enforced' is 'network isolation'
(singular), not 'policies' (plural).

Assisted-By: Claude <noreply@anthropic.com>
Signed-off-by: Aleksei Sviridkin <f@lex.la>
@kvaps kvaps merged commit be69d4a into main Apr 12, 2026
6 checks passed
@kvaps kvaps deleted the docs/tenant-isolation-and-apiserver-access branch April 12, 2026 09:34
@lexfrei lexfrei self-assigned this Apr 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants