fixup! build: Integrate with vscode

Author: jimmidyson

.golangci-kal.yml

@@ -23,6 +23,7 @@ linters:
     - govet
     - importas
     - ineffassign
+    - kubeapilinter
     - lll
     - misspell
     - nolintlint
@@ -74,8 +75,55 @@ linters:
         - github.com/onsi/gomega
     testifylint:
       enable-all: true
+    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.
+              - "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.
+              - "maxlength" # Ensure all strings and arrays have maximum lengths/maximum items.
+              - "nobools" # Bools do not evolve over time, should use enums instead.
+              - "nofloats" # Ensure floats are not used.
+              # - "nomaps" # Ensure maps are not used.
+              # - "nophase" # Ensure phases are not used, as they are not extensible.
+              - "optionalfields" # Ensure that all fields marked as optional adhere to being pointers and
+                                 # having the `omitempty` value in their `json` tag where appropriate.
+              - "optionalorrequired" # Every field should be marked as `+optional` or `+required`.
+              - "requiredfields" # Required fields should not be pointers, and should not have `omitempty`.
+              # - "ssatags" # Ensure array fields have the appropriate listType markers
+              # - "statusoptional" # Ensure all first children within status should be optional.
+              # - "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:
+            optionalfields:
+              pointers:
+                preference: WhenRequired # Always | WhenRequired # Whether to always require pointers, or only when required. Defaults to `Always`.
+            jsontags:
+              jsonTagRegex: "^[a-z][a-z0-9-]*(?:[A-Z][a-z0-9]*)*$" # The default regex is appropriate for our use case.
+            optionalorrequired:
+              preferredOptionalMarker: kubebuilder:validation:Optional # The preferred optional marker to use, fixes will suggest to use this marker. Defaults to `optional`.
+              preferredRequiredMarker: kubebuilder:validation:Required # The preferred required marker to use, fixes will suggest to use this marker. Defaults to `required`.
   exclusions:
-    generated: lax
+    generated: strict
+    paths:
+      # Ignore generated files.
+      - zz_generated.*\.go$
+      # Ignore external API packages.
+      - external/
+      # Ignore test files.
+      - '.+_test\.go$'
+      # Ignore aggregate types.
+      - 'aggregate_types\.go$'
     presets:
       - comments
       - common-false-positives
@@ -103,11 +151,36 @@ linters:
           - gocritic
         path: internal/test/envtest
         text: 'hugeParam: input is heavy'
-    paths:
-      - external
-      - third_party$
-      - builtin$
-      - examples$
+
+      # START kube-api-linter rules
+      - path: ".*"
+        text: "optionalorrequired: embedded field  must be marked as kubebuilder:validation:Optional or kubebuilder:validation:Required"
+        linters:
+          - kubeapilinter
+
+      # kube-api-linter does not handle formats correctly yet.
+      - path: '/addon_types\.go$'
+        text: "maxlength: field (Start|End) must have a maximum length, add kubebuilder:validation:MaxLength marker"
+        linters:
+          - kubeapilinter
+      - path: '/common_types\.go$'
+        text: "maxlength: field Address must have a maximum length, add kubebuilder:validation:MaxLength marker"
+        linters:
+          - kubeapilinter
+
+      # kube-api-linter does not handle patterns correctly yet.
+      - path: '/aws_(clusterconfig|node)_types\.go$'
+        text: "maxlength: field (ID|IAMInstanceProfile|InstanceType|Org) must have a maximum length, add kubebuilder:validation:MaxLength marker"
+        linters:
+          - kubeapilinter
+      - path: '/(nutanix_)?(clusterconfig)_types\.go$'
+        text: "maxlength: field (URL|Tag) must have a maximum length, add kubebuilder:validation:MaxLength marker"
+        linters:
+          - kubeapilinter
+      - path-except: "^/api/"
+        linters:
+          - kubeapilinter
+      # END kube-api-linter rules
 formatters:
   enable:
     - gci

