provider

package
v0.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 16, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package provider defines the unified interface for infrastructure operations. Each cloud provider and orchestrator (Kubernetes, Nomad, AWS ECS, Docker, Fly.io, etc.) implements the Provider interface, giving library consumers a single API for all infrastructure operations.

Index

Constants

This section is empty.

Variables

View Source 
var ErrProviderNotFound = errors.New("ctrlplane: provider not registered")

ErrProviderNotFound indicates the named provider is not registered.

Functions

func HasCapability 

func HasCapability(p Provider, capability Capability) bool

HasCapability checks whether the provider supports a given capability.

Types

type Capability 

type Capability string

Capability declares what a provider supports. Consumers can query capabilities before calling unsupported methods. 

const (
	// CapProvision indicates the provider can create infrastructure.
	CapProvision Capability = "provision"

	// CapDeploy indicates the provider can deploy releases.
	CapDeploy Capability = "deploy"

	// CapScale indicates the provider can adjust resources.
	CapScale Capability = "scale"

	// CapLogs indicates the provider can stream logs.
	CapLogs Capability = "logs"

	// CapExec indicates the provider can execute commands in instances.
	CapExec Capability = "exec"

	// CapVolumes indicates the provider supports persistent volumes.
	CapVolumes Capability = "volumes"

	// CapGPU indicates the provider supports GPU workloads.
	CapGPU Capability = "gpu"

	// CapBlueGreen indicates the provider supports blue-green deployments.
	CapBlueGreen Capability = "strategy:blue-green"

	// CapCanary indicates the provider supports canary deployments.
	CapCanary Capability = "strategy:canary"

	// CapRolling indicates the provider supports rolling deployments.
	CapRolling Capability = "strategy:rolling"

	// CapAutoScale indicates the provider supports autoscaling.
	CapAutoScale Capability = "autoscale"

	// CapCustomDomains indicates the provider supports custom domains.
	CapCustomDomains Capability = "custom-domains"

	// CapTLS indicates the provider supports TLS termination.
	CapTLS Capability = "tls"
)

type DeployRequest 

type DeployRequest struct {
	InstanceID  id.ID             `json:"instance_id"`
	ReleaseID   id.ID             `json:"release_id"`
	Image       string            `json:"image"`
	Env         map[string]string `json:"env,omitempty"`
	Strategy    string            `json:"strategy"`
	HealthCheck *HealthCheckSpec  `json:"health_check,omitempty"`
}

DeployRequest describes a deployment operation.

type DeployResult 

type DeployResult struct {
	ProviderRef string `json:"provider_ref"`
	Status      string `json:"status"`
}

DeployResult holds the result of a deploy operation.

type Endpoint 

type Endpoint struct {
	URL      string `json:"url"`
	Port     int    `json:"port"`
	Protocol string `json:"protocol"`
	Public   bool   `json:"public"`
}

Endpoint describes an accessible endpoint for an instance.

type ExecRequest 

type ExecRequest struct {
	Command []string  `json:"command"`
	Stdin   io.Reader `json:"-"`
	TTY     bool      `json:"tty"`
}

ExecRequest describes a command to run inside an instance.

type ExecResult 

type ExecResult struct {
	ExitCode int    `json:"exit_code"`
	Stdout   []byte `json:"stdout"`
	Stderr   []byte `json:"stderr"`
}

ExecResult holds the result of an exec operation.

type HealthCheckSpec 

type HealthCheckSpec struct {
	Path     string        `json:"path,omitempty"`
	Port     int           `json:"port"`
	Interval time.Duration `json:"interval"`
	Timeout  time.Duration `json:"timeout"`
	Retries  int           `json:"retries"`
}

HealthCheckSpec configures health checking during deployment.

type InstanceState 

type InstanceState string

InstanceState represents the lifecycle state of an instance. 

const (
	// StateProvisioning indicates the instance is being provisioned.
	StateProvisioning InstanceState = "provisioning"

	// StateStarting indicates the instance is starting up.
	StateStarting InstanceState = "starting"

	// StateRunning indicates the instance is running and healthy.
	StateRunning InstanceState = "running"

	// StateStopping indicates the instance is shutting down.
	StateStopping InstanceState = "stopping"

	// StateStopped indicates the instance is stopped.
	StateStopped InstanceState = "stopped"

	// StateFailed indicates the instance is in a failed state.
	StateFailed InstanceState = "failed"

	// StateDestroying indicates the instance is being torn down.
	StateDestroying InstanceState = "destroying"

	// StateDestroyed indicates the instance has been fully removed.
	StateDestroyed InstanceState = "destroyed"
)

type InstanceStatus 

type InstanceStatus struct {
	State     InstanceState     `json:"state"`
	Ready     bool              `json:"ready"`
	Restarts  int               `json:"restarts"`
	StartedAt *time.Time        `json:"started_at,omitempty"`
	Message   string            `json:"message,omitempty"`
	Endpoints []Endpoint        `json:"endpoints"`
	Metadata  map[string]string `json:"metadata,omitempty"`
}

InstanceStatus describes the current runtime state of an instance.

type LogOptions 

type LogOptions struct {
	Follow bool      `json:"follow"`
	Since  time.Time `json:"since,omitzero"`
	Tail   int       `json:"tail,omitempty"`
}

LogOptions configures log streaming.

type PortSpec 

