add kube-api-linter and resolve API issues

Add kube-api-linter to `make lint`.

kube-api-linter is based on golangci-lint v2, so it is upgraded to the
latest version.

kube-api-linter could be integrated with COSI CI in many ways. After
experimentation, it is fastest to run it as a standalone install rather
than build it each time `make lint` is run.

Signed-off-by: Blaine Gardner <[email protected]>

Author: BlaineEXE

.golangci.yaml

@@ -1,27 +1,11 @@
+version: "2"
+
 run:
   timeout: 5m
   allow-parallel-runners: true
 
-issues:
-  # don't skip warning about doc comments
-  # don't exclude the default set of lint
-  exclude-use-default: false
-  # restore some of the defaults
-  # (fill in the rest as needed)
-  exclude-rules:
-    - path: "apis/*"
-      linters:
-        - lll
-    - path: "internal/*"
-      linters:
-        - dupl
-        - lll
-    - path: "_test.go"
-      linters:
-        - goconst
-
 linters:
-  disable-all: true
+  default: none
   enable:
     - copyloopvar
     - dupl
@@ -31,7 +15,6 @@ linters:
     - gocyclo
     - gofmt
     - goimports
-    - gosimple
     - govet
     - ineffassign
     - lll
@@ -40,12 +23,32 @@ linters:
     - prealloc
     - revive
     - staticcheck
-    - typecheck
     - unconvert
     - unparam
     - unused
 
-linters-settings:
-  revive:
+  settings:
+    revive:
+      rules:
+        - name: comment-spacings
+
+  exclusions:
+    generated: lax
     rules:
