Enable KAL linter

Signed-off-by: Prajyot-Parab <prajyot.parab2@ibm.com>

Author: Prajyot-Parab

.golangci-kal.yml

@@ -0,0 +1,76 @@
+version: "2"
+run:
+  go: "1.24"
+  allow-parallel-runners: true
+linters:
+  default: none
+  enable:
+    - kubeapilinter # linter for Kube API conventions
+  settings:
+    custom:
+      kubeapilinter:
+        type: module
+        description: KAL is the Kube-API-Linter and lints Kube like APIs based on API conventions and best practices.
+        settings:
+          linters:
+            enable:
+              - "commentstart" # Ensure comments start with the serialized version of the field name.
+              - "conditions" # Ensure conditions have the correct json tags and markers.
+              - "conflictingmarkers"
+              - "duplicatemarkers" # Ensure there are no exact duplicate markers. for types and fields.
+              - "integers" # Ensure only int32 and int64 are used for integers.
+              - "jsontags" # Ensure every field has a json tag.
+              - "nodurations" # Prevents usage of `Duration` types.
+              - "nofloats" # Ensure floats are not used.
+              - "nonullable" # Ensure that types and fields do not have the nullable marker.
+              - "notimestamp" # Prevents usage of 'Timestamp' fields
+              - "statussubresource" # All root objects that have a `status` field should have a status subresource.
+              - "uniquemarkers" # Ensure that types and fields do not contain more than a single definition of a marker that should only be present once.
+
+            # Linters below this line are disabled, pending conversation on how and when to enable them.
+            disable:
+            - "*" # We will manually enable new linters after understanding the impact. Disable all by default.
+
+          lintersConfig:
+            conflictingmarkers:
+              conflicts:
+              - name: "default_vs_required"
+                sets:
+                  - ["default", "kubebuilder:default"]
+                  - ["required", "kubebuilder:validation:Required", "k8s:required"]
+                description: "A field with a default value cannot be required"
+            conditions:
+              isFirstField: Warn # Require conditions to be the first field in the status struct.
+              usePatchStrategy: Forbid # Forbid patchStrategy markers on the Conditions field.
+              useProtobuf: Forbid # We don't use protobuf, so protobuf tags are not required.
+
+  exclusions:
+    generated: strict
+    paths:
+      - zz_generated.*\.go$
+      - vendored_openapi\.go$
+      - ".*_test.go"  # Exclude test files.
+    rules:
+    ## KAL should only run on API folders.
+    - path-except: "api//*"
+      linters:
+        - kubeapilinter
+
+    ## Excludes for old apiVersions that can be removed once the apiVersions are dropped (we don't want to make any changes to these APIs).
+    - path: "api/powervs/v1beta2"
+      linters:
+        - kubeapilinter
+
+    ## Excludes for VPC apiVersions.
+    - path: "api/vpc"
+      linters:
+        - kubeapilinter
+
+    ## Exclude deprecated v1beta2 status structs from conditions linter (backward compatibility)
+    - text: "Conditions field in .*V1Beta2DeprecatedStatus must be a slice of metav1.Condition"
+      linters:
+        - kubeapilinter
+
+issues:
+  max-same-issues: 0
+  max-issues-per-linter: 0

Makefile

@@ -38,6 +38,7 @@ TEMPLATES_DIR := $(REPO_ROOT)/templates
 
 GO_APIDIFF := $(TOOLS_BIN_DIR)/go-apidiff
 GOLANGCI_LINT := $(TOOLS_BIN_DIR)/golangci-lint
+GOLANGCI_LINT_KAL := $(TOOLS_BIN_DIR)/golangci-lint-kube-api-linter
 KUSTOMIZE := $(TOOLS_BIN_DIR)/kustomize
 GOJQ := $(TOOLS_BIN_DIR)/gojq
 CONVERSION_GEN := $(TOOLS_BIN_DIR)/conversion-gen
@@ -502,6 +503,14 @@ lint: $(GOLANGCI_LINT) ## Lint codebase
 lint-fix: $(GOLANGCI_LINT) ## Lint the codebase and run auto-fixers if supported by the linter
 	GOLANGCI_LINT_EXTRA_ARGS=--fix $(MAKE) lint
 
+.PHONY: lint-api
+lint-api: $(GOLANGCI_LINT_KAL)
+	$(GOLANGCI_LINT_KAL) run -v --config ./.golangci-kal.yml $(GOLANGCI_LINT_EXTRA_ARGS)
+
+.PHONY: lint-api-fix
+lint-api-fix: $(GOLANGCI_LINT_KAL)
+	GOLANGCI_LINT_EXTRA_ARGS=--fix $(MAKE) lint-api
+
 APIDIFF_OLD_COMMIT ?= $(shell git rev-parse origin/main)
 
 .PHONY: apidiff

api/powervs/v1beta3/ibmpowervscluster_types.go

