docs(v1): migrate ConfigMap references to Platform Package - #426

content/en/docs/v1/operations/cluster/upgrade.md (1)

46-56: Consider adding a --set example to reinforce the warning.

The alert advises against --reuse-values and says to pass custom values with --set, but the code block immediately after shows no --set flag. A brief illustration would make this actionable:

✏️ Suggested enhancement

 ```bash
 helm upgrade cozystack oci://ghcr.io/cozystack/cozystack/cozy-installer \
   --version X.Y.Z \
-  --namespace cozy-system
+  --namespace cozy-system \
+  --set disableTelemetry=true   # pass any custom values explicitly

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @content/en/docs/v1/operations/cluster/upgrade.md around lines 46 - 56, Add a
concrete --set example to the existing helm upgrade invocation shown by the
"helm upgrade cozystack oci://ghcr.io/cozystack/cozystack/cozy-installer"
snippet: modify that command to demonstrate passing a custom value (e.g., "--set
disableTelemetry=true") alongside "--version X.Y.Z" and "--namespace
cozy-system" so readers see exactly how to pass explicit values instead of using
--reuse-values.

</details>

</blockquote></details>

</blockquote></details>

<details>
<summary>🤖 Prompt for all review comments with AI agents</summary>

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @content/en/docs/v1/guides/resource-management/_index.md:

• Around line 109-110: The snippet hardcodes "variant: isp-full" under the spec
  key which can cause users to copy an incorrect deployment variant; update the
  example around the spec -> variant: isp-full entry to either replace the literal
  with a clear placeholder (e.g., ) or add an inline comment
  directly above/beside "variant: isp-full" stating that users must set this to
  the actual installed variant for their environment, and keep the identifier
  "variant: isp-full" so reviewers can find and verify the change.

In @content/en/docs/v1/install/cozystack/_index.md:

• Around line 103-108: Replace the hardcoded version flag (--version
  1.0.0-beta.6) in the Helm install snippet with a placeholder like --version
  vX.Y.Z and add a short note/link directing users to the releases page
  (https://github.com/cozystack/cozystack/releases) so readers are instructed to
  substitute the desired release; apply the same change to the matching snippet in
  hetzner.md so both files follow the getting-started/install-cozystack.md
  pattern.

In @content/en/docs/v1/install/providers/hetzner.md:

• Around line 318-323: Replace the hardcoded version in the Helm install snippet
  (the --version 1.0.0-beta.6 value in the helm install cozystack oci://... --version ... command) with the placeholder X.Y.Z and add the same guidance
  note used in telemetry.md telling users to substitute the desired released
  version; ensure the change mirrors the telemetry.md phrasing and keeps the rest
  of the Helm example unchanged.

In @content/en/docs/v1/operations/configuration/bundles.md:

• Around line 88-111: Add a short clarifying paragraph to the bundles.md doc
  that maps the human-facing section bundle names to the v1 Package variant
  values: explicitly state that the section headings use bundle names (e.g.,
  "paas-full", "paas-hosted") while the Package spec's variant field must use the
  corresponding v1 values ("isp-full", "isp-hosted"); reference the Package field
  name variant and the example YAML snippet shown so readers know to use variant:
  isp-full or variant: isp-hosted rather than variant: paas-full.

In @content/en/docs/v1/operations/configuration/configmap.md:

• Line 8: Remove the self-referential alias entry in the page's front matter:
  locate the aliases field that includes
  "/docs/v1/operations/configuration/configmap" and either delete that alias or
  replace it with a different external/previous URL; ensure the page front matter
  (aliases) no longer contains the identical canonical URL to avoid generating a
  redirect loop.

In @content/en/docs/v1/operations/upgrades/_index.md:

• Around line 28-31: The prerequisites list fails to document that the
  --take-ownership flag requires Helm v3.17.0+, so update the Helm bullet (the
  line that currently reads "helm — required for installing the new operator") to
  explicitly state the minimum version (e.g., "helm v3.17.0+ — required for
  installing the new operator; required for the --take-ownership flag introduced
  in v3.17.0"). Ensure the text references the flag name "--take-ownership" and
  the minimum version "v3.17.0+" so users know to upgrade their Helm if they see
  the "unknown flag: --take-ownership" error.
• Around line 75-82: The helm install example uses a non-prefixed version
  placeholder that conflicts with GHCR tags; update the command's --version
  placeholder in the helm install example (the line containing "--version
  <TARGET_VERSION>") to require the v-prefixed format (e.g., "--version v1.0.0")
  so it matches Cozystack release tags and the other doc example
  (install-cozystack.md) and will resolve correctly against the OCI chart
  registry.

In @content/en/docs/v1/virtualization/_index.md:

• Around line 70-83: The current kubectl patch uses --type=merge which, because
  JSON Merge Patch replaces arrays, will overwrite the existing exposedServices
  array (removing pre-existing entries like "api"); change the patch to use a JSON
  Patch that appends items (use ops on the "exposedServices" array) or
  alternatively update the docs to show the full desired array so existing entries
  aren't lost; look for the kubectl patch command targeting packages.cozystack.io
  cozystack.cozystack-platform and the exposedServices field to implement the JSON
  Patch append or to replace the example with the complete list.

In @content/en/docs/v1/virtualization/gpu.md:

• Line 55: The numbered sub-steps under the "1. Install the GPU Operator"
  section have a gap: after step 2 the next item is labeled 4 ("Ensure all pods
  are in a running state... sandbox-validator"), so renumber that item to 3 (and
  renumber any subsequent steps accordingly), update any in-text references to
  step numbers, and verify the ordered list markup is consistent so the sequence
  reads 1, 2, 3, ...; specifically edit the line containing "Ensure all pods are
  in a running state and all validations succeed with the sandbox-validator
  component" to be step 3 and adjust following steps if present.
• Around line 38-51: The kubectl patch shown uses --type=merge which will
  replace the enabledPackages array instead of appending; update the instructions
  to use a JSON Patch add that appends to the array (using an "add" operation with
  path ending in "/-") or, if you keep --type=merge, add a clear warning that
  enabledPackages will be replaced and show the safe two-step approach (initialize
  enabledPackages to an empty array then merge) so users don't accidentally lose
  existing entries; reference the kubectl patch command, the --type=merge flag,
  and the enabledPackages field when making the change.

In @content/en/docs/v1/virtualization/proxmox-migration.md:

• Around line 26-38: The patch example uses kubectl patch with --type=merge
  which performs a JSON Merge Patch and will replace arrays like "exposedServices"
  wholesale; update the proxmox-migration.md snippet to add a short inline note
  next to the kubectl patch example warning that JSON Merge Patch replaces arrays
  and that users must include all desired services (e.g., include existing
  "ingress-nginx" as well) or first read the current value (suggest using kubectl
  get ... -o jsonpath or kubectl get -o yaml) before applying the patch so they
  don't accidentally drop entries.

---

Outside diff comments:
In @content/en/docs/v1/getting-started/install-cozystack.md:

• Around line 472-516: Remove the third kubectl patch block that targets the
  custom CRD "ingresses.apps.cozystack.io ingress" (the patch that sets
  "spec.externalIPs") since the production guide only requires patching the
  Platform Package and setting tenant "ingress: true"; instead either delete that
  entire code block or replace it with a short note instructing readers to verify
  externalIPs on the Service (e.g., kubectl get svc -n tenant-root) if
  confirmation is needed, and ensure references to "externalIPs" and the
  "ingresses.apps.cozystack.io ingress" patch are removed so the tutorial matches
  the production guide.

In @content/en/docs/v1/guides/resource-management/_index.md:

• Around line 130-146: Replace the remaining kebab-case ConfigMap references of
  "cpu-allocation-ratio" with the new camelCase key "cpuAllocationRatio" in this
  markdown section so the page is consistent (update the occurrences shown in the
  examples and headings that currently say cpu-allocation-ratio to
  cpuAllocationRatio); ensure you update all inline code spans and any table
  headings or example captions that reference the old key, e.g., the Example 1
  title and Example 2 title and any inline code blocks that still contain
  cpu-allocation-ratio.

In @content/en/docs/v1/operations/configuration/configmap.md:

• Around line 159-164: Remove or restore the two orphaned link-reference
  definitions [overwrite-parameters] and [telemetry] in the markdown: either
  delete those unused reference lines from the bottom of the file (to clean up
  dead references) or reintroduce in-text links that point to them (e.g., a
  sentence referring readers to the overwrite-parameters section and the telemetry
  opt-out page) so the definitions are actually referenced by the page.

In @content/en/docs/v1/virtualization/proxmox-migration.md:

• Line 209: The troubleshooting line referencing the old ConfigMap is
  stale—locate the exact string 'Ensure Cozystack ConfigMap has expose-services: "dashboard,cdi-uploadproxy"' and replace it with a Platform Package–centric
  instruction that matches the migration described earlier (e.g., tell users to
  ensure the Cozystack Platform Package has the expose-services setting configured
  in its spec or via the Platform Package config, not in a ConfigMap) so the
  Troubleshooting section aligns with the Prerequisites and migration guidance.

---

Duplicate comments:
In @content/en/docs/v1/getting-started/install-cozystack.md:

• Around line 84-92: The helm command snippet uses an inconsistent OCI tag
  format; update the snippet's --version value (in the "helm install cozystack
  ..." block) to match the actual OCI tag format used elsewhere (remove the
  leading "v" so it reads --version 1.0.0 or replace with a placeholder like
  --version <CHART_TAG>) and add a short note telling readers to verify the exact
  tag format with the verification script referenced in the upgrades doc; ensure
  the change keeps the same helm install line and --version flag.

---

Nitpick comments:
In @content/en/docs/v1/operations/cluster/upgrade.md:

• Around line 46-56: Add a concrete --set example to the existing helm upgrade
  invocation shown by the "helm upgrade cozystack
  oci://ghcr.io/cozystack/cozystack/cozy-installer" snippet: modify that command
  to demonstrate passing a custom value (e.g., "--set disableTelemetry=true")
  alongside "--version X.Y.Z" and "--namespace cozy-system" so readers see exactly
  how to pass explicit values instead of using --reuse-values.

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->

layouts/shortcodes/reuse-values-warning.html (1)

4-5: Replace <br/><br/> with <p> tags for semantic paragraph separation.

<br/><br/> is a presentational hack; <p> tags convey paragraph structure to screen readers and are easier to style via CSS.

♻️ Proposed refactor

-Do not use <code>--reuse-values</code> when upgrading the Cozystack operator. The Helm chart values contain hardcoded references to the platform OCI repository. Reusing old values would result in the operator pointing to old package versions.
-<br/><br/>
-If you have custom values (e.g., <code>disableTelemetry</code>), pass them explicitly with <code>--set</code>.
+<p>Do not use <code>--reuse-values</code> when upgrading the Cozystack operator. The Helm chart values contain hardcoded references to the platform OCI repository. Reusing old values would result in the operator pointing to old package versions.</p>
+<p>If you have custom values (e.g., <code>disableTelemetry</code>), pass them explicitly with <code>--set</code>.</p>

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@layouts/shortcodes/reuse-values-warning.html` around lines 4 - 5, Replace the
presentational line breaks with semantic paragraph elements in the
reuse-values-warning snippet: remove the literal "<br/><br/>" and wrap the
sentence "If you have custom values (e.g., <code>disableTelemetry</code>), pass
them explicitly with <code>--set</code>." in a proper <p>…</p> element so screen
readers and CSS can target a semantic paragraph; ensure the paragraph is
correctly opened and closed within the same snippet.

