feat(api): extend DependencyReference type to support any Kubernetes resource

[vecil]

Summary

The shared DependencyReference type now supports depending on any Kubernetes object, improving flexibility in release ordering and readiness handling.

Dependencies can reference arbitrary Kubernetes resources and are considered satisfied based on either existence or readiness (via the new ready field). The runtime/dependency sort package has been updated to operate on typed references, so dependencies across different apiVersion/kind combinations are correctly ordered and cycle-checked. The new TypedNamespacedObjectReference type carries the same shape as the previous NamespacedObjectReference plus the apiVersion and kind fields, and MakeDependsOn now parses the new apiVersion/Kind/[namespace/]name[:ready][@readyExpr] format.

Changes include:

• Extend DependencyReference with optional apiVersion, kind, and ready fields, and add a TypedNamespacedObjectReference type for typed cross-resource references
• Extend MakeDependsOn to parse apiVersion/Kind/[namespace/]name[:ready][@readyExpr] strings, with backward-compatible parsing of the existing name and namespace/name formats
• Render the new fields in DependencyReference.String() so dependencies round-trip correctly
• Update runtime/dependency.Sort to return TypedNamespacedObjectReference, require GetAPIVersion()/GetKind() on the Dependent interface, and only default the dependency namespace when the kind matches the parent
• Improve tests to cover arbitrary resource types, the ready toggle, and cross-kind dependency graphs

Relates fluxcd/flux2#5879

[matheuscscp]

Because most API types would normally require a custom ReadyExpr anyway, we would like to make it so that if the API group (ignoring the version) or the kind differ from the type managed by the respective controller, then ReadyExpr becomes mandatory.

This means everything except Kustomization will require ReadyExpr in kustomize-controller, and everything except HelmRelease will require ReadyExpr in helm-controller.

Maybe we can add xvalidation rule with a CEL expression to the DependsOn field in each controller to enforce this.

[vecil]

If the ReadyExpr-only approach is adopted, this proposal would provide a clear separation of behavior between HR-to-HR/KS-to-KS and cross-resource dependencies, and would reduce the cognitive load of writing such dependency rules 👍

[vecil]

On second thought, I have the feeling this proposal would introduce additional complexity when defining dependencies on resource types other than Appliers. Built-in readiness checks based on fluxcd/cli-utils/pkg/kstatus/status types and functions may already cover many use cases.

However, the proposed xvalidation rule introduces a limitation: it would require readyExpr to always be set, even when no custom check is desired. This prevents relying solely on built-in readiness checks in cases where they would otherwise be sufficient.

• When the AdditiveCELDependencyCheck feature gate is enabled, built-in readiness checks will always run alongside required readyExpr, with only the overhead of specifying a value (e.g. "true").
• When the gate is disabled, requiring readyExpr via xvalidation would prevent users from relying on built-in readiness checks alone.

[matheuscscp]

@vecil I think we can try and implement as much as possible of this feature in this repo. Besides the new types/fields in apis/meta, we can add also more logic to runtime/dependency as much as possible to slim down the code in the controllers. Unfotunately we will need the xvalidations in the respective DependsOn struct fields of each controller due to them being different, as they depend on the respective type managed by that controller. But I think a large part of the code could be implemented in runtime/dependency, maybe even existing code in the controllers.

One more thing: we need the schema validations that will be applied via xvalidations in the DependsOn struct fields of each controller to also be checked in the Reconcile() loop, this is a standard we have all across Flux to keep validation tight and error messages clear. This is so old API servers not supporting xvalidation still get guarded asynchronously after admission.