@@ -54,7 +54,7 @@ jobs:
 
       - name: Install generate
         run: |
-          curl -sSL https://github.com/cozystack/cozyvalues-gen/releases/download/v1.6.0/cozyvalues-gen-linux-amd64.tar.gz | tar -xzvf- -C /usr/local/bin/ cozyvalues-gen
+          curl -sSL https://github.com/cozystack/cozyvalues-gen/releases/download/v1.7.0/cozyvalues-gen-linux-amd64.tar.gz | tar -xzvf- -C /usr/local/bin/ cozyvalues-gen
 
       - name: Run pre-commit hooks
         run: |
 
@@ -99,6 +99,8 @@ Build environment variables:
 
 Package `values.yaml` files carry annotations (`@param`, `@typedef`, `@field`, `@enum`, `@section`) that `cozyvalues-gen` turns into `values.schema.json` and `README.md`. Run `make generate` in the package after editing annotations. A pre-commit hook runs `make generate` across `packages/apps/*` and `packages/extra/*` on every commit to keep these in sync — see [`contributing.md`](./contributing.md) for the regenerate-before-commit rule.
 
+A chart also declares the limits on its own resource name there, with `## @name {string} - <why>` followed by the constraint tags (`@maxLength`, `@minLength`, `@pattern`) it needs. `cozyvalues-gen` publishes the declaration at the root of `values.schema.json` as `x-cozystack-name`, from where `hack/update-crd.sh` carries it into the ApplicationDefinition, and the aggregated API server enforces it on `metadata.name` for whatever kind the definition describes. The description is the message a rejected name is answered with, so write it as the explanation of the limit. A `@pattern` is unanchored, as JSON Schema specifies, so one meant for the whole name is written `^...$`. A declaration the server cannot enforce as written — an unknown keyword, a wrong type, a limit no name satisfies, a pattern that is not RE2 — refuses every create of that kind with a configuration error rather than being dropped. A cap only ever tightens: `prefix + name` must still fit the 53-character Helm release name limit, and a declaration looser than that budget does not widen it. The limits belong in the chart because that is where the facts behind them are — which sub-resources it renders and what release names they take — and a chart that needs nothing beyond the platform-wide limits declares nothing.
+
 ## Testing
 
 - **Helm unit tests:** `make helm-unit-tests` (runs `hack/helm-unit-tests.sh` over every package that defines a `test` target). A `test` target is expected to run helm-unittest: the sweep fails a package whose run reports no suite, because exiting 0 having asserted nothing is indistinguishable from passing. A target that drives something else belongs under another name, as `packages/core/testing` already does with its sandbox flow. `make unit-tests` runs the unit suite — Helm, BATS, Go, and the preset/readiness checks. It does not reach the controller and contract tests under `./internal/...`, which have their own target, `make test-controllers`, so covering both locally means running that target as well; CI runs them as two steps of one job.
 
@@ -157,6 +157,9 @@ func diffResource(base, head Resource) []string {
 		for _, c := range diffSchema("spec", base.Versions[v], headSchema) {
 			out = append(out, fmt.Sprintf("[%s] %s", v, c))
 		}
+		for _, c := range diffNameSchema(base.Versions[v], headSchema) {
+			out = append(out, fmt.Sprintf("[%s] %s", v, c))
+		}
 	}
 	return out
 }
 
@@ -126,3 +126,40 @@ func TestClassify(t *testing.T) {
 		}
 	})
 }
+
+// TestClassifyNameDeclaration covers the constraints an application declares
+// on its own metadata.name at the schema root: tightening one rejects names
+// the base accepted, loosening or dropping one does not.
+func TestClassifyNameDeclaration(t *testing.T) {
+	kube := func(declaration map[string]any) Resource {
+		s := Schema{"type": "object", "properties": map[string]any{}}
+		if declaration != nil {
+			s["x-cozystack-name"] = declaration
+		}
+		return res("apps.cozystack.io", "Kubernetes", "kuberneteses", SourceCozyRD, s)
+	}
+	capAt := func(n float64) map[string]any { return map[string]any{"type": "string", "maxLength": n} }
+
+	for _, tc := range []struct {
+		name       string
+		base, head Resource
+		breaking   bool
+	}{
+		{"cap added", kube(nil), kube(capAt(32)), true},
+		{"cap lowered", kube(capAt(32)), kube(capAt(30)), true},
+		{"pattern added", kube(capAt(32)), kube(map[string]any{"type": "string", "maxLength": 32.0, "pattern": "^[a-z]+$"}), true},
+		{"cap raised", kube(capAt(32)), kube(capAt(40)), false},
+		{"cap dropped", kube(capAt(32)), kube(nil), false},
+		{"unchanged", kube(capAt(32)), kube(capAt(32)), false},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			got := countCategory(Classify(snap(tc.base), snap(tc.head)), Breaking)
+			if tc.breaking && got != 1 {
+				t.Fatalf("expected 1 breaking finding, got %d", got)
+			}
+			if !tc.breaking && got != 0 {
+				t.Fatalf("expected no breaking finding, got %d", got)
+			}
+		})
+	}
+}
@@ -20,6 +20,8 @@ import (
 	"fmt"
 	"sort"
 	"strings"
+
+	appsv1alpha1 "github.com/cozystack/cozystack/pkg/apis/apps/v1alpha1"
 )
 
 // diffSchema walks a base and head OpenAPIv3Schema node in lockstep and