content/en/docs/v1/storage/nfs.md (1)

14-32: Move the array-clobbering warning to before the code block.

The {{% alert %}} warning about JSON Merge Patch replacing enabledPackages wholesale appears after the kubectl patch command. A user who copies and runs the command before reading the warning will silently wipe any pre-existing entries. Swapping the order ensures the caution is visible before execution.

♻️ Proposed reordering

+{{% alert color="warning" %}}
+JSON Merge Patch (`--type=merge`) replaces arrays wholesale. If you already have entries in `enabledPackages`, include all of them in the patch to avoid losing existing values.
+{{% /alert %}}
+
 ```bash
 kubectl patch packages.cozystack.io cozystack.cozystack-platform --type=merge -p '{
   "spec": {
     "components": {
       "platform": {
         "values": {
           "bundles": {
             "enabledPackages": ["nfs-driver"]
           }
         }
       }
     }
   }
 }'

-{{% alert color="warning" %}}
-JSON Merge Patch (--type=merge) replaces arrays wholesale. If you already have entries in enabledPackages, include all of them in the patch to avoid losing existing values.
-{{% /alert %}}

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @content/en/docs/v1/storage/nfs.md around lines 14 - 32, Move the warning
alert (the {{% alert color="warning" %}} block) so it appears immediately before
the kubectl patch code block rather than after it; update the document around
the kubectl patch command and the {{% alert %}} block so the caution about JSON
Merge Patch replacing arrays wholesale is visible above the kubectl patch
example (refer to the kubectl patch command and the {{% alert color="warning"
%}} block to locate the elements to reorder).

</details>

</blockquote></details>
<details>
<summary>content/en/docs/v1/operations/upgrades/_index.md (1)</summary><blockquote>

`95-99`: **Migration script references `main` branch — pin to a release tag for reproducibility.**

The `curl | bash` URL points to the `main` branch of the cozystack repo. If the script is updated after a release (e.g., for v1.1 migration), users running this guide for a v0.41→v1.0 upgrade could silently execute a different script version.



<details>
<summary>♻️ Proposed fix</summary>

```diff
-curl -fsSL https://raw.githubusercontent.com/cozystack/cozystack/main/hack/migrate-to-version-1.0.sh | bash
+curl -fsSL https://raw.githubusercontent.com/cozystack/cozystack/v<TARGET_VERSION>/hack/migrate-to-version-1.0.sh | bash

Apply the same change to the download-and-inspect alternative on lines 112–113.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@content/en/docs/v1/operations/upgrades/_index.md` around lines 95 - 99, The
migration instruction currently downloads the script from the repository "main"
branch (the curl | bash URL) which is not reproducible; update the URL to
reference the specific release tag for v1.0 (or the intended release) instead of
"main" so the exact script version is fetched, and make the same change for the
alternate download-and-inspect command mentioned later (the download URL on
lines 112–113) so both examples point to the same pinned release tag.