Documentation
¶
Overview ¶
Package clusterrole provides a builder and resource for managing Kubernetes ClusterRoles.
Index ¶
- func ExtractInto[V any](b *Builder, cell *concepts.Data[V], fn func(rbacv1.ClusterRole) (V, error))
- type Builder
- func (b *Builder) Build() (*Resource, error)
- func (b *Builder) WithDataGuard(cells ...concepts.DataCell) *Builder
- func (b *Builder) WithGuard(guard func(rbacv1.ClusterRole) (concepts.GuardStatusWithReason, error)) *Builder
- func (b *Builder) WithMetricsIdentifier(identifier string) *Builder
- func (b *Builder) WithMutation(ms ...Mutation) *Builder
- func (b *Builder) WithOptionalData(cells ...concepts.DataCell) *Builder
- type Mutation
- type Mutator
- func (m *Mutator) AddRule(rule rbacv1.PolicyRule)
- func (m *Mutator) Apply() error
- func (m *Mutator) EditObjectMetadata(edit func(*editors.ObjectMetaEditor) error)
- func (m *Mutator) EditRules(edit func(*editors.PolicyRulesEditor) error)
- func (m *Mutator) NextFeature()
- func (m *Mutator) SetAggregationRule(rule *rbacv1.AggregationRule)
- type Resource
- func (r *Resource) ConsumedData() []concepts.DataConsumption
- func (r *Resource) ExtractData() error
- func (r *Resource) FiringSet() ([]string, error)
- func (r *Resource) GuardStatus() (concepts.GuardStatusWithReason, error)
- func (r *Resource) Identity() string
- func (r *Resource) MetricsIdentifier() string
- func (r *Resource) Mutate(current client.Object) error
- func (r *Resource) Object() (client.Object, error)
- func (r *Resource) Preview() (client.Object, error)
- func (r *Resource) ProducedData() []concepts.DataCell
- func (r *Resource) RecordObservation(observed client.Object) error
- func (r *Resource) RegisteredMutations() []string
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExtractInto ¶ added in v0.18.0
ExtractInto declares that this ClusterRole produces the value of cell. fn computes the value from a copy of the reconciled ClusterRole; the framework stores it in the cell and marks it present, immediately after the ClusterRole is applied or fetched. Extracting several values means several ExtractInto calls, one per cell. This is a package-level function because Go methods cannot introduce the extra type parameter V.
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder is a configuration helper for creating and customizing a ClusterRole Resource.
It provides a fluent API for registering mutations and declared data extractions. Build() validates the configuration and returns an initialized Resource ready for use in a reconciliation loop.
func NewBuilder ¶
func NewBuilder(cr *rbacv1.ClusterRole) *Builder
NewBuilder initializes a new Builder with the provided ClusterRole object.
The ClusterRole object serves as the desired base state. During reconciliation the Resource will make the cluster's state match this base, modified by any registered mutations.
The provided ClusterRole must have Name set (ClusterRole is cluster-scoped and does not use a namespace), which is validated during the Build() call.
func (*Builder) Build ¶
Build validates the configuration and returns the initialized Resource.
It returns an error if:
- No ClusterRole object was provided.
- The ClusterRole is missing a Name.
func (*Builder) WithDataGuard ¶ added in v0.18.0
WithDataGuard declares that the ClusterRole reads the given data cells and must not be applied until every one of them is set. The framework generates the guard and its reason (waiting for data "<name>"), and component Build validates that a producer for each cell is registered earlier. Data guards are evaluated before any custom guard registered with WithGuard.
func (*Builder) WithGuard ¶ added in v0.4.0
func (b *Builder) WithGuard(guard func(rbacv1.ClusterRole) (concepts.GuardStatusWithReason, error)) *Builder
WithGuard registers a guard precondition that is evaluated before the ClusterRole is applied during reconciliation. If the guard returns Blocked, the ClusterRole and all resources registered after it are skipped until the guard clears. Passing nil clears any previously registered guard.
func (*Builder) WithMetricsIdentifier ¶ added in v0.20.0
WithMetricsIdentifier sets the ClusterRole's identifier for resource-level metrics, used as the value of the `resource` label on ocf_resource_apply_total and ocf_resource_apply_errors_total.
It is a Prometheus label value, not a Kubernetes name: it must be low-cardinality and stable across reconciles, never derived from a per-owner value such as the owning custom resource's name. When unset, the resource is labelled `clusterrole`. Build rejects a blank identifier.
func (*Builder) WithMutation ¶
WithMutation registers one or more mutations for the ClusterRole.
Mutations are applied sequentially during the Mutate() phase of reconciliation. A mutation with a nil Feature is applied unconditionally; one with a non-nil Feature is applied only when that feature is enabled.
func (*Builder) WithOptionalData ¶ added in v0.18.0
WithOptionalData declares that the ClusterRole reads the given data cells without gating on them. Component Build still validates that a producer is registered earlier, and the dependency stays visible to introspection. Consumers in this mode use Get and skip quietly when a cell is absent.
type Mutation ¶
Mutation defines a mutation that is applied to a ClusterRole Mutator only if its associated feature gate is enabled.
type Mutator ¶
type Mutator struct {
// contains filtered or unexported fields
}
Mutator is a high-level helper for modifying a Kubernetes ClusterRole.
It uses a "plan-and-apply" pattern: mutations are recorded first, then applied to the ClusterRole in a single controlled pass when Apply() is called.
The Mutator maintains feature boundaries: each feature's mutations are planned together and applied in the order the features were registered. Within each feature, edits are applied in category order: metadata, then rules, then aggregation rule.
Mutator implements editors.ObjectMutator.
func NewMutator ¶
func NewMutator(cr *rbacv1.ClusterRole) *Mutator
NewMutator creates a new Mutator for the given ClusterRole. The constructor creates the initial feature scope, so mutations can be registered immediately without an explicit call to NextFeature.
func (*Mutator) AddRule ¶
func (m *Mutator) AddRule(rule rbacv1.PolicyRule)
AddRule records that a PolicyRule should be appended to .rules.
Convenience wrapper over EditRules.
func (*Mutator) Apply ¶
Apply executes all recorded mutation intents on the underlying ClusterRole.
Execution order across all registered features:
- Metadata edits (in registration order within each feature)
- Rules edits — EditRules, AddRule (in registration order within each feature)
- Aggregation rule — SetAggregationRule (last call wins within each feature)
Features are applied in the order they were registered. Later features observe the ClusterRole as modified by all previous features.
func (*Mutator) EditObjectMetadata ¶
func (m *Mutator) EditObjectMetadata(edit func(*editors.ObjectMetaEditor) error)
EditObjectMetadata records a mutation for the ClusterRole's own metadata.
Metadata edits are applied before rules edits within the same feature. A nil edit function is ignored.
func (*Mutator) EditRules ¶
func (m *Mutator) EditRules(edit func(*editors.PolicyRulesEditor) error)
EditRules records a mutation for the ClusterRole's .rules field via a PolicyRulesEditor.
The editor provides structured operations (AddRule, RemoveRuleByIndex, Clear) as well as Raw() for free-form access. Rules edits are applied after metadata edits within the same feature, in registration order.
A nil edit function is ignored.
func (*Mutator) NextFeature ¶
func (m *Mutator) NextFeature()
NextFeature advances to a new feature planning scope. All subsequent mutation registrations will be grouped into this scope until NextFeature is called again.
The first scope is created automatically by NewMutator. This method is called by the framework between mutations to maintain per-feature ordering semantics.
func (*Mutator) SetAggregationRule ¶
func (m *Mutator) SetAggregationRule(rule *rbacv1.AggregationRule)
SetAggregationRule records that the ClusterRole's .aggregationRule should be set to the given value.
An aggregation rule causes the API server to combine rules from ClusterRoles whose labels match the provided selectors, instead of using .rules directly. If called multiple times within the same feature, the last call wins.
A nil value clears the aggregation rule.
type Resource ¶
type Resource struct {
// contains filtered or unexported fields
}
Resource is a high-level abstraction for managing a Kubernetes ClusterRole within a controller's reconciliation loop.
It implements the following component interfaces:
- component.Resource: for basic identity and mutation behaviour.
- concepts.Guardable: for conditional reconciliation based on a guard precondition.
- concepts.DataExtractable: for exporting values after successful reconciliation.
- concepts.ObservationRecorder: for surfacing live cluster state to declared data extractions on read-only reconciliation.
ClusterRole resources are static: they do not model convergence health, grace periods, or suspension. Use a workload or task primitive for resources that require those concepts.
ClusterRole is cluster-scoped: it has no namespace.
func (*Resource) ConsumedData ¶ added in v0.18.0
func (r *Resource) ConsumedData() []concepts.DataConsumption
ConsumedData returns the ClusterRole's declared data reads. It satisfies concepts.DataConsumer for component topology validation and introspection.
func (*Resource) ExtractData ¶
ExtractData executes all declared data extractions against a deep copy of the reconciled ClusterRole.
This is called by the framework after successful reconciliation, allowing the component to read generated or updated values from the ClusterRole.
func (*Resource) FiringSet ¶ added in v0.14.0
FiringSet returns the Names of registered mutations whose gate is enabled for the version the ClusterRole was built at. It satisfies concepts.MutationInspector.
func (*Resource) GuardStatus ¶ added in v0.4.0
func (r *Resource) GuardStatus() (concepts.GuardStatusWithReason, error)
GuardStatus evaluates the resource's guard precondition. If no guard was registered, the resource is unconditionally unblocked.
func (*Resource) Identity ¶
Identity returns a unique identifier for the ClusterRole in the format "rbac.authorization.k8s.io/v1/ClusterRole/<name>".
func (*Resource) MetricsIdentifier ¶ added in v0.20.0
MetricsIdentifier returns the identifier set with Builder.WithMetricsIdentifier, or an empty string when none was set, in which case the framework labels the resource with its lowercased kind. It satisfies concepts.MetricsIdentifiable.
func (*Resource) Mutate ¶
Mutate transforms the current state of a Kubernetes ClusterRole into the desired state.
The mutation process follows this order:
- The desired base state is applied to the current object.
- Feature mutations: all registered feature-gated mutations are applied in order.
This method is invoked by the framework during the Update phase of reconciliation.
func (*Resource) Object ¶
Object returns a deep copy of the underlying Kubernetes ClusterRole object.
The returned object implements client.Object, making it compatible with controller-runtime's Client for Create, Update, and Patch operations.
func (*Resource) Preview ¶ added in v0.11.0
Preview renders the ClusterRole as a client.Object with feature mutations applied, without modifying the resource's internal state. It satisfies the component's Previewable capability so the component can assemble a cluster-free preview.
Suspension mutations are not applied; the preview reflects content state only. Callers needing the concrete type can type-assert the returned object.
func (*Resource) ProducedData ¶ added in v0.18.0
ProducedData returns the cells this ClusterRole declares extractions into. It satisfies concepts.DataProducer for component topology validation and introspection.
func (*Resource) RecordObservation ¶ added in v0.9.1
RecordObservation stores the supplied object as the resource's most recently observed cluster state. The framework invokes this on read-only resources after fetching them so that declared data extractions observe the live object rather than the inert base used to construct the resource.
func (*Resource) RegisteredMutations ¶ added in v0.14.0
RegisteredMutations returns the deduplicated Names of every mutation registered on the ClusterRole, independent of version. It satisfies concepts.MutationInspector so the resource can be introspected for version-matrix golden generation.
Source Files