@@ -35,12 +35,12 @@ func init() {
 
 // IBMPowerVSClusterSpec defines the desired state of IBMPowerVSCluster.
 type IBMPowerVSClusterSpec struct {
-	// Deprecated: use ServiceInstance instead
+	// serviceInstanceID is the id of the power cloud instance where the vsi instance will get deployed.
 	//
-	// ServiceInstanceID is the id of the power cloud instance where the vsi instance will get deployed.
+	// Deprecated: use ServiceInstance instead
 	ServiceInstanceID string `json:"serviceInstanceID"`
 
-	// Network is the reference to the Network to use for this cluster.
+	// network is the reference to the Network to use for this cluster.
 	// when the field is omitted, A DHCP service will be created in the Power VS workspace and its private network will be used.
 	// the DHCP service created network will have the following name format
 	// 1. in the case of DHCPServer.Name is not set the name will be DHCPSERVER<CLUSTER_NAME>_Private.
@@ -56,7 +56,7 @@ type IBMPowerVSClusterSpec struct {
 	// +optional
 	DHCPServer *DHCPServer `json:"dhcpServer,omitempty"`
 
-	// ControlPlaneEndpoint represents the endpoint used to communicate with the control plane.
+	// controlPlaneEndpoint represents the endpoint used to communicate with the control plane.
 	// +optional
 	ControlPlaneEndpoint clusterv1beta1.APIEndpoint `json:"controlPlaneEndpoint"`
 
@@ -108,7 +108,7 @@ type IBMPowerVSClusterSpec struct {
 	// +optional
 	VPCSubnets []Subnet `json:"vpcSubnets,omitempty"`
 
-	// VPCSecurityGroups to attach it to the VPC resource
+	// vpcSecurityGroups to attach it to the VPC resource
 	// +optional
 	VPCSecurityGroups []VPCSecurityGroup `json:"vpcSecurityGroups,omitempty"`
 
@@ -141,14 +141,15 @@ type IBMPowerVSClusterSpec struct {
 	// +optional
 	CosInstance *CosInstance `json:"cosInstance,omitempty"`
 
-	// Ignition defined options related to the bootstrapping systems where Ignition is used.
+	// ignition defined options related to the bootstrapping systems where Ignition is used.
 	// +optional
 	Ignition *Ignition `json:"ignition,omitempty"`
 }
 
 // IBMPowerVSClusterStatus defines the observed state of IBMPowerVSCluster.
 type IBMPowerVSClusterStatus struct {
 	// conditions represents the observations of a IBMPowerVSCluster's current state.
+	// +optional
 	// +listType=map
 	// +listMapKey=type
 	// +kubebuilder:validation:MaxItems=32
@@ -158,13 +159,13 @@ type IBMPowerVSClusterStatus struct {
 	// +kubebuilder:default=false
 	Ready bool `json:"ready"`
 
-	// ResourceGroup is the reference to the Power VS resource group under which the resources will be created.
+	// resourceGroupID is the reference to the Power VS resource group under which the resources will be created.
 	ResourceGroup *ResourceReference `json:"resourceGroupID,omitempty"`
 
 	// serviceInstance is the reference to the Power VS service on which the server instance(VM) will be created.
 	ServiceInstance *ResourceReference `json:"serviceInstance,omitempty"`
 
-	// networkID is the reference to the Power VS network to use for this cluster.
+	// network is the reference to the Power VS network to use for this cluster.
 	Network *ResourceReference `json:"network,omitempty"`
 
 	// dhcpServer is the reference to the Power VS DHCP server.
@@ -231,20 +232,20 @@ type IBMPowerVSClusterList struct {
 
 // DHCPServer contains the DHCP server configurations.
 type DHCPServer struct {
-	// Optional cidr for DHCP private network
+	// cidr for DHCP private network
 	Cidr *string `json:"cidr,omitempty"`
 
-	// Optional DNS Server for DHCP service
+	// dnsServer for DHCP service
 	// +kubebuilder:default="1.1.1.1"
 	DNSServer *string `json:"dnsServer,omitempty"`
 
-	// Optional name of DHCP Service. Only alphanumeric characters and dashes are allowed.
+	// name of DHCP Service. Only alphanumeric characters and dashes are allowed.
 	Name *string `json:"name,omitempty"`
 
-	// Optional id of the existing DHCPServer
+	// id of the existing DHCPServer
 	ID *string `json:"id,omitempty"`
 
-	// Optional indicates if SNAT will be enabled for DHCP service
+	// snat indicates if SNAT will be enabled for DHCP service
 	// +kubebuilder:default=true
 	Snat *bool `json:"snat,omitempty"`
 }
@@ -309,7 +310,7 @@ type CosInstance struct {
 
 // Ignition defines options related to the bootstrapping systems where Ignition is used.
 type Ignition struct {
-	// Version defines which version of Ignition will be used to generate bootstrap data.
+	// version defines which version of Ignition will be used to generate bootstrap data.
 	//
 	// +optional
 	// +kubebuilder:default="2.3"
@@ -321,17 +322,17 @@ type Ignition struct {
 type ResourceReference struct {
 	// id represents the id of the resource.
 	ID *string `json:"id,omitempty"`
-	// +kubebuilder:default=false
 	// controllerCreated indicates whether the resource is created by the controller.
+	// +kubebuilder:default=false
 	ControllerCreated *bool `json:"controllerCreated,omitempty"`
 }
 
 // TransitGatewayStatus defines the status of transit gateway as well as it's connection's status.
 type TransitGatewayStatus struct {
 	// id represents the id of the resource.
 	ID *string `json:"id,omitempty"`
-	// +kubebuilder:default=false
 	// controllerCreated indicates whether the resource is created by the controller.
+	// +kubebuilder:default=false
 	ControllerCreated *bool `json:"controllerCreated,omitempty"`
 	// vpcConnection defines the vpc connection status in transit gateway.
 	VPCConnection *ResourceReference `json:"vpcConnection,omitempty"`

api/powervs/v1beta3/ibmpowervsclustertemplate_types.go

@@ -28,6 +28,7 @@ func init() {
 
 // IBMPowerVSClusterTemplateSpec defines the desired state of IBMPowerVSClusterTemplate.
 type IBMPowerVSClusterTemplateSpec struct {
+	// template is the IBMPowerVSClusterTemplateResource.
 	Template IBMPowerVSClusterTemplateResource `json:"template"`
 }
 
@@ -60,9 +61,10 @@ type IBMPowerVSClusterTemplateList struct {
 
 // IBMPowerVSClusterTemplateResource describes the data needed to create an IBMPowerVSCluster from a template.
 type IBMPowerVSClusterTemplateResource struct {
-	// Standard object's metadata.
+	// metadata is the standard object's metadata.
 	// More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
 	// +optional
 	ObjectMeta clusterv1beta1.ObjectMeta `json:"metadata,omitempty"`
-	Spec       IBMPowerVSClusterSpec     `json:"spec"`
+	// spec is the IBMPowerVSClusterSpec.
+	Spec IBMPowerVSClusterSpec `json:"spec"`
 }

api/powervs/v1beta3/ibmpowervsimage_types.go

@@ -34,13 +34,13 @@ func init() {
 
 // IBMPowerVSImageSpec defines the desired state of IBMPowerVSImage.
 type IBMPowerVSImageSpec struct {
-	// ClusterName is the name of the Cluster this object belongs to.
+	// clusterName is the name of the Cluster this object belongs to.
 	// +kubebuilder:validation:MinLength=1
 	ClusterName string `json:"clusterName"`
 
-	// Deprecated: use ServiceInstance instead
+	// serviceInstanceID is the id of the power cloud instance where the image will get imported.
 	//
-	// ServiceInstanceID is the id of the power cloud instance where the image will get imported.
+	// Deprecated: use ServiceInstance instead
 	ServiceInstanceID string `json:"serviceInstanceID"`
 
 	// serviceInstance is the reference to the Power VS workspace on which the server instance(VM) will be created.
@@ -53,22 +53,22 @@ type IBMPowerVSImageSpec struct {
 	// +optional
 	ServiceInstance *IBMPowerVSResourceReference `json:"serviceInstance,omitempty"`
 
-	// Cloud Object Storage bucket name; bucket-name[/optional/folder]
+	// bucket is the Cloud Object Storage bucket name; bucket-name[/optional/folder]
 	Bucket *string `json:"bucket"`
 
-	// Cloud Object Storage image filename.
+	// object is the Cloud Object Storage image filename.
 	Object *string `json:"object"`
 
-	// Cloud Object Storage region.
+	// region is the Cloud Object Storage region.
 	Region *string `json:"region"`
 
-	// Type of storage, storage pool with the most available space will be selected.
+	// storageType is the type of storage, storage pool with the most available space will be selected.
 	// +kubebuilder:default=tier1
 	// +kubebuilder:validation:Enum=tier0;tier1;tier3
 	// +optional
 	StorageType string `json:"storageType,omitempty"`
 
-	// DeletePolicy defines the policy used to identify images to be preserved beyond the lifecycle of associated cluster.
+	// deletePolicy defines the policy used to identify images to be preserved beyond the lifecycle of associated cluster.
 	// +kubebuilder:default=delete
 	// +kubebuilder:validation:Enum=delete;retain
 	// +optional
@@ -84,18 +84,18 @@ type IBMPowerVSImageStatus struct {
 	// +kubebuilder:validation:MaxItems=32
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
 
-	// Ready is true when the provider resource is ready.
+	// ready is true when the provider resource is ready.
 	// +optional
 	Ready bool `json:"ready"`
 
-	// ImageID is the id of the imported image.
+	// imageID is the id of the imported image.
 	ImageID string `json:"imageID,omitempty"`
 
-	// ImageState is the status of the imported image.
+	// imageState is the status of the imported image.
 	// +optional
 	ImageState PowerVSImageState `json:"imageState,omitempty"`
 
-	// JobID is the job ID of an import operation.
+	// jobID is the job ID of an import operation.
 	// +optional
 	JobID string `json:"jobID,omitempty"`