Documentation
¶
Overview ¶
Package ingress provides a builder and resource for managing Kubernetes Ingresses.
Index ¶
- func DefaultDeleteOnSuspendHandler(_ *networkingv1.Ingress) bool
- func DefaultGraceStatusHandler(ing *networkingv1.Ingress) (concepts.GraceStatusWithReason, error)
- func DefaultOperationalStatusHandler(_ concepts.ConvergingOperation, ing *networkingv1.Ingress) (concepts.OperationalStatusWithReason, error)
- func DefaultSuspendMutationHandler(_ *Mutator) error
- func DefaultSuspensionStatusHandler(_ *networkingv1.Ingress) (concepts.SuspensionStatusWithReason, error)
- type Builder
- func (b *Builder) Build() (*Resource, error)
- func (b *Builder) WithCustomGraceStatus(handler func(*networkingv1.Ingress) (concepts.GraceStatusWithReason, error)) *Builder
- func (b *Builder) WithCustomOperationalStatus(...) *Builder
- func (b *Builder) WithCustomSuspendDeletionDecision(handler func(*networkingv1.Ingress) bool) *Builder
- func (b *Builder) WithCustomSuspendMutation(handler func(*Mutator) error) *Builder
- func (b *Builder) WithCustomSuspendStatus(...) *Builder
- func (b *Builder) WithDataExtractor(extractor func(networkingv1.Ingress) error) *Builder
- func (b *Builder) WithGuard(guard func(networkingv1.Ingress) (concepts.GuardStatusWithReason, error)) *Builder
- func (b *Builder) WithMutation(m Mutation) *Builder
- type Mutation
- type Mutator
- type Resource
- func (r *Resource) ConvergingStatus(op concepts.ConvergingOperation) (concepts.OperationalStatusWithReason, error)
- func (r *Resource) DeleteOnSuspend() bool
- func (r *Resource) ExtractData() error
- func (r *Resource) GraceStatus() (concepts.GraceStatusWithReason, 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() (*networkingv1.Ingress, error)
- func (r *Resource) Suspend() error
- func (r *Resource) SuspensionStatus() (concepts.SuspensionStatusWithReason, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultDeleteOnSuspendHandler ¶
func DefaultDeleteOnSuspendHandler(_ *networkingv1.Ingress) bool
DefaultDeleteOnSuspendHandler provides the default decision of whether to delete the Ingress when the parent component is suspended.
It always returns false. Deleting an Ingress causes the ingress controller (e.g. nginx) to reload its configuration, which affects the entire cluster's routing — not just the suspended service. When a backend service is suspended, the Ingress returning 502/503 is the correct observable behaviour.
Operators that want explicit deletion can set DeleteOnSuspend: true via Builder.WithCustomSuspendDeletionDecision.
func DefaultGraceStatusHandler ¶
func DefaultGraceStatusHandler(ing *networkingv1.Ingress) (concepts.GraceStatusWithReason, error)
DefaultGraceStatusHandler provides a default health assessment of the Ingress after the component's grace period has expired.
It categorizes the current state into:
- GraceStatusHealthy: At least one IP or hostname is assigned in Status.LoadBalancer.Ingress.
- GraceStatusDegraded: No load balancer address has been assigned yet.
This function is used as the default handler by the Resource if no custom handler is registered via Builder.WithCustomGraceStatus. It can be reused within custom handlers to augment the default behavior.
func DefaultOperationalStatusHandler ¶
func DefaultOperationalStatusHandler( _ concepts.ConvergingOperation, ing *networkingv1.Ingress, ) (concepts.OperationalStatusWithReason, error)
DefaultOperationalStatusHandler is the default logic for determining if an Ingress has reached its operational state.
It considers an Ingress operational when at least one IP or hostname is assigned in Status.LoadBalancer.Ingress. Until then it reports Pending.
This function is used as the default handler by the Resource if no custom handler is registered via Builder.WithCustomOperationalStatus.
func DefaultSuspendMutationHandler ¶
DefaultSuspendMutationHandler provides the default mutation applied to an Ingress when the component is suspended.
It is a no-op. The Ingress is left in place and the backend service returning 502/503 is the expected observable behaviour during suspension.
func DefaultSuspensionStatusHandler ¶
func DefaultSuspensionStatusHandler(_ *networkingv1.Ingress) (concepts.SuspensionStatusWithReason, error)
DefaultSuspensionStatusHandler monitors the progress of the suspension process.
Since the default suspension is a no-op (the Ingress is not deleted or modified), it immediately reports Suspended with a reason indicating the backend is unavailable.
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder is a configuration helper for creating and customizing an Ingress Resource.
It provides a fluent API for registering mutations, status handlers, and data extractors. Build() validates the configuration and returns an initialized Resource ready for use in a reconciliation loop.
func NewBuilder ¶
func NewBuilder(ing *networkingv1.Ingress) *Builder
NewBuilder initializes a new Builder with the provided Ingress object.
The Ingress 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 Ingress 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 Ingress object was provided.
- The Ingress is missing a Name or Namespace.
func (*Builder) WithCustomGraceStatus ¶
func (b *Builder) WithCustomGraceStatus( handler func(*networkingv1.Ingress) (concepts.GraceStatusWithReason, error), ) *Builder
WithCustomGraceStatus overrides how the Ingress reports its health after the component's grace period has expired.
The default behavior uses DefaultGraceStatusHandler.
This is used to provide more granular feedback in the component's status about the severity of a load balancer assignment delay.
If you want to augment the default behavior, you can call DefaultGraceStatusHandler within your custom handler.
func (*Builder) WithCustomOperationalStatus ¶
func (b *Builder) WithCustomOperationalStatus( handler func(concepts.ConvergingOperation, *networkingv1.Ingress) (concepts.OperationalStatusWithReason, error), ) *Builder
WithCustomOperationalStatus overrides the default logic for determining if the Ingress has reached its operational state.
The default behavior uses DefaultOperationalStatusHandler, which considers an Ingress operational when at least one IP or hostname is assigned in Status.LoadBalancer.Ingress. Use this method if your Ingress requires more complex health checks.
func (*Builder) WithCustomSuspendDeletionDecision ¶
func (b *Builder) WithCustomSuspendDeletionDecision( handler func(*networkingv1.Ingress) bool, ) *Builder
WithCustomSuspendDeletionDecision overrides the decision of whether to delete the Ingress when the component is suspended.
The default behavior uses DefaultDeleteOnSuspendHandler, which returns false. Deleting an Ingress causes the ingress controller to reload its configuration, affecting the entire cluster's routing. Return true from this handler only if explicit deletion is required for your use case.
func (*Builder) WithCustomSuspendMutation ¶
WithCustomSuspendMutation defines how the Ingress should be modified when the component is suspended.
The default behavior uses DefaultSuspendMutationHandler, which is a no-op. Deleting an Ingress causes ingress controller churn; the recommended approach is to let the backend service return 502/503.
func (*Builder) WithCustomSuspendStatus ¶
func (b *Builder) WithCustomSuspendStatus( handler func(*networkingv1.Ingress) (concepts.SuspensionStatusWithReason, error), ) *Builder
WithCustomSuspendStatus overrides how the progress of suspension is reported.
The default behavior uses DefaultSuspensionStatusHandler, which immediately reports Suspended since the default suspension is a no-op.
func (*Builder) WithDataExtractor ¶
func (b *Builder) WithDataExtractor(extractor func(networkingv1.Ingress) error) *Builder
WithDataExtractor registers a function to read values from the Ingress after it has been successfully reconciled.
The extractor receives a value copy of the reconciled Ingress. This is useful for surfacing generated or updated entries (such as assigned load balancer addresses) to other components or resources.
A nil extractor is ignored.
func (*Builder) WithGuard ¶ added in v0.4.0
func (b *Builder) WithGuard(guard func(networkingv1.Ingress) (concepts.GuardStatusWithReason, error)) *Builder
WithGuard registers a guard precondition that is evaluated before the Ingress is applied during reconciliation. If the guard returns Blocked, the Ingress 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 Ingress.
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 an ingress 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 Ingress.
It uses a "plan-and-apply" pattern: mutations are recorded first, then applied to the Ingress 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.
Apply order within each feature:
- Object metadata edits
- Ingress spec edits
Mutator implements editors.ObjectMutator.
func NewMutator ¶
func NewMutator(ing *networkingv1.Ingress) *Mutator
NewMutator creates a new Mutator for the given Ingress. The constructor creates the initial feature scope automatically.
func (*Mutator) Apply ¶
Apply executes all recorded mutation intents on the underlying Ingress.
Execution order across all registered features:
- Metadata edits (in registration order within each feature)
- Ingress spec edits (in registration order within each feature)
Features are applied in the order they were registered. Later features observe the Ingress as modified by all previous features.
func (*Mutator) EditIngressSpec ¶
func (m *Mutator) EditIngressSpec(edit func(*editors.IngressSpecEditor) error)
EditIngressSpec records a mutation for the Ingress's spec via an IngressSpecEditor.
The editor provides structured operations (SetIngressClassName, SetDefaultBackend, EnsureRule, RemoveRule, EnsureTLS, RemoveTLS) as well as Raw() for free-form access. Ingress spec 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 Ingress's own metadata.
Metadata edits are applied before ingress spec 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.
type Resource ¶
type Resource struct {
// contains filtered or unexported fields
}
Resource is a high-level abstraction for managing a Kubernetes Ingress within a controller's reconciliation loop.
It implements the following component lifecycle interfaces:
- component.Resource: for basic identity and mutation behaviour.
- concepts.Operational: for tracking whether the ingress has been assigned an address.
- concepts.Graceful: for health assessment after the component's grace period has expired.
- concepts.Suspendable: for controlled suspension when the parent component is suspended.
- concepts.Guardable: for conditional reconciliation based on a guard precondition.
- concepts.DataExtractable: for exporting values after successful reconciliation.
Ingress resources are integration primitives: they depend on an external ingress controller to assign load balancer addresses. The default operational status handler reports OperationPending (concepts.OperationalStatusPending) until at least one IP or hostname is assigned, then Operational.
func (*Resource) ConvergingStatus ¶
func (r *Resource) ConvergingStatus(op concepts.ConvergingOperation) (concepts.OperationalStatusWithReason, error)
ConvergingStatus evaluates whether the Ingress has reached its operational state.
By default, it uses DefaultOperationalStatusHandler, which reports OperationPending until the ingress controller has assigned at least one IP or hostname, then Operational.
func (*Resource) DeleteOnSuspend ¶
DeleteOnSuspend determines whether the Ingress should be deleted from the cluster when the parent component is suspended.
By default, it uses DefaultDeleteOnSuspendHandler, which returns false. Deleting an Ingress causes the ingress controller to reload its configuration, affecting the entire cluster's routing — not just the suspended service.
func (*Resource) ExtractData ¶
ExtractData executes all registered data extractor functions against a deep copy of the reconciled Ingress.
This is called by the framework after successful reconciliation, allowing the component to read generated or updated values (such as assigned load balancer addresses) from the Ingress.
func (*Resource) GraceStatus ¶
func (r *Resource) GraceStatus() (concepts.GraceStatusWithReason, error)
GraceStatus provides a health assessment of the Ingress after the component's grace period has expired.
By default, it uses DefaultGraceStatusHandler, which categorizes the current state into:
- GraceStatusHealthy: At least one IP or hostname is assigned in Status.LoadBalancer.Ingress.
- GraceStatusDegraded: No load balancer address has been assigned yet.
This information is surfaced through the component's health reporting, allowing operators to understand the severity of a load balancer assignment delay.
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 Ingress in the format "networking.k8s.io/v1/Ingress/<namespace>/<name>".
func (*Resource) Mutate ¶
Mutate transforms the current state of a Kubernetes Ingress into the desired state.
The mutation process follows this order:
- Feature mutations: all registered feature-gated mutations are applied in order.
- Suspension mutation: if the component is suspended, the suspension mutation is applied.
This method is invoked by the framework during the reconciliation loop.
func (*Resource) Object ¶
Object returns a deep copy of the underlying Kubernetes Ingress 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
func (r *Resource) PreviewObject() (*networkingv1.Ingress, error)
PreviewObject returns the Ingress 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.
func (*Resource) Suspend ¶
Suspend triggers the suspension of the Ingress.
It registers a mutation that will be executed during the next Mutate call. The default behavior is a no-op — the Ingress is left in place and the backend service returning 502/503 is the expected observable behaviour.
func (*Resource) SuspensionStatus ¶
func (r *Resource) SuspensionStatus() (concepts.SuspensionStatusWithReason, error)
SuspensionStatus monitors the progress of the suspension process.
By default, it uses DefaultSuspensionStatusHandler, which immediately reports Suspended with a reason indicating the backend is unavailable.
Source Files