.golangci.yml

@@ -26,12 +26,6 @@ repos:
     language: system
     files: "(.*\\.go|go.mod|go.sum|go.mk)$"
     pass_filenames: false
-  - id: kube-api-linter
-    name: kube-api-linter
-    entry: make lint-kube-api
-    language: system
-    files: "((^api/(.*\\.go|go.mod|go.sum))|go.mk)$"
-    pass_filenames: false
   - id: chart-docs
     name: chart-docs
     entry: make chart-docs

.pre-commit-config.yaml

@@ -284,7 +284,7 @@ type StorageClassConfig struct {
 
 	// If the storage class should allow volume expanding
 	// +kubebuilder:validation:Optional
-	AllowExpansion bool `json:"allowExpansion,omitempty"` //nolint:kubeapilinter,lll // Leave as bool for backward compatibility and this comment makes it a long line.
+	AllowExpansion bool `json:"allowExpansion,omitempty"`
 }
 
 type CSICredentials struct {

api/v1alpha1/addon_types.go

@@ -35,7 +35,7 @@ type NutanixPrismCentralEndpointSpec struct {
 
 	// use insecure connection to Prism Central endpoint
 	// +kubebuilder:validation:Optional
-	Insecure bool `json:"insecure,omitempty"` //nolint:kubeapilinter // Leave as bool for backward compatibility.
+	Insecure bool `json:"insecure,omitempty"`
 
 	// A base64 PEM encoded x509 cert for the RootCA that was used to create
 	// the certificate for a Prism Central that uses certificates that were issued by a non-publicly trusted RootCA.

api/v1alpha1/nutanix_clusterconfig_types.go

@@ -0,0 +1,36 @@
++++
+title = "Linting"
+icon = "fa-solid fa-magnifying-glass"
++++
+
+This project uses [`golangci-lint`][golangci-lint] to both lint and format the CAREN sourcecode. `golangci-lint` is
+installed via devbox, just as every other development tool that this project uses. The `golangci-lint` configuration
+includes a custom linter, [`kube-api-linter`][kube-api-linter], integrated as a `golangci-lint` [module plugin].
+
+## Installing `golangci-lint` with KAL
+
+To install the customized linter binary into `hack/tools/golangci-lint-kube-api-linter`, run:
+
+```bash
+make hack/tools/golangci-lint-kube-api-linter
+```
+
+## Integrating with vscode
+
+One the customized linter has been installed above, `vscode` can be configured to run this linter. Add the followin
+configuration to `.vscode/settings.json`:
+
+```json
+  "go.lintTool": "golangci-lint",
+  "go.lintFlags": ["--path-mode=abs"],
+  "go.formatTool": "custom",
+  "go.alternateTools": {
+    "customFormatter": "golangci-lint",
+    "golangci-lint": "${workspaceFolder}/hack/tools/golangci-lint-kube-api-linter"
+  },
+  "go.formatFlags": ["fmt", "--stdin"]
+```
+
+[golangci-lint]: https://golangci-lint.run/
+[kube-api-linter]: https://github.com/kubernetes-sigs/kube-api-linter/
+[module plugin]: https://golangci-lint.run/plugins/module-plugins/

docs/content/contributing/linting.md

@@ -1,7 +1,7 @@
 # Copyright 2025 Nutanix. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-version: v2.2.1
+version: v2.2.2
 name: golangci-lint-kube-api-linter
 plugins:
 - module: 'sigs.k8s.io/kube-api-linter'

hack/tools/.custom-gcl.yml

@@ -153,14 +153,8 @@ endif
 
 .PHONY: lint.%
 lint.%: ## Runs golangci-lint run for a specific module
-lint.%: fmt.% ; $(info $(M) linting $* module)
-	$(if $(filter-out root,$*),cd $* && )golangci-lint run --fix --config=$(GOLANGCI_CONFIG_FILE)
-
-.PHONY: lint-kube-api
-lint-kube-api: ## Runs kube-api-linter via custom golangci-lint configuration
-lint-kube-api: go-generate hack/tools/golangci-lint-kube-api-linter
-lint-kube-api: ; $(info $(M) running kube-api-linter)
-	cd api && $(PWD)/hack/tools/golangci-lint-kube-api-linter run --config=$(PWD)/.golangci-kal.yml
+lint.%: hack/tools/golangci-lint-kube-api-linter fmt.% ; $(info $(M) linting $* module)
+	$(if $(filter-out root,$*),cd $* && )$(PWD)/hack/tools/golangci-lint-kube-api-linter run --fix --config=$(GOLANGCI_CONFIG_FILE)
 
 hack/tools/golangci-lint-kube-api-linter: hack/tools/.custom-gcl.yml
 hack/tools/golangci-lint-kube-api-linter: ; $(info $(M) installing golangci-lint-kube-api-linter tool)

make/go.mk

@@ -7,6 +7,7 @@ import (
 	"context"
 	"fmt"
 
+	"github.com/blang/semver/v4"
 	apiextensionsv1 "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1"
 	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
 	bootstrapv1 "sigs.k8s.io/cluster-api/bootstrap/kubeadm/api/v1beta1"
@@ -15,16 +16,13 @@ import (
 	ctrl "sigs.k8s.io/controller-runtime"
 	ctrlclient "sigs.k8s.io/controller-runtime/pkg/client"
 
-	"github.com/blang/semver/v4"
 	"github.com/nutanix-cloud-native/cluster-api-runtime-extensions-nutanix/common/pkg/capi/clustertopology/handlers/mutation"
 	"github.com/nutanix-cloud-native/cluster-api-runtime-extensions-nutanix/common/pkg/capi/clustertopology/patches"
 	"github.com/nutanix-cloud-native/cluster-api-runtime-extensions-nutanix/common/pkg/capi/clustertopology/patches/selectors"
 	"github.com/nutanix-cloud-native/cluster-api-runtime-extensions-nutanix/common/pkg/capi/clustertopology/variables"
 )
 
-var (
-	versionGreaterOrEqualTo133Range = semver.MustParseRange(">=1.33.0-0")
-)
+var versionGreaterOrEqualTo133Range = semver.MustParseRange(">=1.33.0-0")
 
 type externalCloudProviderPatchHandler struct{}
 
@@ -58,7 +56,8 @@ func (h *externalCloudProviderPatchHandler) Mutate(
 		}
 
 		// This is a fatal error, we can't proceed without the control plane version.
-		log.WithValues("variables", vars).Error(err, "failed to get control plane Kubernetes version from builtin variable")
+		log.WithValues("variables", vars).
+			Error(err, "failed to get control plane Kubernetes version from builtin variable")
 		return fmt.Errorf("failed to get control plane Kubernetes version from builtin variable: %w", err)
 	}
 
@@ -87,7 +86,7 @@ func (h *externalCloudProviderPatchHandler) Mutate(
 			if obj.Spec.Template.Spec.KubeadmConfigSpec.ClusterConfiguration.APIServer.ExtraArgs == nil {
 				obj.Spec.Template.Spec.KubeadmConfigSpec.ClusterConfiguration.APIServer.ExtraArgs = make(map[string]string, 1)
 			}
-			if _, ok := obj.Spec.Template.Spec.KubeadmConfigSpec.ClusterConfiguration.APIServer.ExtraArgs["cloud-provider"]; !ok {
+			if _, ok := obj.Spec.Template.Spec.KubeadmConfigSpec.ClusterConfiguration.APIServer.ExtraArgs["cloud-provider"]; !ok { //nolint:lll // Easier to read this way.
 				obj.Spec.Template.Spec.KubeadmConfigSpec.ClusterConfiguration.APIServer.ExtraArgs["cloud-provider"] = "external"
 			}