.golangci-kal.yml

version: "2"
run:
  go: "1.25"
  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.
              - "forbiddenmarkers" # Ensure that types and fields do not contain any markers that are forbidden.
              - "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.
              - "nodurations" # Prevents usage of `Duration` types.
              - "nofloats" # Ensure floats are not used.
              - "nomaps" # Ensure maps are not used.
              - "nonullable" # Ensure that types and fields do not have the nullable marker.
              - "notimestamp" # Prevents usage of 'Timestamp' fields
              - "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.

            # Per discussion in July 2024, we are keeping phase fields for now.
            # See https://github.com/kubernetes-sigs/cluster-api/pull/10897#discussion_r1685929508
            # and https://github.com/kubernetes-sigs/cluster-api/pull/10897#discussion_r1685919394.
            # - "nophase" # Phase fields are discouraged by the Kube API conventions, use conditions instead.

            # 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"
            forbiddenmarkers:
              markers:
                # We don't want to do any defaulting (including OpenAPI) anymore on API fields because we prefer
                # to have a clear signal on user intent. This also allows us to easily change the default behavior if necessary.
                - identifier: "kubebuilder:default"
                - identifier: "default"
            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.
            optionalfields:
              pointers:
                preference: WhenRequired # Always | WhenRequired # Whether to always require pointers, or only when required. Defaults to `Always`.
                policy: SuggestFix # SuggestFix | Warn # The policy for pointers in optional fields. Defaults to `SuggestFix`.
              omitempty:
                policy: SuggestFix # SuggestFix | Warn | Ignore # The policy for omitempty in optional fields. Defaults to `SuggestFix`.

  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/addons/v1beta1|api/bootstrap/kubeadm/v1beta1|api/controlplane/kubeadm/v1beta1|api/core/v1beta1|api/ipam/v1beta1|api/ipam/v1alpha1|api/runtime/v1alpha1"
      linters:
        - kubeapilinter

    ## Excludes for current apiVersions that can be removed once v1beta1 is removed.
    # .status.deprecated.v1beta1.conditions fields are using v1beta1.Condition types.
    - path: "api/addons/v1beta2|api/bootstrap/kubeadm/v1beta2|api/controlplane/kubeadm/v1beta2|api/core/v1beta2|api/ipam/v1beta2|api/runtime/v1beta2"
      text: "Conditions field in .*V1Beta1DeprecatedStatus must be a slice of metav1.Condition"
      linters:
        - kubeapilinter
    - path: "api/addons/v1beta2|api/bootstrap/kubeadm/v1beta2|api/controlplane/kubeadm/v1beta2|api/core/v1beta2|api/ipam/v1beta2|api/runtime/v1beta2"
      text: "ssatags: .*Conditions should have a listType marker for proper Server-Side Apply behavior"
      linters:
        - kubeapilinter
    - path: "api/core/v1beta2"
      text: "field .*Conditions type Conditions must have a maximum items, add kubebuilder:validation:MaxItems marker"
      linters:
        - kubeapilinter
    - path: "api/core/v1beta2/condition_types.go"
      text: "requiredfields: field (Type|Status|LastTransitionTime) should have the omitempty tag"
      linters:
        - kubeapilinter

    ## Excludes for current clusterctl v1alpha3 and Runtime Hooks v1alpha1 apiVersions (can be fixed once we bump their apiVersion).
    # Note: The types in api/runtime/hooks/v1alpha1 are not CRDs, so e.g. SSA markers don't make sense there.
    - path: "cmd/clusterctl/api/v1alpha3|api/runtime/hooks/v1alpha1"
      text: "maxlength|ssatags"
      linters:
        - kubeapilinter
    - path: "cmd/clusterctl/api/v1alpha3|api/runtime/hooks/v1alpha1/(common_types.go|discovery_types.go|lifecyclehooks_types.go|topologymutation_types.go|topologymutation_variable_types.go)"
      text: "optionalfields|requiredfields"
      linters:
        - kubeapilinter

    ## Excludes for JSONSchemaProps
    # We want to align to the JSON tags of the CustomResourceDefinition fields.
    - path: "api/core/v1beta2/clusterclass_types"
      text: "field JSONSchemaProps.(XPreserveUnknownFields|XPreserveUnknownFields|XValidations|XMetadata|XIntOrString) json tag does not match pattern"
      linters:
        - kubeapilinter
    # We want to align Properties to the corresponding field in CustomResourceDefinitions.
    - path: "api/core/v1beta2/clusterclass_types"
      text: "Properties should not use a map type, use a list type with a unique name/identifier instead"
      linters:
        - kubeapilinter
    # It's simpler to check these fields against nil vs. using reflect.DeepEqual everywhere.
    - path: "api/core/v1beta2/clusterclass_types.go"
      text: "optionalfields: field (AdditionalProperties|Items|Not) does not allow the zero value. (The field does not need to be a pointer|It must have the omitzero tag)"
      linters:
        - kubeapilinter

    ## Removal of bool fields of existing types requires further discussion
    - path: "api/bootstrap/kubeadm/v1beta2|api/controlplane/kubeadm/v1beta2|api/core/v1beta2|api/addons/v1beta2"
      text: "nobools"
      linters:
        - kubeapilinter

    ## Excludes for kubeadm types
    # We want to align the FeatureGates field to the FeatureGates field in kubeadm.
    - path: "api/bootstrap/kubeadm/v1beta2/kubeadm_types.go"
      text: "nomaps: ClusterConfiguration.FeatureGates should not use a map type, use a list type with a unique name/identifier instead"
      linters:
        - kubeapilinter

    ## Excludes for requiredfields
    # Empty Bootstrap object is blocked via validating webhooks. This cannot be detected by KAL (same if we move the validation to CEL).
    - path: "api/core/v1beta2/machine_types.go"
      text: "requiredfields: field Bootstrap has a valid zero value \\({}\\), but the validation is not complete \\(e.g. min properties/adding required fields\\). The field should be a pointer to allow the zero value to be set. If the zero value is not a valid use case, complete the validation and remove the pointer."
      linters:
        - kubeapilinter

    ## Excludes for optionalfields
    ## The ExtraEnvs field intentionally has type *[]EnvVar.
    ## Today we have MinItems=1, but we might have to support MinItems=0 in the future if kubeadm starts supporting it.
    - path: "api/bootstrap/kubeadm/v1beta2/kubeadm_types.go"
      text: "optionalfields: field ExtraEnvs does not allow the zero value. The field does not need to be a pointer."
      linters:
        - kubeapilinter

    # Excludes for existing default markers 
    - path: "api/core/v1beta2/clusterclass_types.go"
      text: 'forbiddenmarkers: field ValidationRule.Reason has forbidden marker "kubebuilder:default=FieldValueInvalid"'
      linters:
        - kubeapilinter
    - path: "api/core/v1beta2/clusterclass_types.go"
      text: 'forbiddenmarkers: field ValidationRule.Reason has forbidden marker "default=ref\(sigs.k8s.io/cluster-api/api/core/v1beta2.FieldValueInvalid\)"'
      linters:
        - kubeapilinter

    # TODO: Excludes that should be removed once the corresponding issues in KAL are fixed
    # KAL incorrectly reports that the Taints field doesn't have to be a pointer (it has to be to preserve []).
    # See: https://github.com/kubernetes-sigs/kube-api-linter/issues/116
    - path: "api/bootstrap/kubeadm/v1beta2/kubeadm_types.go"
      text: "optionalfields: field Taints underlying type does not need to be a pointer. The pointer should be removed."
      linters:
        - kubeapilinter
     # KAL incorrectly reports that the zero value is valid
     # See: https://github.com/kubernetes-sigs/kube-api-linter/issues/138
    - path: "api/bootstrap/kubeadm/v1beta2/kubeadm_types.go"
      text: "requiredfields: field Token has a valid zero value \\({\"\": \"\", \"\": \"\"}\\) and should be a pointer."
      linters:
        - kubeapilinter

issues:
  max-same-issues: 0
  max-issues-per-linter: 0