conditions

package
v0.49.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 13, 2024 License: Apache-2.0 Imports: 18 Imported by: 25

Documentation

Overview

Package conditions provides utilities for manipulating the status conditions of Kubernetes resource objects that implement the Getter and/or Setter interfaces.

Usage of this package within GitOps Toolkit components working with conditions is RECOMMENDED, as it provides a wide range of helpers to work around common reconciler problems, like setting a Condition status based on a summarization of other conditions, producing an aggregate Condition based on the conditions of a list of Kubernetes resources objects, recognition of negative polarity or "abnormal-true" conditions, etc.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrUnstructuredFieldNotFound = fmt.Errorf("field not found")
)

Functions

func Delete 

func Delete(to Setter, t string)

Delete deletes the condition with the given type.

func FalseCondition 

func FalseCondition(t, reason, messageFormat string, messageArgs ...interface{}) *metav1.Condition

FalseCondition returns a condition with Status=False and the given type, reason and message.

func Get 

func Get(from Getter, t string) *metav1.Condition

Get returns the condition with the given type, if the condition does not exists, it returns nil.

func GetLastTransitionTime 

func GetLastTransitionTime(from Getter, t string) *metav1.Time

GetLastTransitionTime returns the LastTransitionType or nil if the condition does not exist (is nil).

func GetMessage 

func GetMessage(from Getter, t string) string

GetMessage returns a nil safe string of Message for the condition with the given type.

func GetObservedGeneration 

func GetObservedGeneration(from Getter, t string) int64

GetObservedGeneration returns a nil safe int64 of ObservedGeneration for the condition with the given type.

func GetReason 

func GetReason(from Getter, t string) string

GetReason returns a nil safe string of Reason for the condition with the given type.

func Has 

func Has(from Getter, t string) bool

Has returns true if a condition with the given type exists.

func HasAny added in v0.28.0 

func HasAny(from Getter, t []string) bool

HasAny returns true if a condition with any of the given types exist.

func HasAnyReason added in v0.44.1 

func HasAnyReason(from Getter, t string, r ...string) bool

HasAnyReason returns true if a condition with the given type exists and any of the given reasons exist.

func HaveSameStateOf 

func HaveSameStateOf(expected *metav1.Condition) types.GomegaMatcher

HaveSameStateOf returns a custom matcher to check equality of a metav1.Condition, the condition message is checked for a subset string match.

func IsFalse 

func IsFalse(from Getter, t string) bool

IsFalse is true if the condition with the given type is False, otherwise it is false if the condition is not False or if the condition does not exist (is nil).

func IsReady 

func IsReady(from Getter) bool

IsReady is true if IsStalled and IsReconciling are False, and meta.ReadyCondition is True, otherwise it is false if the condition is not True or if it does not exist (is nil).

func IsReconciling 

func IsReconciling(from Getter) bool

IsReconciling is true if meta.ReconcilingCondition is True and meta.StalledCondition is False or does not exist, otherwise it is false.

func IsStalled 

func IsStalled(from Getter) bool

IsStalled is true if meta.StalledCondition is True and meta.ReconcilingCondition is False or does not exist, otherwise it is false.

func IsTrue 

func IsTrue(from Getter, t string) bool

IsTrue is true if the condition with the given type is True, otherwise it is false if the condition is not True or if the condition does not exist (is nil).

func IsUnknown 

func IsUnknown(from Getter, t string) bool

IsUnknown is true if the condition with the given type is Unknown or if the condition does not exist (is nil).

func MarkFalse 

func MarkFalse(to Setter, t, reason, messageFormat string, messageArgs ...interface{})

MarkFalse sets Status=False for the condition with the given type, reason and message.

func MarkReconciling 

func MarkReconciling(to Setter, reason, messageFormat string, messageArgs ...interface{})

MarkReconciling sets meta.ReconcilingCondition=True with the given reason and message, and deletes the meta.StalledCondition. This is normally called at the beginning of a reconcile run for an object. For more information about the condition types, see the kstatus spec: https://github.com/kubernetes-sigs/cli-utils/blob/e351b2bc43cec2107ba1d874c3dec54fd0956c59/pkg/kstatus/README.md#conditions

func MarkStalled 

func MarkStalled(to Setter, reason, messageFormat string, messageArgs ...interface{})

MarkStalled sets meta.StalledCondition=True with the given reason and message, and deletes the meta.ReconcilingCondition. This is normally deferred and conditionally called at the end of a reconcile run for an object. A common approach is to mark the object stalled if the object is not requeued as a reconcile result. For more information about the condition types, see the kstatus spec: https://github.com/kubernetes-sigs/cli-utils/blob/e351b2bc43cec2107ba1d874c3dec54fd0956c59/pkg/kstatus/README.md#conditions

