Documentation
¶
Overview ¶
Package scope provides resource scope management for Kubernaut.
Business Requirements ¶
BR-SCOPE-001: Resource Scope Management - Opt-In Model ADR-053: Resource Scope Management Architecture
Overview ¶
Kubernaut only remediates resources that are explicitly opted-in by operators using the kubernaut.ai/managed label. The Manager validates scope using a 2-level hierarchy:
- Resource label (if resource exists and has label)
- Namespace label (for namespaced resources)
- Default: unmanaged (safe default)
For cluster-scoped resources (namespace==""), only the resource label is checked.
Usage ¶
The Manager accepts a client.Reader. Both Gateway and RO inject the cached client (informer-backed) because namespace labels are stable — they are set well before alerts or reconciliation runs. This avoids unnecessary API server load under high alert volume. The Manager implements the ScopeChecker interface for DI (see checker.go).
mgr := scope.NewManager(cachedClient) // Gateway + RO: informer-backed reads managed, err := mgr.IsManaged(ctx, "production", "Deployment", "payment-api")
Index ¶
Constants ¶
const ( // ManagedLabelKey is the canonical label key for Kubernaut resource scope management. // Resources/namespaces with this label set to "true" are managed by Kubernaut; // those with "false" or without the label are unmanaged (safe default). // // Reference: BR-SCOPE-001, ADR-053 ManagedLabelKey = "kubernaut.ai/managed" // ManagedLabelValueTrue indicates the resource is managed by Kubernaut. ManagedLabelValueTrue = "true" // ManagedLabelValueFalse indicates the resource is explicitly unmanaged. ManagedLabelValueFalse = "false" )
Variables ¶
var NamespaceFilePath = "/var/run/secrets/kubernetes.io/serviceaccount/namespace"
NamespaceFilePath is the path to the Kubernetes service account namespace file. Exported to allow tests to override it with a temp file.
ADR-057: CRD Namespace Consolidation — controller namespace discovery.
Functions ¶
func GetControllerNamespace ¶
GetControllerNamespace returns the namespace where kubernaut controllers are deployed.
Discovery order:
- KUBERNAUT_CONTROLLER_NAMESPACE environment variable (for local dev / testing)
- Kubernetes service account namespace file (standard in-cluster discovery)
ADR-057: All kubernaut CRDs are consolidated into the controller namespace. Controllers call this at startup to determine the namespace for CRD creation and watch restriction via Cache.ByObject.
func ScopeGVKs ¶
func ScopeGVKs() []schema.GroupVersionKind
ScopeGVKs returns the GroupVersionKinds that the scope manager needs cached for resource-level label lookups. Both Gateway and RO should include these GVKs in their RBAC ClusterRole (list+watch permissions) to enable metadata-only informers.
This function exports the static mapping from kindToGroup so that RBAC configuration, cache setup, and documentation remain consistent across services.
Reference: ADR-053 (Resource Scope Management Architecture)
Types ¶
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager validates resource scope using the 2-level hierarchy defined in ADR-053. It is shared by the Gateway (uncached reader for immediate namespace visibility) and the Remediation Orchestrator (cached reader, sufficient for reconciliation). Implements the ScopeChecker interface for dependency injection.
func NewManager ¶
NewManager creates a new scope Manager with the given client reader. Both Gateway and RO pass their cached client (ctrlClient / mgr.GetClient()), which creates metadata-only informers for PartialObjectMetadata lookups.
func (*Manager) IsManaged ¶
IsManaged checks whether a Kubernetes resource is managed by Kubernaut.
The 2-level hierarchy (ADR-053):
- Check resource label: "true" → managed, "false" → unmanaged, missing/invalid → continue
- Check namespace label: "true" → managed, "false" → unmanaged, missing → unmanaged
For cluster-scoped resources (namespace==""), only the resource label is checked. Resource not found: falls through to namespace check. Namespace not found: returns false, nil (unmanaged, not an error).
Parameters:
- namespace: the resource's namespace (empty for cluster-scoped resources like Node, PV)
- kind: the Kubernetes resource kind (e.g., "Pod", "Deployment", "Node")
- name: the resource instance name
type ScopeChecker ¶
type ScopeChecker interface {
// IsManaged checks whether a Kubernetes resource is managed by Kubernaut.
// Returns (true, nil) if managed, (false, nil) if unmanaged, or (false, error) on failure.
//
// The 2-level hierarchy (ADR-053):
// 1. Resource label: kubernaut.ai/managed=true → managed
// 2. Namespace label: kubernaut.ai/managed=true → managed
// 3. Default: unmanaged (safe default)
IsManaged(ctx context.Context, namespace, kind, name string) (bool, error)
}
ScopeChecker validates if a resource is within Kubernaut's management scope.
This interface abstracts the scope validation logic so that:
- Production uses *scope.Manager (backed by metadata-only cache per ADR-053)
- Unit/integration tests use a mock implementation via dependency injection
Both Gateway and Remediation Orchestrator inject this as a mandatory dependency. The pattern follows the same DI approach as processing.RetryObserver.
Business Requirements:
BR-SCOPE-001: Resource Scope Management (2-level hierarchy) BR-SCOPE-002: Gateway Signal Filtering BR-SCOPE-010: RO Scope Blocking
Architecture:
ADR-053: Resource Scope Management Architecture
Source Files