controller

package
v1.2.0 Latest Latest
Warning

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

Go to latest
Published: Jul 24, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source
const (
	AnnotationKeyDisplayName = "openchoreo.dev/display-name"
	AnnotationKeyDescription = "openchoreo.dev/description"

	// AnnotationKeyRestartedAt is set on a ReleaseBinding to trigger a rolling
	// restart of every Deployment deployed by the binding. The ReleaseBinding
	// controller propagates the annotation to the dataplane RenderedRelease,
	// and the rendered release controller sets the same annotation on each
	// Deployment's pod template at apply time. The value is opaque; any change
	// triggers a restart.
	AnnotationKeyRestartedAt = "openchoreo.dev/restartedAt"

	// SchemaExtensionComponentParameterRepositoryPrefix is the common prefix for all openAPIV3Schema
	// x- extension keys that mark component repository parameter fields (set to true on the property).
	// The suffix after the prefix is used as the role key in the map returned by ExtractComponentRepositoryPaths
	// (e.g. "url", "branch", "commit", "app-path", "secret-ref").
	SchemaExtensionComponentParameterRepositoryPrefix    = "x-openchoreo-component-parameter-repository-"
	SchemaExtensionComponentParameterRepositoryURL       = SchemaExtensionComponentParameterRepositoryPrefix + "url"
	SchemaExtensionComponentParameterRepositoryBranch    = SchemaExtensionComponentParameterRepositoryPrefix + "branch"
	SchemaExtensionComponentParameterRepositoryCommit    = SchemaExtensionComponentParameterRepositoryPrefix + "commit"
	SchemaExtensionComponentParameterRepositoryAppPath   = SchemaExtensionComponentParameterRepositoryPrefix + "app-path"
	SchemaExtensionComponentParameterRepositorySecretRef = SchemaExtensionComponentParameterRepositoryPrefix + "secret-ref"
)
View Source
const (
	TypeAccepted    = "Accepted"
	TypeProgressing = "Progressing"
	TypeAvailable   = "Available"
	TypeCreated     = "Created"
	TypeReady       = "Ready"
	TypeTerminating = "Terminating"
)

States for conditions

View Source
const (
	// IndexKeyReleaseBindingOwnerComponentName indexes ReleaseBinding by owner component name.
	IndexKeyReleaseBindingOwnerComponentName = "releasebinding.spec.owner.componentName"

	// IndexKeyReleaseBindingOwnerEnv indexes ReleaseBinding by the composite key
	// (projectName, componentName, environment) for efficient lookups.
	IndexKeyReleaseBindingOwnerEnv = "releasebinding.spec.owner.projectName/componentName/environment"

	// IndexKeyComponentOwnerProjectName indexes Component by owner project name.
	IndexKeyComponentOwnerProjectName = "component.spec.owner.projectName"

	// IndexKeyResourceOwnerProjectName indexes Resource by owner project name.
	IndexKeyResourceOwnerProjectName = "resource.spec.owner.projectName"

	// IndexKeyProjectDeploymentPipelineRef indexes Project by deploymentPipelineRef.
	IndexKeyProjectDeploymentPipelineRef = "project.spec.deploymentPipelineRef"

	// IndexKeyDeploymentPipelineEnvironmentRef indexes DeploymentPipeline by the environment names
	// referenced in its promotionPaths (both source and target environments).
	IndexKeyDeploymentPipelineEnvironmentRef = "deploymentpipeline.spec.promotionPaths.environmentRefs"

	// IndexKeyResourceReleaseOwnerResourceName indexes ResourceRelease by owner resource name.
	IndexKeyResourceReleaseOwnerResourceName = "resourcerelease.spec.owner.resourceName"

	// IndexKeyResourceReleaseBindingOwnerResourceName indexes ResourceReleaseBinding by owner resource name.
	IndexKeyResourceReleaseBindingOwnerResourceName = "resourcereleasebinding.spec.owner.resourceName"

	// IndexKeyResourceReleaseBindingOwnerEnv indexes ResourceReleaseBinding by the composite key
	// (projectName, resourceName, environment) so consumer ReleaseBindings can locate the
	// matching provider for a (project, ref, env) tuple in O(1).
	IndexKeyResourceReleaseBindingOwnerEnv = "resourcereleasebinding.spec.owner.projectName/resourceName/environment"

	// IndexKeyProjectReleaseBindingOwner indexes ProjectReleaseBinding by owner project name
	// so the Project controller can list all bindings of a project regardless of author
	// (labels are optional on externally authored bindings).
	IndexKeyProjectReleaseBindingOwner = "projectreleasebinding.spec.owner.projectName"
)

