types

Documentation

Index

• type AWSResource
• type AWSResourceDescriptor
• type AWSResourceIdentifiers
• type AWSResourceManager
• type AWSResourceManagerFactory
• type AWSResourceReconciler
• type AdoptedResourceReconciler
• type ConditionManager
• type FieldExportReconciler
• type Logger
• type Reconciler
• type ReferenceManager
• type ServiceController
• type ServiceControllerMetadata
• type TraceExiter
• type Tracer
• type VersionInfo

Types

type AWSResource

type AWSResource interface {
	ConditionManager
	// 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
	// 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() rtclient.Object
	// MetaObject returns the Kubernetes apimachinery/apis/meta/v1.Object
	// representation of the AWSResource
	// TODO(vijtrip2) Consider removing MetaObject method since RuntimeObject
	// returns superset of MetaObject
	MetaObject() metav1.Object
	// 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
	// SetStatus will set the Status field for the resource
	SetStatus(AWSResource)
	// DeepCopy will return a copy of the resource
	DeepCopy() AWSResource
	// PopulateResourceFromAnnotation will set the Spec or Status field that user
	// provided from annotations
	PopulateResourceFromAnnotation(fields map[string]string) 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 {
	// GroupVersionKind returns a Kubernetes schema.GroupVersionKind struct that
	// describes the API Group, Version and Kind of CRs described by the
	// descriptor
	GroupVersionKind() schema.GroupVersionKind
	// EmptyRuntimeObject returns an empty object prototype that may be used in
	// apimachinery and k8s client operations
	EmptyRuntimeObject() rtclient.Object
	// ResourceFromRuntimeObject returns an AWSResource that has been
	// initialized with the supplied runtime.Object
	ResourceFromRuntimeObject(rtclient.Object) AWSResource
	// Delta returns an `ackcompare.Delta` object containing the difference between
	// one `AWSResource` and another.
	Delta(a, b AWSResource) *ackcompare.Delta
	// 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
	// Region is the AWS region in which the resource exists or will exist.
	Region() *ackv1alpha1.AWSRegion
}

AWSResourceIdentifiers has methods that returns common identifying information about a resource

type AWSResourceManager

type AWSResourceManager interface {
	ReferenceManager
	// 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, returning an AWSResource representing the
	// resource being deleted (if delete is asynchronous and takes time)
	Delete(context.Context, AWSResource) (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
	// LateInitialize returns an AWS Resource after setting the late initialized
	// fields from the ReadOne call. This method will initialize the optional fields
	// which were not provided by the k8s user but were defaulted by the AWS service.
	// If there are no such fields to be initialized, the returned object is identical to
	// object passed in the parameter.
	// This method also adds/updates the ConditionTypeLateInitialized for the AWSResource.
	LateInitialize(context.Context, AWSResource) (AWSResource, error)
	// IsSynced returns true if a resource is synced.
	IsSynced(context.Context, AWSResource) (bool, error)
	// EnsureTags ensures that tags are present inside the AWSResource.
	// If the AWSResource does not have any existing resource tags, the 'tags'
	// field is initialized and the controller tags are added.
	// If the AWSResource has existing resource tags, then controller tags are
	// added to the existing resource tags without overriding them.
	// If the AWSResource does not support tags, only then the controller tags
	// will not be added to the AWSResource.
	EnsureTags(context.Context, AWSResource, ServiceControllerMetadata) error
}

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,
		ackv1alpha1.AWSResourceName,
	) (AWSResourceManager, error)
	// IsAdoptable returns true if the resource is able to be adopted
	IsAdoptable() bool
	// RequeueOnSuccessSeconds returns true if the resource should be requeued after specified seconds
	// Default is false which means resource will not be requeued after success.
	RequeueOnSuccessSeconds() int
}

AWSResourceManagerFactory returns an AWSResourceManager that can be used to manage AWS resources for a particular AWS account TODO(jaypipes): Move AWSResourceManagerFactory into its own file

type AWSResourceReconciler

