Documentation
¶
Overview ¶
Package provider defines the infrastructure provider interface for instance and load balancer operations.
Index ¶
- Constants
- Variables
- func IsUnhealthy(status string) bool
- func WaitForIPBindable(ctx context.Context, logger *slog.Logger, ipAddr string) error
- type CreateInstanceRequest
- type CreateInstanceResponse
- type DeregisterLBRequest
- type InstanceAnnotations
- type InstanceStatus
- type LeaderNetwork
- type ListInstancesRequest
- type ListInstancesResponse
- type ListLBInstancesRequest
- type LoadBalancerConfig
- type Provider
- type ProviderConfig
- type RegisterLBRequest
Constants ¶
const ( StatusPending = "pending" // AWS: "pending", GCP: "PROVISIONING"/"STAGING", mock: on create StatusRunning = "running" // AWS: "running", GCP: "RUNNING", Proxmox: "running", tmux: window alive, mock: after create StatusStopping = "stopping" // AWS: "stopping", GCP: "STOPPING" StatusStopped = "stopped" // AWS: "stopped", GCP: "STOPPED", Proxmox: "stopped" StatusSuspending = "suspending" // GCP: "SUSPENDING" StatusSuspended = "suspended" // GCP: "SUSPENDED", Proxmox: "paused" StatusDeleting = "deleting" // AWS: "shutting-down", mock: on delete StatusDeleted = "deleted" // AWS: "terminated", GCP: "TERMINATED", tmux: window dead/missing, mock: after delete StatusRepairing = "repairing" // GCP: "REPAIRING" (live migration) StatusUnknown = "unknown" // AWS/GCP/Proxmox: any unrecognised state (not in IsUnhealthy, not filtered by SQL) )
Common instance statuses - standardized across all cloud providers
Variables ¶
var ErrInstanceNotFound = errors.New("instance not found")
ErrInstanceNotFound is returned when an instance does not exist in the provider. This is a normal condition when instances have been externally deleted.
Functions ¶
func IsUnhealthy ¶
IsUnhealthy checks if an instance status indicates it needs replacement
func WaitForIPBindable ¶
WaitForIPBindable waits for the specified IP address to be bindable at the OS level. Cloud provider APIs may report network interface attachment or IP aliasing as complete before the IP is actually usable on the host. This function polls by attempting a test net.Listen on the IP with an ephemeral port (port 0), closing the listener immediately on success. This approach works regardless of whether the IP was added via interface assignment (e.g. AWS ENI attached via DHCP) or local route (e.g. GCP guest agent's "ip route add to local"), both of which make the IP bindable without necessarily adding it to net.InterfaceAddrs.
Types ¶
type CreateInstanceRequest ¶
type CreateInstanceRequest struct {
ClusterID string `json:"cluster_id"`
Shard string `json:"shard"`
Group string `json:"group"`
Template string `json:"template"`
InstanceKind string `json:"instance_kind"`
InstanceID string `json:"instance_id"`
InstanceType string `json:"instance_type"`
SubnetID string `json:"subnet_id"`
UserData string `json:"user_data"`
Nonce string `json:"nonce"` // Registration nonce JWT (used by dev provider)
CACertPEM []byte `json:"ca_cert"` // CA certificate PEM (used by dev provider)
Args map[string]interface{} `json:"args"`
// CustomTags are user-defined tags that providers apply as-is
CustomTags map[string]string `json:"custom_tags"`
}
CreateInstanceRequest contains parameters for creating & tagging an instance
type CreateInstanceResponse ¶
type CreateInstanceResponse struct {
InstanceID string `json:"instance_id"`
ProviderInstanceID string `json:"provider_instance_id"`
Status string `json:"status"`
PrivateIPv4 string `json:"private_ipv4"`
PrivateIPv6 string `json:"private_ipv6"`
Hostname string `json:"hostname"`
LaunchedAt time.Time `json:"launched_at"`
Tags map[string]string `json:"tags"`
}
CreateInstanceResponse contains the result of instance creation
type DeregisterLBRequest ¶
type DeregisterLBRequest struct {
ProviderInstanceID string
LBConfig LoadBalancerConfig
Zone string
}
DeregisterLBRequest contains parameters for deregistering an instance from a load balancer
type InstanceAnnotations ¶
type InstanceAnnotations struct {
Group string `json:"group,omitempty"`
Kind string `json:"kind,omitempty"`
CreatedAt *time.Time `json:"created_at,omitempty"`
}
InstanceAnnotations contains informational metadata about an instance. These are not used for filtering, GC, or reconciliation - only for display purposes.
type InstanceStatus ¶
type InstanceStatus struct {
InstanceID string `json:"instance_id"`
ProviderInstanceID string `json:"provider_instance_id"`
Status string `json:"status"`
InstanceType string `json:"instance_type"`
PrivateIPv4 string `json:"private_ipv4"`
PrivateIPv6 string `json:"private_ipv6"`
Hostname string `json:"hostname"`
LaunchedAt time.Time `json:"launched_at"`
Tags map[string]string `json:"tags"`
Region string `json:"region"`
Zone string `json:"zone"`
// "Associations" Metadata - used for filtering/GC/reconciliation.
// These are authoritative metadata fields that determine ownership.
ClusterID string `json:"cluster_id"`
Shard string `json:"shard"`
// "Annotations" Metadata - informational, not used for filtering or reconciliation.
// May be nil if not available from provider (e.g. Proxmox VE requires per-VM lookup, so /cluster/resources is nil).
Annotations *InstanceAnnotations `json:"annotations,omitempty"`
}
InstanceStatus represents the current state of an instance
func (*InstanceStatus) GetGroup ¶
func (s *InstanceStatus) GetGroup() string
GetGroup returns the group from annotations, or empty string if not available.
func (*InstanceStatus) GetKind ¶
func (s *InstanceStatus) GetKind() string
GetKind returns the kind from annotations, or empty string if not available.
type LeaderNetwork ¶
type LeaderNetwork struct {
IP string // Stable leader IP address: AWS wait-for-routable, GCP alias IP.
InterfaceID string // Provider resource ID: ENI ID for AWS, empty for GCP.
}
LeaderNetwork contains the stable network configuration for shard leadership. This is used to assign/release a stable IP address when acquiring/losing leadership.
type ListInstancesRequest ¶
type ListInstancesRequest struct {
ClusterID string `json:"cluster_id"`
Shard string `json:"shard"`
Limit int `json:"limit"`
NextToken string `json:"next_token"`
}
ListInstancesRequest contains parameters for listing instances with pagination
type ListInstancesResponse ¶
type ListInstancesResponse struct {
Instances []*InstanceStatus `json:"instances"`
NextToken string `json:"next_token"`
Total int `json:"total"`
}
ListInstancesResponse contains the result of paginated instance listing
type ListLBInstancesRequest ¶
type ListLBInstancesRequest struct {
LBConfig LoadBalancerConfig
Zone string
}
ListLBInstancesRequest contains parameters for listing load balancer instances
type LoadBalancerConfig ¶
type LoadBalancerConfig struct {
Provider string
TargetGroupArns []string // AWS: multiple ARNs for multi-port NLBs
BackendServiceName *string // GCP
InstanceGroupName *string // GCP
}
LoadBalancerConfig mirrors config.LoadBalancerConfig to avoid circular imports
type Provider ¶
type Provider interface {
Kind() string
// Instance lifecycle
CreateInstance(ctx context.Context, req CreateInstanceRequest) (*CreateInstanceResponse, error)
DeleteInstance(ctx context.Context, instanceID, providerInstanceID string) error
GetInstanceStatus(ctx context.Context, instanceID, providerInstanceID string) (*InstanceStatus, error)
ListInstances(ctx context.Context, req ListInstancesRequest) (*ListInstancesResponse, error)
// Leader network operations (stable IP for shard leadership)
AssignLeaderNetwork(ctx context.Context, providerInstanceID string, ln LeaderNetwork) error
ReleaseLeaderNetwork(ctx context.Context, providerInstanceID string, ln LeaderNetwork) error
// Networking
CheckSubnetCapacity(ctx context.Context, subnetID string) (bool, error)
// Load balancer groups
RegisterWithLB(ctx context.Context, req RegisterLBRequest) error
DeregisterFromLB(ctx context.Context, req DeregisterLBRequest) error
ListLBInstances(ctx context.Context, req ListLBInstancesRequest) ([]string, error)
}
Provider defines the unified interface for cloud provider operations
type ProviderConfig ¶
type ProviderConfig struct {
Kind string `json:"kind"`
Region string `json:"region"`
Zone string `json:"zone"`
Options map[string]interface{} `json:"options,omitempty"` // Provider-specific options
}
ProviderConfig contains provider-specific configuration
type RegisterLBRequest ¶
type RegisterLBRequest struct {
ProviderInstanceID string
LBConfig LoadBalancerConfig
Zone string
}
RegisterLBRequest contains parameters for registering an instance with a load balancer
Source Files