README
¶
pkg/provisioners/managers/instance
Purpose
This package is the controller-side realization of the compute instance abstraction.
It reads stored ComputeInstance desired state and makes sure there is a
matching backing region.Server with the expected shape. It also mirrors
provider-facing status back from the server onto the instance and tears down the
associated quota allocation after the backing server is gone.
If pkg/server/handler/instance defines the public contract, this package is
where that contract is translated into the hidden execution primitive.
Invariants And Guard Rails
- A backing server is located by scoped
regionquery plus the reserved instance tag, not by an explicit foreign key stored on the instance. - Create and update requests sent to region always carry the reserved instance tag so later lookup and reverse mapping can find the server again.
- Instance status is projection-only here: IP addresses, MAC address, power state, and health are copied from the server response.
- Deprovision is two-stage: delete the backing server first, then release the identity allocation record only after the server is gone.
- The controller yields while region still reports provisioning or while delete is still in flight. Final instance completion is intentionally downstream of region's lifecycle.
Destructive Update Semantics
This package hides a major nuance the higher-level architecture needs to state clearly: some instance updates are actually rebuilds.
When flavor or image changes are detected, the controller treats that as replacement-worthy and deletes the existing backing server before continuing. That is not a cosmetic implementation detail. It means an apparently simple instance update can imply loss of server-local state and changes to IP/disk continuity.
Instance names are immutable end-to-end: the API handler rejects renames with HTTP 422 and region enforces the same at its layer. The controller therefore never encounters a name change at reconcile time; name-change detection has been removed from the rebuild heuristic.
Caveats
- The lookup contract is weaker than the handler-side one.
getServer()returns the first match and does not enforce uniqueness, so multiple matching servers would create ambiguous controller behaviour. - The current rebuild heuristic is intentionally incomplete. The code comments already admit that flavor-change detection is constrained by lower-level region/provider visibility and that live-migration preservation is not modeled.
- The region client is not cached and the code already notes token/cache churn risk during busy periods.
- This package depends on region to be the truth source for provisioning progress and health. Compute does not independently observe provider state.
TODO
- Enforce uniqueness when resolving the backing server, not just existence.
- Make rebuild semantics explicit in status or events so users are not left inferring destructive replacement from delayed side effects.
- Cache or otherwise amortize controller-side region client construction if identity token churn becomes operationally significant.
- Revisit whether backing-server identity should stay tag-based or become a more explicit coordination contract.
Cross-Package Context
- ../../../server/handler/instance documents the API-side invariants this package realizes asynchronously
- ../../../managers/instance documents
the controller wiring and reverse watch path from
region.Serverback toComputeInstance
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func New ¶
func New(options manager.ControllerOptions) provisioners.ManagerProvisioner
New returns a new initialized provisioner object.
Types ¶
type Options ¶
type Options struct {
// contains filtered or unexported fields
}
Options allows access to CLI options in the provisioner.
type Provisioner ¶
type Provisioner struct {
provisioners.Metadata
// contains filtered or unexported fields
}
Provisioner encapsulates control plane provisioning.
func (*Provisioner) Deprovision ¶
func (p *Provisioner) Deprovision(ctx context.Context) error
Deprovision implements the Provision interface.
func (*Provisioner) Object ¶
func (p *Provisioner) Object() unikornv1core.ManagableResourceInterface
Source Files