func MarkTrue 

func MarkTrue(to Setter, t, reason, messageFormat string, messageArgs ...interface{})

MarkTrue sets Status=True for the condition with the given type, reason and message.

func MarkUnknown 

func MarkUnknown(to Setter, t, reason, messageFormat string, messageArgs ...interface{})

MarkUnknown sets Status=Unknown for the condition with the given type, reason and message.

func MatchCondition 

func MatchCondition(expected metav1.Condition) types.GomegaMatcher

MatchCondition returns a custom matcher to check equality of metav1.Condition.

func MatchConditions 

func MatchConditions(expected []metav1.Condition) types.GomegaMatcher

MatchConditions returns a custom matcher to check equality of a metav1.Condition slice, the condition messages are checked for a subset string match.

func Set 

func Set(to Setter, condition *metav1.Condition)

Set sets the given condition.

NOTE: If a condition already exists, the LastTransitionTime is updated only if a change is detected in any of the following fields: Status, Reason, and Message. The ObservedGeneration is always updated.

func SetAggregate 

func SetAggregate(to Setter, targetCondition string, from []Getter, options ...MergeOption)

SetAggregate creates a new condition with the aggregation of all the conditions from a list of dependency objects, or a subset using WithConditions; if none of the source objects have a condition within the scope of the merge operation, no target condition is generated.

func SetMirror 

func SetMirror(to Setter, targetCondition string, from Getter, options ...MirrorOptions)

SetMirror creates a new condition by mirroring the the Ready condition from a dependent object; if the Ready condition does not exists in the source object, no target conditions is generated.

func SetSummary 

func SetSummary(to Setter, targetCondition string, options ...MergeOption)

SetSummary creates a new summary condition with the summary of all the conditions existing on an object. If the object does not have other conditions, no summary condition is generated.

func TrueCondition 

func TrueCondition(t, reason, messageFormat string, messageArgs ...interface{}) *metav1.Condition

TrueCondition returns a condition with Status=True and the given type, reason and message.

func UnknownCondition 

func UnknownCondition(t, reason, messageFormat string, messageArgs ...interface{}) *metav1.Condition

UnknownCondition returns a condition with Status=Unknown and the given type, reason and message.

func UnstructuredUnmarshalField 

func UnstructuredUnmarshalField(u *unstructured.Unstructured, v interface{}, fields ...string) error

UnstructuredUnmarshalField is a wrapper around JSON and Unstructured objects to decode and copy a specific field value into an object.

Types

type ApplyOption 

type ApplyOption func(*applyOptions)

ApplyOption defines an option for applying a condition patch.

func WithForceOverwrite 

func WithForceOverwrite(v bool) ApplyOption

WithForceOverwrite instructs the patch helper to always use the value provided by the controller in case of conflicts for the owned conditions.

func WithOwnedConditions 

func WithOwnedConditions(t ...string) ApplyOption

WithOwnedConditions allows to define condition types owned by the controller. In case of conflicts for the owned conditions, the patch helper will always use the value provided by the controller.

type ConditionMatcher 

type ConditionMatcher struct {
	Expected *metav1.Condition
}

func (*ConditionMatcher) FailureMessage 

func (matcher *ConditionMatcher) FailureMessage(actual interface{}) (message string)

func (*ConditionMatcher) Match 

func (matcher *ConditionMatcher) Match(actual interface{}) (success bool, err error)

func (*ConditionMatcher) NegatedFailureMessage 

func (matcher *ConditionMatcher) NegatedFailureMessage(actual interface{}) (message string)

type Getter 

type Getter interface {
	client.Object
	meta.ObjectWithConditions
}

Getter interface defines methods that a Kubernetes resource object should implement in order to use the conditions package for getting conditions.

func UnstructuredGetter 

func UnstructuredGetter(u *unstructured.Unstructured) Getter

UnstructuredGetter return a Getter object that can read conditions from an Unstructured object.

IMPORTANT: This method should be used only with types implementing status conditions with a metav1.Condition type.

type MergeOption 

type MergeOption func(*mergeOptions)

MergeOption defines an option for computing a summary of conditions.

func WithConditions 

func WithConditions(t ...string) MergeOption

WithConditions instructs merge about the condition types to consider when doing a merge operation; if this option is not specified, all the conditions (except Ready, Stalled, and Reconciling) will be considered. This is required so we can provide some guarantees about the semantic of the target condition without worrying about side effects if someone or something adds custom conditions to the objects.

NOTE: The order of conditions types defines the priority for determining the Reason and Message for the target condition. IMPORTANT: This options works only while generating a Summary or Aggregated condition.

func WithCounter 

func WithCounter() MergeOption

