instances

package
v1.1.0 Latest Latest
Warning

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

 Go to latest Published: Apr 22, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Overview

Package instances orchestrates instance lifecycle: generating IDs, registration nonce JWTs, and userdata, then delegating VM creation to the infra package. It is the single writer for instance/{shard}/*.json records in S3, using read-modify-write to update registration data after initial creation.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ParseStorageKey 

func ParseStorageKey(storageKey string) (string, error)

ParseStorageKey extracts the original puidv7 instance ID from a storage key. e.g., "01970a1c-e31e-7422-9cd5-e9651d11cc97-knc" -> "knc06bgm7733st2576nx5jht4ecjw"

func StorageKey 

func StorageKey(instanceID string) (string, error)

StorageKey converts a puidv7 instance ID to S3 key format: "uuid-prefix" e.g., "knc06bgm7733st2576nx5jht4ecjw" -> "01970a1c-e31e-7422-9cd5-e9651d11cc97-knc"

This format preserves UUIDv7's time-ordering property when used as S3 object keys, while keeping the 3-character type prefix visible for debugging.

Types

type ClusterData 

type ClusterData struct {
	ID     string `json:"id"`
	CACert string `json:"ca_cert"` // CA certificate PEM
}

ClusterData contains cluster information for template processing

type CreateInstanceRequest 

type CreateInstanceRequest struct {
	InstanceID   string                 `json:"instance_id"`   // If empty, will be generated
	Group        string                 `json:"group"`         // Required group reference
	Tenant       string                 `json:"tenant"`        // Tenant identifier
	Template     string                 `json:"template"`      // Template name from configuration (optional override)
	InstanceType string                 `json:"instance_type"` // Override template/group instance type
	SubnetPool   string                 `json:"subnet_pool"`   // Override template/group subnet pool
	Vars         map[string]string      `json:"vars"`          // Additional vars
	Args         map[string]interface{} `json:"args"`          // Override template/group args
	Tags         map[string]string      `json:"tags"`          // Additional instance tags
	OnDemand     bool                   `json:"on_demand"`     // Whether this is an on-demand instance (not managed by group reconciliation)
}

CreateInstanceRequest contains parameters for creating an instance

type CreateInstanceResponse 

type CreateInstanceResponse struct {
	InstanceID         string    `json:"instance_id"`
	Group              string    `json:"group"`
	Template           string    `json:"template"`
	ProviderInstanceID string    `json:"provider_instance_id"`
	Status             string    `json:"status"`
	PrivateIPv4        string    `json:"private_ipv4"`
	PrivateIPv6        string    `json:"private_ipv6"`
	Hostname           string    `json:"hostname"`
	CreatedAt          time.Time `json:"created_at"`
	RegistrationJWT    string    `json:"registration_jwt"`
}

CreateInstanceResponse contains the result of instance creation

type GroupInstanceRequest 

type GroupInstanceRequest struct {
	Group        string                 `json:"group"`
	Template     string                 `json:"template"`
	Count        int                    `json:"count"`
	InstanceType string                 `json:"instance_type"`
	SubnetPool   string                 `json:"subnet_pool"`
	Vars         map[string]string      `json:"vars"`
	Args         map[string]interface{} `json:"args"`
	Tags         map[string]string      `json:"tags"`
}

GroupInstanceRequest represents a request to create instances for a group

type ImageGetter 

type ImageGetter interface {
	GetAll() map[string]string
}

ImageGetter provides access to resolved image IDs

type InstanceData 

type InstanceData struct {
	ID   string `json:"id"`
	Kind string `json:"kind"`
	Arch string `json:"arch"`
	Type string `json:"type"`
}

InstanceData contains instance information for template processing

type InstanceRecord 

type InstanceRecord struct {
	InstanceID         string               `json:"instance_id"`
	Tenant             string               `json:"tenant"`
	Group              string               `json:"group"`
	OnDemand           bool                 `json:"on_demand"`
	ProviderInstanceID string               `json:"provider_instance_id"`
	InstanceType       string               `json:"instance_type"`
	Status             string               `json:"status"`
	PrivateIPv4        string               `json:"private_ipv4"`
	PrivateIPv6        string               `json:"private_ipv6"`
	Hostname           string               `json:"hostname"`
	CreatedAt          time.Time            `json:"created_at"`
	LastUpdated        time.Time            `json:"last_updated"`
	RegistrationJWT    string               `json:"registration_jwt"`
	Config             *config.MergedConfig `json:"config"` // Merged configuration used
	Tags               map[string]string    `json:"tags"`
	InfraConfigHash    string               `json:"infra_config_hash"` // Infra config hash at provision time

	// Registration data (populated after registration completes)
	RegisteredAt  *time.Time `json:"registered_at,omitempty"`
	PublicKeyPEM  string     `json:"public_key_pem,omitempty"`
	CertSerial    string     `json:"cert_serial,omitempty"`
	CertExpiresAt *time.Time `json:"cert_expires_at,omitempty"`
}

InstanceRecord represents the stored instance data

type InstanceStatus 

type InstanceStatus struct {
	InstanceID         string            `json:"instance_id"`
	Group              string            `json:"group"`
	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"`
	CreatedAt          time.Time         `json:"created_at"`
	LastUpdated        time.Time         `json:"last_updated"`
	Tags               map[string]string `json:"tags"`
}

InstanceStatus represents the current state of an instance

type JWTSigner 

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

JWTSigner handles signing of registration nonce JWTs

func NewJWTSigner 

func NewJWTSigner(privateKey ed25519.PrivateKey) *JWTSigner

NewJWTSigner creates a new JWT signer

func (*JWTSigner) GenerateRegistrationNonce 

func (s *JWTSigner) GenerateRegistrationNonce(params RegistrationNonceParams) (string, error)

GenerateRegistrationNonce generates a registration nonce JWT for the given instance/cluster

type Manager 

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

Manager handles instance lifecycle management

func NewManager 

func NewManager(opts ManagerOptions) (*Manager, error)

NewManager creates a new instance manager

func (*Manager) CreateInstance 

func (m *Manager) CreateInstance(ctx context.Context, req CreateInstanceRequest) (*CreateInstanceResponse, error)

CreateInstance creates a new instance using the specified group and configuration

func (*Manager) DeleteInstance 

func (m *Manager) DeleteInstance(ctx context.Context, instanceID string) error

DeleteInstance deletes an instance

func (*Manager) GetInstanceStatus 

func (m *Manager) GetInstanceStatus(ctx context.Context, instanceID string) (*InstanceStatus, error)

GetInstanceStatus returns the current status of an instance

func (*Manager) RebuildCache 

func (m *Manager) RebuildCache(ctx context.Context) error

RebuildCache rebuilds the local SQLite cache from S3 and provider on leadership acquisition

func (*Manager) UpdateRegistration 

func (m *Manager) UpdateRegistration(ctx context.Context, tenant, instanceID, publicKeyPEM, certSerial string, expiresAt time.Time, providerID *string, privateIPv4, privateIPv6, hostname string) error

UpdateRegistration updates registration data for an instance using read-modify-write. providerID is the provider's instance ID from SQLite (may be nil if provider call failed). privateIPv4, privateIPv6 and hostname are authoritative values reported by the agent.

type ManagerOptions 

type ManagerOptions struct {
	ConfigLoader *config.Loader
	SecretsStore secrets.Store
	Storage      storage.Storage
	LocalDB      *localdb.DB
	Provider     infra.Provider
	ImageGetter  ImageGetter // Optional: can be nil if no images configured
	CACert       []byte      // PEM-encoded CA certificate
	Logger       *slog.Logger
}

ManagerOptions contains options for creating an instance manager

type ProviderData 

type ProviderData struct {
	Kind   string `json:"kind"` // aws, azure, gcp
	Region string `json:"region"`
	Zone   string `json:"zone"`
}

ProviderData contains provider information for template processing

type RegistrationNonceClaims 

type RegistrationNonceClaims struct {
	jwt.RegisteredClaims
	Kind       string `json:"kind"`        // "agent" or "operator"
	Sub        string `json:"sub"`         // instance ID or cluster ID
	ConfigHash string `json:"config_hash"` // group runtime config hash at provision time
	ClusterID  string `json:"cluster_id"`  // cluster ID
	Shard      string `json:"shard"`       // shard/zone
	Group      string `json:"group"`       // group key
	OnDemand   bool   `json:"on_demand"`   // is on-demand instance
	Tenant     string `json:"tenant"`      // tenant identifier
}

RegistrationNonceClaims represents the claims in a registration nonce JWT

type RegistrationNonceParams 

type RegistrationNonceParams struct {
	SubjectID  string        // Instance ID or cluster ID
	Kind       string        // "agent" or "operator"
	ConfigHash string        // Group runtime config hash at provision time
	ClusterID  string        // Cluster ID
	Shard      string        // Shard/zone
	Group      string        // Group key (empty for operator)
	OnDemand   bool          // Is on-demand instance
	Expiry     time.Duration // JWT expiry duration
	Tenant     string        // Tenant identifier (required)
}

RegistrationNonceParams contains parameters for generating a registration nonce JWT

type ServerData 

type ServerData struct {
	Shard            string `json:"shard"`
	RegistrationAddr string `json:"registration_addr"`
	AgentAddr        string `json:"agent_addr"`
	OperatorAddr     string `json:"operator_addr"`
}

ServerData contains server information for template processing

type UserdataTemplateData 

type UserdataTemplateData struct {
	Cluster  ClusterData       `json:"cluster"`
	Server   ServerData        `json:"server"`
	Provider ProviderData      `json:"provider"`
	Instance InstanceData      `json:"instance"`
	Vars     map[string]string `json:"vars"`
	Image    map[string]string `json:"image"` // Resolved image IDs (if any)
	Nonce    string            `json:"nonce"` // Registration nonce JWT
}

UserdataTemplateData contains data available for userdata template processing

Source Files

View all Source files

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.