README
¶
pkg/provisioners
Intention
pkg/provisioners defines the repository's reconciler-oriented provisioning contract. It is the abstraction layer used to drive resource lifecycle through idempotent Provision(ctx) and Deprovision(ctx) operations that can make partial progress, yield, and converge over repeated controller-runtime retries.
This package itself is intentionally small:
- the
ProvisionerandManagerProvisionerinterfaces - the
RemoteClusterinterface for deriving remote kubeconfigs and identities - shared metadata for provisioner names
- shared sentinel errors, especially
ErrYield
Most of the real behavior lives in the lower-level adapters and combinators under this directory.
Invariants And Guard Rails
- Provisioners are intended to run inside reconcilers. They are expected to be idempotent and safe to revisit across repeated reconcile passes.
ErrYieldis a core part of the model, not an edge case. It means "stop now and let the controller retry later" when a provisioner would otherwise block for too long waiting on external progress.- The preferred progress model is framework-driven retry, not long local retry loops. Provisioners should generally fail or yield quickly and let controller-runtime handle fairness and requeue.
Deprovision(ctx)is part of the same convergence model. It may make partial progress and returnErrYieldwhile waiting for external deletion or teardown to complete.ManagerProvisioneris the top-level provisioner shape that bridges directly into the controller-runtime layer for managed resources.RemoteClusteris the narrow interface used by remote-scope provisioners to derive the target cluster identity and kubeconfig.
Package Map
- application: CD-managed Helm application provisioner. Resolves application/version, derives application identity from resource scope, applies generator customizations, and delegates lifecycle to the CD driver.
- remotecluster: switches active provisioning scope into a remote cluster, constructs the remote client, and coordinates shared remote lifecycle for descendants.
- serial: ordered composition combinator for dependency-sensitive children. Provision in order, deprovision in reverse order.
- concurrent: parallel composition combinator for independent children that should make progress in the same reconcile pass.
- conditional: binary desired-state gate where predicate false means actively deprovision the child, not merely skip it.
- resource: legacy single-
client.Objectadapter. Historical hack, not a recommended pattern for new code. - util: small provisioner-side helper bucket, mostly scheduling/config-generation fragments and a couple of operational helpers.
Caveats
pkg/provisionersis a contract layer, not a clean architecture in itself. Much of the real complexity is pushed into the subpackages, especiallyapplicationandremotecluster.- The whole model assumes reconciler-friendly behavior: idempotence, quick yields, and retry-based convergence. If child provisioners block internally or depend on one-shot success, the abstraction breaks down.
- Several important subpackages are tightly coupled to the older context-scoping and in-tree CD model documented in pkg/client, especially application and remotecluster.
- Not every subpackage here is equally healthy.
resourceis legacy baggage, and some of the extension seams inapplicationare historical compromise rather than clean design.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
View Source
var ( // ErrYield is raised when a provision/deprovision optation could // block for a long time, in particular the bits that wait for apllication // available status. This will trigger a controller to requeue the request. // The key things are that workers are unblocked, allowing other reconciles // to be triggered, and we can pick up an modifications (e.g. the cluster is // gubbed - thanks CAPO - and we can delete it without waiting for 10m as the // case used to be in the old world. ErrYield = errors.New("controller timeout yield") // ErrNotFound is when a resource is not found. ErrNotFound = errors.New("resource not found") )
Functions ¶
This section is empty.
Types ¶
type ManagerProvisioner ¶
type ManagerProvisioner interface {
Provisioner
// Object returns a reference to the generic object type, internally
// the provisioner will have a type specific version.
Object() unikornv1.ManagableResourceInterface
}
ManagerProvisioner top-level manager provisioners hook directly into the controller runtime layer, and are a little special in that they abstract away type specific things.
type Metadata ¶
type Metadata struct {
// Name is the name of the provisioner.
Name string
}
Metadata is a container for geneirc provisioner metadata.
func (*Metadata) ProvisionerName ¶
ProvisionerName implements the Provisioner interface.
type Provisioner ¶
type Provisioner interface {
// ProvisionerName returns the provisioner name.
ProvisionerName() string
// Provision deploys the requested package.
// Implementations should ensure this receiver is idempotent.
Provision(ctx context.Context) error
// Deprovision does any special handling of resource/component
// removal. In the general case, you should rely on cascading
// deletion i.e. kill the namespace, use owner references.
// Deprovisioners should be gating, waiting for their resources
// to be removed before indicating success.
Deprovision(ctx context.Context) error
}
Provisioner is an abstract type that allows provisioning of Kubernetes packages in a technology agnostic way. For example some things may be installed as a raw set of resources, a YAML manifest, Helm etc.
type RemoteCluster ¶
type RemoteCluster interface {
// ID is the unique resource identifier for this remote cluster.
ID() *cd.ResourceIdentifier
// Config returns the client configuration (aka parsed Kubeconfig.)
Config(ctx context.Context) (*clientcmdapi.Config, error)
}
Generator is an abstraction around the sources of remote clusters e.g. a cluster API or vcluster Kubernetes instance.
Source Files
Directories
Click to show internal directories.
Click to hide internal directories.