ci: add kube-api-linter and fix doc and marker findings in api types

[Mesut Oezdil (mesutoezdil)]

Part of #207, following the plan discussed there with Julian Gutierrez Oschmann (@juli4n) and Kevin Hannon (@kannon92): plumbing plus the non invasive fixes first, with the existing invasive findings excluded so new APIs do not regress (as Kevin Hannon (@kannon92) suggested in #207 (comment)). The linter itself was originally suggested by Benjamin Elder (@BenTheElder) in #188.

Plumbing:

• hack/tools/kube-api-linter module with the golangci-lint-kube-api-linter tool, same pattern as the other tools.
• .golangci-kal.yaml config. The pre-existing findings from rules that need Go API changes (nomaps, nonpointerstructs, nophase, optionalfields, requiredfields, ssatags) are excluded per file for the three existing v1alpha1 type files, not disabled globally, so the rules still apply to new API files. Fixing them on the existing types is the follow up in Integrate with github.com/kubernetes-sigs/kube-api-linter #207.
• hack/verify/kube-api-linter.sh runs it against ./pkg/api/... and is picked up by hack/verify-all.sh in CI.

Fixes in pkg/api/v1alpha1 (doc and marker only, no Go API change):

• commentstart: field godocs now start with the serialized field name.
• conditions: Conditions moved to the first position in ActorTemplateStatus and got the listType, listMapKey and patch markers.
• defaultorrequired: SandboxConfigSpec.SandboxClass had both a default and required; now optional with omitempty, matching the same field on WorkerPoolSpec and ActorTemplateSpec. The ValidatingAdmissionPolicy in sandboxconfig-validation.yaml is unaffected since CRD defaulting runs before admission, so spec.sandboxClass is always set by then.
• optionalorrequired: missing +optional markers added on ActorTemplateStatus fields.
• defaults: configured preferredDefaultMarker to kubebuilder:default since CRDs are generated with controller-gen.

Generated CRDs regenerated. Structural schema changes are only the conditions listType/listMapKey and sandboxClass no longer in the required list (it is defaulted, so behavior is the same); the rest is description text.

Note: my earlier count of 50 issues in #207 was capped by the default golangci-lint issue limit. With the cap removed the real total is 86; the extra ones are requiredfields (20) and ssatags (4), both in the excluded set above.

Test plan

• hack/verify/kube-api-linter.sh passes (0 issues).
• Exclusion verified both ways: removing the exclude rule brings back the 41 pre-existing findings, and a scratch new API file with a struct-valued map and a phase field is flagged by nomaps and nophase.
• TestSandboxConfigValidation passes against the regenerated CRD.
• go build ./... and go test ./pkg/api/... ./cmd/atecontroller/... pass.
• gofmt, shellcheck and the regular golangci-lint on pkg/api are clean.

[Kevin Hannon (kannon92)]

And sorry if my comment sends you on a wild goose chase. I am not really involved in this project but I follow it for interest.

cc Benjamin Elder (@BenTheElder) Tim Hockin (@thockin)

I think having kube-api-linter is useful btu not sure what maintainers think.

[Kevin Hannon (kannon92)]

Benjamin Elder (@BenTheElder)
seems like you mentioned you'd like to see this linter. Do you want to take a look?

[Benjamin Elder (BenTheElder)]

In the future I'd recommend:

1. split introducing the linter into one commit, and fixing the failure types into a commit per grouped type
2. prevent including merge commits

this time I think it's small enough to just squash to one commit on merge.

Tim Hockin (@thockin) Julian Gutierrez Oschmann (@juli4n) PTAL

[Mesut Oezdil (mesutoezdil)]

In the future I'd recommend:

1. split introducing the linter into one commit, and fixing the failure types into a commit per grouped type
2. prevent including merge commits

this time I think it's small enough to just squash to one commit on merge.

Tim Hockin (Tim Hockin (@thockin)) Julian Gutierrez Oschmann (Julian Gutierrez Oschmann (@juli4n)) PTAL

thx for feedback