Skip to content

Commit 15459c9

Browse files
authored
fix(api): declare OpenAPIModelName for core and sdn types (#3808)
## What this PR does Fixes #3806. Declares `OpenAPIModelName` for the `core` and `sdn` API groups the way #3273 already did for `apps`, so every published OpenAPI definition name is the dotted Kubernetes model name rather than a Go import path. Worth noting the two are the same event. #3273 landed the k8s 0.35 work, hit the loud half of this in server-side apply where no apps kind resolved at all, fixed `apps`, and left `core` and `sdn` with the quieter half. Its merge commit `960d85370` is exactly where the window opens: 190 failed-E2E logs from 2026-06-25 to 07-19 carry no occurrence, and the first one is 11 hours after it. Before this, 20 definitions shipped under names like `github.com/cozystack/cozystack/pkg/apis/core/v1alpha1.Option`, while every `$ref` pointing at them spelled each slash `~1`. Clients resolve a `$ref` by trimming `#/definitions/` and looking the remainder up verbatim with no unescaping, so the two spellings never meet and the reference dangles. `kubectl apply --validate` against a cluster running a `cozystack-api` built after 2026-07-21 therefore fails on any resource, and in e2e the platform install fails on `cozy-backup-controller/backupstrategy-controller` and never completes. The mechanism is a Kubernetes 0.35 change: `DefinitionNamer.GetDefinitionName` now returns the model name verbatim, where it previously converted the Go import-path form into the friendly reversed-path form. So whatever name the generated map uses becomes both the published key and the escaped `$ref`, and slash-freedom stops being a nice-to-have and becomes the correctness condition. ### Why hand-written methods openapi-gen can emit these with `--output-model-name-file`, but that also rewrites `zz_generated.model_name.go` inside the read-only apimachinery and apiextensions module-cache packages that the shared `gen_openapi` helper always passes as inputs, which fails for any consumer that vendors deps from the cache, CI included. The `apps` group settled this the same way and the reasoning is repeated in each new `model_name.go` so nobody simplifies it back into the flag. Once a package carries `+k8s:openapi-model-package`, openapi-gen emits `Type{}.OpenAPIModelName()` for every type it writes a schema or a `$ref` for, so a missing method is a build failure rather than a silent skip. That makes a future omission inside these groups loud by construction, and the new tests make an omission on a future group loud at the group level. ### Guard tests `pkg/generated/openapi/definitions_test.go` adds two, both asserting the invariant rather than today's 20 names, and both refusing to pass on an empty or cozystack-free definition map so they cannot go vacuously green. `TestDefinitionNamesAreDottedModelNames` fails on any definition name containing a slash, naming the offender and the fix. `TestDefinitionRefsResolve` builds each `$ref` the way kube-openapi's builder does and resolves it the way a client does, which checks the failure directly rather than through the slash-freedom proxy, and also catches a group whose types disagree with each other. Nothing asserted this before, which is why the defect reached v1.6.0 and v1.6.1 unnoticed. ### Screenshots Not applicable. ### Downstream repositories Walked the trigger map against the diff. Published model names change, so I swept for consumers pinning the old form: every hit on `github.com/cozystack/cozystack/pkg/apis` in the tree is a Go import, which is unaffected because the package path does not change, and `api/api-rules/cozystack_api_violation_exceptions.list` keys off the Go package path in its own format and was unchanged by regeneration. No string literal anywhere pins the old model-name form, and `apiPrefix` in `pkg/cmd/server/openapi.go` is an apps-only const that this does not touch. - [x] No downstream repository is affected by this change ### Testing - `go build ./... && go vet ./...` - `go test ./...` - `make generate && git diff --exit-code`, clean and idempotent - `pre-commit run --all-files` - Both guard tests run against the pre-fix tree first: `TestDefinitionNamesAreDottedModelNames` named all 20 offenders and `TestDefinitionRefsResolve` reproduced the reported error string with 15 dangling refs, fewer than 20 because some of the 20 are only referenced-from and never referencing. - An independent check driving the real `openapi.NewDefinitionNamer(apiserver.Scheme)` reports 104 published definitions with 0 slashes, 106 emitted refs with 0 dangling, and all 23 cozystack kinds resolving to a published definition carrying `x-kubernetes-group-version-kind`, which also confirms the `apps` server-side-apply fix still holds. `make unit-tests` aborts at `hack/ghcr-mirror_test.bats`, which fails on a pristine `origin/main` in my environment while passing in CI, so I ran the chain standalone: the other 60 bats files pass, as do `helm-unit-tests`, `go-unit-tests`, `rd-presets-check`, `test-check-readiness` and `migrations-target-check`. ### Release note ```release-note fix(api): publish OpenAPI model names for the core and sdn API groups as dotted Kubernetes names, so `$ref`s resolve and client-side validation works again against the aggregated apiserver ``` <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Enhancements** * Added OpenAPI metadata for Core v1alpha1 API models. * Added OpenAPI metadata for SDN v1alpha1 API models. * API schemas now provide consistent canonical model names, supporting more reliable documentation and schema references. * Added package-level OpenAPI markers to improve API discovery and tooling compatibility. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
2 parents 1b4b6ff + cea1703 commit 15459c9

6 files changed

Lines changed: 488 additions & 135 deletions

File tree

‎pkg/apis/core/v1alpha1/doc.go‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ limitations under the License.
1515
*/
1616

1717
// +k8s:openapi-gen=true
18+
// +k8s:openapi-model-package=com.github.cozystack.cozystack.pkg.apis.core.v1alpha1
1819
// +k8s:deepcopy-gen=package
1920
// +k8s:conversion-gen=github.com/cozystack/cozystack/pkg/apis/core
2021
// +k8s:conversion-gen=k8s.io/apiextensions-apiserver/pkg/apis/apiextensions
Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
/*
2+
Copyright 2026 The Cozystack Authors.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
package v1alpha1
18+
19+
// OpenAPIModelName pins the OpenAPI model name for the core.cozystack.io types.
20+
// This is hand-written (not generated) on purpose.
21+
//
22+
// Without it, openapi-gen keys the generated definition map on the Go import
23+
// path ("github.com/cozystack/cozystack/pkg/apis/core/v1alpha1.Option"), and
24+
// since Kubernetes 0.35 the apiserver's DefinitionNamer.GetDefinitionName
25+
// returns whatever name it is given verbatim instead of converting it to the
26+
// "friendly" reversed-path form. The published document then keys the definition
27+
// on the raw path while every $ref to it is JSON pointer escaped
28+
// ("#/definitions/github.com~1cozystack~1…v1alpha1.OptionSpec", ~1 being a
29+
// slash), and clients resolve a $ref by trimming "#/definitions/" without
30+
// unescaping. The two spellings never meet, so the reference dangles and
31+
// client-side validation fails on every resource in the group, not only the one
32+
// named in the error:
33+
//
34+
// error validating data: SchemaError(…core/v1alpha1.Option.spec):
35+
// unknown model in reference: "github.com~1cozystack~1…v1alpha1.OptionSpec"
36+
//
37+
// Declaring the dotted name here makes GetCanonicalTypeName,
38+
// Scheme.ToOpenAPIDefinitionName and the generated openapi map key all agree on
39+
// a name with no slash in it, so nothing needs escaping and every $ref resolves.
40+
// The same agreement is what lets DefinitionNamer attach the
41+
// x-kubernetes-group-version-kind extension, which server-side apply needs to
42+
// resolve a kind (see the apps package, where its absence broke SSA instead).
43+
//
44+
// code-generator's openapi-gen could emit these via --output-model-name-file,
45+
// but that also rewrites zz_generated.model_name.go in the read-only apimachinery
46+
// / apiextensions module-cache packages the shared gen_openapi helper always
47+
// passes as inputs, which fails on any consumer (including CI) that vendors deps
48+
// from the module cache. Keeping the methods here sidesteps that.
49+
//
50+
// The +k8s:openapi-model-package marker in doc.go makes openapi-gen emit
51+
// Type{}.OpenAPIModelName() for every type in this package it generates a schema
52+
// or a reference for, so a new core.cozystack.io type without a method here
53+
// fails the build rather than silently reintroducing a Go-path name. The
54+
// returned string must be the dotted form Scheme.ToOpenAPIDefinitionName derives
55+
// from the type's Go package path, which is the marker's value plus the type
56+
// name. See https://github.com/cozystack/cozystack/issues/3806.
57+
58+
func (in Option) OpenAPIModelName() string {
59+
return "com.github.cozystack.cozystack.pkg.apis.core.v1alpha1.Option"
60+
}
61+
62+
func (in OptionItem) OpenAPIModelName() string {
63+
return "com.github.cozystack.cozystack.pkg.apis.core.v1alpha1.OptionItem"
64+
}
65+
66+
func (in OptionList) OpenAPIModelName() string {
67+
return "com.github.cozystack.cozystack.pkg.apis.core.v1alpha1.OptionList"
68+
}
69+
70+
func (in OptionSpec) OpenAPIModelName() string {
71+
return "com.github.cozystack.cozystack.pkg.apis.core.v1alpha1.OptionSpec"
72+
}
73+
74+
func (in TenantModule) OpenAPIModelName() string {
75+
return "com.github.cozystack.cozystack.pkg.apis.core.v1alpha1.TenantModule"
76+
}
77+
78+
func (in TenantModuleList) OpenAPIModelName() string {
79+
return "com.github.cozystack.cozystack.pkg.apis.core.v1alpha1.TenantModuleList"
80+
}
81+
82+
func (in TenantModuleStatus) OpenAPIModelName() string {
83+
return "com.github.cozystack.cozystack.pkg.apis.core.v1alpha1.TenantModuleStatus"
84+
}
85+
86+
func (in TenantNamespace) OpenAPIModelName() string {
87+
return "com.github.cozystack.cozystack.pkg.apis.core.v1alpha1.TenantNamespace"
88+
}
89+
90+
func (in TenantNamespaceList) OpenAPIModelName() string {
91+
return "com.github.cozystack.cozystack.pkg.apis.core.v1alpha1.TenantNamespaceList"
92+
}
93+
94+
func (in TenantSecret) OpenAPIModelName() string {
95+
return "com.github.cozystack.cozystack.pkg.apis.core.v1alpha1.TenantSecret"
96+
}
97+
98+
func (in TenantSecretList) OpenAPIModelName() string {
99+
return "com.github.cozystack.cozystack.pkg.apis.core.v1alpha1.TenantSecretList"
100+
}

‎pkg/apis/sdn/v1alpha1/doc.go‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ limitations under the License.
1515
*/
1616

1717
// +k8s:openapi-gen=true
18+
// +k8s:openapi-model-package=com.github.cozystack.cozystack.pkg.apis.sdn.v1alpha1
1819
// +k8s:deepcopy-gen=package
1920
// +k8s:conversion-gen=github.com/cozystack/cozystack/pkg/apis/sdn
2021
// +k8s:conversion-gen=k8s.io/apiextensions-apiserver/pkg/apis/apiextensions
Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
/*
2+
Copyright 2026 The Cozystack Authors.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
package v1alpha1
18+
19+
// OpenAPIModelName pins the OpenAPI model name for the sdn.cozystack.io types.
20+
// This is hand-written (not generated) on purpose.
21+
//
22+
// Without it, openapi-gen keys the generated definition map on the Go import
23+
// path ("github.com/cozystack/cozystack/pkg/apis/sdn/v1alpha1.SecurityGroup"),
24+
// and since Kubernetes 0.35 the apiserver's DefinitionNamer.GetDefinitionName
25+
// returns whatever name it is given verbatim instead of converting it to the
26+
// "friendly" reversed-path form. The published document then keys the definition
27+
// on the raw path while every $ref to it is JSON pointer escaped
28+
// ("#/definitions/github.com~1cozystack~1…v1alpha1.SecurityGroupSpec", ~1 being
29+
// a slash), and clients resolve a $ref by trimming "#/definitions/" without
30+
// unescaping. The two spellings never meet, so the reference dangles and
31+
// client-side validation fails on every resource in the group, not only the one
32+
// named in the error:
33+
//
34+
// error validating data: SchemaError(…sdn/v1alpha1.SecurityGroup.spec):
35+
// unknown model in reference: "github.com~1cozystack~1…v1alpha1.SecurityGroupSpec"
36+
//
37+
// Declaring the dotted name here makes GetCanonicalTypeName,
38+
// Scheme.ToOpenAPIDefinitionName and the generated openapi map key all agree on
39+
// a name with no slash in it, so nothing needs escaping and every $ref resolves.
40+
// The same agreement is what lets DefinitionNamer attach the
41+
// x-kubernetes-group-version-kind extension, which server-side apply needs to
42+
// resolve a kind (see the apps package, where its absence broke SSA instead).
43+
//
44+
// code-generator's openapi-gen could emit these via --output-model-name-file,
45+
// but that also rewrites zz_generated.model_name.go in the read-only apimachinery
46+
// / apiextensions module-cache packages the shared gen_openapi helper always
47+
// passes as inputs, which fails on any consumer (including CI) that vendors deps
48+
// from the module cache. Keeping the methods here sidesteps that.
49+
//
50+
// The +k8s:openapi-model-package marker in doc.go makes openapi-gen emit
51+
// Type{}.OpenAPIModelName() for every type in this package it generates a schema
52+
// or a reference for, so a new sdn.cozystack.io type without a method here fails
53+
// the build rather than silently reintroducing a Go-path name. The returned
54+
// string must be the dotted form Scheme.ToOpenAPIDefinitionName derives from the
55+
// type's Go package path, which is the marker's value plus the type name. See
56+
// https://github.com/cozystack/cozystack/issues/3806.
57+
58+
func (in ApplicationReference) OpenAPIModelName() string {
59+
return "com.github.cozystack.cozystack.pkg.apis.sdn.v1alpha1.ApplicationReference"
60+
}
61+
62+
func (in EgressRule) OpenAPIModelName() string {
63+
return "com.github.cozystack.cozystack.pkg.apis.sdn.v1alpha1.EgressRule"
64+
}
65+
66+
func (in FQDNSelector) OpenAPIModelName() string {
67+
return "com.github.cozystack.cozystack.pkg.apis.sdn.v1alpha1.FQDNSelector"
68+
}
69+
70+
func (in IngressRule) OpenAPIModelName() string {
71+
return "com.github.cozystack.cozystack.pkg.apis.sdn.v1alpha1.IngressRule"
72+
}
73+
74+
func (in PortProtocol) OpenAPIModelName() string {
75+
return "com.github.cozystack.cozystack.pkg.apis.sdn.v1alpha1.PortProtocol"
76+
}
77+
78+
func (in PortRule) OpenAPIModelName() string {
79+
return "com.github.cozystack.cozystack.pkg.apis.sdn.v1alpha1.PortRule"
80+
}
81+
82+
func (in SecurityGroup) OpenAPIModelName() string {
83+
return "com.github.cozystack.cozystack.pkg.apis.sdn.v1alpha1.SecurityGroup"
84+
}
85+
86+
func (in SecurityGroupList) OpenAPIModelName() string {
87+
return "com.github.cozystack.cozystack.pkg.apis.sdn.v1alpha1.SecurityGroupList"
88+
}
89+
90+
func (in SecurityGroupSpec) OpenAPIModelName() string {
91+
return "com.github.cozystack.cozystack.pkg.apis.sdn.v1alpha1.SecurityGroupSpec"
92+
}
Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
/*
2+
Copyright 2026 The Cozystack Authors.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
package openapi
18+
19+
import (
20+
"sort"
21+
"strings"
22+
"testing"
23+
24+
"k8s.io/kube-openapi/pkg/common"
25+
"k8s.io/kube-openapi/pkg/validation/spec"
26+
)
27+
28+
// The two tests below guard the published OpenAPI document against the class of
29+
// defect in https://github.com/cozystack/cozystack/issues/3806: a definition
30+
// name that is a Go import path rather than a dotted Kubernetes model name.
31+
//
32+
// Since Kubernetes 0.35 the apiserver's DefinitionNamer.GetDefinitionName
33+
// returns the model name it was given verbatim — it no longer converts the Go
34+
// import-path form into the "friendly" reversed-path form — so whatever name
35+
// this generated map uses becomes both the published definition key and, JSON
36+
// pointer escaped, the $ref that points at it. A name containing "/" therefore
37+
// ships as a definition keyed on the raw path while every reference to it is
38+
// spelled with "~1" in place of each slash, and clients resolve a $ref by
39+
// trimming "#/definitions/" without unescaping (kube-openapi
40+
// pkg/util/proto/document.go). The two spellings never meet, so the reference
41+
// dangles and client-side validation fails on every resource of the group:
42+
//
43+
// error validating data: SchemaError(…core/v1alpha1.Option.spec):
44+
// unknown model in reference: "github.com~1cozystack~1…v1alpha1.OptionSpec"
45+
//
46+
// The fix for a group is the +k8s:openapi-model-package marker in its doc.go
47+
// plus an OpenAPIModelName method per type (see each package's model_name.go).
48+
// Nothing asserted that, which is why the core and sdn groups shipped broken in
49+
// v1.6.0 and v1.6.1. These tests assert the invariant rather than today's set of
50+
// names, so a future group that omits the marker fails here instead of in a
51+
// cluster.
52+
53+
// buildDefinitions builds the generated definition map, recording every model
54+
// name the generated code passes to the reference callback. Refs are built
55+
// exactly as kube-openapi's builder builds them, so the recorded name and the
56+
// emitted $ref differ in the same way they do in the served document.
57+
func buildDefinitions() (defs map[string]common.OpenAPIDefinition, refNames []string) {
58+
defs = GetOpenAPIDefinitions(func(path string) spec.Ref {
59+
refNames = append(refNames, path)
60+
return spec.MustCreateRef("#/definitions/" + common.EscapeJsonPointer(path))
61+
})
62+
return defs, refNames
63+
}
64+
65+
// sortedKeys returns the definition names in a stable order so failures are
66+
// reproducible rather than map-iteration ordered.
67+
func sortedKeys(defs map[string]common.OpenAPIDefinition) []string {
68+
out := make([]string, 0, len(defs))
69+
for name := range defs {
70+
out = append(out, name)
71+
}
72+
sort.Strings(out)
73+
return out
74+
}
75+
76+
// TestDefinitionNamesAreDottedModelNames asserts that no published definition
77+
// name contains a slash. A slash-bearing name is a Go import path that escaped
78+
// as-is, which means the group it belongs to is missing its
79+
// +k8s:openapi-model-package marker and its OpenAPIModelName methods.
80+
func TestDefinitionNamesAreDottedModelNames(t *testing.T) {
81+
defs, _ := buildDefinitions()
82+
83+
// Guard against the assertion going vacuous: the map must be populated and
84+
// must actually cover cozystack's own types, not only the vendored
85+
// apimachinery and apiextensions models that already declare their names.
86+
if len(defs) == 0 {
87+
t.Fatal("GetOpenAPIDefinitions returned no definitions; this test is asserting nothing")
88+
}
89+
own := 0
90+
for _, name := range sortedKeys(defs) {
91+
if strings.Contains(name, "cozystack") {
92+
own++
93+
}
94+
}
95+
if own == 0 {
96+
t.Fatal("no cozystack-owned definitions found; this test is asserting nothing")
97+
}
98+
99+
for _, name := range sortedKeys(defs) {
100+
if strings.Contains(name, "/") {
101+
t.Errorf("definition %q is a Go import path, not a dotted model name: "+
102+
"every $ref to it is escaped with ~1 and will not resolve. Add "+
103+
"+k8s:openapi-model-package=<dotted package> to that package's doc.go and an "+
104+
"OpenAPIModelName method for the type in its model_name.go, then re-run make generate",
105+
name)
106+
}
107+
}
108+
}
109+
110+
// TestDefinitionRefsResolve asserts that every $ref the generated document
111+
// emits resolves to a published definition, resolving it the way a client does:
112+
// trim "#/definitions/" and look the remainder up verbatim, with no
113+
// unescaping. This is the failure the user sees, so it is checked directly
114+
// rather than only through the slash-freedom proxy above; it also catches a
115+
// group whose types disagree with each other (some named, some not) and a ref
116+
// to a model that is not published at all.
117+
func TestDefinitionRefsResolve(t *testing.T) {
118+
defs, refNames := buildDefinitions()
119+
120+
if len(refNames) == 0 {
121+
t.Fatal("generated definitions emitted no $ref; this test is asserting nothing")
122+
}
123+
124+
// Index the published definitions under the key a client sees, which is the
125+
// definition name exactly as published.
126+
published := make(map[string]struct{}, len(defs))
127+
for name := range defs {
128+
published[name] = struct{}{}
129+
}
130+
131+
seen := make(map[string]struct{}, len(refNames))
132+
for _, modelName := range refNames {
133+
// The served $ref, built the way kube-openapi's builder builds it.
134+
ref := "#/definitions/" + common.EscapeJsonPointer(modelName)
135+
// The lookup a client performs on it.
136+
resolved := strings.TrimPrefix(ref, "#/definitions/")
137+
if _, ok := published[resolved]; ok {
138+
continue
139+
}
140+
if _, dup := seen[resolved]; dup {
141+
continue
142+
}
143+
seen[resolved] = struct{}{}
144+
t.Errorf("$ref %q does not resolve: no definition is published under %q (model name %q)",
145+
ref, resolved, modelName)
146+
}
147+
148+
// Dependencies must agree with the refs: the generated code lists them from
149+
// the same set, and consumers walk them to build the transitive closure.
150+
for _, name := range sortedKeys(defs) {
151+
for _, dep := range defs[name].Dependencies {
152+
if _, ok := published[dep]; !ok {
153+
t.Errorf("definition %q declares dependency %q, which is not published", name, dep)
154+
}
155+
}
156+
}
157+
}

0 commit comments

Comments
 (0)