interfaces

Documentation

Index

• type APIObjectAdapter
• type BaseResourceActuator
• type Controller
• type CreateResourceActuator
• type DeleteResourceActuator
• type ORCApplyConfig
• type ORCStatusApplyConfig
• type ReconcileResourceActuator
• type ResourceController
• type ResourceHelperFactory
• type ResourceReconciler
• type ResourceStatusWriter

Types

type APIObjectAdapter

type APIObjectAdapter[orcObjectPT any, resourceSpecT any, filterT any] interface {
	// NOTE: the objects we generate which implement this interface all also
	// implement client.Object. Despite this, they fail at runtime when passed
	// to the controller-runtime client. Therefore we deliberately don't declare
	// this interface here to prevent accidental usage.
	metav1.Object

	GetObject() orcObjectPT

	GetManagementPolicy() orcv1alpha1.ManagementPolicy
	GetManagedOptions() *orcv1alpha1.ManagedOptions

	GetStatusID() *string
	GetResourceSpec() *resourceSpecT
	GetImportID() *string
	GetImportFilter() *filterT
}

type BaseResourceActuator

type BaseResourceActuator[
	orcObjectPT interface {
		*orcObjectT
		client.Object
		orcv1alpha1.ObjectWithConditions
	}, orcObjectT any,
	osResourceT any,
] interface {
	// GetResourceID returns a string identifier for the OpenStack resource
	// managed by this actuator, typically the object's uuid. This is the value
	// stored in status.id.
	GetResourceID(osResource *osResourceT) string

	// GetOSResourceByID fetches this actuator's OpenStack resource by id.
	GetOSResourceByID(ctx context.Context, id string) (*osResourceT, progress.ReconcileStatus)

	// ListOSResourcesForAdoption is used to prevent resource leaks in the event
	// that we create an OpenStack resource, but fail to write its ID to the
	// object's status. It returns a set of resources which match what the
	// actuator would have created for this object. Ideally it should attempt to
	// do this match as accurately as possible, remembering that OpenStack does
	// not prevent the creation of objects with duplicate names.
	//
	// It is called in the creation flow immediately before creating a resource,
	// and in the deletion flow when deleting an object which has a finalizer
	// but no status.id.
	//
	// It returns 2 values:
	// - an iterator over the matching OpenStack resources
	// - a boolean indicating whether adoption should be considered for this object
	//
	// For example, we must return false for an object with no resource spec.
	ListOSResourcesForAdoption(ctx context.Context, orcObject orcObjectPT) (iter.Seq2[*osResourceT, error], bool)
}

type Controller

type Controller interface {
	SetupWithManager(context.Context, ctrl.Manager, controller.Options) error
	GetName() string
}

type CreateResourceActuator

type CreateResourceActuator[
	orcObjectPT interface {
		*orcObjectT
		client.Object
		orcv1alpha1.ObjectWithConditions
	}, orcObjectT any,
	filterT any,
	osResourceT any,
] interface {
	BaseResourceActuator[orcObjectPT, orcObjectT, osResourceT]

	// ListOSResourcesForImport returns all OpenStack resources matching the
	// given resource import filter.
	ListOSResourcesForImport(ctx context.Context, orcObject orcObjectPT, filter filterT) (iter.Seq2[*osResourceT, error], progress.ReconcileStatus)

	// CreateResource creates an OpenStack resource for the current object. It
	// will return successfully at most once for a managed object, at the time
	// it is created. See `ResourceReconciler` for how to modify an existing
	// object.
	//
	// CreateResource MUST NOT perform any action which can fail after creating
	// the primary OpenStack resource. Once the OpenStack resource exists this
	// method will not be called again, so any failure after creation of the
	// OpenStack resource is not safe.
	//
	// If further initialisation of a resource is required after creation, for
	// example a Neutron object whose tags cannot be set during creation, this
	// must be done by a reconciler instead.
	//
	// CreateResource MAY also perform other actions prior to creating the
	// primary OpenStack resource, e.g. creating dependent ORC objects. These
	// must be created idempotently, and must be created BEFORE creating the
	// OpenStack resource.
	//
	// CreateResource does not need to check if the resource already exists, as
	// that is done before it is called.
	//
	// If CreateResource cannot create the resource it MUST return either one or
	// more ProgressStatuses, or an error. If returning ProgressStatuses, these
	// MUST be sufficient to ensure that the object will be reconciled again at
	// an appropriate time.
	CreateResource(ctx context.Context, orcObject orcObjectPT) (*osResourceT, progress.ReconcileStatus)
}

