Skip to content

Commit a391181

Browse files
committed
feat(api): take Application name limits from the application's schema
The API server capped Kubernetes and Kafka names by knowing what those two charts render: worker pool releases under a 17-character prefix, controller pods with a 13-character suffix. That is the charts' knowledge sitting in the platform, and it does not generalise. The next application with a sub-resource budget needs another branch on Kind, and an application served from outside this repository cannot get one at all. An application now declares the limits on its own name in its schema, under x-cozystack-name, and the server applies whatever it finds there for whatever kind the ApplicationDefinition describes. A declaration only tightens: prefix + name must still fit the 53-character Helm release name limit. A rejected name is answered with the chart's own explanation of the limit. The schema is untrusted input, and definitions from other repositories are written by hand. A declaration that cannot be enforced as written, whether an unknown keyword, a wrong type, a limit no name satisfies or a pattern Go cannot compile, refuses creates of that kind with a configuration error. Dropping it would admit names the chart cannot render; applying it would reject every name and blame the user. An upgrade brings cozystack-api up before the definitions it serves are re-rendered, so for a while the new server can read a Kubernetes or Kafka definition that predates its declaration. The two old caps stay as a floor for exactly that case, a definition that declares nothing, until no supported upgrade starts from one. Assisted-by: LLM Signed-off-by: Timofei Larkin <[email protected]>
1 parent 06b41da commit a391181

6 files changed

Lines changed: 462 additions & 107 deletions

File tree

‎docs/agents/overview.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,8 @@ Build environment variables:
9898

9999
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.
100100

101+
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.
102+
101103
## Testing
102104

103105
- **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 full unit suite — Helm, BATS, Go, and the preset/readiness checks.

‎packages/core/platform/images/migrations/migrations/56‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -423,9 +423,9 @@ kubectl get helmrelease --all-namespaces \
423423
continue
424424
fi
425425

426-
# Helm refuses release names longer than 53 characters. rest.go today caps a
427-
# new cluster name at 32 (maxKubernetesClusterName = 53 - len("kubernetes-nodes-")
428-
# - len("-md0")) precisely so its pools fit, but a legacy or hand-created
426+
# Helm refuses release names longer than 53 characters. The kubernetes chart
427+
# caps a new cluster name at 32 (its `## @name` declaration, enforced by
428+
# cozystack-api) precisely so its pools fit, but a legacy or hand-created
429429
# cluster name can be longer, and combined with the longer kubernetes-nodes-
430430
# prefix the child name can overflow. Do NOT fail the whole migration
431431
# here: exiting would deadlock the platform pre-upgrade hook for EVERY

‎pkg/apis/apps/v1alpha1/types.go‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,11 @@ const (
2828
ApplicationNameLabel = "apps.cozystack.io/application.name"
2929
)
3030

31+
// NameSchemaExtension is the root-level key of an ApplicationDefinition's
32+
// openAPISchema under which an application declares the constraints on its own
33+
// metadata.name. cozyvalues-gen emits it from a chart's `## @name` annotation.
34+
const NameSchemaExtension = "x-cozystack-name"
35+
3136
// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
3237

3338
// ApplicationList is a list of Application objects.

‎pkg/registry/apps/application/rest.go‎

Lines changed: 181 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -17,10 +17,12 @@ limitations under the License.
1717
package application
1818

1919
import (
20+
"bytes"
2021
"context"
2122
"encoding/json"
2223
"fmt"
2324
"net/http"
25+
"regexp"
2426
"strconv"
2527
"strings"
2628
"sync"
@@ -96,6 +98,8 @@ type REST struct {
9698
singularName string
9799
releaseConfig config.ReleaseConfig
98100
specSchema *structuralschema.Structural
101+
nameSchema *applicationNameSchema
102+
nameSchemaErr error
99103
}
100104

101105
// buildSpecSchema parses an OpenAPI-v3 JSON schema string and returns the
@@ -134,6 +138,12 @@ func NewREST(c client.Client, w client.WithWatch, config *config.Resource) *REST
134138
klog.Errorf("Failed to build spec schema: %v", err)
135139
}
136140

