types

Documentation

Index

• type AWSResource
• type AWSResourceDescriptor
• type AWSResourceIdentifiers
• type AWSResourceManager
• type AWSResourceManagerFactory
• type AWSResourceReconciler
• type Reconciler
• type RuntimeMetaObject
• type ServiceController

Types

type AWSResource

type AWSResource interface {
	// Identifiers returns an AWSResourceIdentifiers object containing various
	// identifying information, including the AWS account ID that owns the
	// resource, the resource's AWS Resource Name (ARN)
	Identifiers() AWSResourceIdentifiers
	// Conditions returns the ACK Conditions collection for the AWSResource
	Conditions() []*ackv1alpha1.Condition
	// IsBeingDeleted returns true if the Kubernetes resource has a non-zero
	// deletion timestamp
	IsBeingDeleted() bool
	// RuntimeObject returns the Kubernetes apimachinery/runtime representation
	// of the AWSResource
	RuntimeObject() k8srt.Object
	// MetaObject returns the Kubernetes apimachinery/apis/meta/v1.Object
	// representation of the AWSResource
	MetaObject() metav1.Object
	// RuntimeMetaObject returns an object that implements both the Kubernetes
	// apimachinery/runtime.Object and the Kubernetes
	// apimachinery/apis/meta/v1.Object interfaces
	RuntimeMetaObject() RuntimeMetaObject
	// SetObjectMeta sets the ObjectMeta field for the resource
	SetObjectMeta(meta metav1.ObjectMeta)
	// SetIdentifiers will set the the Spec or Status field that represents the
	// identifier for the resource.
	SetIdentifiers(*ackv1alpha1.AWSIdentifiers) error
}

AWSResource represents a custom resource object in the Kubernetes API that corresponds to a resource in an AWS service API.

type AWSResourceDescriptor

type AWSResourceDescriptor interface {
	// GroupKind returns a Kubernetes metav1.GroupKind struct that describes
	// the API Group and Kind of CRs described by the descriptor
	GroupKind() *metav1.GroupKind
	// EmptyRuntimeObject returns an empty object prototype that may be used in
	// apimachinery and k8s client operations
	EmptyRuntimeObject() k8srt.Object
	// ResourceFromRuntimeObject returns an AWSResource that has been
	// initialized with the supplied runtime.Object
	ResourceFromRuntimeObject(k8srt.Object) AWSResource
	// Delta returns an `ackcompare.Delta` object containing the difference between
	// one `AWSResource` and another.
	Delta(a, b AWSResource) *ackcompare.Delta
	// UpdateCRStatus accepts an AWSResource object and changes the Status
	// sub-object of the AWSResource's Kubernetes custom resource (CR) and
	// returns whether any changes were made
	UpdateCRStatus(AWSResource) (bool, error)
	// IsManaged returns true if the supplied AWSResource is under the
	// management of an ACK service controller. What this means in practice is
	// that the underlying custom resource (CR) in the AWSResource has had a
	// resource-specific finalizer associated with it.
	IsManaged(AWSResource) bool
	// MarkManaged places the supplied resource under the management of ACK.
	// What this typically means is that the resource manager will decorate the
	// underlying custom resource (CR) with a finalizer that indicates ACK is
	// managing the resource and the underlying CR may not be deleted until ACK
	// is finished cleaning up any backend AWS service resources associated
	// with the CR.
	MarkManaged(AWSResource)
	// MarkUnmanaged removes the supplied resource from management by ACK.
	// What this typically means is that the resource manager will remove a
	// finalizer underlying custom resource (CR) that indicates ACK is managing
	// the resource. This will allow the Kubernetes API server to delete the
	// underlying CR.
	MarkUnmanaged(AWSResource)
	// MarkAdopted places descriptors on the custom resource that indicate the
	// resource was not created from within ACK.
	MarkAdopted(AWSResource)
}

AWSResourceDescriptor provides metadata that describes the Kubernetes metadata associated with an AWSResource, the Kubernetes runtime.Object prototype for that AWSResource, and the relationships between the AWSResource and other AWSResources

type AWSResourceIdentifiers

type AWSResourceIdentifiers interface {
	// OwnerAccountID returns the AWS account identifier in which the
	// backend AWS resource resides, or should reside in.
	OwnerAccountID() *ackv1alpha1.AWSAccountID
	// ARN returns the AWS Resource Name for the backend AWS resource. If nil,
	// this means the resource has not yet been created in the backend AWS
	// service.
	ARN() *ackv1alpha1.AWSResourceName
}

AWSResourceIdentifiers has methods that returns common identifying information about a resource

type AWSResourceManager

type AWSResourceManager interface {
	// ReadOne returns the currently-observed state of the supplied AWSResource
	// in the backend AWS service API.
	//
	// Implementers should return (nil, ackerrors.NotFound) when the backend
	// AWS service API cannot find the resource identified by the supplied
	// AWSResource's AWS identifier information.
	ReadOne(context.Context, AWSResource) (AWSResource, error)
	// Create attempts to create the supplied AWSResource in the backend AWS
	// service API, returning an AWSResource representing the newly-created
	// resource
	Create(context.Context, AWSResource) (AWSResource, error)
	// Update attempts to mutate the supplied desired AWSResource in the
	// backend AWS service API, returning an AWSResource representing the
	// newly-mutated resource.
	// Note for specialized logic implementers can check to see how the latest
	// observed resource differs from the supplied desired state. The
	// higher-level reconciler determines whether or not the desired differs
	// from the latest observed and decides whether to call the resource
	// manager's Update method
	Update(
		context.Context,
		AWSResource,
		AWSResource,
		*ackcompare.Delta,
	) (AWSResource, error)

	// Delete attempts to destroy the supplied AWSResource in the backend AWS
	// service API.
	Delete(context.Context, AWSResource) error
	// ARNFromName returns an AWS Resource Name from a given string name. This
	// is useful for constructing ARNs for APIs that require ARNs in their
	// GetAttributes operations but all we have (for new CRs at least) is a
	// name for the resource
	ARNFromName(string) string
}