Shared field index keys for use across controllers. These constants ensure consistency when multiple controllers need to use the same field index.

View Source
const (
	// DefaultPlaneName is the default name for plane resources when no explicit reference is provided
	DefaultPlaneName = "default"
)
View Source
const (
	// StatusUpdateInterval is the interval at which controllers should refresh status fields
	// This is used for periodic status updates like agent connection status
	StatusUpdateInterval = 1 * time.Minute
)

Status update intervals

Variables

This section is empty.

Functions

func ExtractComponentRepositoryPaths added in v1.0.0

func ExtractComponentRepositoryPaths(schema *runtime.RawExtension) (map[string]string, error)

ExtractComponentRepositoryPaths scans an openAPIV3Schema RawExtension for boolean x-openchoreo-component-parameter-repository-* extension keys (e.g. "x-openchoreo-component-parameter-repository-url", "x-openchoreo-component-parameter-repository-branch", "-commit", "-app-path", "-secret-ref") and returns a map from the key suffix (e.g. "url", "branch", "commit", "app-path", "secret-ref") to the dotted property path of the annotated field within the parameters object (e.g. "repository.url", "repository.revision.branch").

func GetComponentName

func GetComponentName(obj client.Object) string

GetComponentName returns the component name that the object belongs to.

func GetDataPlaneByEnvironment added in v0.2.0

func GetDataPlaneByEnvironment(ctx context.Context, c client.Client, env *openchoreov1alpha1.Environment) (*openchoreov1alpha1.DataPlane, error)

GetDataPlaneByEnvironment retrieves the DataPlane object for the given Environment. It uses the DataPlaneRef field in the Environment to find the DataPlane object. Note: This function only returns DataPlane, not ClusterDataPlane. For environments referencing ClusterDataPlane, use GetDataPlaneFromRef from reference.go.

func GetDataPlaneName added in v0.2.0

func GetDataPlaneName(obj client.Object) string

GetDataPlaneName returns the data plane name that the object belongs to.

func GetDescription

func GetDescription(obj client.Object) string

GetDescription returns the description of the object.

func GetDisplayName

func GetDisplayName(obj client.Object) string

GetDisplayName returns the display name of the object.

func GetEnvironmentName

func GetEnvironmentName(obj client.Object) string

GetEnvironmentName returns the environment name that the object belongs to.

func GetName

func GetName(obj client.Object) string

GetName returns the name of the object. This is specific to the Choreo, and it is not the Kubernetes object name.

func GetNamespaceName added in v0.13.0

func GetNamespaceName(obj client.Object) string

GetNamespaceName returns the namespace name that the object belongs to.

func GetProjectName

func GetProjectName(obj client.Object) string

GetProjectName returns the project name that the object belongs to.

func HasPatchChanges added in v0.3.0

func HasPatchChanges(original, desired client.Object) (bool, []byte, error)

HasPatchChanges determines if two Kubernetes objects have differences by comparing their patch data.

func HierarchyWatchHandler

func HierarchyWatchHandler[From client.Object, To client.Object](
	c client.Client,
	hierarchyFunc HierarchyFunc[To],
) func(ctx context.Context, obj client.Object) []reconcile.Request

HierarchyWatchHandler is a function that creates a watch handler for a specific hierarchy. It can be used to watch from parent object for child object updates. The hierarchyFunc should return the target object that is being watched given the source object.

func IgnoreHierarchyNotFoundError

func IgnoreHierarchyNotFoundError(err error) error

IgnoreHierarchyNotFoundError returns nil if the given error is a HierarchyNotFoundError. This is useful during the reconciliation process to ignore the error if the parent object is not found and avoid retrying.

func IndexProjectReleaseBindingOwner added in v1.2.0

func IndexProjectReleaseBindingOwner(obj client.Object) []string