WithCounter instructs merge to add a "x of y Type" string to the message, where x is the number of conditions in the top group, y is the number of objects in scope, and Type is the top group condition type.

func WithCounterIfOnly 

func WithCounterIfOnly(t ...string) MergeOption

WithCounterIfOnly ensures a counter is show only if a subset of condition exists. This may apply when you want to use a step counter while reconciling the resource, but then want to move away from this notation as soon as the resource has been reconciled, and e.g. a health check condition is generated.

IMPORTANT: This options requires WithStepCounter or WithStepCounterIf to be set. IMPORTANT: This option works only while generating the Aggregated condition.

func WithLatestGeneration 

func WithLatestGeneration() MergeOption

WithLatestGeneration instructs merge to consider the conditions with the latest observed generation only.

func WithNegativePolarityConditions 

func WithNegativePolarityConditions(t ...string) MergeOption

WithNegativePolarityConditions instructs merge about the condition types that adhere to a "normal-false" or "abnormal-true" pattern, i.e. that conditions are present with a value of True whenever something unusual happens.

NOTE: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties IMPORTANT: This option works only while generating the Summary or Aggregated condition.

func WithSourceRef 

func WithSourceRef() MergeOption

WithSourceRef instructs merge to add info about the originating object to the target Reason and in summaries.

func WithSourceRefIf 

func WithSourceRefIf(t ...string) MergeOption

WithSourceRefIf ensures a source ref is show only if one of the types in the set exists.

func WithStepCounter 

func WithStepCounter() MergeOption

WithStepCounter instructs merge to add a "x of y completed" string to the message, where x is the number of conditions with Status=true and y is the number of conditions in scope.

IMPORTANT: This option works only while generating the Summary or Aggregated condition.

func WithStepCounterIf 

func WithStepCounterIf(value bool) MergeOption

WithStepCounterIf adds a step counter if the value is true. This can be used e.g. to add a step counter only if the object is not being deleted.

IMPORTANT: This option works only while generating the Summary or Aggregated condition.

func WithStepCounterIfOnly 

func WithStepCounterIfOnly(t ...string) MergeOption

WithStepCounterIfOnly ensures a step counter is show only if a subset of condition exists. This may apply when you want to use a step counter while reconciling the resource, but then want to move away from this notation as soon as the resource has been reconciled, and e.g. a health check condition is generated.

IMPORTANT: This options requires WithStepCounter or WithStepCounterIf to be set. IMPORTANT: This option works only while generating the Summary or Aggregated condition.

type MirrorOptions 

type MirrorOptions func(*mirrorOptions)

MirrorOptions defines an option for mirroring conditions.

func WithFallbackValue 

func WithFallbackValue(fallbackValue bool, reason string, message string) MirrorOptions

WithFallbackValue specify a fallback value to use in case the mirrored condition does not exists; in case the fallbackValue is false, given values for reason and message will be used.

type Patch 

type Patch []PatchOperation

Patch defines a list of operations to change a list of conditions into another.

func NewPatch 

func NewPatch(before Getter, after Getter) Patch

NewPatch returns the list of Patch required to align source conditions to after conditions.

func (Patch) Apply 

func (p Patch) Apply(latest Setter, options ...ApplyOption) error

Apply executes a three-way merge of a list of Patch. When merge conflicts are detected (latest deviated from before in an incompatible way), an error is returned.

func (Patch) IsZero 

func (p Patch) IsZero() bool

IsZero returns true if the patch has no changes.

type PatchOperation 

type PatchOperation struct {
	Before *metav1.Condition
	After  *metav1.Condition
	Op     PatchOperationType
}

PatchOperation define an operation that changes a single condition.

type PatchOperationType 

type PatchOperationType string

PatchOperationType defines patch operation types. 

const (
	// AddConditionPatch defines an add condition patch operation.
	AddConditionPatch PatchOperationType = "Add"

	// ChangeConditionPatch defines an change condition patch operation.
	ChangeConditionPatch PatchOperationType = "Change"

	// RemoveConditionPatch defines a remove condition patch operation.
	RemoveConditionPatch PatchOperationType = "Remove"
)

type Setter 

type Setter interface {
	Getter
	meta.ObjectWithConditionsSetter
}

Setter is an interface that defines methods a Kubernetes object should implement in order to use the conditions package for setting conditions.

func UnstructuredSetter 

func UnstructuredSetter(u *unstructured.Unstructured) Setter

UnstructuredSetter return a Setter object that can set conditions from an Unstructured object.

IMPORTANT: This method should be used only with types implementing status conditions with a metav1.Condition type.

Source Files

View all Source files

Directories

Path Synopsis
Package check provides warning and failure checks for the status of K8s object based on the various properties of the object status.
 Package check provides warning and failure checks for the status of K8s object based on the various properties of the object status.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.