CreateResourceActuator provides methods required by the generic controller during the create and update flows.

type DeleteResourceActuator

type DeleteResourceActuator[
	orcObjectPT interface {
		*orcObjectT
		client.Object
		orcv1alpha1.ObjectWithConditions
	}, orcObjectT any,
	osResourceT any,
] interface {
	BaseResourceActuator[orcObjectPT, orcObjectT, osResourceT]

	// DeleteResource deletes the OpenStack resource owned by the current
	// object.
	//
	// The delete flow does not succeed until an attempt to get the resource
	// returns no results, so DeleteResource does not need to verify that
	// deletion has completed.
	//
	// DeleteResource SHOULD NOT return an error if the resource no longer exists.
	//
	// DeleteResource MAY also perform other actions prior to deleting the
	// OpenStack resource, e.g. deleting dependent ORC objects. These actions
	// must be performed idempotently, and must be performed BEFORE deleting the
	// OpenStack resource.
	//
	// If DeleteResource cannot delete the resource it MUST return either one or
	// more ProgressStatuses, or an error. If returning ProgressStatuses, these
	// MUST be sufficient to ensure that the objet will be reconciled again at
	// an appropriate time.
	DeleteResource(ctx context.Context, orcObject orcObjectPT, osResource *osResourceT) progress.ReconcileStatus
}

DeleteResourceActuator provides methods required by the generic controller during the delete flow.

type ORCApplyConfig

type ORCApplyConfig[objectApplyPT any, statusApplyPT ORCStatusApplyConfig[statusApplyPT]] interface {
	WithUID(types.UID) objectApplyPT
	WithStatus(statusApplyPT) objectApplyPT
}

ORCApplyConfig is an interface implemented by any apply configuration for an ORC API object. Specifically its WithStatus method is constrained to return an ORCStatusApplyConfig.

type ORCStatusApplyConfig

type ORCStatusApplyConfig[statusApplyPT any] interface {
	WithConditions(...*applyconfigv1.ConditionApplyConfiguration) statusApplyPT
	WithID(id string) statusApplyPT
}

ORCStatusApplyConfig is an interface implemented by the status of any apply configuration for an ORC API object. It has Conditions and an ID field.

type ReconcileResourceActuator

type ReconcileResourceActuator[orcObjectPT, osResourceT any] interface {
	// GetResourceReconcilers returns zero or more ResourceReconcilers to be executed during the current reconcile.
	//
	// All ResourceReconcilers returned will be executed in the order returned.
	// They will all be passed the orcObject and osResource passed to
	// GetResourceReconcilers. Note therefore that any state changes performed
	// by earlier ResourceReconcilers may not be reflected in the objects passed
	// to later ones.
	//
	// Failure of a ResourceReconciler does not prevent execution of later
	// ResourceReconcilers. All ResourceReconcilers will be executed, and their
	// ProgressStatuses and errors aggregated.
	//
	// NOTE: Contrary to the typical Go idiom, GetResourceReconcilers may return
	// both valid results, and an error. In this case, all returned
	// ResourceReconcilers will still be executed. The error returned by
	// GetResourceReconcilers itself will be aggregated with those returned by
	// the ResourceReconcilers. An example situation in which
	// GetResourceReconcilers itself might fail is if it fetched a list of
	// objects and returned a separate ResourceReconciler for each of them.
	GetResourceReconcilers(ctx context.Context, orcObject orcObjectPT, osResource *osResourceT, controller ResourceController) ([]ResourceReconciler[orcObjectPT, osResourceT], progress.ReconcileStatus)
}