@@ -39,6 +41,32 @@ func diffSchema(path string, base, head Schema) []string {
 	return out
 }
 
+// diffNameSchema reports a tightened constraint on metadata.name. An
+// application declares those beside "properties" at the schema root, where the
+// walk over spec never looks. The type is left out: a name is a string whether
+// or not the declaration says so.
+func diffNameSchema(base, head Schema) []string {
+	headName := nameDeclaration(head)
+	if headName == nil {
+		return nil
+	}
+	return diffSchema("metadata.name", nameDeclaration(base), headName)
+}
+
+func nameDeclaration(s Schema) Schema {
+	declared, ok := s[appsv1alpha1.NameSchemaExtension].(map[string]any)
+	if !ok {
+		return nil
+	}
+	out := Schema{}
+	for k, v := range declared {
+		if k != "type" {
+			out[k] = v
+		}
+	}
+	return out
+}
+
 func diffNode(path string, base, head Schema, out *[]string) {
 	// A nil head means the schema at this path was removed entirely. Dropping a
 	// constraint is a widening, never a break, so there is nothing to report.
 
@@ -1,6 +1,11 @@
 {
   "title": "Chart Values",
   "type": "object",
+  "x-cozystack-name": {
+    "type": "string",
+    "description": "Kafka cluster name. The KRaft controller pods are named `kafka-\u003cname\u003e-c-\u003chash\u003e-\u003cid\u003e` with an 8-character hash, and that pod hostname must fit the 63-character DNS-1123 label limit even for the smallest cluster.",
+    "maxLength": 44
+  },
   "properties": {
     "external": {
       "description": "Enable external access from outside the cluster.",
 
@@ -1,3 +1,6 @@
+## @name {string} - Kafka cluster name. The KRaft controller pods are named `kafka-<name>-c-<hash>-<id>` with an 8-character hash, and that pod hostname must fit the 63-character DNS-1123 label limit even for the smallest cluster.
+## @maxLength 44
+
 ##
 ## @section Common parameters
 ##
 
@@ -1,6 +1,11 @@
 {
   "title": "Chart Values",
   "type": "object",
+  "x-cozystack-name": {
+    "type": "string",
+    "description": "Cluster name. Every worker pool is a separate KubernetesNodes release named `kubernetes-nodes-\u003cname\u003e-\u003cpool\u003e`, so the name must leave room for the default `md0` pool inside the 53-character Helm release name limit.",
+    "maxLength": 32
+  },
   "properties": {
     "storageClass": {
       "description": "Default StorageClass inside the tenant cluster. Remote-accessible LINSTOR classes are auto-propagated to the tenant under the same name.",
 
@@ -1,3 +1,6 @@
+## @name {string} - Cluster name. Every worker pool is a separate KubernetesNodes release named `kubernetes-nodes-<name>-<pool>`, so the name must leave room for the default `md0` pool inside the 53-character Helm release name limit.
+## @maxLength 32
+
 ##
 ## @section Common Parameters
 ##
 
@@ -423,9 +423,9 @@ kubectl get helmrelease --all-namespaces \
         continue
       fi
 
-      # Helm refuses release names longer than 53 characters. rest.go today caps a
-      # new cluster name at 32 (maxKubernetesClusterName = 53 - len("kubernetes-nodes-")
-      # - len("-md0")) precisely so its pools fit, but a legacy or hand-created
+      # Helm refuses release names longer than 53 characters. The kubernetes chart
+      # caps a new cluster name at 32 (its `## @name` declaration, enforced by
+      # cozystack-api) precisely so its pools fit, but a legacy or hand-created
       # cluster name can be longer, and combined with the longer kubernetes-nodes-
       # prefix the child name can overflow. Do NOT fail the whole migration
       # here: exiting would deadlock the platform pre-upgrade hook for EVERY
Original file line number	Diff line number	Diff line change
`@@ -157,6 +157,9 @@ func diffResource(base, head Resource) []string {`
`157`	`157`	`for _, c := range diffSchema("spec", base.Versions[v], headSchema) {`
`158`	`158`	`out = append(out, fmt.Sprintf("[%s] %s", v, c))`
`159`	`159`	`}`
	`160`	`+ for _, c := range diffNameSchema(base.Versions[v], headSchema) {`
	`161`	`+ out = append(out, fmt.Sprintf("[%s] %s", v, c))`
	`162`	`+ }`
`160`	`163`	`}`
`161`	`164`	`return out`
`162`	`165`	`}`