meta

package module
v1.18.0 Latest Latest
Warning

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

Go to latest
Published: Jul 15, 2025 License: Apache-2.0 Imports: 1 Imported by: 186

Documentation

Overview

Package meta contains the generic metadata APIs for use by GitOps Toolkit components.

It is intended only to help adhere to Kubernetes API conventions, utility integrations, and Flux project considered best practices. It may therefore be suitable for usage by Kubernetes resources with no relationship to the GitOps Toolkit. +kubebuilder:object:generate=true

Index

Constants

View Source
const (
	// ReconcileRequestAnnotation is the annotation used for triggering a reconciliation
	// outside of a defined interval. The value is interpreted as a token, and any change
	// in value SHOULD trigger a reconciliation.
	ReconcileRequestAnnotation string = "reconcile.fluxcd.io/requestedAt"

	// ForceRequestAnnotation is the annotation used for triggering a one-off forced
	// reconciliation, for example, of a HelmRelease when there are no new changes,
	// or of something that runs on a schedule when the schedule is not due at the moment.
	// The specific conditions for triggering a forced reconciliation depend on the
	// specific controller implementation, but the annotation is used to standardize
	// the mechanism across controllers. The value is interpreted as a token, and must
	// equal the value of ReconcileRequestAnnotation in order to trigger a release.
	ForceRequestAnnotation string = "reconcile.fluxcd.io/forceAt"
)
View Source
const (
	// ReadyCondition indicates the resource is ready and fully reconciled.
	// If the Condition is False, the resource SHOULD be considered to be in the process of reconciling and not a
	// representation of actual state.
	ReadyCondition string = "Ready"

	// StalledCondition indicates the reconciliation of the resource has stalled, e.g. because the controller has
	// encountered an error during the reconcile process or it has made insufficient progress (timeout).
	// The Condition adheres to an "abnormal-true" polarity pattern, and MUST only be present on the resource if the
	// Condition is True.
	// For more information about polarity patterns, see:
	// https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties
	StalledCondition string = "Stalled"

	// ReconcilingCondition indicates the controller is currently working on reconciling the latest changes. This MAY be
	// True for multiple reconciliation attempts, e.g. when an transient error occurred.
	// The Condition adheres to an "abnormal-true" polarity pattern, and MUST only be present on the resource if the
	// Condition is True.
	// For more information about polarity patterns, see:
	// https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties
	ReconcilingCondition string = "Reconciling"

	// HealthyCondition represents the last recorded
	// health assessment result.
	HealthyCondition string = "Healthy"
)

These constants define generic Condition types to be used by GitOps Toolkit components.

The ReadyCondition SHOULD be implemented by all components' Kubernetes resources to indicate they have been fully reconciled by their respective reconciler. This MAY suffice for simple resources, e.g. a resource that just declares state once and is not expected to receive any updates afterwards.

For Kubernetes resources that are expected to receive spec updates over time, take a longer time to reconcile, or deal with more complex logic in which for example a finite error state can be observed, it is RECOMMENDED to implement the StalledCondition and ReconcilingCondition.

By doing this, observers making use of kstatus to determine the current state of the resource will have a better experience while they are e.g. waiting for a change to be reconciled, and will be able to stop waiting for a change if a StalledCondition is observed, without having to rely on a timeout.

For more information on kstatus, see: https://github.com/kubernetes-sigs/cli-utils/blob/v0.25.0/pkg/kstatus/README.md