type ResourceController

type ResourceController interface {
	GetName() string

	GetK8sClient() client.Client
	GetScopeFactory() scope.Factory
}

type ResourceHelperFactory

type ResourceHelperFactory[
	orcObjectPT interface {
		*orcObjectT
		client.Object
		orcv1alpha1.ObjectWithConditions
	}, orcObjectT any,
	resourceSpecT any, filterT any,
	osResourceT any,
] interface {
	// NewAPIObjectAdapter returns an APIObjectAdapter wrapping orcObject
	NewAPIObjectAdapter(orcObject orcObjectPT) APIObjectAdapter[orcObjectPT, resourceSpecT, filterT]

	// NewCreateActuator returns a CreateResourceActuator for the given
	// orcObject. If it is not able to return an actuator, it MUST return either
	// one or more ProgressStatuses, or an error. If returning ProgressStatuses,
	// these MUST ensure that the object will be reconciled again at an
	// appropriate time.
	NewCreateActuator(ctx context.Context, orcObject orcObjectPT, controller ResourceController) (CreateResourceActuator[orcObjectPT, orcObjectT, filterT, osResourceT], progress.ReconcileStatus)

	// NewDeleteActuator returns a DeleteResourceActuator for the given
	// orcObject. If it is not able to return an actuator, it MUST return either
	// one or more ProgressStatuses, or an error. If returning ProgressStatuses,
	// these MUST ensure that the object will be reconciled again at an
	// appropriate time.
	//
	// Consider carefully whether a DeleteResourceActuator needs all the same
	// initialisation dependencies as a CreateResourceActuator. Consider that we
	// may want to delete a resource that is partially or not initialised, or
	// whose creation dependencies may no longer be in a healthy state.
	NewDeleteActuator(ctx context.Context, orcObject orcObjectPT, controller ResourceController) (DeleteResourceActuator[orcObjectPT, orcObjectT, osResourceT], progress.ReconcileStatus)
}

ResourceHelperFactory is an interface defining constructors for objects required by the generic controller.

type ResourceReconciler

type ResourceReconciler[orcObjectPT, osResourceT any] func(ctx context.Context, orcObject orcObjectPT, osResource *osResourceT) progress.ReconcileStatus

ResourceReconciler is a function which reconciles an object after creation.

ResourceReconcilers are called on every non-delete reconciliation when the resource exists, including the reconciliation which created the resource.

A ResourceReconciler may return one or more ProgressStatuses, and/or an error. Both errors and ProgressStatuses returned by ResourceReconcilers are aggregated before being passed to the ResourceStatusWriter.

In addition to informing the Progressing condition in the object's status, a ProgressStatus returned by a ResourceReconciler may be used to cause the controller to poll, for example because the resource has not yet reached an ACTIVE status.

type ResourceStatusWriter

type ResourceStatusWriter[objectPT orcv1alpha1.ObjectWithConditions, osResourcePT any, objectApplyPT ORCApplyConfig[objectApplyPT, statusApplyPT], statusApplyPT ORCStatusApplyConfig[statusApplyPT]] interface {
	// GetApplyConfig returns an ORCApplyConfig for this object for use in an
	// SSA transaction, initialised with a name and a namespace.
	GetApplyConfig(name, namespace string) objectApplyPT

	// ResourceAvailableStatus returns what the status of the Available
	// condition should be set to based on the observed state of the given
	// orcObject and osResource.
	ResourceAvailableStatus(orcObject objectPT, osResource osResourcePT) (metav1.ConditionStatus, progress.ReconcileStatus)

	// ApplyResourceStatus writes status.resource to the given status apply
	// configuration based on the given osResource
	ApplyResourceStatus(log logr.Logger, osResource osResourcePT, statusApply statusApplyPT)
}

ResourceStatusWriter defines methods for writing an ORC object status