[Tracking Umbrella] Integrate Kube API Linter for Declarative Validation Linting

[yongruilin]

The Declarative Validation (KEP-5073) requires a linter for its IDL tags (e.g., +k8s:minimum). While validation-gen has some initial linting logic (e.g., for optional/required conflicts), kube-api-linter is a robust, existing tool for linting Kubernetes API types. This issue tracks leveraging kube-api-linter as the core linter for declarative validation IDL tags, aiming to replace or augment custom logic in validation-gen.

What you expected to happen:

Use kube-api-linter to:

1. Validate correct usage of declarative validation IDL tags based on defined rules.
2. Provide clear errors and potential auto-fixes for IDL tag mistakes.
3. Replace/augment validation-gen's current linting capabilities for these specific rules.
4. Ensure these linting rules are maintainable and extensible if new, similar interaction rules are defined.

To integrate, contributors need to address:

1. Parsing/AST Interoperability & Data Model Definition

   • Define and document the structured data model for IDL tags and their Go code context (field, type, source location) required by linter rules. This model must be consistent with and leverage existing Kubernetes API Conventions, including any necessary extensions or specific interpretations for IDL tag linting.
   • Document the mechanism for kube-api-linter to reliably access or receive this structured data, ensuring accuracy despite potential interpretation differences between gengo (used by validation-gen) and go/ast (used by kube-api-linter).

2. Linter Rules for Declarative Validation Tag Interactions (Additional rules may be identified as work progresses or KEP-5073 evolves.)

   • Conflicting Tags Rule: Implement rules to detect fields marked with mutually exclusive tags. New Linter: Generic conflictingmarkers #97
     • +k8s:optional and +k8s:required
     • +k8s:required and +default
   • Dependent Tags Rule: Implement rules to ensure that if a primary tag is present, its dependent tag(s) must also be present.
     • +k8s:unionMember requires the field to also be marked with +k8s:optional.
   • Fields requirement Rule: Implement rules to ensure some tags must be present in specific fields New Linter: pointeroptional #93
     • All pointer fields must have the +k8s:optional tag.

3. Configuration and Integration

   • Specify the configuration mechanism for enabling, disabling, and parameterizing declarative validation lint rules within kube-api-linter.
   • Detail the planned invocation methods (e.g., via validation-gen --lint, direct kube-api-linter CLI, golangci-lint plugin) and how lint results (errors, warnings, fixes) will be processed and reported.
   • Develop a strategy for integrating these linters into the Kubernetes CI/presubmit checks.

[yongruilin]

/cc @thockin @JoelSpeed

[JoelSpeed]

Optional and required conflicts are already handled in the optionalorrequired linter, which also enforces that every field is marked as either optional or required.

In the future, do we want core Kubernetes types to include both optional and k8s:optional, or is the latter sufficient? If the latter is sufficient, then I think we want to update that implementation to suggest k8s:optional as the default choice in all cases, and to update all tooling (including for CRDs) to prefer the k8s:optional marker instead of the optional marker

---

Dependent Tags Rule:

I would expect to implement this in a similar pattern to the conflicting markers base that we recently introduced. And then build specific rules as invocations of that base linter.

---

Fields requirement Rule: Implement rules to ensure some tags must be present in specific fields #93

All pointer fields must have the +k8s:optional tag.

I don't think this is a valid rule. Per recent discussion with @liggitt and updates to the API conventions, any field that has a valid zero value, even when required, must be a pointer. For example, I believe the replicas field on a Deployment is required, and has a pointer to allow the 0 value to round trip through a structured client.

---

Specify the configuration mechanism

As someone who is also heavily invested in the controller-tools project, I would like to see us build consistency across both built in types and custom resources. In the long term, I see KAL recommending to replace existing markers from Kubebuilder with the declarative validation markers.

I would like us to try and get to a point where we can make that something that is certain, at which point, configuration for whether to enforce the declarative validation markers or not is moot.

Detail the planned invocation methods
Develop a strategy for integrating these linters

KAL has already been included in K/K, though we haven't enabled any rules specifically yet. Linting the declarative markers for types that have not been migrated yet shouldn't cause issues, do we need a way to filter them or is the current invocation of golangci-lint and KAL sufficient?