flux2/rfcs/RFC-0012-wildcard-namespace-support-for-alerts/README.md

RFC-0012 Namespace Wildcard Alert Support

Status: provisional

Creation date: 2025-06-29

Last update: 2025-06-29

Summary

Enable Alert.spec.eventSources[].namespace: "*" in the FluxCD Notification Controller behind a dedicated feature gate (--enable-namespace-wildcard-events) while preserving the global kill-switch (--no-cross-namespace-refs) for multi-tenant isolation. This provides cluster-wide alert configuration with minimal operator effort and no additional surface area for secret leakage.

Motivation

Flux’s Notification Controller today requires one Alert per namespace or explicit namespace lists, making cluster-wide error monitoring laborious and brittle. A user-land PR #504 to allow wildcard namespaces has been on hold pending a formal RFC, and issue #71 has long requested this enhancement. Meanwhile, multi-tenant operators rely on --no-cross-namespace-refs=true to enforce strict per-namespace boundaries.

Goals

• Operator Convenience: Support a single Alert watching all namespaces via namespace: "*" without templating per-namespace resources.
• Opt-in Safety: Gate wildcard support behind --enable-namespace-wildcard-events (default off).
• Global Kill-Switch: Honor --no-cross-namespace-refs=true to disable wildcard (and all cross-namespace refs) when set.
• Minimal Surface Area: No new CRD types or cross-namespace secret reads.

Non-Goals

• Introducing new CRDs (e.g., ClusterAlert).
• Implementing complex cross-namespace authorization (e.g., ReferenceGrant).
• Allowing Provider references across namespaces.

Proposal

1. New Feature Flag

   • Introduce --enable-namespace-wildcard-events (boolean; default false).
   • When true, controllers accept literal "*" in Alert.spec.eventSources[].namespace.
   • When false, any "*" is rejected during validation with an explicit error.

2. Interaction with --no-cross-namespace-refs

   • --no-cross-namespace-refs=true remains the global kill-switch: if set, wildcard is rejected regardless of the new flag.

3. CRD Validation

   • Update the Alert CRD schema (spec.eventSources[].namespace) to allow "*" only if --enable-namespace-wildcard-events=true.
   • Webhook returns:

     spec.eventSources[i].namespace: '*' is not allowed; enable via --enable-namespace-wildcard-events
     

     or, if --no-cross-namespace-refs=true:

     spec.eventSources[i].namespace: '*' is disallowed by --no-cross-namespace-refs
     

4. RBAC Requirements

   • To monitor all namespaces, the controller’s ServiceAccount must have list,watch on Flux source CRs (e.g., GitRepository, HelmRelease) cluster-wide.
   • In tenant-isolated installs where the SA lacks these permissions, wildcard support is effectively inert.

5. Secret Access Boundary

   • Providers continue to reference secrets in their own namespace; no cross-namespace secret reads are introduced by wildcard alerts.

User Stories

• Cluster Operator

  As a cluster operator, I want to define a single Alert in flux-system that picks up all HelmRelease failures across every namespace so that I don’t need to manage per-namespace Alert CRDs.

• Multi-Tenant Admin

  As a multi-tenant platform admin, I want to ensure that no tenant can enable wildcard alerts unless I explicitly allow it, and I want a single flag (--no-cross-namespace-refs=true) to disable all cross-namespace features.

Alternatives

• ReferenceGrant-Gated Wildcard: Leverage Kubernetes ReferenceGrant API for explicit per-namespace grants (rejected due to KEP-3766 closure).
• Namespace Label Selector: Use spec.namespaceSelector to select labeled namespaces (requires cluster-wide label management).
• Namespace Regex Matching: Permit regex patterns in place of exact namespace names (error-prone and overly broad).
• ClusterAlert CRD: Introduce a cluster-scoped Alert type (adds new API surface).
• ResourceSet Templating: Use Flux ResourceSet to generate per-namespace Alerts (still creates multiple CRs).

Design Details

• CLI Changes: Add --enable-namespace-wildcard-events to controller options alongside existing flags like --no-cross-namespace-refs.
• Validation Webhook: Enforce schema constraint on namespace field based on feature gates.
• Controller Logic:
  • On reconciliation, if wildcard is enabled and not globally disabled, list/watch across all namespaces.
  • Otherwise, restrict to the Alert’s own namespace.
• Documentation: Update Flux Notification Controller Options and the Alerts guide to include wildcard examples and flag semantics.

Implementation History

• 2025-06-29: Draft RFC-0012 created.
• TBD: Feature implementation, tests, docs.
• TBD: Community review and merge into flux2/rfcs.