141+
nameSchema, nameSchemaErr := resolveNameSchema(config)
142+
if nameSchemaErr != nil {
143+
klog.Errorf("ApplicationDefinition for %s declares an invalid %s, refusing to create %s objects until it is fixed: %v",
144+
config.Application.Kind, appsv1alpha1.NameSchemaExtension, config.Application.Kind, nameSchemaErr)
145+
}
146+
137147
return &REST{
138148
c: c,
139149
w: w,
@@ -150,6 +160,8 @@ func NewREST(c client.Client, w client.WithWatch, config *config.Resource) *REST
150160
singularName: config.Application.Singular,
151161
releaseConfig: config.Release,
152162
specSchema: specSchema,
163+
nameSchema: nameSchema,
164+
nameSchemaErr: nameSchemaErr,
153165
}
154166
}
155167

@@ -1284,51 +1296,173 @@ func validateNoInternalKeys(values *apiextv1.JSON) error {
12841296
// chart-generated resource suffixes within the 63-char DNS-1035 label limit.
12851297
const maxHelmReleaseName = 53
12861298

1287-
// kubernetesKind is the Application.Kind of the parent Kubernetes cluster CR,
1288-
// whose worker pools are separate KubernetesNodes releases.
1289-
const kubernetesKind = "Kubernetes"
1290-
1291-
// maxKubernetesClusterName caps a Kubernetes cluster name so its worker pools
1292-
// can always render. Since Phase 2 worker pools are separate KubernetesNodes
1293-
// releases named "<cluster>-<pool>" under the "kubernetes-nodes-" prefix (17
1294-
// chars), the smallest such child release is "kubernetes-nodes-<cluster>-md0".
1295-
// The parent's own "kubernetes-" prefix would let the cluster name reach 42,
1296-
// but that leaves no room for even the default "md0" pool's child release
1297-
// (17 + len(cluster) + len("-md0") <= 53 => len(cluster) <= 32). Capping the
1298-
// parent name at admission surfaces the overflow on the Kubernetes CR the
1299-
// operator is editing, instead of at render time on a child that can never be
1300-
// created (the migration pins and skips such a pool, leaving no way to add
1301-
// workers).
1302-
const maxKubernetesClusterName = maxHelmReleaseName - len("kubernetes-nodes-") - len("-md0")
1303-
1304-
// kafkaKind is the Application.Kind of a Kafka cluster. Its KRaft controller
1305-
// pods are named "<release>-c-<hash>-<id>" (hash is 8 hex; id is at least one
1306-
// digit for the smallest cluster), and that derived pod hostname must fit the
1307-
// 63-char DNS-1123 label limit. The controller-node suffix beyond the release
1308-
// name — "-c-" (3) + 8 (hash) + "-" (1) + 1 (smallest id) = 13 — is stricter
1309-
// than the 53-char release-name budget, so cap the name at admission. This
1310-
// surfaces the overflow on the Kafka CR the operator is editing instead of at
1311-
// render time on a pod Strimzi can never create (its render guard,
1312-
// kafka.assertNameLength, is the second line of defense and also catches larger
1313-
// clusters whose higher node ids need more digits).
1314-
const kafkaKind = "Kafka"
1315-
const kafkaControllerNodeOverhead = len("-c-") + 8 + len("-") + 1
1316-
13171299
// maxNamespaceName is the DNS-1123 label limit for Kubernetes namespace names.
13181300
// The tenant Helm chart creates a Namespace whose name is the computed
13191301
// workload namespace (parent namespace + "-" + tenant name), so the total
13201302
// must fit inside a single 63-char DNS-1123 label.
13211303
const maxNamespaceName = 63
13221304

1323-
// validateNameFormat checks an Application name against DNS-1035 and any
1305+
// applicationNameSchema is an application's own declaration of what its name
1306+
// may look like. A chart's naming budget follows from the sub-resources the
1307+
// chart renders and the names they take — facts that live in the chart and
1308+
// nowhere else — so the budget travels with the chart's schema instead of
1309+
// being a branch on Kind here.
1310+
type applicationNameSchema struct {
1311+
Type string `json:"type,omitempty"`
1312+
Description string `json:"description,omitempty"`
1313+
MinLength *int64 `json:"minLength,omitempty"`
1314+
MaxLength *int64 `json:"maxLength,omitempty"`
1315+
Pattern string `json:"pattern,omitempty"`
1316+
1317+
compiledPattern *regexp.Regexp
1318+
}
1319+
1320+
// legacyNameCaps are the caps this server enforced in code before applications
1321+
// declared their own. An upgrade brings cozystack-api up before the
1322+
// application definitions it serves are re-rendered, so for that window a
1323+
// definition can predate its chart's declaration, and without these a name
1324+
// admitted then renders sub-resources that cannot exist. They apply only to a
1325+
// definition that declares nothing, and go once no supported upgrade starts
1326+
// from a definition without the declaration.
1327+
var legacyNameCaps = map[string]applicationNameSchema{
1328+
"Kubernetes": {
1329+
MaxLength: new(int64(32)),
1330+
Description: "worker pools are KubernetesNodes releases named `kubernetes-nodes-<name>-<pool>`, which must fit the 53-character Helm release name limit",
1331+
},
1332+
"Kafka": {
1333+
MaxLength: new(int64(44)),
1334+
Description: "the KRaft controller pod hostname `kafka-<name>-c-<hash>-<id>` must fit the 63-character DNS-1123 label limit",
1335+
},
1336+
}
1337+
1338+
// resolveNameSchema returns the name constraints for the kind cfg describes.
1339+
// An error means the declaration exists but cannot be enforced as written;
1340+
// the caller refuses creates for that kind rather than guess, since guessing
1341+
// either admits names the chart cannot render or rejects names it can.
1342+
func resolveNameSchema(cfg *config.Resource) (*applicationNameSchema, error) {
1343+
declared, err := parseNameSchema(cfg.Application.OpenAPISchema)
1344+
if err != nil {
1345+
return nil, err
1346+
}
1347+
if declared == nil {
1348+
if legacy, ok := legacyNameCaps[cfg.Application.Kind]; ok {
1349+
return &legacy, nil
1350+
}
1351+
return nil, nil
1352+
}
1353+
if budget := maxHelmReleaseName - len(cfg.Release.Prefix); declared.MinLength != nil && *declared.MinLength > int64(budget) {
1354+
return nil, fmt.Errorf("minLength %d exceeds the %d characters the release prefix %q leaves, so no name fits",
1355+
*declared.MinLength, budget, cfg.Release.Prefix)
1356+
}
1357+
return declared, nil
1358+
}
1359+
1360+
// parseNameSchema extracts the x-cozystack-name declaration from an
1361+
// ApplicationDefinition's openAPISchema. Returns (nil, nil) when the schema is
1362+
// empty or declares nothing about the name. The openAPISchema is untrusted
1363+
// input — definitions from other repositories are written by hand — so an
1364+
// unknown keyword, a wrong type or a declaration no name can satisfy is an
1365+
// error rather than a constraint silently dropped.
1366+
func parseNameSchema(raw string) (*applicationNameSchema, error) {
1367+
raw = strings.TrimSpace(raw)
1368+
if raw == "" {
1369+
return nil, nil
1370+
}
1371+
var doc map[string]json.RawMessage
1372+
if err := json.Unmarshal([]byte(raw), &doc); err != nil {
1373+
return nil, fmt.Errorf("unmarshal OpenAPI schema: %w", err)
1374+
}
1375+
declared, ok := doc[appsv1alpha1.NameSchemaExtension]
1376+
if !ok {
1377+
return nil, nil
1378+
}
1379+
1380+
// encoding/json decodes null as "leave unset", which would turn a null
1381+
// declaration into an empty one that skips legacyNameCaps, and a null
1382+
// keyword into a dropped constraint.
1383+
var keywords map[string]json.RawMessage
1384+
if err := json.Unmarshal(declared, &keywords); err != nil {
1385+
return nil, fmt.Errorf("decode: %w", err)
1386+
}
1387+
if keywords == nil {
1388+
return nil, fmt.Errorf("declaration is null")
1389+
}
1390+
for k, v := range keywords {
1391+
if string(bytes.TrimSpace(v)) == "null" {
1392+
return nil, fmt.Errorf("%s is null", k)
1393+
}
1394+
}
1395+
1396+
var ns applicationNameSchema
1397+
dec := json.NewDecoder(bytes.NewReader(declared))
1398+
dec.DisallowUnknownFields()
1399+
if err := dec.Decode(&ns); err != nil {
1400+
return nil, fmt.Errorf("decode: %w", err)
1401+
}
1402+
switch {
1403+
case ns.Type != "" && ns.Type != "string":
1404+
return nil, fmt.Errorf("type %q: a name is a string", ns.Type)
1405+
case ns.MaxLength != nil && *ns.MaxLength < 1:
1406+
return nil, fmt.Errorf("maxLength %d admits no name", *ns.MaxLength)
1407+
case ns.MinLength != nil && *ns.MinLength < 0:
1408+
return nil, fmt.Errorf("minLength %d is negative", *ns.MinLength)
1409+
case ns.MinLength != nil && ns.MaxLength != nil && *ns.MinLength > *ns.MaxLength:
1410+
return nil, fmt.Errorf("minLength %d exceeds maxLength %d", *ns.MinLength, *ns.MaxLength)
1411+
}
1412+
if ns.Pattern != "" {
1413+
re, err := regexp.Compile(ns.Pattern)
1414+
if err != nil {
1415+
return nil, fmt.Errorf("pattern %q does not compile as RE2: %w", ns.Pattern, err)
1416+
}
1417+
ns.compiledPattern = re
1418+
}
1419+
return &ns, nil
1420+
}
1421+
1422+
// validateNameFormat checks an Application name against DNS-1035, any
13241423
// kind-specific format rules (e.g. Tenant names must be alphanumeric — see
1325-
// validation.ValidateApplicationName for the reasoning).
1424+
// validation.ValidateApplicationName for the reasoning), and the format the
1425+
// application declares for itself in its schema.
13261426
func (r *REST) validateNameFormat(name string) field.ErrorList {
1327-
return validation.ValidateApplicationName(name, r.kindName, field.NewPath("metadata").Child("name"))
1427+
allErrs := validation.ValidateApplicationName(name, r.kindName, field.NewPath("metadata").Child("name"))
1428+
return append(allErrs, r.validateNameAgainstSchema(name)...)
13281429
}
13291430

1330-
// validateNameLength checks that the application name won't exceed Kubernetes limits.
1331-
// prefix + name must fit within the Helm release name limit (53 chars).
1431+
// validateNameAgainstSchema applies the minLength and pattern the application
1432+
// declares for its name; maxLength is applied in validateNameLength, together
1433+
// with the Helm budget it shares. The pattern is unanchored, as JSON Schema
1434+
// specifies: a declaration that means the whole name writes ^...$.
1435+
func (r *REST) validateNameAgainstSchema(name string) field.ErrorList {
1436+
if r.nameSchema == nil {
1437+
return nil
1438+
}
1439+
fldPath := field.NewPath("metadata").Child("name")
1440+
allErrs := field.ErrorList{}
1441+
1442+
if minLen := r.nameSchema.MinLength; minLen != nil && int64(len(name)) < *minLen {
1443+
allErrs = append(allErrs, field.Invalid(fldPath, name,
1444+
fmt.Sprintf("must be at least %d characters (%s)", *minLen, r.declaredReason())))
1445+
}
1446+
if re := r.nameSchema.compiledPattern; re != nil && !re.MatchString(name) {
1447+
allErrs = append(allErrs, field.Invalid(fldPath, name,
1448+
fmt.Sprintf("must match %q (%s)", r.nameSchema.Pattern, r.declaredReason())))
1449+
}
1450+
return allErrs
1451+
}
1452+
1453+
// declaredReason is what a name rejected by the application's own
1454+
// declaration is told: the chart's explanation when it gives one.
1455+
func (r *REST) declaredReason() string {
1456+
if r.nameSchema.Description != "" {
1457+
return r.nameSchema.Description
1458+
}
1459+
return fmt.Sprintf("limit declared by the %s application", r.kindName)
1460+
}
1461+
1462+
// validateNameLength checks that the application name fits both the Helm
1463+
// release name limit (prefix + name <= 53) and any stricter budget the
1464+
// application declares for itself. The tighter one wins and reports itself; a
1465+
// declaration can never widen the Helm budget.
13321466
func (r *REST) validateNameLength(name string) field.ErrorList {
13331467
fldPath := field.NewPath("metadata").Child("name")
13341468
allErrs := field.ErrorList{}
@@ -1340,37 +1474,21 @@ func (r *REST) validateNameLength(name string) field.ErrorList {
13401474
fmt.Sprintf("configuration error: no valid name length possible (release prefix %q)", r.releaseConfig.Prefix)))
13411475
return allErrs
13421476
}
1343-
1344-
// A Kubernetes cluster's worker pools are separate KubernetesNodes releases
1345-
// named "<cluster>-<pool>", so the parent name must leave room for at least
1346-
// the default "md0" pool's child release. This is stricter than the parent's
1347-
// own Helm-prefix budget and fails at admission on the parent rather than at
1348-
// render time on an un-creatable child (see maxKubernetesClusterName).
1349-
if r.kindName == kubernetesKind && maxLen > maxKubernetesClusterName {
1350-
if len(name) > maxKubernetesClusterName {
1351-
allErrs = append(allErrs, field.Invalid(fldPath, name,
1352-
fmt.Sprintf("must be no more than %d characters so its worker pools (KubernetesNodes releases named \"kubernetes-nodes-<cluster>-<pool>\") fit the %d-character Helm release name limit", maxKubernetesClusterName, maxHelmReleaseName)))
1353-
}
1477+
if r.nameSchemaErr != nil {
1478+
allErrs = append(allErrs, field.Invalid(fldPath, name,
1479+
fmt.Sprintf("configuration error: the %s ApplicationDefinition declares an invalid %s: %v", r.kindName, appsv1alpha1.NameSchemaExtension, r.nameSchemaErr)))
13541480
return allErrs
13551481
}
13561482

1357-
// A Kafka cluster's KRaft controller pod hostname "<release>-c-<hash>-<id>"
1358-
// is a tighter bound than the release-name limit (see kafkaControllerNodeOverhead).
1359-
if r.kindName == kafkaKind {
1360-
maxKafkaName := maxNamespaceName - kafkaControllerNodeOverhead - len(r.releaseConfig.Prefix)
1361-
if maxKafkaName < 0 {
1362-
maxKafkaName = 0
1363-
}
1364-
if len(name) > maxKafkaName {
1365-
allErrs = append(allErrs, field.Invalid(fldPath, name,
1366-
fmt.Sprintf("must be no more than %d characters so its KRaft controller pod hostname \"<release>-c-<hash>-<id>\" fits the 63-character DNS-1123 label limit", maxKafkaName)))
1367-
}
1368-
return allErrs
1483+
reason := fmt.Sprintf("release prefix %q", r.releaseConfig.Prefix)
1484+
if declared := r.nameSchema; declared != nil && declared.MaxLength != nil && *declared.MaxLength < int64(maxLen) {
1485+
maxLen = int(*declared.MaxLength)
1486+
reason = r.declaredReason()
13691487
}
13701488

13711489
if len(name) > maxLen {
13721490
allErrs = append(allErrs, field.Invalid(fldPath, name,
1373-
fmt.Sprintf("must be no more than %d characters (release prefix %q)", maxLen, r.releaseConfig.Prefix)))
1491+
fmt.Sprintf("must be no more than %d characters (%s)", maxLen, reason)))
13741492
}
13751493
return allErrs
13761494
}
@@ -1973,6 +2091,10 @@ func (r *REST) warnLegacyPresets(app *appsv1alpha1.Application) {
19732091
}
19742092
}
19752093

2094+
// kubernetesKind is the Application.Kind of the Kubernetes cluster CR whose
2095+
// Phase 2-removed value keys the warning below reports on.
2096+
const kubernetesKind = "Kubernetes"
2097+
19762098
// removedKubernetesFields are Kubernetes CR value keys that Phase 2 moved to the
19772099
// separate KubernetesNodes resource. They are still accepted and stored -- an
19782100
// upgraded cluster keeps them in its values until re-edited, and the adoption

0 commit comments

Comments
 (0)