Skip to content

Commit f00ba71

Browse files
pgmpofupgmpofu
committed
ci: add kube-api-linter to linters
Adds sigs.k8s.io/kube-api-linter (KAL) as a golangci-lint v2 module plugin and wires it into a new CI job that lints the API type definitions in ./apis against Kubernetes API conventions. Only the commentstart rule is enabled for now: it requires field godoc comments to start with the lowerCamelCase JSON field name, and its fixes are purely textual. Other KAL default rules (optionalorrequired, nonpointerstructs, arrayofstruct, nomaps) were evaluated but not enabled here, since applying them can suggest changing exported Go field types (e.g. value -> pointer with omitempty), which is a wire-compatibility decision that needs separate discussion, not something to fold into enabling a linter. Fixes the ~280 existing commentstart violations this surfaced across apis/, and regenerates CRDs and manifest_staging/ to match the updated doc comments. Fixes #4219 Signed-off-by: Patience Mpofu <pgmpofu@gmail.com>
1 parent c50fc29 commit f00ba71

77 files changed

Lines changed: 2741 additions & 1048 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.custom-gcl.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
version: v2.9.0
2+
name: golangci-lint-kube-api-linter
3+
destination: ./bin
4+
plugins:
5+
- module: 'sigs.k8s.io/kube-api-linter'
6+
version: 'v0.0.0-20260716143926-092fe0c72997'

‎.github/workflows/lint.yaml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,3 +41,25 @@ jobs:
4141

4242
- name: lint
4343
run: make lint
44+
45+
kube-api-lint:
46+
runs-on: oracle-vm-4cpu-16gb-x86-64
47+
steps:
48+
- name: Harden Runner
49+
uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1
50+
with:
51+
egress-policy: audit
52+
53+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
54+
55+
- name: Set up Go
56+
uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
57+
with:
58+
go-version-file: go.mod
59+
check-latest: true
60+
61+
- name: lint (kube-api-linter)
62+
run: make lint-kube-api
63+
64+
- name: fail if lint changed generated API docs
65+
run: git diff --exit-code -- apis/