View Source
const (
	// SucceededReason indicates a condition or event observed a success, for example when declared desired state
	// matches actual state, or a performed action succeeded.
	//
	// More information about the reason of success MAY be available as additional metadata in an attached message.
	SucceededReason string = "Succeeded"

	// FailedReason indicates a condition or event observed a failure, for example when declared state does not match
	// actual state, or a performed action failed.
	//
	// More information about the reason of failure MAY be available as additional metadata in an attached message.
	FailedReason string = "Failed"

	// ProgressingReason indicates a condition or event observed progression, for example when the reconciliation of a
	// resource or an action has started.
	//
	// When this reason is given, other conditions and types MAY no longer be considered as an up-to-date observation.
	// Producers of the specific condition type or event SHOULD provide more information about the expectations and
	// precise meaning in their API specification.
	//
	// More information about the reason or the current state of the progression MAY be available as additional metadata
	// in an attached message.
	ProgressingReason string = "Progressing"

	// SuspendedReason indicates a condition or event has observed a suspension, for
	// example because a resource has been suspended, or a dependency is.
	SuspendedReason string = "Suspended"

	// ProgressingWithRetryReason represents the fact that
	// the reconciliation encountered an error that will be retried.
	ProgressingWithRetryReason string = "ProgressingWithRetry"

	// DependencyNotReadyReason represents the fact that
	// one of the dependencies is not ready.
	DependencyNotReadyReason string = "DependencyNotReady"

	// InvalidPathReason signals a failure caused by an invalid path.
	InvalidPathReason string = "InvalidPath"

	// InvalidURLReason signals a failure caused by an invalid URL.
	InvalidURLReason string = "InvalidURL"

	// InsecureConnectionsDisallowedReason signals a failure caused by
	// the use of insecure HTTP connections.
	InsecureConnectionsDisallowedReason = "InsecureConnectionsDisallowed"

	// UnsupportedConnectionTypeReason signals a failure caused by
	// the use of unsupported network protocols.
	UnsupportedConnectionTypeReason = "UnsupportedConnectionType"

	// PruneFailedReason represents the fact that the
	// pruning of the resources failed.
	PruneFailedReason string = "PruneFailed"

	// ArtifactFailedReason represents the fact that the
	// source artifact download failed.
	ArtifactFailedReason string = "ArtifactFailed"

	// BuildFailedReason represents the fact that the
	// build failed.
	BuildFailedReason string = "BuildFailed"

	// HealthCheckFailedReason represents the fact that
	// one of the health checks failed.
	HealthCheckFailedReason string = "HealthCheckFailed"

	// ReconciliationSucceededReason represents the fact that
	// the reconciliation succeeded.
	ReconciliationSucceededReason string = "ReconciliationSucceeded"

	// ReconciliationFailedReason represents the fact that
	// the reconciliation failed.
	ReconciliationFailedReason string = "ReconciliationFailed"

	// InvalidCELExpressionReason represents the fact that a CEL expression
	// in the configuration is invalid.
	InvalidCELExpressionReason string = "InvalidCELExpression"

	// FeatureGateDisabledReason represents the fact that a feature is trying to
	// be used, but the feature gate for that feature is disabled.
	FeatureGateDisabledReason string = "FeatureGateDisabled"
)

These constants define generic Condition reasons to be used by GitOps Toolkit components.

Making use of a generic Reason is RECOMMENDED whenever it can be applied to a Condition in which it provides sufficient context together with the type to summarize the meaning of the Condition cause.

Where any of the generic Condition reasons does not suffice, GitOps Toolkit components can introduce new reasons to their API specification, or use an arbitrary PascalCase string when setting the Condition. Declaration of domain common Condition reasons in the API specification is RECOMMENDED, as it eases observations for user and computer.

For more information on Condition reason conventions, see: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties

View Source
const (
	// LabelKeyWatch is used to indicate that a resource should be watched by Flux.
	LabelKeyWatch = "reconcile.fluxcd.io/watch"

	// LabelValueWatchEnabled is the value for LabelKeyWatch that indicates a resource should be watched.
	LabelValueWatchEnabled = "Enabled"
)
View Source
const (
	// KubeConfigKeyProvider is the key in the ConfigMap that contains the provider name.
	KubeConfigKeyProvider = "provider"
	// KubeConfigKeyAddress is the key in the ConfigMap that contains the cluster resource
	// name in the provider API
	KubeConfigKeyCluster = "cluster"
	// KubeConfigKeyAddress is the key in the ConfigMap that contains the address of the
	// Kubernetes API server.
	KubeConfigKeyAddress = "address"
	// KubeConfigKeyCACert is the key in the ConfigMap that contains the PEM-encoded CA
	// certificate for the Kubernetes API server.
	KubeConfigKeyCACert = "ca.crt"
	// KubeConfigKeyAudiences is the key in the ConfigMap that contains the audiences
	// for the Kubernetes ServiceAccount token.
	KubeConfigKeyAudiences = "audiences"
	// KubeConfigKeyServiceAccountName is the key in the ConfigMap that contains the
	// name of the Kubernetes ServiceAccount in the same namespace that should be used
	// for authentication.
	KubeConfigKeyServiceAccountName = "serviceAccountName"
)

Variables

This section is empty.

Functions

func HandleAnnotationRequest added in v1.13.0

func HandleAnnotationRequest(obj ObjectWithAnnotationRequests, annotation string, lastHandled *string) bool

