Documentation
¶
Index ¶
- Constants
- func CloneExecutionID(assocID entity.Id) string
- func DeprovisionExecutionID(assocID entity.Id) string
- func IsSharedVariant(variantName string) bool
- func NameFromRef(ref entity.Id) string
- func ParseStorageGb(s string) int64
- func ProvisionExecutionID(assocID entity.Id) string
- func RequestClones(ctx context.Context, eac *entityserver_v1alpha.EntityAccessClient, ...) error
- func ResolveImage(baseImage, defaultVersion, requestedVersion string) string
- func SanitizeIdentifier(name string, maxLen int) string
- func WaitForAssociations(ctx context.Context, eac *entityserver_v1alpha.EntityAccessClient, ...) error
- type AddonAssociation
- type AddonCloner
- type AddonDefinition
- type AddonProvider
- type App
- type CreateSandboxPoolSpec
- type CredentialRotator
- type Disk
- type ExpectedAddon
- type ImageChecker
- type LocalityMode
- type OneShotSandboxSpec
- type ProviderFramework
- func (fw *ProviderFramework) CreateSandboxPool(ctx context.Context, spec CreateSandboxPoolSpec) (entity.Id, error)
- func (fw *ProviderFramework) CreateService(ctx context.Context, name string, matchLabels types.Labels, port int64) (entity.Id, error)
- func (fw *ProviderFramework) DeleteDiskByName(ctx context.Context, diskName string) error
- func (fw *ProviderFramework) DeleteSandboxPool(ctx context.Context, poolID entity.Id) error
- func (fw *ProviderFramework) DeleteService(ctx context.Context, serviceID entity.Id) error
- func (fw *ProviderFramework) ExecInPool(ctx context.Context, poolID entity.Id, args ...string) error
- func (fw *ProviderFramework) GetServiceAddress(ctx context.Context, serviceID entity.Id) (string, error)
- func (fw *ProviderFramework) RunOneShotSandbox(ctx context.Context, spec OneShotSandboxSpec, timeout time.Duration) (entity.Id, error)
- func (fw *ProviderFramework) ScalePool(ctx context.Context, poolID entity.Id, desired int64) error
- func (fw *ProviderFramework) WaitForPool(ctx context.Context, poolID entity.Id, timeout time.Duration) error
- func (fw *ProviderFramework) WaitForServiceAddress(ctx context.Context, serviceID entity.Id, timeout time.Duration) (string, error)
- type ProvisionResult
- type Registry
- func (r *Registry) EnsureEntities(ctx context.Context, ec *entityserver.Client) error
- func (r *Registry) Get(name string) (AddonProvider, AddonDefinition, bool)
- func (r *Registry) GetVariantConfig(addonName, variantName, version string) (map[string]string, error)
- func (r *Registry) ListAddons() []AddonDefinition
- func (r *Registry) Register(name string, provider AddonProvider, def AddonDefinition)
- func (r *Registry) ResolveAddonAndVariant(spec string) (addonName, variantName string, err error)
- type RegistryImageChecker
- type RotationResult
- type SandboxExecutor
- type Variable
- type Variant
- type VariantDefinition
Constants ¶
const CloneCleanupWaitCeiling = 2 * CloneWaitCeiling
Teardown may wait for an in-flight clone and then resume its unfinished saga before undoing it. Both passes need room for copying and rollback.
const CloneCopyTimeout = 30 * time.Minute
CloneCopyTimeout applies to both physical backups and logical dump/restore.
const CloneWaitCeiling = CloneCopyTimeout + 3*WaitCeiling
Preview deploys do not hold the normal deployment lock. Allow a full copy, pool/service readiness, and exec overhead rather than the primary's budget.
const ConfigImage = "_image"
ConfigImage is the well-known key used in variant config maps to pass the resolved container image to provider saga actions.
const WaitCeiling = 10 * time.Minute
WaitCeiling leaves room above providers' five-minute readiness timeouts for their failure to surface, while staying below the thirty-minute deploy lock.
Variables ¶
This section is empty.
Functions ¶
func CloneExecutionID ¶ added in v0.17.0
func DeprovisionExecutionID ¶ added in v0.14.0
func IsSharedVariant ¶ added in v0.7.0
IsSharedVariant returns true if the variant is a shared-server variant.
func NameFromRef ¶
NameFromRef extracts the addon name from an entity reference like "addon/postgresql".
func ParseStorageGb ¶ added in v0.7.0
ParseStorageGb converts a Kubernetes-style size string (e.g. "1Gi", "50Gi") to an int64 value in gigabytes. Returns 1 if the string cannot be parsed.
func ProvisionExecutionID ¶ added in v0.14.0
ProvisionExecutionID and DeprovisionExecutionID name an association's saga after the association itself. That is what lets a later reconcile pass continue an attempt a crash interrupted, instead of starting a second one alongside whatever the first already built.
Two passes must not drive the same execution at once. The executor guards against that within a single instance, but each operation here builds its own, so what actually serializes association work is the reconcile controller: it processes one event per entity at a time and queues the rest. Anything that drives a provision from outside that loop would need its own answer.
func RequestClones ¶ added in v0.17.0
func RequestClones(ctx context.Context, eac *entityserver_v1alpha.EntityAccessClient, appID, versionID entity.Id, spec core_v1alpha.ConfigSpec) error
RequestClones creates one version-scoped association for each selected primary association on an app. It is idempotent so a resumed deploy does not create a second clone of the same addon.
func ResolveImage ¶ added in v0.7.0
ResolveImage returns the container image for the given version. If version is empty, the default version is used. If version contains ":", it is used as the full image reference. Otherwise, it is appended as a tag to the base image.
func SanitizeIdentifier ¶ added in v0.7.0
SanitizeIdentifier converts a name into a safe database identifier by keeping only lowercase alphanumeric characters and underscores, converting uppercase to lowercase and hyphens to underscores, and truncating to maxLen.
func WaitForAssociations ¶ added in v0.17.0
func WaitForAssociations( ctx context.Context, eac *entityserver_v1alpha.EntityAccessClient, log *slog.Logger, appName string, appID entity.Id, versionID entity.Id, expected []ExpectedAddon, ceiling time.Duration, status waitStatus, ) error
WaitForAssociations blocks until each expected addon has an active association on the app (or exactly versionID for a preview). With nothing expected it returns at once without touching the store. Status may be nil.
Creating an association only records the request; the addon controller provisions the backing service on its own clock and flips the association to active once the database is listening and reachable. Nothing downstream of the deploy can use the addon before that: ResolveRuntimeConfig injects variables only from active associations, so a deploy task run earlier would have no DATABASE_URL, and a version activated earlier would sit at 0/0 instances until the launcher's gate released it, long after the CLI gave up waiting for health.
The wait is driven by what the deploy declared, not by whatever records happen to exist. An expected addon whose association is not visible yet is simply not active yet, so a slow index never lets the deploy through early. It watches the app's association index rather than polling it, so the deploy moves on the moment the controller flips the status.
An expected addon in error fails the deploy: error is terminal in the controller and nothing in a redeploy heals it, so the user has to act, and the message says how. One being deprovisioned fails too: it was destroyed out from under this deploy and will not come back on its own.
Types ¶
type AddonAssociation ¶
type AddonAssociation struct {
ID entity.Id
App entity.Id
AppVersion entity.Id
SourceAssociation entity.Id
Addon entity.Id
Variant string
// Read-only in practice, despite the type. Providers report writes by
// returning Attrs on a ProvisionResult, and a resumed saga could not write
// through this anyway: it arrives as a detached copy via JSON.
Entity *entity.Entity
}
AddonAssociation is the provider's view of an association: enough to name the work after it, plus the entity so a teardown or rotation can read what an earlier run recorded.
func AssociationFrom ¶ added in v0.14.0
func AssociationFrom(assoc *addon_v1alpha.AddonAssociation, ent *entity.Entity) AddonAssociation
AssociationFrom builds the provider view from a decoded association and the entity it came out of.
NOTE for future cleanup: this type is a subset of addon_v1alpha.AddonAssociation plus that entity. Passing the decoded association through instead would delete the type, this function, and every conversion at once.
type AddonCloner ¶ added in v0.17.0
type AddonCloner interface {
Clone(ctx context.Context, source, target AddonAssociation, app App, variant Variant) (*ProvisionResult, error)
}
AddonCloner is an optional provider capability used by ephemeral versions. The provider owns consistency: it may coordinate with a live engine before copying storage, or use an engine-native clone for shared infrastructure.
type AddonDefinition ¶
type AddonDefinition struct {
Name string
DisplayName string
Description string
DefaultVariant string
Variants []VariantDefinition
BaseImage string // container image without tag (e.g., "oci.miren.cloud/postgres")
DefaultVersion string // default tag when no version is specified (e.g., "17")
}
AddonDefinition describes an addon's metadata and available variants.
type AddonProvider ¶
type AddonProvider interface {
// LocalityMode returns where this addon's backing resources run.
LocalityMode() LocalityMode
// Provision creates the backing resources for an addon and returns the
// environment variables and entity attributes to store. It takes the
// association so the work can be named after it, which is what lets a
// later pass continue an attempt a crash interrupted rather than start
// over on top of what it already built.
Provision(ctx context.Context, assoc AddonAssociation, app App, variant Variant) (*ProvisionResult, error)
// AdjustEnvVars is called when provisioned env vars collide with existing
// app env vars. The provider can rename or adjust variables.
AdjustEnvVars(ctx context.Context, result *ProvisionResult, assoc AddonAssociation, collisions []string) ([]Variable, error)
// Deprovision tears down the backing resources for an addon.
Deprovision(ctx context.Context, assoc AddonAssociation) error
}
AddonProvider defines the interface that addon implementations must satisfy.
type CreateSandboxPoolSpec ¶
type CreateSandboxPoolSpec struct {
Name string
Image string
Env []string
Ports []compute_v1alpha.SandboxSpecContainerPort
DesiredInstances int64
Labels types.Labels
SandboxPrefix string
Command string
Mounts []compute_v1alpha.SandboxSpecContainerMount
Volumes []compute_v1alpha.SandboxSpecVolume
// PortWaitTimeout overrides the sandbox controller's port-bind health
// check budget. Parsed via time.ParseDuration (e.g. "60s"). Empty means
// use the default (15s). Addons with slow cold-init should set this.
PortWaitTimeout string
}
CreateSandboxPoolSpec describes the desired sandbox pool configuration.
type CredentialRotator ¶ added in v0.12.1
type CredentialRotator interface {
// RotateCredential rotates the named credential on the server backing assoc
// to newSecret. credential selects which secret to rotate (provider-defined;
// empty means the provider's default/only credential).
//
// newSecret is supplied (and durably recorded) by the controller rather than
// generated per call, so the operation is idempotent: re-invoking after a
// crash converges on the same target instead of minting a new secret. Every
// implementation must be safe to call repeatedly with the same newSecret.
RotateCredential(ctx context.Context, assoc AddonAssociation, credential, newSecret string) (*RotationResult, error)
}
CredentialRotator is an optional capability for providers that support rotating a backing server credential in place. Rotation applies a freshly generated secret to the live engine and updates the stored value; the returned EnvVars are the updated variables the controller propagates to consuming apps.
Not every provider implements this — the controller type-asserts for it and reports "rotation not supported" when a provider does not.
type Disk ¶ added in v0.14.0
type Disk struct {
// Name identifies the disk within a service's spec.
Name string
// Provider selects the volume provider (see controllers/sandbox/volume.go).
Provider string
// MountPath is where the disk appears inside the container.
MountPath string
// DbFile names a database within the mounted directory, for providers that
// manage one. Empty for providers that do not.
DbFile string
// Services names the services that receive this disk. Empty means every
// service in the app, matching how addon env vars reach every service.
Services []string
// RequiresSingleWriter marks storage that only one process may write, such
// as a SQLite database. Services receiving such a disk must run a single
// fixed instance; the controller refuses to attach it otherwise.
//
// The provider declares this rather than the controller inferring it,
// because whether concurrent writers are safe is a property of what the
// addon put on the disk, not of the disk itself.
RequiresSingleWriter bool
}
Disk is a storage attachment an addon contributes to the app's own sandbox.
Only InApp addons use this. An OnCluster addon owns its storage privately — it declares volumes on the sandbox pool it creates — whereas an InApp addon has no sandbox of its own and must reach into the app's.
type ExpectedAddon ¶ added in v0.17.0
ExpectedAddon is one addon the deploy declared and therefore requires to be active before the version can serve.
type ImageChecker ¶ added in v0.7.0
ImageChecker validates that a container image is accessible in its registry.
type LocalityMode ¶ added in v0.7.0
type LocalityMode string
LocalityMode describes where an addon's backing resources run.
const ( // OnCluster means the addon runs within the Miren cluster. OnCluster LocalityMode = "on_cluster" // Remote means the addon connects to an external service. Remote LocalityMode = "remote" // InApp means the addon has no server of its own: its backing resource is // attached to the app's own sandbox. An embedded database like SQLite is // in-process, so there is no host to connect to — the app opens a file the // addon arranged to have mounted. Such an addon contributes Disks rather // than standing up a sandbox pool, and has no container image. InApp LocalityMode = "in_app" )
type OneShotSandboxSpec ¶ added in v0.17.0
type OneShotSandboxSpec struct {
Name string
Image string
Command string
Env []string
Labels types.Labels
Mounts []compute_v1alpha.SandboxSpecContainerMount
Volumes []compute_v1alpha.SandboxSpecVolume
}
OneShotSandboxSpec describes a command that runs once with addon-managed storage attached. The sandbox is retained after exit so a resumed saga can observe the original result instead of executing the command twice.
type ProviderFramework ¶
type ProviderFramework struct {
EC *entityserver.Client
EAC *entityserver_v1alpha.EntityAccessClient
Storage saga.Storage
Log *slog.Logger
// Exec runs commands inside a pool's sandbox. Wired after the exec service
// is available (see coordinate.go); nil until then. Only credential rotation
// for engines with no network-level password change (RabbitMQ) needs it, and
// that runs long after startup.
Exec SandboxExecutor
}
ProviderFramework provides common operations that addon providers need when creating backing infrastructure (pools, services, etc).
func NewProviderFramework ¶
func NewProviderFramework(log *slog.Logger, ec *entityserver.Client, eac *entityserver_v1alpha.EntityAccessClient, storage saga.Storage) *ProviderFramework
NewProviderFramework creates a new provider framework.
func (*ProviderFramework) CreateSandboxPool ¶
func (fw *ProviderFramework) CreateSandboxPool(ctx context.Context, spec CreateSandboxPoolSpec) (entity.Id, error)
CreateSandboxPool creates a fixed-mode SandboxPool entity.
func (*ProviderFramework) CreateService ¶
func (fw *ProviderFramework) CreateService(ctx context.Context, name string, matchLabels types.Labels, port int64) (entity.Id, error)
CreateService creates a network Service entity that routes to pods matching the given labels.
func (*ProviderFramework) DeleteDiskByName ¶ added in v0.7.0
func (fw *ProviderFramework) DeleteDiskByName(ctx context.Context, diskName string) error
DeleteDiskByName finds a disk entity by its Name field and deletes it. Returns nil if no disk with that name exists.
func (*ProviderFramework) DeleteSandboxPool ¶
DeleteSandboxPool scales a pool to zero and then deletes it.
func (*ProviderFramework) DeleteService ¶
DeleteService deletes a network Service entity.
func (*ProviderFramework) ExecInPool ¶ added in v0.12.1
func (fw *ProviderFramework) ExecInPool(ctx context.Context, poolID entity.Id, args ...string) error
ExecInPool runs a command inside a running sandbox of the given pool and returns an error if the command cannot be run or exits non-zero. Output is captured only to enrich error messages. It targets any running instance; callers should use it for node-local operations (e.g. rabbitmqctl) that are safe to run against a single instance.
func (*ProviderFramework) GetServiceAddress ¶
func (fw *ProviderFramework) GetServiceAddress(ctx context.Context, serviceID entity.Id) (string, error)
GetServiceAddress reads the Service entity and returns its first allocated IP.
func (*ProviderFramework) RunOneShotSandbox ¶ added in v0.17.0
func (fw *ProviderFramework) RunOneShotSandbox(ctx context.Context, spec OneShotSandboxSpec, timeout time.Duration) (entity.Id, error)
RunOneShotSandbox creates an at-most-once sandbox and waits for its command to exit. The caller owns deleting the returned sandbox after durably recording the result.
func (*ProviderFramework) WaitForPool ¶
func (fw *ProviderFramework) WaitForPool(ctx context.Context, poolID entity.Id, timeout time.Duration) error
WaitForPool watches a pool entity until it has at least one ready instance or the timeout is reached.
type ProvisionResult ¶
type ProvisionResult struct {
EnvVars []Variable
Attrs []entity.Attr
// Disks are attached to the app's own sandbox. Only InApp providers set
// this; the controller writes them into the app's config the same way it
// writes EnvVars, so they are removed again on deprovision.
Disks []Disk
}
ProvisionResult is returned by a provider after successful provisioning.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry holds registered addon providers and their definitions.
func (*Registry) EnsureEntities ¶
EnsureEntities creates or updates Addon entities in the entity store for each registered addon, so they can be discovered by the CLI and API.
func (*Registry) Get ¶
func (r *Registry) Get(name string) (AddonProvider, AddonDefinition, bool)
Get returns the provider and definition for the named addon.
func (*Registry) GetVariantConfig ¶
func (r *Registry) GetVariantConfig(addonName, variantName, version string) (map[string]string, error)
GetVariantConfig returns the provider-internal config for a specific variant, with the resolved container image injected under the ConfigImage key. If version is empty, the addon's default version is used.
func (*Registry) ListAddons ¶
func (r *Registry) ListAddons() []AddonDefinition
ListAddons returns all registered addon definitions.
func (*Registry) Register ¶
func (r *Registry) Register(name string, provider AddonProvider, def AddonDefinition)
Register adds an addon provider with its definition to the registry.
type RegistryImageChecker ¶ added in v0.7.0
type RegistryImageChecker struct{}
RegistryImageChecker checks image accessibility by resolving the manifest against the remote registry.
func NewRegistryImageChecker ¶ added in v0.7.0
func NewRegistryImageChecker() *RegistryImageChecker
func (*RegistryImageChecker) CheckImage ¶ added in v0.7.0
func (c *RegistryImageChecker) CheckImage(ctx context.Context, image string) error
type RotationResult ¶ added in v0.12.1
type RotationResult struct {
// EnvVars are the updated variables consuming apps must pick up. It is empty
// when consumers don't embed the rotated secret (e.g. a shared-Postgres
// superuser password that apps never receive), in which case no redeploy is
// needed.
EnvVars []Variable
}
RotationResult is returned by a CredentialRotator after a successful rotation.
type SandboxExecutor ¶ added in v0.12.1
type SandboxExecutor interface {
Exec(ctx context.Context, category string, value string, command string, options *exec_v1alpha.ShellOptions, input stream.RecvStream[[]byte], output stream.SendStream[[]byte], windowUpdates stream.RecvStream[*exec_v1alpha.WindowSize]) (*exec_v1alpha.SandboxExecClientExecResults, error)
}
SandboxExecutor runs a command inside a running sandbox and reports its exit code. *exec_v1alpha.SandboxExecClient satisfies it; tests can substitute a stub.