IndexProjectReleaseBindingOwner extracts the owner project name from a ProjectReleaseBinding. Exported for fake-client tests so they can register the same indexer the production setup uses.

func IndexResourceReleaseBindingOwner added in v1.1.0

func IndexResourceReleaseBindingOwner(obj client.Object) []string

IndexResourceReleaseBindingOwner extracts the owner resource name from a ResourceReleaseBinding. Exported for fake-client tests so they can register the same indexer the production setup uses.

func IndexResourceReleaseBindingOwnerEnv added in v1.1.0

func IndexResourceReleaseBindingOwnerEnv(obj client.Object) []string

IndexResourceReleaseBindingOwnerEnv extracts the composite (project, resource, environment) index key from a ResourceReleaseBinding. Exported for fake-client tests so they can register the same indexer the production setup uses.

func IndexResourceReleaseOwner added in v1.1.0

func IndexResourceReleaseOwner(obj client.Object) []string

IndexResourceReleaseOwner extracts the owner resource name from a ResourceRelease. Exported for fake-client tests so they can register the same indexer the production setup uses.

func MakeReleaseBindingOwnerEnvKey added in v0.17.0

func MakeReleaseBindingOwnerEnvKey(projectName, componentName, environment string) string

MakeReleaseBindingOwnerEnvKey creates the composite index key for ReleaseBinding lookups by (project, component, environment).

func MakeResourceReleaseBindingOwnerEnvKey added in v1.1.0

func MakeResourceReleaseBindingOwnerEnvKey(projectName, resourceName, environment string) string

MakeResourceReleaseBindingOwnerEnvKey creates the composite index key for ResourceReleaseBinding lookups by (project, resource, environment). Used by consumer ReleaseBindings to locate the matching provider for a (project, ref, env) tuple.

func MarkFalseCondition added in v0.3.0

func MarkFalseCondition(obj ConditionedObject, ct ConditionType, reason ConditionReason, message string) (changed bool)

func MarkTrueCondition added in v0.3.0

func MarkTrueCondition(obj ConditionedObject, ct ConditionType, reason ConditionReason, message string) (changed bool)

func MarkUnknownCondition added in v0.3.0

func MarkUnknownCondition(obj ConditionedObject, ct ConditionType, reason ConditionReason, message string) (changed bool)

func Merge added in v0.3.0

func Merge[T any](base, overlay *T) (*T, error)

Merge applies a strategic merge patch to the base object using the overlay object. This function uses Kubernetes strategic merge patch semantics to combine two objects of the same type.

Parameters:

  • base: the original object to merge into
  • overlay: the object containing changes to apply

Returns:

  • *T: the merged result object, or nil if either input is nil
  • error: any error that occurred during marshaling, patching, or unmarshaling

Example usage:

base := &v1.Pod{ObjectMeta: metav1.ObjectMeta{Name: "test"}}
overlay := &v1.Pod{Spec: v1.PodSpec{RestartPolicy: v1.RestartPolicyAlways}}
merged, err := controller.Merge(base, overlay)
if err != nil {
    return fmt.Errorf("failed to merge: %w", err)
}

func NeedConditionUpdate

func NeedConditionUpdate(currentConditions, updatedConditions []metav1.Condition) bool

NeedConditionUpdate checks if the conditions need to be updated based on the current and updated conditions.

func NewCondition

func NewCondition(conditionType ConditionType, status metav1.ConditionStatus, reason ConditionReason,
	message string, observedGeneration int64) metav1.Condition

NewCondition creates a new condition with the last transition time set to the current time.

func NewHierarchyNotFoundError

func NewHierarchyNotFoundError(obj client.Object, parentObj client.Object, parentHierarchyObjs ...client.Object) error

NewHierarchyNotFoundError creates a new error with the given object and parent object details. The parentObj is the immediate parent of the obj The parentHierarchyObjs are the hierarchy of objects from the parentObj to the top level object starting from the top level object. Example: NewHierarchyNotFoundError(deployment, deploymentTrack, namespace, project, component)

func SetupSharedIndexes added in v0.9.0

func SetupSharedIndexes(ctx context.Context, mgr ctrl.Manager) error

SetupSharedIndexes registers field indexes that are shared across multiple controllers. This must be called before any controllers are set up with the manager.