‎.golangci-kube-api-linter.yaml‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
version: "2"
2+
run:
3+
go: "1.26"
4+
linters:
5+
default: none
6+
enable:
7+
- kubeapilinter
8+
settings:
9+
custom:
10+
kubeapilinter:
11+
type: module
12+
description: >-
13+
Kube API Linter (https://github.com/kubernetes-sigs/kube-api-linter)
14+
lints Kubernetes-like APIs based on API conventions and best practices.
15+
settings:
16+
linters:
17+
disable:
18+
- "*"
19+
enable:
20+
# commentstart checks that field godoc comments start with the
21+
# lowerCamelCase JSON field name, per Kubernetes API conventions.
22+
# Only rules that are purely doc-comment fixes are enabled here;
23+
# rules that recommend Go type changes (e.g. optionalorrequired,
24+
# nonpointerstructs) are left for a follow-up once the team has
25+
# decided how to apply them without altering wire compatibility.
26+
- commentstart

‎Makefile‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -427,6 +427,18 @@ lint:
427427
-w /app golangci/golangci-lint:${GOLANGCI_LINT_VERSION} \
428428
golangci-lint run -v --fix --concurrency 2
429429

430+
# lint-kube-api builds a golangci-lint binary with the kube-api-linter module
431+
# (https://github.com/kubernetes-sigs/kube-api-linter) plugged in, and runs it
432+
# against the API type definitions in ./apis, checking them against
433+
# Kubernetes API conventions. Requires a local Go toolchain; unlike `lint`
434+
# this isn't dockerized because the module plugin build needs `go` and `git`
435+
# on the host.
436+
.PHONY: lint-kube-api
437+
lint-kube-api:
438+
GOBIN=$(shell pwd)/bin go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@${GOLANGCI_LINT_VERSION}
439+
./bin/golangci-lint custom
440+
./bin/golangci-lint-kube-api-linter run -c .golangci-kube-api-linter.yaml --fix ./apis/...
441+
430442
# Generate code
431443
generate: __conversion-gen __controller-gen
432444
$(CONTROLLER_GEN) object:headerFile=./hack/boilerplate.go.txt paths="./apis/..." paths="./pkg/..."

‎apis/config/v1alpha1/config_types.go‎

Lines changed: 30 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -26,42 +26,46 @@ import (
2626
type ConfigSpec struct {
2727
// Important: Run "make" to regenerate code after modifying this file
2828

29-
// Configuration for syncing k8s objects
29+
// sync is the configuration for syncing k8s objects
3030
Sync Sync `json:"sync,omitempty"`
3131

32-
// Configuration for validation
32+
// validation is the configuration for validation
3333
Validation Validation `json:"validation,omitempty"`
3434

35-
// Configuration for namespace exclusion
35+
// match is the configuration for namespace exclusion
3636
Match []MatchEntry `json:"match,omitempty"`
3737

38-
// Configuration for readiness tracker
38+
// readiness is the configuration for readiness tracker
3939
Readiness ReadinessSpec `json:"readiness,omitempty"`
4040
}
4141

4242
type Validation struct {
43-
// List of requests to trace. Both "user" and "kinds" must be specified
43+
// traces is the list of requests to trace. Both "user" and "kinds" must be specified
4444
Traces []Trace `json:"traces,omitempty"`
4545
}
4646

4747
type Trace struct {
48-
// Only trace requests from the specified user
48+
// user restricts tracing to requests from the specified user
4949
User string `json:"user,omitempty"`
50-
// Only trace requests of the following GroupVersionKind
50+
// kind restricts tracing to requests of the following GroupVersionKind
5151
Kind GVK `json:"kind,omitempty"`
52-
// Also dump the state of OPA with the trace. Set to `All` to dump everything.
52+
// dump also dumps the state of OPA with the trace. Set to `All` to dump everything.
5353
Dump string `json:"dump,omitempty"`
5454
}
5555

5656
type Sync struct {
57-
// If non-empty, only entries on this list will be replicated into OPA
57+
// syncOnly restricts replication into OPA to only the entries on this list,
58+
// when non-empty
5859
SyncOnly []SyncOnlyEntry `json:"syncOnly,omitempty"`
5960
}
6061

6162
type SyncOnlyEntry struct {
62-
Group string `json:"group,omitempty"`
63+
// group is the API group of the resource to sync.
64+
Group string `json:"group,omitempty"`
65+
// version is the API version of the resource to sync.
6366
Version string `json:"version,omitempty"`
64-
Kind string `json:"kind,omitempty"`
67+
// kind is the kind of the resource to sync.
68+
Kind string `json:"kind,omitempty"`
6569
}
6670

6771
func (e *SyncOnlyEntry) ToGroupVersionKind() schema.GroupVersionKind {
@@ -73,23 +77,30 @@ func (e *SyncOnlyEntry) ToGroupVersionKind() schema.GroupVersionKind {
7377
}
7478

7579
type MatchEntry struct {
76-
Processes []string `json:"processes,omitempty"`
80+
// processes lists the Gatekeeper processes this exclusion applies to.
81+
Processes []string `json:"processes,omitempty"`
82+
// excludedNamespaces lists the namespaces excluded from the listed processes.
7783
ExcludedNamespaces []wildcard.Wildcard `json:"excludedNamespaces,omitempty"`
7884
}
7985

8086
type ReadinessSpec struct {
87+
// statsEnabled enables reporting of readiness tracker statistics.
8188
StatsEnabled bool `json:"statsEnabled,omitempty"`
8289
}
8390

8491
// ConfigStatus defines the observed state of Config.
8592
type ConfigStatus struct { // Important: Run "make" to regenerate code after modifying this file
93+
// byPod lists the observed status of this Config for each pod.
8694
ByPod []status.ConfigPodStatusStatus `json:"byPod,omitempty"`
8795
}
8896

8997
type GVK struct {
90-
Group string `json:"group,omitempty"`
98+
// group is the API group of the resource.
99+
Group string `json:"group,omitempty"`
100+
// version is the API version of the resource.
91101
Version string `json:"version,omitempty"`
92-
Kind string `json:"kind,omitempty"`
102+
// kind is the kind of the resource.
103+
Kind string `json:"kind,omitempty"`
93104
}
94105

95106
// +kubebuilder:resource:scope=Namespaced
@@ -99,10 +110,13 @@ type GVK struct {
99110

100111
// Config is the Schema for the configs API.
101112
type Config struct {
102-
metav1.TypeMeta `json:",inline"`
113+
metav1.TypeMeta `json:",inline"`
114+
// metadata is the standard object metadata.
103115
metav1.ObjectMeta `json:"metadata,omitempty"`
104116

105-
Spec ConfigSpec `json:"spec,omitempty"`
117+
// spec defines the desired state of Config.
118+
Spec ConfigSpec `json:"spec,omitempty"`
119+
// status is the observed state of Config.
106120
Status ConfigStatus `json:"status,omitempty"`
107121
}
108122

‎apis/connection/v1alpha1/connection_types.go‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,9 +26,10 @@ import (
2626

2727
// ConnectionSpec defines the desired state of Connection.
2828
type ConnectionSpec struct {
29+
// driver is the name of one of the expected drivers i.e. dapr, disk
2930
// +kubebuilder:validation:Required
30-
// Driver is the name of one of the expected drivers i.e. dapr, disk
3131
Driver string `json:"driver"`
32+
// config is the driver-specific configuration for this connection.
3233
// +kubebuilder:validation:Required
3334
// +kubebuilder:validation:Schemaless
3435
// +kubebuilder:pruning:PreserveUnknownFields
@@ -37,6 +38,7 @@ type ConnectionSpec struct {
3738

3839
// ConnectionStatus defines the observed state of Connection.
3940
type ConnectionStatus struct {
41+
// byPod lists the observed status of this Connection for each pod.
4042
ByPod []statusv1alpha1.ConnectionPodStatusStatus `json:"byPod,omitempty"`
4143
}
4244

@@ -46,10 +48,13 @@ type ConnectionStatus struct {
4648
// +kubebuilder:storageversion
4749
// Connection is the Schema for the connections API.
4850
type Connection struct {
49-
metav1.TypeMeta `json:",inline"`
51+
metav1.TypeMeta `json:",inline"`
52+
// metadata is the standard object metadata.
5053
metav1.ObjectMeta `json:"metadata,omitempty"`
5154

52-
Spec ConnectionSpec `json:"spec,omitempty"`
55+
// spec defines the desired state of Connection.
56+
Spec ConnectionSpec `json:"spec,omitempty"`
57+
// status is the observed state of Connection.
5358
Status ConnectionStatus `json:"status,omitempty"`
5459
}
5560

‎apis/expansion/unversioned/expansiontemplate_types.go‎

Lines changed: 15 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -29,29 +29,32 @@ type ExpansionTemplateSpec struct {
2929
// INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
3030
// Important: Run "make" to regenerate code after modifying this file
3131

32-
// ApplyTo lists the specific groups, versions and kinds of generator resources
32+
// applyTo lists the specific groups, versions and kinds of generator resources
3333
// which will be expanded.
3434
ApplyTo []match.ApplyTo `json:"applyTo,omitempty"`
3535

36-
// TemplateSource specifies the source field on the generator resource to
36+
// templateSource specifies the source field on the generator resource to
3737
// use as the base for expanded resource. For Pod-creating generators, this
3838
// is usually spec.template
3939
TemplateSource string `json:"templateSource,omitempty"`
4040

41-
// GeneratedGVK specifies the GVK of the resources which the generator
41+
// generatedGVK specifies the GVK of the resources which the generator
4242
// resource creates.
4343
GeneratedGVK GeneratedGVK `json:"generatedGVK,omitempty"`
4444

45-
// EnforcementAction specifies the enforcement action to be used for resources
45+
// enforcementAction specifies the enforcement action to be used for resources
4646
// matching the ExpansionTemplate. Specifying an empty value will use the
4747
// enforcement action specified by the Constraint in violation.
4848
EnforcementAction string `json:"enforcementAction,omitempty"`
4949
}
5050

5151
type GeneratedGVK struct {
52-
Group string `json:"group,omitempty"`
52+
// group is the API group of the generated resource.
53+
Group string `json:"group,omitempty"`
54+
// version is the API version of the generated resource.
5355
Version string `json:"version,omitempty"`
54-
Kind string `json:"kind,omitempty"`
56+
// kind is the kind of the generated resource.
57+
Kind string `json:"kind,omitempty"`
5558
}
5659

5760
// +kubebuilder:object:root=true
@@ -61,15 +64,19 @@ type GeneratedGVK struct {
6164

6265
// ExpansionTemplate is the Schema for the ExpansionTemplate API.
6366
type ExpansionTemplate struct {
64-
metav1.TypeMeta `json:",inline"`
67+
metav1.TypeMeta `json:",inline"`
68+
// metadata is the standard object metadata.
6569
metav1.ObjectMeta `json:"metadata,omitempty"`
6670

67-
Spec ExpansionTemplateSpec `json:"spec,omitempty"`
71+
// spec defines the desired state of ExpansionTemplate.
72+
Spec ExpansionTemplateSpec `json:"spec,omitempty"`
73+
// status is the observed state of ExpansionTemplate.
6874
Status ExpansionTemplateStatus `json:"status,omitempty"`
6975
}
7076

7177
// ExpansionTemplateStatus defines the observed state of ExpansionTemplate.
7278
type ExpansionTemplateStatus struct {
79+
// byPod lists the observed status of this ExpansionTemplate for each pod.
7380
ByPod []statusv1alpha1.ExpansionTemplatePodStatusStatus `json:"byPod,omitempty"`
7481
}
7582

‎apis/expansion/v1alpha1/expansiontemplate_types.go‎

Lines changed: 15 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -29,29 +29,32 @@ type ExpansionTemplateSpec struct {
2929
// INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
3030
// Important: Run "make" to regenerate code after modifying this file
3131

32-
// ApplyTo lists the specific groups, versions and kinds of generator resources
32+
// applyTo lists the specific groups, versions and kinds of generator resources
3333
// which will be expanded.
3434
ApplyTo []match.ApplyTo `json:"applyTo,omitempty"`
3535

36-
// TemplateSource specifies the source field on the generator resource to
36+
// templateSource specifies the source field on the generator resource to
3737
// use as the base for expanded resource. For Pod-creating generators, this
3838
// is usually spec.template
3939
TemplateSource string `json:"templateSource,omitempty"`
4040

41-
// GeneratedGVK specifies the GVK of the resources which the generator
41+
// generatedGVK specifies the GVK of the resources which the generator
4242
// resource creates.
4343
GeneratedGVK GeneratedGVK `json:"generatedGVK,omitempty"`
4444

45-
// EnforcementAction specifies the enforcement action to be used for resources
45+
// enforcementAction specifies the enforcement action to be used for resources
4646
// matching the ExpansionTemplate. Specifying an empty value will use the
4747
// enforcement action specified by the Constraint in violation.
4848
EnforcementAction string `json:"enforcementAction,omitempty"`
4949
}
5050

5151
type GeneratedGVK struct {
52-
Group string `json:"group,omitempty"`
52+
// group is the API group of the generated resource.
53+
Group string `json:"group,omitempty"`
54+
// version is the API version of the generated resource.
5355
Version string `json:"version,omitempty"`
54-
Kind string `json:"kind,omitempty"`
56+
// kind is the kind of the generated resource.
57+
Kind string `json:"kind,omitempty"`
5558
}
5659

5760
// +kubebuilder:object:root=true
@@ -62,15 +65,19 @@ type GeneratedGVK struct {
6265

6366
// ExpansionTemplate is the Schema for the ExpansionTemplate API.
6467
type ExpansionTemplate struct {
65-
metav1.TypeMeta `json:",inline"`
68+
metav1.TypeMeta `json:",inline"`
69+
// metadata is the standard object metadata.
6670
metav1.ObjectMeta `json:"metadata,omitempty"`
6771

68-
Spec ExpansionTemplateSpec `json:"spec,omitempty"`
72+
// spec defines the desired state of ExpansionTemplate.
73+
Spec ExpansionTemplateSpec `json:"spec,omitempty"`
74+
// status is the observed state of ExpansionTemplate.
6975
Status ExpansionTemplateStatus `json:"status,omitempty"`
7076
}
7177

7278
// ExpansionTemplateStatus defines the observed state of ExpansionTemplate.
7379
type ExpansionTemplateStatus struct {
80+
// byPod lists the observed status of this ExpansionTemplate for each pod.
7481
ByPod []status.ExpansionTemplatePodStatusStatus `json:"byPod,omitempty"`
7582
}
7683

0 commit comments

Comments
 (0)