AWSResourceManager is responsible for providing a consistent way to perform CRUD+L operations in a backend AWS service API for Kubernetes custom resources (CR) corresponding to those AWS service API resources.

Use an AWSResourceManagerFactory to create an AWSResourceManager for a particular APIResource and AWS account.

type AWSResourceManagerFactory

type AWSResourceManagerFactory interface {
	// ResourceDescriptor returns an AWSResourceDescriptor that can be used by
	// the upstream controller-runtime to introspect the CRs that the resource
	// manager will manage as well as produce Kubernetes runtime object
	// prototypes
	ResourceDescriptor() AWSResourceDescriptor
	// ManagerFor returns an AWSResourceManager that manages AWS resources on
	// behalf of a particular AWS account and in a specific AWS region
	ManagerFor(
		ackcfg.Config,
		logr.Logger,
		*ackmetrics.Metrics,
		Reconciler,
		*session.Session,
		ackv1alpha1.AWSAccountID,
		ackv1alpha1.AWSRegion,
	) (AWSResourceManager, error)
	// IsAdoptable returns true if the resource is able to be adopted
	IsAdoptable() bool
}

AWSResourceManagerFactory returns an AWSResourceManager that can be used to manage AWS resources for a particular AWS account

type AWSResourceReconciler

type AWSResourceReconciler interface {
	Reconciler
	// GroupKind returns the
	// sigs.k8s.io/apimachinery/pkg/apis/meta/v1.GroupKind containing the API
	// group and kind reconciled by this reconciler
	GroupKind() *metav1.GroupKind
	// Sync ensures that the supplied AWSResource's backing API resource
	// matches the supplied desired state.
	//
	// NOTE(jaypipes): This is really only here for dependency injection
	// purposes in unit testing in order to simplify test setups.
	Sync(
		context.Context,
		AWSResourceManager,
		AWSResource,
	) error
}

AWSResourceReconciler is responsible for reconciling the state of a SINGLE KIND of Kubernetes custom resources (CRs) that represent AWS service API resources. It implements the upstream controller-runtime `Reconciler` interface.

The upstream controller-runtime.Manager object ends up managing MULTIPLE controller-runtime.Controller objects (each containing a single AWSResourceReconciler object)s and sharing watch and informer queues across those controllers.

type Reconciler

type Reconciler interface {
	ctrlreconcile.Reconciler
	// BindControllerManager sets up the AWSResourceReconciler with an instance
	// of an upstream controller-runtime.Manager
	BindControllerManager(ctrlrt.Manager) error
	// SecretValueFromReference fetches the value of a Secret given a
	// SecretKeyReference
	SecretValueFromReference(context.Context, *v1alpha1.SecretKeyReference) (string, error)
}

Reconciler is responsible for reconciling the state of any single custom resource within the cluster.

The upstream controller-runtime.Manager object ends up managing MULTIPLE controller-runtime.Controller objects (each containing a single Reconciler object)s and sharing watch and informer queues across those controllers.

type RuntimeMetaObject

type RuntimeMetaObject interface {
	metav1.Object
	k8srt.Object
}

RuntimeMetaObject contains both the Kubernetes apimachinery/runtime.Object and apimachinery/apis/meta/v1.Object interfaces

NOTE(jaypipes): This really belongs as an upstream apimachinery type

type ServiceController

type ServiceController interface {
	// GetReconcilers returns a slice of types.AWSResourceReconcilers
	// associated with this service controller
	GetReconcilers() []AWSResourceReconciler
	// GetResourceManagerFactories returns the map of resource manager
	// factories, keyed by the GroupKind of the resource managed by the resource
	// manager produced by that factory
	GetResourceManagerFactories() map[string]AWSResourceManagerFactory

	// WithLogger sets up the service controller with the supplied logger
	WithLogger(logr.Logger) ServiceController
	// WithPrometheusRegistry registers all ACK service controller metrics with
	// the supplied prometheus Registry
	WithPrometheusRegistry(prometheus.Registerer) ServiceController
	// WithResourceManagerFactories sets the controller up to manage resources
	// with a set of supplied factories
	WithResourceManagerFactories(
		[]AWSResourceManagerFactory,
	) ServiceController

	// BindControllerManager takes a `controller-runtime.Manager`, creates all
	// the AWSResourceReconcilers needed for the service and binds all of the
	// reconcilers within the service controller with that manager
	BindControllerManager(
		ctrlrt.Manager,
		ackcfg.Config,
	) error

	// NewSession returns a new session object. By default the returned session
	// is created using pod IRSA environment variables. If assumeRoleARN is not
	// empty, NewSession will call STS::AssumeRole and use the returned
	// credentials to create the session.
	NewSession(
		ackv1alpha1.AWSRegion,
		*string,
		ackv1alpha1.AWSResourceName,
		schema.GroupVersionKind,
	) (*session.Session, error)
}

ServiceController wraps one or more reconcilers (for individual resources in an AWS API) with the upstream common controller-runtime machinery.