func UpdateCondition

func UpdateCondition(
	ctx context.Context,
	c client.StatusWriter,
	resource client.Object,
	conditions *[]metav1.Condition,
	conditionType string,
	status metav1.ConditionStatus,
	reason, message string,
) error

UpdateCondition updates or adds a condition to any resource that has a Status with Conditions

func UpdateStatusConditions

func UpdateStatusConditions[T ConditionedObject](
	ctx context.Context,
	c client.Client,
	current, updated T,
) error

UpdateStatusConditions will compare the current and updated conditions and update the status conditions if needed.

func UpdateStatusConditionsAndRequeue

func UpdateStatusConditionsAndRequeue[T ConditionedObject](
	ctx context.Context, c client.Client, current, updated T,
) (ctrl.Result, error)

UpdateStatusConditionsAndRequeue updates status conditions and requests a requeue. This indicates that the controller should requeue the request for further processing. It returns an error if the status update fails.

func UpdateStatusConditionsAndRequeueAfter

func UpdateStatusConditionsAndRequeueAfter[T ConditionedObject](
	ctx context.Context, c client.Client, current, updated T, duration time.Duration,
) (ctrl.Result, error)

UpdateStatusConditionsAndRequeueAfter updates status conditions and requeues after the specified duration. It returns an error if the status update fails.

func UpdateStatusConditionsAndReturn

func UpdateStatusConditionsAndReturn[T ConditionedObject](
	ctx context.Context, c client.Client, current, updated T,
) (ctrl.Result, error)

UpdateStatusConditionsAndReturn updates status conditions without requeuing. It returns an error if the update fails.

func UpdateStatusConditionsAndReturnError

func UpdateStatusConditionsAndReturnError[T ConditionedObject](
	ctx context.Context, c client.Client, current, updated T, err error,
) (ctrl.Result, error)

UpdateStatusConditionsAndReturnError updates status conditions and returns the given error. It returns an update error if the conditions update fails. It prioritizes the status update error over the provided error, if any.

func UpdateStatusConditionsWithPatch

func UpdateStatusConditionsWithPatch[T ConditionedObject](
	ctx context.Context,
	c client.Client,
	current, updated T,
) error

UpdateStatusConditionsWithPatch updates status conditions using a patch operation with retry on conflicts. This is more robust for handling concurrent updates to the same resource.

Types

type ConditionReason

type ConditionReason string

ConditionReason represents the machine-readable reason for a condition's status. Use CamelCase format (e.g., MinimumReplicasUnavailable, MinimumReplicasMet).

type ConditionType

type ConditionType string

ConditionType represents the type of condition describing a specific state of the resource. Use CamelCase format (e.g., Ready, Available).

func (ConditionType) String

func (c ConditionType) String() string

String returns the string representation of the condition type.

type ConditionedObject

type ConditionedObject interface {
	client.Object

	GetConditions() []metav1.Condition
	SetConditions(conditions []metav1.Condition)
}

ConditionedObject describes a Kubernetes resource that has a mutable Conditions field in its Status

type DataPlaneResult added in v0.15.0

type DataPlaneResult struct {
	DataPlane        *openchoreov1alpha1.DataPlane
	ClusterDataPlane *openchoreov1alpha1.ClusterDataPlane
}

DataPlaneResult contains either a DataPlane or ClusterDataPlane

func GetDataPlaneFromRef added in v1.1.0

func GetDataPlaneFromRef(
	ctx context.Context,
	c client.Client,
	namespace string,
	ref *openchoreov1alpha1.DataPlaneRef,
) (*DataPlaneResult, error)

GetDataPlaneFromRef resolves a DataPlane or ClusterDataPlane from a ref. The namespace parameter is the namespace of the referrer (the resource holding the ref). If namespace is empty, only cluster-scoped resources are considered (cluster-scoped referrer).

When ref is nil, the function applies a default resolution strategy:

  • Namespace-scoped referrer (namespace != ""): tries DataPlane "default" in the namespace, then falls back to ClusterDataPlane "default".
  • Cluster-scoped referrer (namespace == ""): tries ClusterDataPlane "default" only.

When ref is set, it fetches exactly what the ref specifies based on Kind.