type PortSpec struct {
	Container int    `json:"container"`
	Host      int    `json:"host,omitempty"`
	Protocol  string `json:"protocol"`
}

PortSpec declares a port mapping for an instance.

type Provider 

type Provider interface {
	// Info returns metadata about this provider.
	Info() ProviderInfo

	// Capabilities returns what this provider supports.
	Capabilities() []Capability

	// Provision creates infrastructure resources for an instance.
	Provision(ctx context.Context, req ProvisionRequest) (*ProvisionResult, error)

	// Deprovision tears down all resources for an instance.
	Deprovision(ctx context.Context, instanceID id.ID) error

	// Start starts a stopped instance.
	Start(ctx context.Context, instanceID id.ID) error

	// Stop gracefully stops a running instance.
	Stop(ctx context.Context, instanceID id.ID) error

	// Restart performs a stop+start cycle.
	Restart(ctx context.Context, instanceID id.ID) error

	// Status returns the current runtime status.
	Status(ctx context.Context, instanceID id.ID) (*InstanceStatus, error)

	// Deploy pushes a new release to the instance.
	Deploy(ctx context.Context, req DeployRequest) (*DeployResult, error)

	// Rollback reverts to a previous release.
	Rollback(ctx context.Context, instanceID id.ID, releaseID id.ID) error

	// Scale adjusts the instance's resource allocation.
	Scale(ctx context.Context, instanceID id.ID, spec ResourceSpec) error

	// Resources returns current resource utilization.
	Resources(ctx context.Context, instanceID id.ID) (*ResourceUsage, error)

	// Logs streams logs for the instance.
	Logs(ctx context.Context, instanceID id.ID, opts LogOptions) (io.ReadCloser, error)

	// Exec runs a command inside the instance.
	Exec(ctx context.Context, instanceID id.ID, cmd ExecRequest) (*ExecResult, error)
}

Provider is the unified interface for infrastructure operations. Each cloud/orchestrator (K8s, Nomad, AWS ECS, Docker, etc.) implements this.

type ProviderInfo 

type ProviderInfo struct {
	Name    string `json:"name"`
	Version string `json:"version"`
	Region  string `json:"region"`
}

ProviderInfo holds metadata about a provider.

type ProvisionRequest 

type ProvisionRequest struct {
	InstanceID  id.ID             `json:"instance_id"`
	TenantID    string            `json:"tenant_id"`
	Name        string            `json:"name"`
	Image       string            `json:"image"`
	Resources   ResourceSpec      `json:"resources"`
	Env         map[string]string `json:"env,omitempty"`
	Ports       []PortSpec        `json:"ports,omitempty"`
	Volumes     []VolumeSpec      `json:"volumes,omitempty"`
	Labels      map[string]string `json:"labels,omitempty"`
	Annotations map[string]string `json:"annotations,omitempty"`
}

ProvisionRequest describes what resources to create for an instance.

type ProvisionResult 

type ProvisionResult struct {
	ProviderRef string            `json:"provider_ref"`
	Endpoints   []Endpoint        `json:"endpoints"`
	Metadata    map[string]string `json:"metadata,omitempty"`
}

ProvisionResult holds the result of a provision operation.

type Registry 

type Registry struct {
	// contains filtered or unexported fields
}

Registry manages named providers. Thread-safe.

func NewRegistry 

func NewRegistry() *Registry

NewRegistry creates an empty provider registry.

func (*Registry) All 

func (r *Registry) All() map[string]Provider

All returns a snapshot of all registered providers.

func (*Registry) Default 

func (r *Registry) Default() (Provider, error)

Default returns the fallback provider.

func (*Registry) Get 

func (r *Registry) Get(name string) (Provider, error)

Get retrieves a provider by name.

func (*Registry) List 

func (r *Registry) List() []string

List returns all registered provider names.

func (*Registry) Register 

func (r *Registry) Register(name string, p Provider)

Register adds a provider under the given name.

func (*Registry) SetDefault 

func (r *Registry) SetDefault(name string)

SetDefault sets the fallback provider name.

type ResourceSpec 

type ResourceSpec struct {
	CPUMillis int    `json:"cpu_millis"`
	MemoryMB  int    `json:"memory_mb"`
	DiskMB    int    `json:"disk_mb,omitempty"`
	Replicas  int    `json:"replicas"`
	GPU       string `json:"gpu,omitempty"`
}

ResourceSpec declares desired resources for an instance.

type ResourceUsage 

type ResourceUsage struct {
	CPUPercent    float64 `json:"cpu_percent"`
	MemoryUsedMB  int     `json:"memory_used_mb"`
	MemoryLimitMB int     `json:"memory_limit_mb"`
	DiskUsedMB    int     `json:"disk_used_mb,omitempty"`
	NetworkInMB   float64 `json:"network_in_mb"`
	NetworkOutMB  float64 `json:"network_out_mb"`
}

ResourceUsage reports actual resource utilization.

type VolumeSpec 

type VolumeSpec struct {
	Name      string `json:"name"`
	MountPath string `json:"mount_path"`
	SizeMB    int    `json:"size_mb"`
	Type      string `json:"type"`
}

VolumeSpec declares a volume mount for an instance.

Source Files

View all Source files

Directories

Path Synopsis
Package docker implements a Docker-based infrastructure provider for the ctrlplane.
 Package docker implements a Docker-based infrastructure provider for the ctrlplane.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.