Merge 6772ca519f into a4903a95be

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

@@ -0,0 +1,100 @@
+# RFC-0012 Namespace Wildcard Alert Support
+
+<!--
+The title must be short and descriptive.
+-->
+
+**Status:** provisional
+
+<!--
+Status represents the current state of the RFC.
+Must be one of `provisional`, `implementable`, `implemented`, `deferred`, `rejected`, `withdrawn`, or `replaced`.
+-->
+
+**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](https://github.com/fluxcd/notification-controller/pull/504) to allow wildcard namespaces has been on hold pending a formal RFC, and [issue #71](https://github.com/fluxcd/notification-controller/issues/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](https://fluxcd.io/flux/components/notification/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`.