func (*DataPlaneResult) GetK8sClient added in v1.1.0

GetK8sClient returns a Kubernetes client for this data plane result. It dispatches to the correct client constructor based on whether this is a DataPlane or ClusterDataPlane.

func (*DataPlaneResult) GetName added in v0.15.0

func (r *DataPlaneResult) GetName() string

GetName returns the name of the data plane (either DataPlane or ClusterDataPlane)

func (*DataPlaneResult) GetNamespace added in v0.15.0

func (r *DataPlaneResult) GetNamespace() string

GetNamespace returns the namespace (empty for ClusterDataPlane)

func (*DataPlaneResult) GetObservabilityPlane added in v0.15.0

func (r *DataPlaneResult) GetObservabilityPlane(ctx context.Context, c client.Client) (*ObservabilityPlaneResult, error)

GetObservabilityPlane resolves the observability plane for this data plane result.

func (*DataPlaneResult) ToDataPlane added in v0.15.0

func (r *DataPlaneResult) ToDataPlane() *openchoreov1alpha1.DataPlane

ToDataPlane returns a *DataPlane - either the real one or a facade built from ClusterDataPlane. This allows downstream code (e.g. rendering pipeline) to remain unchanged.

type HierarchyFunc

type HierarchyFunc[T any] func(ctx context.Context, c client.Client, obj client.Object) (T, error)

HierarchyFunc is a generic function type that takes a context, client, and object as input and returns an object of type T and an error. This is used for MakeHierarchyWatchHandler to define the function that will be called to get the target object.

type HierarchyNotFoundError

type HierarchyNotFoundError struct {
	// contains filtered or unexported fields
}

HierarchyNotFoundError is an error type that is used to indicate that a parent object in the hierarchy is not found.

func (*HierarchyNotFoundError) Error

func (e *HierarchyNotFoundError) Error() string

type ObservabilityPlaneResult added in v0.15.0

type ObservabilityPlaneResult struct {
	ObservabilityPlane        *openchoreov1alpha1.ObservabilityPlane
	ClusterObservabilityPlane *openchoreov1alpha1.ClusterObservabilityPlane
}

ObservabilityPlaneResult contains either an ObservabilityPlane or ClusterObservabilityPlane

func GetObservabilityPlaneFromRef added in v1.1.0

func GetObservabilityPlaneFromRef(
	ctx context.Context,
	c client.Client,
	namespace string,
	ref *openchoreov1alpha1.ObservabilityPlaneRef,
) (*ObservabilityPlaneResult, error)

GetObservabilityPlaneFromRef resolves an ObservabilityPlane or ClusterObservabilityPlane from a ref. The namespace parameter is the namespace of the referrer (the resource holding the ref). If namespace is empty, only cluster-scoped resources are considered (cluster-scoped referrer).

When ref is nil, the function applies a default resolution strategy:

  • Namespace-scoped referrer (namespace != ""): tries ObservabilityPlane "default" in the namespace, then falls back to ClusterObservabilityPlane "default".
  • Cluster-scoped referrer (namespace == ""): tries ClusterObservabilityPlane "default" only.

When ref is set, it fetches exactly what the ref specifies based on Kind.

func (*ObservabilityPlaneResult) GetK8sClient added in v1.1.0

GetK8sClient returns a Kubernetes client for this observability plane result. It dispatches to the correct client constructor based on whether this is an ObservabilityPlane or ClusterObservabilityPlane.

func (*ObservabilityPlaneResult) GetName added in v0.15.0

func (r *ObservabilityPlaneResult) GetName() string

GetName returns the name of the observability plane

func (*ObservabilityPlaneResult) GetNamespace added in v0.15.0

func (r *ObservabilityPlaneResult) GetNamespace() string

GetNamespace returns the namespace (empty for ClusterObservabilityPlane)

func (*ObservabilityPlaneResult) GetObserverURL added in v0.15.0

func (r *ObservabilityPlaneResult) GetObserverURL() string

GetObserverURL returns the observer URL from either ObservabilityPlane or ClusterObservabilityPlane

func (*ObservabilityPlaneResult) GetPlaneID added in v0.15.0

func (r *ObservabilityPlaneResult) GetPlaneID() string

GetPlaneID returns the plane ID from either ObservabilityPlane or ClusterObservabilityPlane