HandleAnnotationRequest returns true if the object has a request annotation, and the value of the annotation matches the value of the ReconcileRequestAnnotation annotation.

The lastHandled argument is used to ensure that the request is handled only once, and is updated to match the value of the request annotation (even if the request is not handled because the value of the ReconcileRequestAnnotation annotation does not match).

func ReconcileAnnotationValue added in v0.1.0

func ReconcileAnnotationValue(annotations map[string]string) (string, bool)

ReconcileAnnotationValue returns a value for the reconciliation request annotation, which can be used to detect changes, and a boolean indicating whether the annotation was set.

func ShouldHandleForceRequest added in v1.13.0

func ShouldHandleForceRequest(obj interface {
	ObjectWithAnnotationRequests
	GetLastHandledForceRequestStatus() *string
}) bool

ShouldHandleForceRequest returns true if the object has a force request annotation, and the value of the annotation matches the value of the ReconcileRequestAnnotation annotation.

To ensure that the force request is handled only once, the value of <ObjectType>Status.LastHandledForceAt is updated to match the value of the force request annotation (even if the force request is not handled because the value of the ReconcileRequestAnnotation annotation does not match).

Types

type ForceRequestStatus added in v1.13.0

type ForceRequestStatus struct {
	// LastHandledForceAt holds the value of the most recent
	// force request value, so a change of the annotation value
	// can be detected.
	// +optional
	LastHandledForceAt string `json:"lastHandledForceAt,omitempty"`
}

ForceRequestStatus is a struct to embed in a status type, so that all types using the mechanism have the same field. Use it like this:

	type FooStatus struct {
 	meta.ForceRequestStatus `json:",inline"`
 	// other status fields...
	}

func (*ForceRequestStatus) DeepCopy added in v1.13.0

func (in *ForceRequestStatus) DeepCopy() *ForceRequestStatus

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ForceRequestStatus.

func (*ForceRequestStatus) DeepCopyInto added in v1.13.0

