machineops

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 must report them too,
	// so release can clean them up.
	OwnedResources []unboundedv1alpha3.ProviderOwnedResource
}

AllocationResult reports the host confirmed by HostAllocate. Field names match v1alpha3.MachineOperationAllocationResult.

Every terminal HostAllocate Poll result, whether Succeeded, Failed or Canceled, must set OperationResult.Allocation. Its OwnedResources must list every resource created for the allocation, and an empty list means nothing exists. A missing report, or a Poll PermanentError, makes the engine fail the operation with the reason OwnershipUnknown. The allocation then holds and needs manual recovery, because release could act only on the resources it knows.

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 (c *Capacity) PlanAllocation(ctx context.Context, request AllocationPlanRequest) (AllocationPlan, error)

func (c *Capacity) ResolveClass(ctx context.Context, request ClassRequest) (ClassResolution, error)

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 (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 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 (a *OperationAuth) RequiredSecretValue(key string) (string, error)

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() OperationOption

func RequiresReplaceUserData() OperationOption

func WithCleanup(cleanup CleanupFunc) OperationOption

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. Every terminal HostAllocate Poll
	// result must set it, as AllocationResult describes.
	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

type PermanentError struct {
	Reason string
	Err    error
}

PermanentError reports that retrying a provider callback cannot make progress. Providers should return ordinary errors for transient failures.

func (e *PermanentError) Error() string

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(name string, options ...ProviderOption) (*Provider, error)

func (p *Provider) Capacity() (*Capacity, bool)

func (p *Provider) Name() string

func (p *Provider) Operation(kind unboundedv1alpha3.OperationKind) (*Operation, bool)

func (p *Provider) ProviderMachineKind() (schema.GroupKind, bool)

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

type ProviderOperation struct {
	OperationID string
	ResumeToken string
}

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(resolveClass ResolveClassFunc, planAllocation PlanAllocationFunc) ProviderOption

func WithImmediateOperation(
	kind unboundedv1alpha3.OperationKind,
	execute ExecuteFunc,
	options ...OperationOption,
) ProviderOption

func WithLongRunningOperation(
	kind unboundedv1alpha3.OperationKind,
	begin BeginFunc,
	poll PollFunc,
	options ...OperationOption,
) ProviderOption

func WithProviderMachineKind(groupKind schema.GroupKind) ProviderOption

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.