-      - name: comment-spacings
+      - linters:
+          - lll
+        path: apis/*
+      - linters:
+          - dupl
+          - lll
+        path: internal/*
+      - linters:
+          - goconst
+        path: _test.go
+
+formatters:
+  enable:
+    - gofmt
+    - goimports
+  exclusions:
+    generated: lax

Makefile

@@ -56,9 +56,11 @@ export
 all: prebuild build ## Build all container images, plus their prerequisites (faster with 'make -j')
 
 .PHONY: lint
-lint: golangci-lint.client golangci-lint.controller golangci-lint.sidecar spell-lint dockerfiles-lint ## Run all linters (suggest `make -k`)
+lint: golangci-lint.client golangci-lint.controller golangci-lint.sidecar kubeapi-lint spell-lint dockerfiles-lint ## Run all linters (suggest `make -k`)
 golangci-lint.%: golangci-lint
 	cd $* && $(GOLANGCI_LINT) run $(GOLANGCI_LINT_RUN_OPTS) --config $(CURDIR)/.golangci.yaml --new
+kubeapi-lint: kube-api-linter
+	cd client/apis && $(KUBEAPI_LINT) run --config $(CURDIR)/client/.kubeapilint.yaml
 spell-lint:
 	git ls-files | grep -v -e CHANGELOG -e go.mod -e go.sum -e vendor | xargs $(SPELL_LINT) -i "Creater,creater,ect" -error -o stderr
 dockerfiles-lint:
@@ -192,6 +194,7 @@ CRD_REF_DOCS   ?= $(TOOLBIN)/crd-ref-docs
 CTLPTL         ?= $(TOOLBIN)/ctlptl
 GOLANGCI_LINT  ?= $(TOOLBIN)/golangci-lint
 KIND           ?= $(TOOLBIN)/kind
+KUBEAPI_LINT   ?= $(TOOLBIN)/golangci-lint-kube-api-linter
 KUSTOMIZE      ?= $(TOOLBIN)/kustomize
 MDBOOK         ?= $(TOOLBIN)/mdbook
 SPELL_LINT     ?= $(TOOLBIN)/spell-lint
@@ -201,8 +204,9 @@ CHAINSAW_VERSION         ?= v0.2.12
 CONTROLLER_TOOLS_VERSION ?= v0.19.0
 CRD_REF_DOCS_VERSION     ?= v0.2.0
 CTLPTL_VERSION           ?= v0.8.39
-GOLANGCI_LINT_VERSION    ?= v1.64.7
+GOLANGCI_LINT_VERSION    ?= v2.7.2
 KIND_VERSION             ?= v0.27.0
+KUBEAPI_LINT_VERSION     ?= v0.0.0-20251208100930-d3015c953951
 KUSTOMIZE_VERSION        ?= v5.6.0
 MDBOOK_VERSION           ?= v0.4.47
 SPELL_LINT_VERSION       ?= v0.6.0
@@ -238,6 +242,11 @@ kind: $(KIND)-$(KIND_VERSION)
 $(KIND)-$(KIND_VERSION): $(TOOLBIN)
 	$(call go-install-tool,$(KIND),sigs.k8s.io/kind,$(KIND_VERSION))
 
+.PHONY: kube-api-linter
+kube-api-linter: $(KUBEAPI_LINT)-$(KUBEAPI_LINT_VERSION)
+$(KUBEAPI_LINT)-$(KUBEAPI_LINT_VERSION): $(TOOLBIN)
+	$(call go-install-tool,$(KUBEAPI_LINT),sigs.k8s.io/kube-api-linter/cmd/golangci-lint-kube-api-linter,$(KUBEAPI_LINT_VERSION))
+
 .PHONY: kustomize
 kustomize: $(KUSTOMIZE)-$(KUSTOMIZE_VERSION)
 $(KUSTOMIZE)-$(KUSTOMIZE_VERSION): $(TOOLBIN)

client/.kubeapilint.yaml

@@ -0,0 +1,20 @@
+# This is a golangci-lint configuration file specifically for kube-api-linter.
+
+version: "2"
+
+linters:
+  default: none
+  enable:
+    - kubeapilinter
+
+  settings:
+    custom:
+      kubeapilinter:
+        type: module
+        description: Kube API Linter lints Kube like APIs based on API conventions and best practices.
+        settings:
+          linters: {}
+          lintersConfig:
+            optionalfields:
+              pointers:
+                preference: WhenRequired

client/apis/objectstorage/v1alpha2/bucket_types.go

@@ -37,23 +37,23 @@ const (
 )
 
 // BucketSpec defines the desired state of Bucket
-// +kubebuilder:validation:XValidation:message="parameters map is immutable",rule="has(oldSelf.parameters) == has(self.parameters)"
-// +kubebuilder:validation:XValidation:message="protocols list is immutable",rule="has(oldSelf.protocols) == has(self.protocols)"
-// +kubebuilder:validation:XValidation:message="existingBucketID is immutable",rule="has(oldSelf.existingBucketID) == has(self.existingBucketID)"
+// +kubebuilder:validation:XValidation:message="parameters map cannot be added or removed after creation",rule="has(oldSelf.parameters) == has(self.parameters)"
+// +kubebuilder:validation:XValidation:message="protocols list cannot be added or removed after creation",rule="has(oldSelf.protocols) == has(self.protocols)"
+// +kubebuilder:validation:XValidation:message="existingBucketID cannot be added or removed after creation",rule="has(oldSelf.existingBucketID) == has(self.existingBucketID)"
 type BucketSpec struct {
 	// driverName is the name of the driver that fulfills requests for this Bucket.
 	// +required
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:XValidation:message="driverName is immutable",rule="self == oldSelf"
-	DriverName string `json:"driverName"`
+	DriverName string `json:"driverName,omitempty"`
 
 	// deletionPolicy determines whether a Bucket should be deleted when its bound BucketClaim is
 	// deleted. This is mutable to allow Admins to change the policy after creation.
 	// Possible values:
 	//  - Retain: keep both the Bucket object and the backend bucket
 	//  - Delete: delete both the Bucket object and the backend bucket
 	// +required
-	DeletionPolicy BucketDeletionPolicy `json:"deletionPolicy"`
+	DeletionPolicy BucketDeletionPolicy `json:"deletionPolicy,omitempty"`
 
 	// parameters is an opaque map of driver-specific configuration items passed to the driver that
 	// fulfills requests for this Bucket.
@@ -72,68 +72,70 @@ type BucketSpec struct {
 	// For statically-provisioned buckets, set the namespace and name of the BucketClaim that is
 	// allowed to bind to this Bucket.
 	// +required
-	BucketClaimRef BucketClaimReference `json:"bucketClaim"`
+	BucketClaimRef BucketClaimReference `json:"bucketClaim,omitzero"`
 
 	// existingBucketID is the unique identifier for an existing backend bucket known to the driver.
 	// Use driver documentation to determine how to set this value.
 	// This field is used only for Bucket static provisioning.
 	// This field will be empty when the Bucket is dynamically provisioned from a BucketClaim.
 	// +optional
+	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:XValidation:message="existingBucketID is immutable",rule="self == oldSelf"
 	ExistingBucketID string `json:"existingBucketID,omitempty"`
 }
 
 // BucketClaimReference is a reference to a BucketClaim object.
-// +kubebuilder:validation:XValidation:message="namespace is immutable once set",rule="!has(oldSelf.namespace) || has(self.namespace)"
-// +kubebuilder:validation:XValidation:message="uid is immutable once set",rule="!has(oldSelf.uid) || has(self.uid)"
+// +kubebuilder:validation:XValidation:message="namespace cannot be removed once set",rule="!has(oldSelf.namespace) || has(self.namespace)"
+// +kubebuilder:validation:XValidation:message="uid cannot be removed once set",rule="!has(oldSelf.uid) || has(self.uid)"
 type BucketClaimReference struct {
 	// name is the name of the BucketClaim being referenced.
 	// +required
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:MaxLength=253
 	// +kubebuilder:validation:XValidation:message="name is immutable",rule="self == oldSelf"
-	Name string `json:"name"`
+	Name string `json:"name,omitempty"`
 
 	// namespace is the namespace of the BucketClaim being referenced.
-	// If empty, the Kubernetes 'default' namespace is assumed.
-	// namespace is immutable except to update '' to 'default'.
-	// +optional
-	// +kubebuilder:validation:MinLength=0
+	// +required
+	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:MaxLength=253
 	// +kubebuilder:validation:XValidation:message="namespace is immutable",rule="(oldSelf == '' && self == 'default') || self == oldSelf"
-	Namespace string `json:"namespace"`
+	Namespace string `json:"namespace,omitempty"`
 
 	// uid is the UID of the BucketClaim being referenced.
 	// +optional
 	// +kubebuilder:validation:XValidation:message="uid is immutable once set",rule="oldSelf == '' || self == oldSelf"
-	UID types.UID `json:"uid"`
+	UID types.UID `json:"uid,omitempty"`
 }
 
 // BucketStatus defines the observed state of Bucket.
-// +kubebuilder:validation:XValidation:message="bucketID is immutable once set",rule="!has(oldSelf.bucketID) || has(self.bucketID)"
-// +kubebuilder:validation:XValidation:message="protocols is immutable once set",rule="!has(oldSelf.protocols) || has(self.protocols)"
+// +kubebuilder:validation:XValidation:message="bucketID cannot be removed once set",rule="!has(oldSelf.bucketID) || has(self.bucketID)"
+// +kubebuilder:validation:XValidation:message="protocols cannot be removed once set",rule="!has(oldSelf.protocols) || has(self.protocols)"
 type BucketStatus struct {
 	// readyToUse indicates that the bucket is ready for consumption by workloads.
-	ReadyToUse bool `json:"readyToUse"`
+	// +optional
+	ReadyToUse bool `json:"readyToUse,omitempty"`
 
 	// bucketID is the unique identifier for the backend bucket known to the driver.
 	// +optional
+	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:XValidation:message="boundBucketName is immutable once set",rule="oldSelf == '' || self == oldSelf"
-	BucketID string `json:"bucketID"`
+	BucketID string `json:"bucketID,omitempty"`
 
 	// protocols is the set of protocols the Bucket reports to support. BucketAccesses can request
 	// access to this BucketClaim using any of the protocols reported here.
 	// +optional
 	// +listType=set
-	Protocols []ObjectProtocol `json:"protocols"`
+	Protocols []ObjectProtocol `json:"protocols,omitempty"`
 
-	// BucketInfo reported by the driver, rendered in the COSI_<PROTOCOL>_<KEY> format used for the
-	// BucketAccess Secret. e.g., COSI_S3_ENDPOINT, COSI_AZURE_STORAGE_ACCOUNT.
+	// bucketInfo contains info about the bucket reported by the driver, rendered in the same
+	// COSI_<PROTOCOL>_<KEY> format used for the BucketAccess Secret.
+	// e.g., COSI_S3_ENDPOINT, COSI_AZURE_STORAGE_ACCOUNT.
 	// This should not contain any sensitive information.
 	// +optional
 	BucketInfo map[string]string `json:"bucketInfo,omitempty"`
 
-	// Error holds the most recent error message, with a timestamp.
+	// error holds the most recent error message, with a timestamp.
 	// This is cleared when provisioning is successful.
 	// +optional
 	Error *TimestampedError `json:"error,omitempty"`
@@ -154,11 +156,11 @@ type Bucket struct {
 
 	// spec defines the desired state of Bucket
 	// +required
-	Spec BucketSpec `json:"spec"`
+	Spec BucketSpec `json:"spec,omitzero"`
 
 	// status defines the observed state of Bucket
 	// +optional
-	Status BucketStatus `json:"status,omitempty,omitzero"`
+	Status BucketStatus `json:"status,omitzero"`
 }
 
 // +kubebuilder:object:root=true

client/config/crd/objectstorage.k8s.io_buckets.yaml

@@ -55,12 +55,10 @@ spec:
                     - message: name is immutable
                       rule: self == oldSelf
                   namespace:
-                    description: |-
-                      namespace is the namespace of the BucketClaim being referenced.
-                      If empty, the Kubernetes 'default' namespace is assumed.
-                      namespace is immutable except to update '' to 'default'.
+                    description: namespace is the namespace of the BucketClaim being
+                      referenced.
                     maxLength: 253
-                    minLength: 0
+                    minLength: 1
                     type: string
                     x-kubernetes-validations:
                     - message: namespace is immutable
@@ -73,11 +71,12 @@ spec:
                       rule: oldSelf == '' || self == oldSelf
                 required:
                 - name
+                - namespace
                 type: object
                 x-kubernetes-validations:
-                - message: namespace is immutable once set
+                - message: namespace cannot be removed once set
                   rule: '!has(oldSelf.namespace) || has(self.namespace)'
-                - message: uid is immutable once set
+                - message: uid cannot be removed once set
                   rule: '!has(oldSelf.uid) || has(self.uid)'
               deletionPolicy:
                 description: |-
@@ -104,6 +103,7 @@ spec:
                   Use driver documentation to determine how to set this value.
                   This field is used only for Bucket static provisioning.
                   This field will be empty when the Bucket is dynamically provisioned from a BucketClaim.
+                minLength: 1
                 type: string
                 x-kubernetes-validations:
                 - message: existingBucketID is immutable
@@ -140,11 +140,11 @@ spec:
             - driverName
             type: object
             x-kubernetes-validations:
-            - message: parameters map is immutable
+            - message: parameters map cannot be added or removed after creation
               rule: has(oldSelf.parameters) == has(self.parameters)
-            - message: protocols list is immutable
+            - message: protocols list cannot be added or removed after creation
               rule: has(oldSelf.protocols) == has(self.protocols)
-            - message: existingBucketID is immutable
+            - message: existingBucketID cannot be added or removed after creation
               rule: has(oldSelf.existingBucketID) == has(self.existingBucketID)
           status:
             description: status defines the observed state of Bucket
@@ -196,13 +196,11 @@ spec:
                 description: readyToUse indicates that the bucket is ready for consumption
                   by workloads.
                 type: boolean
-            required:
-            - readyToUse
             type: object
             x-kubernetes-validations:
-            - message: bucketID is immutable once set
+            - message: bucketID cannot be removed once set
               rule: '!has(oldSelf.bucketID) || has(self.bucketID)'
-            - message: protocols is immutable once set
+            - message: protocols cannot be removed once set
               rule: '!has(oldSelf.protocols) || has(self.protocols)'
         required:
         - spec

docs/src/api/out.md

@@ -333,7 +333,7 @@ _Appears in:_
 | Field | Description | Default | Validation |
 | --- | --- | --- | --- |
 | `name` _string_ | name is the name of the BucketClaim being referenced. |  | MaxLength: 253 <br />MinLength: 1 <br /> |
-| `namespace` _string_ | namespace is the namespace of the BucketClaim being referenced.<br />If empty, the Kubernetes 'default' namespace is assumed.<br />namespace is immutable except to update '' to 'default'. |  | MaxLength: 253 <br />MinLength: 0 <br /> |
+| `namespace` _string_ | namespace is the namespace of the BucketClaim being referenced. |  | MaxLength: 253 <br />MinLength: 1 <br /> |
 | `uid` _[UID](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#uid-types-pkg)_ | uid is the UID of the BucketClaim being referenced. |  |  |
 
 
@@ -495,7 +495,7 @@ _Appears in:_
 | `parameters` _object (keys:string, values:string)_ | parameters is an opaque map of driver-specific configuration items passed to the driver that<br />fulfills requests for this Bucket. |  |  |
 | `protocols` _[ObjectProtocol](#objectprotocol) array_ | protocols lists object store protocols that the provisioned Bucket must support.<br />If specified, COSI will verify that each item is advertised as supported by the driver. |  | Enum: [S3 Azure GCS] <br /> |
 | `bucketClaim` _[BucketClaimReference](#bucketclaimreference)_ | bucketClaim references the BucketClaim that resulted in the creation of this Bucket.<br />For statically-provisioned buckets, set the namespace and name of the BucketClaim that is<br />allowed to bind to this Bucket. |  |  |
-| `existingBucketID` _string_ | existingBucketID is the unique identifier for an existing backend bucket known to the driver.<br />Use driver documentation to determine how to set this value.<br />This field is used only for Bucket static provisioning.<br />This field will be empty when the Bucket is dynamically provisioned from a BucketClaim. |  |  |
+| `existingBucketID` _string_ | existingBucketID is the unique identifier for an existing backend bucket known to the driver.<br />Use driver documentation to determine how to set this value.<br />This field is used only for Bucket static provisioning.<br />This field will be empty when the Bucket is dynamically provisioned from a BucketClaim. |  | MinLength: 1 <br /> |
 
 
 #### BucketStatus