type WorkflowPlaneResult added in v1.0.0

type WorkflowPlaneResult struct {
	WorkflowPlane        *openchoreov1alpha1.WorkflowPlane
	ClusterWorkflowPlane *openchoreov1alpha1.ClusterWorkflowPlane
}

WorkflowPlaneResult contains either a WorkflowPlane or ClusterWorkflowPlane

func GetWorkflowPlaneFromRef added in v1.1.0

func GetWorkflowPlaneFromRef(
	ctx context.Context,
	c client.Client,
	namespace string,
	ref *openchoreov1alpha1.WorkflowPlaneRef,
) (*WorkflowPlaneResult, error)

GetWorkflowPlaneFromRef resolves a WorkflowPlane or ClusterWorkflowPlane from a ref. The namespace parameter is the namespace of the referrer (the resource holding the ref). If namespace is empty, only cluster-scoped resources are considered (cluster-scoped referrer).

When ref is nil, the function applies a default resolution strategy:

  • Namespace-scoped referrer (namespace != ""): tries WorkflowPlane "default" in the namespace, then falls back to ClusterWorkflowPlane "default".
  • Cluster-scoped referrer (namespace == ""): tries ClusterWorkflowPlane "default" only.

When ref is set, it fetches exactly what the ref specifies based on Kind.

func (*WorkflowPlaneResult) GetK8sClient added in v1.0.0

GetK8sClient returns a Kubernetes client for this workflow plane result. It dispatches to the correct client constructor based on whether this is a WorkflowPlane or ClusterWorkflowPlane.

func (*WorkflowPlaneResult) GetName added in v1.0.0

func (r *WorkflowPlaneResult) GetName() string

GetName returns the name of the workflow plane (either WorkflowPlane or ClusterWorkflowPlane)

func (*WorkflowPlaneResult) GetNamespace added in v1.0.0

func (r *WorkflowPlaneResult) GetNamespace() string

GetNamespace returns the namespace (empty for ClusterWorkflowPlane)

func (*WorkflowPlaneResult) GetObservabilityPlane added in v1.0.0

func (r *WorkflowPlaneResult) GetObservabilityPlane(ctx context.Context, c client.Client) (*ObservabilityPlaneResult, error)

GetObservabilityPlane resolves the observability plane for this workflow plane result.

func (*WorkflowPlaneResult) GetSecretStoreName added in v1.0.0

func (r *WorkflowPlaneResult) GetSecretStoreName() string

GetSecretStoreName returns the secret store name from the workflow plane (either WorkflowPlane or ClusterWorkflowPlane). Returns empty string if no secret store ref is configured.

type WorkflowResult added in v1.0.0

type WorkflowResult struct {
	Workflow        *openchoreov1alpha1.Workflow
	ClusterWorkflow *openchoreov1alpha1.ClusterWorkflow
}

WorkflowResult contains either a Workflow or ClusterWorkflow

func ResolveWorkflow added in v1.0.0

func ResolveWorkflow(ctx context.Context, c client.Client, namespace string, kind openchoreov1alpha1.WorkflowRefKind, name string) (*WorkflowResult, error)

ResolveWorkflow resolves a Workflow or ClusterWorkflow by kind and name.

func (*WorkflowResult) GetName added in v1.0.0

func (r *WorkflowResult) GetName() string

GetName returns the name of the workflow

func (*WorkflowResult) GetNamespace added in v1.0.0

func (r *WorkflowResult) GetNamespace() string

GetNamespace returns the namespace (empty for ClusterWorkflow)

func (*WorkflowResult) GetWorkflowSpec added in v1.0.0

func (r *WorkflowResult) GetWorkflowSpec() openchoreov1alpha1.WorkflowSpec

GetWorkflowSpec converts the resolved workflow (either kind) to a unified WorkflowSpec. For ClusterWorkflow, ClusterWorkflowPlaneRef is mapped to WorkflowPlaneRef with kind ClusterWorkflowPlane. When ClusterWorkflow omits WorkflowPlaneRef, it defaults to ClusterWorkflowPlane "default" so that downstream resolution never falls back to a namespace-scoped WorkflowPlane.

Jump to

Keyboard shortcuts

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