Documentation
¶
Overview ¶
Package secret provides a builder and resource for managing Kubernetes Secrets.
Index ¶
- func DataHash(s corev1.Secret) (string, error)
- type Builder
- type Mutation
- type Mutator
- func (m *Mutator) Apply() error
- func (m *Mutator) EditData(edit func(*editors.SecretDataEditor) error)
- func (m *Mutator) EditObjectMetadata(edit func(*editors.ObjectMetaEditor) error)
- func (m *Mutator) NextFeature()
- func (m *Mutator) RemoveData(key string)
- func (m *Mutator) RemoveStringData(key string)
- func (m *Mutator) SetData(key string, value []byte)
- func (m *Mutator) SetStringData(key, value string)
- type Resource
- func (r *Resource) DesiredHash() (string, error)
- func (r *Resource) ExtractData() error
- func (r *Resource) GuardStatus() (concepts.GuardStatusWithReason, error)
- func (r *Resource) Identity() string
- func (r *Resource) Mutate(current client.Object) error
- func (r *Resource) Object() (client.Object, error)
- func (r *Resource) PreviewObject() (*corev1.Secret, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DataHash ¶
DataHash computes a stable SHA-256 hash of the effective data content of the given Secret.
The hash is derived from the canonical JSON encoding of the merged data map with keys sorted alphabetically, so it is deterministic regardless of insertion order. The returned string is the lowercase hex encoding of the 256-bit digest.
Both .data and .stringData are included. To match Kubernetes API-server write semantics, .stringData entries are merged into a copy of .data (with .stringData keys taking precedence) before hashing. This ensures the hash is consistent whether called on a desired object (which may use .stringData) or a cluster-read object (where the API server has already merged .stringData into .data).
A common use case is to annotate a Deployment's pod template with this hash so that a change in Secret content triggers a rolling restart:
hash, err := secret.DataHash(s)
if err != nil {
return err
}
m.EditPodTemplateMetadata(func(e *editors.ObjectMetaEditor) error {
e.EnsureAnnotation("checksum/secret", hash)
return nil
})
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder is a configuration helper for creating and customizing a Secret Resource.
It provides a fluent API for registering mutations and data extractors. Build() validates the configuration and returns an initialized Resource ready for use in a reconciliation loop.
func NewBuilder ¶
NewBuilder initializes a new Builder with the provided Secret object.
The Secret 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 Secret must have both Name and Namespace set, 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 Secret object was provided.
- The Secret is missing a Name or Namespace.
func (*Builder) WithDataExtractor ¶
WithDataExtractor registers a function to read values from the Secret after it has been successfully reconciled.
The extractor receives a value copy of the reconciled Secret. This is useful for surfacing generated or updated entries to other components or resources.
A nil extractor is ignored.
func (*Builder) WithGuard ¶ added in v0.4.0
func (b *Builder) WithGuard(guard func(corev1.Secret) (concepts.GuardStatusWithReason, error)) *Builder
WithGuard registers a guard precondition that is evaluated before the Secret is applied during reconciliation. If the guard returns Blocked, the Secret and all resources registered after it are skipped until the guard clears. Passing nil clears any previously registered guard.
func (*Builder) WithMutation ¶
WithMutation registers a mutation for the Secret.
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.
type Mutation ¶
Mutation defines a mutation that is applied to a secret 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 Secret.
It uses a "plan-and-apply" pattern: mutations are recorded first, then applied to the Secret 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.
Mutator implements editors.ObjectMutator.
func NewMutator ¶
NewMutator creates a new Mutator for the given Secret. The constructor creates the initial feature scope, so mutations can be registered immediately without an explicit call to NextFeature.
func (*Mutator) Apply ¶
Apply executes all recorded mutation intents on the underlying Secret.
Execution order within each plan:
- Metadata edits (in registration order)
- Data edits — EditData, SetData, RemoveData, SetStringData, RemoveStringData (in registration order)
Plans are applied sequentially. Later edits observe the Secret as modified by all earlier edits.
func (*Mutator) EditData ¶
func (m *Mutator) EditData(edit func(*editors.SecretDataEditor) error)
EditData records a mutation for the Secret's .data and .stringData fields via a SecretDataEditor.
The editor provides structured operations (Set, Remove, SetString, RemoveString) as well as Raw() and RawStringData() for free-form access. Data edits are applied after metadata edits within the same feature, in registration order.
A nil edit function is ignored.
func (*Mutator) EditObjectMetadata ¶
func (m *Mutator) EditObjectMetadata(edit func(*editors.ObjectMetaEditor) error)
EditObjectMetadata records a mutation for the Secret's own metadata.
Metadata edits are applied before data edits within the same feature. 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) RemoveData ¶
RemoveData records that key should be deleted from .data.
Convenience wrapper over EditData.
func (*Mutator) RemoveStringData ¶
RemoveStringData records that key should be deleted from .stringData.
Convenience wrapper over EditData.
func (*Mutator) SetData ¶
SetData records that key in .data should be set to value.
Convenience wrapper over EditData.
func (*Mutator) SetStringData ¶
SetStringData records that key in .stringData should be set to value.
The API server merges .stringData into .data on write; use this when working with plaintext values that should not be pre-encoded.
Convenience wrapper over EditData.
type Resource ¶
type Resource struct {
// contains filtered or unexported fields
}
Resource is a high-level abstraction for managing a Kubernetes Secret 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.
Secret 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.
func (*Resource) DesiredHash ¶
DesiredHash computes the SHA-256 hash of the Secret as it will be written to the cluster, based on the base object and all registered mutations.
The hash covers only operator-controlled data content: the effective Secret data after applying the baseline and mutations, with .stringData merged into .data (and .stringData keys taking precedence), matching DataHash semantics. Fields preserved by flavors from the live cluster state (e.g. PreserveExternalEntries) are intentionally excluded — only changes to operator-owned content will change the hash.
This enables a single-pass checksum pattern: compute the hash before reconciliation and pass it directly to the deployment resource factory, avoiding the need for a second reconcile cycle.
secretResource, err := secret.NewBuilder(base).WithMutation(...).Build()
hash, err := secretResource.DesiredHash()
deployResource, err := deployment.NewBuilder(base).
WithMutation(ChecksumMutation(version, hash)).
Build()
func (*Resource) ExtractData ¶
ExtractData executes all registered data extractor functions against a deep copy of the reconciled Secret.
This is called by the framework after successful reconciliation, allowing the component to read generated or updated values from the Secret.
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 Secret in the format "v1/Secret/<namespace>/<name>".
func (*Resource) Mutate ¶
Mutate transforms the current state of a Kubernetes Secret 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 Secret object.
The returned object implements client.Object, making it compatible with controller-runtime's Client for Create, Update, and Patch operations.
func (*Resource) PreviewObject ¶ added in v0.6.0
PreviewObject returns the Secret as it would appear after feature mutations have been applied, without modifying the resource's internal state.
Suspension mutations are not applied; the preview reflects content state only.
Source Files