Documentation
¶
Index ¶
- type AllocationPlan
- type AllocationPlanRequest
- type AllocationRequest
- type AllocationResult
- type BeginFunc
- type BeginResult
- type Capacity
- type ClassRequest
- type ClassResolution
- type CleanupFunc
- type ExecuteFunc
- type Operation
- func (o *Operation) Begin(ctx context.Context, request OperationRequest) (BeginResult, error)
- func (o *Operation) Cleanup(ctx context.Context, request OperationRequest, result OperationResult) error
- func (o *Operation) Execute(ctx context.Context, request OperationRequest) (OperationResult, error)
- func (o *Operation) Mode() OperationMode
- func (o *Operation) Poll(ctx context.Context, request OperationRequest, operation ProviderOperation) (PollResult, error)
- func (o *Operation) ReplaySafe() bool
- func (o *Operation) RequiresReplaceUserData() bool
- type OperationAuth
- type OperationMode
- type OperationOption
- type OperationRequest
- type OperationResult
- type PermanentError
- type PlanAllocationFunc
- type PollFunc
- type PollResult
- type Provider
- type ProviderConfig
- type ProviderOperation
- type ProviderOperationState
- type ProviderOption
- func WithCapacity(resolveClass ResolveClassFunc, planAllocation PlanAllocationFunc) ProviderOption
- func WithImmediateOperation(kind unboundedv1alpha3.OperationKind, execute ExecuteFunc, ...) ProviderOption
- func WithLongRunningOperation(kind unboundedv1alpha3.OperationKind, begin BeginFunc, poll PollFunc, ...) ProviderOption
- func WithProviderMachineKind(groupKind schema.GroupKind) ProviderOption
- type ResolveClassFunc
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AllocationPlan ¶ added in v0.23.0
type AllocationPlan struct {
// ProviderID is the pre-host locator used as the Machine's
// host.external.providerID before the host exists. It is not necessarily
// a native instance ID.
ProviderID string
// HostImage is the provider-interpreted image the host launches with.
HostImage string
}
AllocationPlan is the planned identity of an allocation's host.
type AllocationPlanRequest ¶ added in v0.23.0
type AllocationPlanRequest struct {
AllocationName string
AllocationUID types.UID
// HostName is the planned name of the allocation's Machine.
HostName string
ProviderConfig ProviderConfig
Offering unboundedv1alpha3.MachineClassOffering
}
AllocationPlanRequest asks a provider for the host identity of one allocation.
type AllocationRequest ¶ added in v0.23.0
type AllocationRequest struct {
Name string
// UID is the MachineAllocation incarnation that owns every provider
// effect. Begin must key replay on it as well as on
// OperationRequest.OperationUID.
UID types.UID
ClassName string
ClassUID types.UID
// HostName is the planned name of the allocation's Machine.
HostName string
// ProviderConfig is supplied only when HostAllocate begins. For Poll and
// for HostRelease it is the zero ProviderConfig.
ProviderConfig ProviderConfig
Offering unboundedv1alpha3.MachineClassOffering
// UserData is first-boot data that may contain credentials: providers
// must never log it, persist it, or copy it into a ResumeToken, status
// message or error. It is supplied only when HostAllocate begins and is
// empty for Poll and for HostRelease.
UserData string
// OwnedResources are the resources recorded as owned by the allocation,
// including those a failed HostAllocate reported. HostRelease may act only
// on these.
OwnedResources []unboundedv1alpha3.ProviderOwnedResource
}
AllocationRequest is the allocation input passed with HostAllocate and HostRelease operations.
type AllocationResult ¶ added in v0.23.0
type AllocationResult struct {
// ProviderResourceID is the provider-native host identifier.
ProviderResourceID string
InstanceType string
Zone string
Image string
// OwnedResources are the resources created for the allocation, with
// provider-native identity. A failed HostAllocate may still report them
// so release can clean them up.
OwnedResources []unboundedv1alpha3.ProviderOwnedResource
}
AllocationResult reports the host confirmed by HostAllocate. Field names match v1alpha3.MachineOperationAllocationResult.
type BeginFunc ¶ added in v0.1.23
type BeginFunc func(context.Context, OperationRequest) (BeginResult, error)
BeginFunc starts a long-running provider operation. It must be idempotent for a stable OperationRequest.OperationUID: repeated calls must return a usable handle for the same logical operation until that handle has been persisted.
type BeginResult ¶ added in v0.1.23
type BeginResult struct {
Operation ProviderOperation
Message string
RequeueAfter time.Duration
}
BeginResult contains the durable handle returned by an idempotent Begin callback. The controller may invoke Begin again with the same OperationUID until a handle for the same logical operation has been persisted.
type Capacity ¶ added in v0.23.0
type Capacity struct {
// contains filtered or unexported fields
}
Capacity is a provider's registered capacity lifecycle. Capacity is all or nothing: it requires HostAllocate and HostRelease registered as long-running operations, and those kinds require capacity.
func (*Capacity) PlanAllocation ¶ added in v0.23.0
func (c *Capacity) PlanAllocation(ctx context.Context, request AllocationPlanRequest) (AllocationPlan, error)
PlanAllocation invokes the registered allocation planning callback.
func (*Capacity) ResolveClass ¶ added in v0.23.0
func (c *Capacity) ResolveClass(ctx context.Context, request ClassRequest) (ClassResolution, error)
ResolveClass invokes the registered class resolution callback.
type ClassRequest ¶ added in v0.23.0
type ClassRequest struct {
ClassName string
ClassUID types.UID
SiteName string
// ProviderConfig is the content of the class's immutable provider
// configuration.
ProviderConfig ProviderConfig
Auth *OperationAuth
}
ClassRequest asks a provider to resolve a MachineClass into offerings.
type ClassResolution ¶ added in v0.23.0
type ClassResolution struct {
Offerings []unboundedv1alpha3.MachineClassOffering
}
ClassResolution is the provider's normalized view of a class. Offerings must carry truthful availability and a ValidUntil after which consumers must not launch from them.
type CleanupFunc ¶ added in v0.1.23
type CleanupFunc func(context.Context, OperationRequest, OperationResult) error
CleanupFunc performs optional provider cleanup after an operation result has been applied to the Machine.
type ExecuteFunc ¶ added in v0.1.23
type ExecuteFunc func(context.Context, OperationRequest) (OperationResult, error)
ExecuteFunc executes an immediate provider operation.
type Operation ¶ added in v0.1.23
type Operation struct {
// contains filtered or unexported fields
}
Operation is an immutable lifecycle strategy registered for one operation kind.
func (*Operation) Begin ¶ added in v0.1.23
func (o *Operation) Begin(ctx context.Context, request OperationRequest) (BeginResult, error)
Begin invokes the registered long-running operation begin callback.
func (*Operation) Cleanup ¶ added in v0.1.23
func (o *Operation) Cleanup(ctx context.Context, request OperationRequest, result OperationResult) error
Cleanup invokes the operation's optional cleanup callback.
func (*Operation) Execute ¶ added in v0.1.23
func (o *Operation) Execute(ctx context.Context, request OperationRequest) (OperationResult, error)
Execute invokes the registered immediate operation callback.
func (*Operation) Mode ¶ added in v0.1.23
func (o *Operation) Mode() OperationMode
Mode returns the lifecycle strategy used for the operation.
func (*Operation) Poll ¶ added in v0.1.23
func (o *Operation) Poll(ctx context.Context, request OperationRequest, operation ProviderOperation) (PollResult, error)
Poll invokes the registered long-running operation poll callback.
func (*Operation) ReplaySafe ¶ added in v0.1.23
ReplaySafe reports whether an immediate operation may be executed again after reconciliation resumes from InProgress.
func (*Operation) RequiresReplaceUserData ¶ added in v0.1.23
RequiresReplaceUserData reports whether replacement bootstrap data is needed.
type OperationAuth ¶
type OperationAuth struct {
Mode unboundedv1alpha3.MachineOperationCredentialAuthMode
SecretData map[string]string
}
OperationAuth is the provider-facing credential material resolved for an operation. Provider packages own the interpretation of SecretData.
func (*OperationAuth) RequiredSecretValue ¶
func (a *OperationAuth) RequiredSecretValue(key string) (string, error)
RequiredSecretValue returns a non-empty provider-specific secret value.
type OperationMode ¶ added in v0.1.23
type OperationMode string
OperationMode identifies how the lifecycle controller executes an operation.
const ( // OperationModeImmediate executes an operation in one provider callback. OperationModeImmediate OperationMode = "Immediate" // OperationModeLongRunning starts an operation and polls its persisted handle. OperationModeLongRunning OperationMode = "LongRunning" )
type OperationOption ¶ added in v0.1.23
type OperationOption interface {
// contains filtered or unexported methods
}
OperationOption configures one registered operation.
func ReplaySafe ¶ added in v0.1.23
func ReplaySafe() OperationOption
ReplaySafe declares that an immediate operation may be executed again when reconciliation resumes after its phase was persisted as InProgress.
func RequiresReplaceUserData ¶ added in v0.1.23
func RequiresReplaceUserData() OperationOption
RequiresReplaceUserData declares that the lifecycle controller must build host replacement bootstrap data before invoking the provider callback.
func WithCleanup ¶ added in v0.1.23
func WithCleanup(cleanup CleanupFunc) OperationOption
WithCleanup registers optional cleanup performed after the controller has applied the provider operation result.
type OperationRequest ¶
type OperationRequest struct {
MachineName string
MachineUID types.UID
MachineGeneration int64
OperationName string
OperationUID types.UID
// ProviderRef snapshots Machine.spec.host.external.machineRef when present.
ProviderRef *unboundedv1alpha3.ProviderMachineSnapshot
// ProviderID is the current canonical or legacy provider-specific host ID.
ProviderID string
HostImage string
Operation unboundedv1alpha3.OperationKind
Parameters map[string]string
ReplaceUserData string
Auth *OperationAuth
// Allocation is the allocation input for HostAllocate and HostRelease. It
// is nil for every other operation kind.
Allocation *AllocationRequest
}
OperationRequest is the generic provider-facing view of a MachineOperation.
type OperationResult ¶
type OperationResult struct {
ProviderID string
CleanupProviderID string
// Allocation is the allocation result reported by HostAllocate. It is
// nil for every other operation kind.
Allocation *AllocationResult
}
OperationResult describes provider-side changes that must be reflected after execution, such as replacement of an underlying cloud resource identity.
type PermanentError ¶ added in v0.1.23
PermanentError reports that retrying a provider callback cannot make progress. Providers should return ordinary errors for transient failures.
func (*PermanentError) Error ¶ added in v0.1.23
func (e *PermanentError) Error() string
func (*PermanentError) Unwrap ¶ added in v0.1.23
func (e *PermanentError) Unwrap() error
type PlanAllocationFunc ¶ added in v0.23.0
type PlanAllocationFunc func(context.Context, AllocationPlanRequest) (AllocationPlan, error)
PlanAllocationFunc computes the host identity for one allocation. It must be pure: deterministic for the same request, with no remote calls and no reservations. A PermanentError reports that the request can never be planned; other errors are retried.
type PollFunc ¶ added in v0.1.23
type PollFunc func(context.Context, OperationRequest, ProviderOperation) (PollResult, error)
PollFunc observes a previously accepted long-running provider operation. Ordinary errors are retried with the same persisted handle. A PermanentError terminates the MachineOperation.
type PollResult ¶ added in v0.1.23
type PollResult struct {
State ProviderOperationState
Result OperationResult
Reason string
Message string
RequeueAfter time.Duration
}
PollResult describes one status observation for a resumable provider operation.
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider is an immutable registration of one provider's supported MachineOperation lifecycle strategies.
func NewProvider ¶ added in v0.1.23
func NewProvider(name string, options ...ProviderOption) (*Provider, error)
NewProvider validates and constructs an immutable provider registration. Capacity is all or nothing: WithCapacity requires long-running HostAllocate and HostRelease registrations, and those kinds require WithCapacity.
func (*Provider) Name ¶
Name returns the external provider name matched against Machine.spec.host.external.provider or a deprecated Machine.spec.provider.
func (*Provider) Operation ¶ added in v0.1.23
func (p *Provider) Operation(kind unboundedv1alpha3.OperationKind) (*Operation, bool)
Operation returns the lifecycle strategy registered for kind.
type ProviderConfig ¶ added in v0.23.0
type ProviderConfig struct {
// Data is the data of the ConfigMap that MachineClass.spec.providerConfigRef
// names, the only kind of reference accepted today.
Data map[string]string
}
ProviderConfig is the class's provider configuration, which only the provider interprets. Further optional fields, for example a structured object for typed per-provider config resources, may be added later as an additive change.
type ProviderOperation ¶ added in v0.1.23
ProviderOperation is the provider-neutral representation of a resumable external operation.
type ProviderOperationState ¶ added in v0.1.23
type ProviderOperationState string
ProviderOperationState is the provider-neutral lifecycle of a resumable operation.
const ( ProviderOperationStateInProgress ProviderOperationState = "InProgress" ProviderOperationStateSucceeded ProviderOperationState = "Succeeded" ProviderOperationStateFailed ProviderOperationState = "Failed" ProviderOperationStateCanceled ProviderOperationState = "Canceled" )
type ProviderOption ¶ added in v0.1.23
type ProviderOption interface {
// contains filtered or unexported methods
}
ProviderOption configures a Provider registration.
func WithCapacity ¶ added in v0.23.0
func WithCapacity(resolveClass ResolveClassFunc, planAllocation PlanAllocationFunc) ProviderOption
WithCapacity registers class resolution and allocation planning. A provider that registers capacity must also register HostAllocate and HostRelease as long-running operations, and a provider that registers either kind must register capacity.
func WithImmediateOperation ¶ added in v0.1.23
func WithImmediateOperation( kind unboundedv1alpha3.OperationKind, execute ExecuteFunc, options ...OperationOption, ) ProviderOption
WithImmediateOperation registers an operation executed by one callback.
func WithLongRunningOperation ¶ added in v0.1.23
func WithLongRunningOperation( kind unboundedv1alpha3.OperationKind, begin BeginFunc, poll PollFunc, options ...OperationOption, ) ProviderOption
WithLongRunningOperation registers an operation executed as begin and poll callbacks.
func WithProviderMachineKind ¶ added in v0.1.23
func WithProviderMachineKind(groupKind schema.GroupKind) ProviderOption
WithProviderMachineKind declares the provider-owned Machine GroupKind accepted through Machine.spec.host.external.machineRef. Providers may also accept host.external.providerID or the deprecated Machine.spec.providerID.
type ResolveClassFunc ¶ added in v0.23.0
type ResolveClassFunc func(context.Context, ClassRequest) (ClassResolution, error)
ResolveClassFunc normalizes a class's provider configuration into capacity offerings. It must not allocate infrastructure. A PermanentError reports invalid configuration; other errors are transient and retried.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package controller registers the reusable MachineOperation provider controller with a controller-runtime manager.
|
Package controller registers the reusable MachineOperation provider controller with a controller-runtime manager. |