type AWSResourceReconciler interface {
	Reconciler
	// BindControllerManager sets up the AWSResourceReconciler with an instance
	// of an upstream controller-runtime.Manager
	BindControllerManager(ctrlrt.Manager) error
	// GroupKind returns the schema.GroupVersionKind containing the API group,
	// version and kind reconciled by this reconciler
	GroupVersionKind() *schema.GroupVersionKind
	// Sync ensures that the supplied AWSResource's backing API resource
	// matches the supplied desired state.
	//
	// It returns a copy of the resource that represents the latest observed
	// 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,
	) (AWSResource, error)
	// HandleReconcileError will handle errors from reconcile handlers, which
	// respects runtime errors.
	//
	// If the `latest` parameter is not nil, this function will ALWAYS patch the
	// latest Status fields back to the Kubernetes API.
	//
	// NOTE(jaypipes): This is really only here for dependency injection
	// purposes in unit testing in order to simplify test setups.
	HandleReconcileError(
		ctx context.Context,
		desired AWSResource,
		latest AWSResource,
		err error,
	) (ctrlrt.Result, 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 AdoptedResourceReconciler

type AdoptedResourceReconciler interface {
	Reconciler
	// BindControllerManager sets up the AdoptedResourceReconciler with an
	// instance of an upstream controller-runtime.Manager
	BindControllerManager(ctrlrt.Manager) error
	// Sync ensures that the supplied AdoptedResource creates the matching
	// AWSResource based on observed state from ReadOne method
	//
	//
	// NOTE(vijtrip2): This is really only here for dependency injection
	// purposes in unit testing in order to simplify test setups.
	Sync(
		context.Context,
		AWSResourceDescriptor,
		AWSResourceManager,
		*ackv1alpha1.AdoptedResource,
	) error
}

AdoptedResourceReconciler is responsible for reconciling an adopted resource that represent AWS service API resource. It implements the upstream controller-runtime `Reconciler` interface.

type ConditionManager

type ConditionManager interface {
	// Conditions returns the ACK Conditions collection for the AWSResource
	Conditions() []*ackv1alpha1.Condition
	// ReplaceConditions replaces the resource's set of Condition structs with
	// the supplied slice of Conditions.
	ReplaceConditions([]*ackv1alpha1.Condition)
}

ConditionManager describes a thing that can set and retrieve Condition objects.

type FieldExportReconciler

type FieldExportReconciler interface {
	Reconciler
	// Sync ensures that the supplied FieldExport has been registered and is
	// actively monitoring the resources.
	Sync(
		context.Context,
		AWSResource,
		ackv1alpha1.FieldExport,
	) (ackv1alpha1.FieldExport, error)
	// BindControllerManager sets up the FieldExportReconciler with an instance
	// of an upstream controller-runtime.Manager
	BindControllerManager(ctrlrt.Manager) error
	// GetFieldExportsForResource will list all FieldExport CRs and filter them
	// based on whether they contain a reference to the given AWS resource.
	GetFieldExportsForResource(
		context.Context,
		schema.GroupKind,
		types.NamespacedName,
	) ([]ackv1alpha1.FieldExport, error)
}

FieldExportReconciler is responsible for reconciling a field export CR. It implements the upstream controller-runtime `Reconciler` interface.

type Logger

type Logger interface {
	Tracer
	// IsDebugEnabled returns true when the underlying logger is configured to
	// write debug messages, false otherwise.
	IsDebugEnabled() bool
	// WithValues adapts the internal logger with a set of additional key/value
	// data
	WithValues(...interface{})
	// Debug writes a supplied log message about a resource that includes a set
	// of standard log values for the resource's kind, namespace, name, etc
	Debug(msg string, additionalValues ...interface{})
	// Info writes a supplied log message about a resource that includes a set
	// of standard log values for the resource's kind, namespace, name, etc
	Info(msg string, additionalValues ...interface{})
	// Enter logs an entry to a function or code block
	Enter(name string, additionalValues ...interface{})
	// Exit logs an exit from a function or code block
	Exit(name string, err error, additionalValues ...interface{})
}

Logger is responsible for writing log messages

type Reconciler

type Reconciler interface {
	ctrlreconcile.Reconciler
	// SecretValueFromReference fetches the value of a Secret given a
	// SecretKeyReference
	SecretValueFromReference(context.Context, *v1alpha1.SecretKeyReference) (string, error)
	// WriteToSecret writes a value to a Secret given the namespace, name,
	// and key of the Secret
	WriteToSecret(context.Context, string, string, string, 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 ReferenceManager

type ReferenceManager interface {
	// ResolveReferences finds if there are any Reference field(s) present
	// inside AWSResource passed in the parameter and attempts to resolve those
	// reference field(s) into their respective target field(s). It returns a
	// copy of the input AWSResource with resolved reference(s), a boolean which
	// is set to true if the resource contains any references (regardless of if
	// they are resolved successfully) and an error if the passed AWSResource's
	// reference field(s) could not be resolved.
	ResolveReferences(context.Context, client.Reader, AWSResource) (AWSResource, bool, error)
	// ClearResolvedReferences removes any reference values that were made
	// concrete in the spec. It returns a copy of the input AWSResource which
	// contains the original *Ref values, but none of their respective concrete
	// values.
	ClearResolvedReferences(AWSResource) AWSResource
}

ReferenceManager describes a thing that can resolve and clear references within an AWSResource.

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)

	// GetMetadata returns the metadata associated with the service controller.
	GetMetadata() ServiceControllerMetadata
}

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

type ServiceControllerMetadata

type ServiceControllerMetadata struct {
	VersionInfo
	// ServiceAlias is a string with the alias of the service API, e.g. "s3"
	ServiceAlias string
	// ServiceAPIGroup is a string with the full DNS-correct API group that
	// this service controller manages, e.g. "s3.services.k8s.aws"
	ServiceAPIGroup string
	// ServiceEndpointsID is a string with the service API's EndpointsID, e.g. "api.sagemaker"
	ServiceEndpointsID string
}

type TraceExiter

type TraceExiter func(err error, additionalValues ...interface{})

TraceExiter demarcates the end of a traced code block or function

type Tracer

type Tracer interface {
	// Trace logs an entry to a function or code block and returns a functor
	// that can be called to log the exit of the function or code block
	Trace(name string, additionalValues ...interface{}) TraceExiter
}

Tracer is responsible for tracing entrance and exit from blocks of code

type VersionInfo

type VersionInfo struct {
	// GitCommit is the SHA1 commit for the service controller's code
	GitCommit string
	// GitVersion is the latest Git tag from the service controller's code
	GitVersion string
	// BuildDate is a timestamp of when the code was built
	BuildDate string
}

VersionInfo contains information about the version of the runtime and service controller in use