func (in *ForceRequestStatus) DeepCopyInto(out *ForceRequestStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type KubeConfigReference added in v0.17.0

type KubeConfigReference struct {
	// ConfigMapRef holds an optional name of a ConfigMap that contains
	// the following keys:
	//
	// - `provider`: the provider to use. One of `aws`, `azure`, `gcp`, or
	//    `generic`. Required.
	// - `cluster`: the fully qualified resource name of the Kubernetes
	//    cluster in the cloud provider API. Not used by the `generic`
	//    provider. Required when one of `address` or `ca.crt` is not set.
	// - `address`: the address of the Kubernetes API server. Required
	//    for `generic`. For the other providers, if not specified, the
	//    first address in the cluster resource will be used, and if
	//    specified, it must match one of the addresses in the cluster
	//    resource.
	//    If audiences is not set, will be used as the audience for the
	//    `generic` provider.
	// - `ca.crt`: the optional PEM-encoded CA certificate for the
	//    Kubernetes API server. If not set, the controller will use the
	//    CA certificate from the cluster resource.
	// - `audiences`: the optional audiences as a list of
	//    line-break-separated strings for the Kubernetes ServiceAccount
	//    token. Defaults to the `address` for the `generic` provider, or
	//    to specific values for the other providers depending on the
	//    provider.
	// -  `serviceAccountName`: the optional name of the Kubernetes
	//    ServiceAccount in the same namespace that should be used
	//    for authentication. If not specified, the controller
	//    ServiceAccount will be used.
	//
	// Mutually exclusive with SecretRef.
	//
	// +optional
	ConfigMapRef *LocalObjectReference `json:"configMapRef,omitempty"`

	// SecretRef holds an optional name of a secret that contains a key with
	// the kubeconfig file as the value. If no key is set, the key will default
	// to 'value'. Mutually exclusive with ConfigMapRef.
	// It is recommended that the kubeconfig is self-contained, and the secret
	// is regularly updated if credentials such as a cloud-access-token expire.
	// Cloud specific `cmd-path` auth helpers will not function without adding
	// binaries and credentials to the Pod that is responsible for reconciling
	// Kubernetes resources. Supported only for the generic provider.
	// +optional
	SecretRef *SecretKeyReference `json:"secretRef,omitempty"`
}

KubeConfigReference contains enough information build a kubeconfig in memory for connecting to remote Kubernetes clusters. +kubebuilder:validation:XValidation:rule="has(self.configMapRef) || has(self.secretRef)", message="exactly one of spec.kubeConfig.configMapRef or spec.kubeConfig.secretRef must be specified" +kubebuilder:validation:XValidation:rule="!has(self.configMapRef) || !has(self.secretRef)", message="exactly one of spec.kubeConfig.configMapRef or spec.kubeConfig.secretRef must be specified"

func (*KubeConfigReference) DeepCopy added in v0.17.0

func (in *KubeConfigReference) DeepCopy() *KubeConfigReference

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new KubeConfigReference.

func (*KubeConfigReference) DeepCopyInto added in v0.17.0

func (in *KubeConfigReference) DeepCopyInto(out *KubeConfigReference)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type LocalObjectReference added in v0.7.0

type LocalObjectReference struct {
	// Name of the referent.
	// +required
	Name string `json:"name"`
}

LocalObjectReference contains enough information to locate the referenced Kubernetes resource object.

func (*LocalObjectReference) DeepCopy added in v0.8.0

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new LocalObjectReference.

func (*LocalObjectReference) DeepCopyInto added in v0.8.0

func (in *LocalObjectReference) DeepCopyInto(out *LocalObjectReference)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type NamespacedObjectKindReference added in v0.7.0

type NamespacedObjectKindReference struct {
	// API version of the referent, if not specified the Kubernetes preferred version will be used.
	// +optional
	APIVersion string `json:"apiVersion,omitempty"`

	// Kind of the referent.
	// +required
	Kind string `json:"kind"`

	// Name of the referent.
	// +required
	Name string `json:"name"`

	// Namespace of the referent, when not specified it acts as LocalObjectReference.
	// +optional
	Namespace string `json:"namespace,omitempty"`
}

NamespacedObjectKindReference contains enough information to locate the typed referenced Kubernetes resource object in any namespace.

func (*NamespacedObjectKindReference) DeepCopy added in v0.8.0

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new NamespacedObjectKindReference.

func (*NamespacedObjectKindReference) DeepCopyInto added in v0.8.0

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type NamespacedObjectReference added in v0.7.0

type NamespacedObjectReference struct {
	// Name of the referent.
	// +required
	Name string `json:"name"`

	// Namespace of the referent, when not specified it acts as LocalObjectReference.
	// +optional
	Namespace string `json:"namespace,omitempty"`
}

NamespacedObjectReference contains enough information to locate the referenced Kubernetes resource object in any namespace.

func (*NamespacedObjectReference) DeepCopy added in v0.8.0

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new NamespacedObjectReference.

func (*NamespacedObjectReference) DeepCopyInto added in v0.8.0

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (NamespacedObjectReference) String added in v1.16.0

func (in NamespacedObjectReference) String() string

String implements the fmt.Stringer interface for NamespacedObjectReference.

type ObjectWithAnnotationRequests added in v1.13.0

type ObjectWithAnnotationRequests interface {
	GetAnnotations() map[string]string
	StatusWithHandledReconcileRequest
}

ObjectWithAnnotationRequests is an interface that describes an object that has annotations and a status with a last handled reconcile request. +k8s:deepcopy-gen=false

type ObjectWithConditions added in v0.12.0

type ObjectWithConditions interface {
	// GetConditions returns a slice of metav1.Condition
	GetConditions() []metav1.Condition
}

ObjectWithConditions describes a Kubernetes resource object with status conditions. +k8s:deepcopy-gen=false

type ObjectWithConditionsSetter added in v0.12.0

type ObjectWithConditionsSetter interface {
	// SetConditions sets the status conditions on the object
	SetConditions([]metav1.Condition)
}

ObjectWithConditionsSetter describes a Kubernetes resource object with a status conditions setter. +k8s:deepcopy-gen=false

type ObjectWithDependencies added in v0.12.0

type ObjectWithDependencies interface {
	// GetDependsOn returns a NamespacedObjectReference list the object depends on.
	GetDependsOn() []NamespacedObjectReference
}

ObjectWithDependencies describes a Kubernetes resource object with dependencies. +k8s:deepcopy-gen=false

type ReconcileRequestStatus added in v0.1.0

type ReconcileRequestStatus struct {
	// LastHandledReconcileAt holds the value of the most recent
	// reconcile request value, so a change of the annotation value
	// can be detected.
	// +optional
	LastHandledReconcileAt string `json:"lastHandledReconcileAt,omitempty"`
}

ReconcileRequestStatus is a struct to embed in a status type, so that all types using the mechanism have the same field. Use it like this:

	type FooStatus struct {
 	meta.ReconcileRequestStatus `json:",inline"`
 	// other status fields...
	}

func (*ReconcileRequestStatus) DeepCopy added in v0.8.0

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ReconcileRequestStatus.

func (*ReconcileRequestStatus) DeepCopyInto added in v0.8.0

func (in *ReconcileRequestStatus) DeepCopyInto(out *ReconcileRequestStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (ReconcileRequestStatus) GetLastHandledReconcileRequest added in v0.1.0

func (in ReconcileRequestStatus) GetLastHandledReconcileRequest() string

GetLastHandledReconcileRequest returns the most recent reconcile request value from the ReconcileRequestStatus.

func (*ReconcileRequestStatus) SetLastHandledReconcileRequest added in v0.1.0

func (in *ReconcileRequestStatus) SetLastHandledReconcileRequest(token string)

SetLastHandledReconcileRequest sets the most recent reconcile request value in the ReconcileRequestStatus.

type SecretKeyReference added in v0.13.0

type SecretKeyReference struct {
	// Name of the Secret.
	// +required
	Name string `json:"name"`

	// Key in the Secret, when not specified an implementation-specific default key is used.
	// +optional
	Key string `json:"key,omitempty"`
}

SecretKeyReference contains enough information to locate the referenced Kubernetes Secret object in the same namespace. Optionally a key can be specified. Use this type instead of core/v1 SecretKeySelector when the Key is optional and the Optional field is not applicable.

func (*SecretKeyReference) DeepCopy added in v0.13.0

func (in *SecretKeyReference) DeepCopy() *SecretKeyReference

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new SecretKeyReference.

func (*SecretKeyReference) DeepCopyInto added in v0.13.0

func (in *SecretKeyReference) DeepCopyInto(out *SecretKeyReference)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type StatusWithHandledReconcileRequest added in v0.12.0

type StatusWithHandledReconcileRequest interface {
	GetLastHandledReconcileRequest() string
}

StatusWithHandledReconcileRequest describes a status type which holds the value of the most recent ReconcileAnnotationValue. +k8s:deepcopy-gen=false

type StatusWithHandledReconcileRequestSetter added in v0.12.0

type StatusWithHandledReconcileRequestSetter interface {
	SetLastHandledReconcileRequest(token string)
}

StatusWithHandledReconcileRequestSetter describes a status with a setter for the most ReconcileAnnotationValue. +k8s:deepcopy-gen=false

type ValuesReference added in v1.8.0

type ValuesReference struct {
	// Kind of the values referent, valid values are ('Secret', 'ConfigMap').
	// +kubebuilder:validation:Enum=Secret;ConfigMap
	// +required
	Kind string `json:"kind"`

	// Name of the values referent. Should reside in the same namespace as the
	// referring resource.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +required
	Name string `json:"name"`

	// ValuesKey is the data key where the values.yaml or a specific value can be
	// found at. Defaults to 'values.yaml'.
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:Pattern=`^[\-._a-zA-Z0-9]+$`
	// +optional
	ValuesKey string `json:"valuesKey,omitempty"`

	// TargetPath is the YAML dot notation path the value should be merged at. When
	// set, the ValuesKey is expected to be a single flat value. Defaults to 'None',
	// which results in the values getting merged at the root.
	// +kubebuilder:validation:MaxLength=250
	// +kubebuilder:validation:Pattern=`^([a-zA-Z0-9_\-.\\\/]|\[[0-9]{1,5}\])+$`
	// +optional
	TargetPath string `json:"targetPath,omitempty"`

	// Optional marks this ValuesReference as optional. When set, a not found error
	// for the values reference is ignored, but any ValuesKey, TargetPath or
	// transient error will still result in a reconciliation failure.
	// +optional
	Optional bool `json:"optional,omitempty"`
}

ValuesReference contains a reference to a resource containing Helm values, and optionally the key they can be found at.

func (*ValuesReference) DeepCopy added in v1.8.0

func (in *ValuesReference) DeepCopy() *ValuesReference

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ValuesReference.

func (*ValuesReference) DeepCopyInto added in v1.8.0

func (in *ValuesReference) DeepCopyInto(out *ValuesReference)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (ValuesReference) GetValuesKey added in v1.8.0

func (in ValuesReference) GetValuesKey() string

GetValuesKey returns the defined ValuesKey, or the default ('values.yaml').

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL