instances

Documentation

Overview

Package instances manages instances on KraftCloud.

Index

• Constants
• type ConsoleResponseItem
• type CreateRequest
• type CreateRequestServiceGroup
• type CreateRequestVolume
• type CreateResponseItem
• type DeleteResponseItem
• type Feature
• type GetResponseItem
• type GetResponseNetworkInterface
• type GetResponseServiceGroup
• type GetResponseVolume
• type InstancesService
  • func NewInstancesClientFromOptions(opts *options.Options) InstancesService
• type ListResponseItem
• type StartResponseItem
• type StopResponseItem

Constants

const DefaultAutoStart = true

DefaultAutoStart is the default autostart value - whether the instance will start immediately after creation

const Endpoint = "/instances"

Endpoint is the public path for the instances service.

Types

type ConsoleResponseItem

type ConsoleResponseItem struct {
	Status string `json:"status"`
	UUID   string `json:"uuid"`
	Name   string `json:"name"`
	Output string `json:"output"`

	kcclient.APIResponseCommon
}

ConsoleResponseItem is a data item from a response to a GET /instances/console request. https://docs.kraft.cloud/api/v1/instances/#retrieve-the-console-output

type CreateRequest

type CreateRequest struct {
	Name          *string                    `json:"name"`
	Image         string                     `json:"image"`
	Args          []string                   `json:"args"`
	Env           map[string]string          `json:"env"`
	MemoryMB      *int                       `json:"memory_mb"`
	ServiceGroup  *CreateRequestServiceGroup `json:"service_group"`
	Volumes       []CreateRequestVolume      `json:"volumes"`
	Autostart     *bool                      `json:"autostart"`
	Replicas      *int                       `json:"replicas"`
	WaitTimeoutMs *int                       `json:"wait_timeout_ms"`
	Features      []Feature                  `json:"features"`
}

CreateRequest is the payload for a POST /instances request. https://docs.kraft.cloud/api/v1/instances/#creating-a-new-instance

type CreateRequestServiceGroup

type CreateRequestServiceGroup struct {
	UUID     *string                         `json:"uuid"`
	Name     *string                         `json:"name"`
	Services []services.CreateRequestService `json:"services"`
	DNSName  *string                         `json:"dns_name"`
}

type CreateRequestVolume

type CreateRequestVolume struct {
	UUID     string `json:"uuid"`
	Name     string `json:"name"`
	SizeMB   int    `json:"size_mb"`
	At       string `json:"at"`
	ReadOnly *bool  `json:"readonly"`
}

type CreateResponseItem

type CreateResponseItem struct {
	Status      string `json:"status"`
	State       string `json:"state"`
	UUID        string `json:"uuid"`
	Name        string `json:"name"`
	FQDN        string `json:"fqdn"`
	PrivateFQDN string `json:"private_fqdn"`
	PrivateIP   string `json:"private_ip"`
	BootTimeUs  *int   `json:"boot_time_us"` // only if wait_timeout_ms was set in the request

	kcclient.APIResponseCommon
}

CreateResponseItem is a data item from a response to a POST /instances request. https://docs.kraft.cloud/api/v1/instances/#creating-a-new-instance

type DeleteResponseItem

type DeleteResponseItem struct {
	Status        string `json:"status"`
	UUID          string `json:"uuid"`
	Name          string `json:"name"`
	PreviousState string `json:"previous_state"`

	kcclient.APIResponseCommon
}

DeleteResponseItem is a data item from a response to a DELETE /instances request. https://docs.kraft.cloud/api/v1/instances/#deleting-an-instance

type Feature

type Feature string

Feature is a special feature of an instance.

const FeatureScaleToZero Feature = "scale-to-zero"

FeatureScaleToZero indicates that the instance can be scaled to zero.

type GetResponseItem

type GetResponseItem struct {
	Status            string                        `json:"status"`
	UUID              string                        `json:"uuid"`
	Name              string                        `json:"name"`
	CreatedAt         string                        `json:"created_at"`
	State             string                        `json:"state"`
	Image             string                        `json:"image"`
	MemoryMB          int                           `json:"memory_mb"`
	Args              []string                      `json:"args"`
	Env               map[string]string             `json:"env"`
	FQDN              string                        `json:"fqdn"`
	PrivateFQDN       string                        `json:"private_fqdn"`
	PrivateIP         string                        `json:"private_ip"`
	ServiceGroup      *GetResponseServiceGroup      `json:"service_group"`
	Volumes           []GetResponseVolume           `json:"volumes"`
	NetworkInterfaces []GetResponseNetworkInterface `json:"network_interfaces"`
	BootTimeUs        int                           `json:"boot_time_us"` // always returned, even if never started

	kcclient.APIResponseCommon
}

GetResponseItem is a data item from a response to a GET /instances request. https://docs.kraft.cloud/api/v1/instances/#getting-the-status-of-an-instance

type GetResponseNetworkInterface

type GetResponseNetworkInterface struct {
	UUID      string `json:"uuid"`
	PrivateIP string `json:"private_ip"`
	MAC       string `json:"mac"`
}

type GetResponseServiceGroup

type GetResponseServiceGroup struct {
	UUID string `json:"uuid"`
	Name string `json:"name"`
}

type GetResponseVolume

type GetResponseVolume struct {
	UUID     string `json:"uuid"`
	Name     string `json:"name"`
	At       string `json:"at"`
	ReadOnly bool   `json:"readonly"`
}

type InstancesService

type InstancesService interface {
	kcclient.ServiceClient[InstancesService]

	// Creates one or more new instances of the specified Unikraft images. You can
	// describe the properties of the new instances such as their startup
	// arguments and amount of memory. Note that, the instance properties can only
	// be defined during creation. They cannot be changed later.
	//
	// See: https://docs.kraft.cloud/api/v1/instances/#creating-a-new-instance
	Create(ctx context.Context, req CreateRequest) (*CreateResponseItem, error)

	// GetByUUIDs returns the current state and the configuration of one or
	// more instance(s) based on the provided UUID(s).
	//
	// See: https://docs.kraft.cloud/api/v1/instances/#getting-the-status-of-an-instance
	GetByUUIDs(ctx context.Context, uuids ...string) ([]GetResponseItem, error)

	// GetByNames returns the current state and the configuration of one or
	// more instances based on the provided name(s).
	//
	// See: https://docs.kraft.cloud/api/v1/instances/#getting-the-status-of-an-instance
	GetByNames(ctx context.Context, names ...string) ([]GetResponseItem, error)

	// DeleteByUUIDs deletes the specified instances based on their UUID.
	// After this call the UUIDs of the instances are no longer valid. If the
	// instances are currently running, they are force stopped.
	//
	// See: https://docs.kraft.cloud/api/v1/instances/#deleting-an-instance
	DeleteByUUIDs(ctx context.Context, uuids ...string) ([]DeleteResponseItem, error)

	// DeleteByNames deletes the specified instances based on their names.
	// After this call the UUIDs of the instances are no longer valid. If the
	// instances are currently running, they are force stopped.
	//
	// See: https://docs.kraft.cloud/api/v1/instances/#deleting-an-instance
	DeleteByNames(ctx context.Context, names ...string) ([]DeleteResponseItem, error)

	// Lists all existing instances.
	//
	// See: https://docs.kraft.cloud/api/v1/instances/#list-existing-instances
	List(ctx context.Context) ([]ListResponseItem, error)

	// Starts a previously stopped instance(s) based on their UUID(s).
	// Does nothing for instances that are already running.
	//
	// See: https://docs.kraft.cloud/api/v1/instances/#starting-an-instance
	StartByUUIDs(ctx context.Context, waitTimeoutMs int, uuids ...string) ([]StartResponseItem, error)

	// Starts a previously stopped instance(s) based on their name(s).
	// Does nothing for instances that are already running.
	//
	// See: https://docs.kraft.cloud/api/v1/instances/#starting-an-instance
	StartByNames(ctx context.Context, waitTimeoutMs int, names ...string) ([]StartResponseItem, error)

	// StopByUUIDs stops the specified instance(s) based on their UUID(s), but
	// does not destroy them.  All volatile state (e.g., RAM contents) is lost.
	// Does nothing for instances that are already stopped. Instances can be
	// started again with the start endpoint.
	//
	// See: https://docs.kraft.cloud/api/v1/instances/#stopping-an-instance
	StopByUUIDs(ctx context.Context, drainTimeoutMs int, uuid ...string) ([]StopResponseItem, error)

	// StopByNames stops the specified instance(s) based on their name(s), but
	// does not destroy them.  All volatile state (e.g., RAM contents) is lost.
	// Does nothing for instances that are already stopped. Instances can be
	// started again with the start endpoint.
	//
	// See: https://docs.kraft.cloud/api/v1/instances/#stopping-an-instance
	StopByNames(ctx context.Context, drainTimeoutMs int, names ...string) ([]StopResponseItem, error)

	// ConsoleByName returns the console output of the specified instance based
	// on its name.
	//
	// See: https://docs.kraft.cloud/api/v1/instances/#retrieve-the-console-output
	ConsoleByName(ctx context.Context, name string, maxLines int, latest bool) (*ConsoleResponseItem, error)

	// ConsoleByUUID returns the console output of the specified instance based
	// on its UUID.
	//
	// See: https://docs.kraft.cloud/api/v1/instances/#retrieve-the-console-output
	ConsoleByUUID(ctx context.Context, uuid string, maxLines int, latest bool) (*ConsoleResponseItem, error)
}

func NewInstancesClientFromOptions

func NewInstancesClientFromOptions(opts *options.Options) InstancesService

NewInstancesClientFromOptions instantiates a new instances services client based on the provided pre-existing options.

type ListResponseItem

type ListResponseItem struct {
	UUID string `json:"uuid"`
	Name string `json:"name"`

	kcclient.APIResponseCommon
}

ListResponseItem is a data item from a response to a GET /instances/list request. https://docs.kraft.cloud/api/v1/instances/#list-existing-instances

type StartResponseItem

type StartResponseItem struct {
	Status        string `json:"status"`
	UUID          string `json:"uuid"`
	Name          string `json:"name"`
	State         string `json:"state"`
	PreviousState string `json:"previous_state"`

	kcclient.APIResponseCommon
}

StartResponseItem is a data item from a response to a POST /instances/start request. https://docs.kraft.cloud/api/v1/instances/#starting-an-instance

type StopResponseItem

type StopResponseItem struct {
	Status        string `json:"status"`
	UUID          string `json:"uuid"`
	Name          string `json:"name"`
	State         string `json:"state"`
	PreviousState string `json:"previous_state"`

	kcclient.APIResponseCommon
}

StopResponseItem is a data item from a response to a POST /instances/stop request. https://docs.kraft.cloud/api/v1/instances/#stopping-an-instance