instances

Documentation

Overview

package instances manages instances on KraftCloud.

Index

• Constants
• type CreateInstanceRequest
• type CreateInstanceServiceGroupRequest
• type CreateInstanceVolumeRequest
• type Instance
  • func (i Instance) String() string
• type InstanceFeature
• type InstanceVolume
• type InstancesService
  • func NewInstancesClientFromOptions(opts *options.Options) InstancesService
• type NetworkInterface

Constants

const (
	// DefaultAutoStart is the default autostart value - whether the instance will
	// start immediately after creation
	DefaultAutoStart = true
)

const (
	// Endpoint is the public path for the instances service.
	Endpoint = "/instances"
)

Types

type CreateInstanceRequest

type CreateInstanceRequest struct {
	// Name of the Unikraft image to instantiate. Private images will be available
	// under your user's namespace.
	Image string `json:"image,omitempty"`

	// Application arguments.
	Args []string `json:"args,omitempty"`

	// Amount of memory to assign to the instance in megabytes.
	MemoryMB int64 `json:"memory_mb,omitempty"`

	// Service group to assign the instance to.
	ServiceGroup CreateInstanceServiceGroupRequest `json:"service_group,omitempty"`

	// Description of volumes
	Volumes []CreateInstanceVolumeRequest `json:"volumes,omitempty"`

	// Any special features to enable.
	Features []InstanceFeature `json:"features,omitempty"`

	// Autostart behavior. If true the instance will start immediately after
	// creation.
	Autostart bool `json:"autostart,omitempty"`

	// Number of replicas to create with these properties.
	Replicas int `json:"replicas,omitempty"`

	// Key/value pairs to be set as environment variables at boot time.
	// Values must be strings.
	Env map[string]string `json:"env,omitempty"`

	// Name of the created instance. If not set, a random name will be generated.
	Name string `json:"name,omitempty"`
}

CreateInstanceRequest holds all the data necessary to create an instance via the API.

See: https://docs.kraft.cloud/002-rest-api-v1-instances.html#create

type CreateInstanceServiceGroupRequest

type CreateInstanceServiceGroupRequest struct {
	// Name of the existing service group.
	Name string `json:"name,omitempty"`

	// UUID of the existing service group.
	UUID string `json:"uuid,omitempty"`

	// The DNS name under which the group is accessible from the internet.  If the
	// DNSName is terminates with a `.` it represents a FQDN, otherwise the
	// provided string will be used as subdomain on the given metro.
	DNSName string `json:"dns_name,omitempty"`

	// Services contains the descriptions of exposed network services.
	Services []services.Service `json:"services,omitempty"`
}

type CreateInstanceVolumeRequest

type CreateInstanceVolumeRequest struct {
	// Name of the existing service group.
	Name string `json:"name,omitempty"`

	// UUID of the existing service group.
	UUID string `json:"uuid,omitempty"`

	// Size of the new volume in megabytes.
	SizeMB int `json:"size_mb,omitempty"`

	// Path of the mountpoint. Must be empty. Automatically created if it does not
	// exist.
	At string `json:"at,omitempty"`

	// Whether the volume should be mounted read-only.
	ReadOnly bool `json:"readonly,omitempty"`
}

type Instance

type Instance struct {
	// UUID of the instance.
	UUID string `json:"uuid,omitempty"`

	// Name of the instance.
	Name string `json:"name,omitempty"`

	// Publicly accessible FQDN name of the instance.
	FQDN string `json:"fqdn,omitempty"`

	// Private IPv4 of the instance in CIDR notation for communication between
	// instances of the same user. This is equivalent to the IPv4 address of the
	// first network interface.
	PrivateIP string `json:"private_ip,omitempty"`

	// Private fully qualified domain name of the instance for communication
	// between instances of the same user.
	PrivateFQDN string `json:"private_fqdn,omitempty"`

	// Current state of the instance or error if the request failed.
	State string `json:"state,omitempty"`

	// Date and time of creation in ISO8601.
	CreatedAt string `json:"created_at,omitempty"`

	// Digest of the image that the instance uses.  Note that the image tag (e.g.,
	// latest) is translated by KraftCloud to the image digest that was assigned
	// the tag at the time of instance creation. The image is pinned to this
	// particular version.
	Image string `json:"image,omitempty"`

	// Amount of memory assigned to the instance in megabytes.
	MemoryMB int `json:"memory_mb,omitempty"`

	// Application arguments.
	Args []string `json:"args,omitempty"`

	// Key/value pairs to be set as environment variables at boot time.
	Env map[string]string `json:"env,omitempty"`

	// The service group that the instance is part of.
	ServiceGroup *services.ServiceGroup `json:"service_group,omitempty"`

	// Description of volumes.
	Volumes []InstanceVolume `json:"volumes,omitempty"`

	// Special features of the instance.
	Features []InstanceFeature `json:"features,omitempty"`

	// List of network interfaces attached to the instance.
	NetworkInterfaces []NetworkInterface `json:"network_interfaces,omitempty"`

	// Time it took to start the instance including booting Unikraft in
	// microseconds.
	BootTimeUS int64 `json:"boot_time_us,omitempty"`

	// When an instance has a specific issue an accompanying message is included
	// to help diagnose the state of the instance.
	Message string `json:"message,omitempty"`

	// An error response code dictating the specific error type.
	Error int64 `json:"error,omitempty"`

	// Base 64 encoded console output.
	Output string `json:"output,omitempty"`
}

Instance holds the description of the KraftCloud compute instance, as understood by the API server.

See: https://docs.kraft.cloud/002-rest-api-v1-instances.html#response_2

func (Instance) String

func (i Instance) String() string

String implements fmt.Stringer

type InstanceFeature

type InstanceFeature string

InstanceFeature is a special feature of an instance.

const (
	// FeatureScaleToZero indicates that the instance can be scaled to zero.
	FeatureScaleToZero InstanceFeature = "scale-to-zero"
)

type InstanceVolume

type InstanceVolume struct {
	// UUID of the volume
	UUID string `json:"uuid,omitempty"`

	// Name of the volume
	Name string `json:"name,omitempty"`

	// Path of the mountpoint
	At string `json:"at,omitempty"`

	// Whether the volume is mounted read-only
	ReadOnly bool `json:"readonly,omitempty"`
}

type InstancesService

type InstancesService interface {
	client.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/002-rest-api-v1-instances.html#create
	Create(ctx context.Context, req CreateInstanceRequest) (*Instance, error)

	// GetByUUID returns the current state and the configuration of an instance
	// based on the provided UUID.
	//
	// See: https://docs.kraft.cloud/002-rest-api-v1-instances.html#state
	GetByUUID(ctx context.Context, uuid string) (*Instance, error)

	// GetByName returns the current state and the configuration of an instance
	// based on the provided name.
	//
	// See: https://docs.kraft.cloud/002-rest-api-v1-instances.html#state
	GetByName(ctx context.Context, name string) (*Instance, error)

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

	// StopByUUID the specified instance based on its UUID, but does not destroy
	// it.  All volatile state (e.g., RAM contents) is lost. Does nothing for an
	// instance that is already stopped. The instance can be started again with
	// the start endpoint.
	//
	// See: https://docs.kraft.cloud/002-rest-api-v1-instances.html#stop
	StopByUUID(ctx context.Context, uuid string, drainTimeoutMS int64) (*Instance, error)

	// Stops the specified instance based on its name, but does not destroy it.
	// All volatile state (e.g., RAM contents) is lost. Does nothing for an
	// instance that is already stopped. The instance can be started again with
	// the start endpoint.
	//
	// See: https://docs.kraft.cloud/002-rest-api-v1-instances.html#stop
	StopByName(ctx context.Context, name string, drainTimeoutMS int64) (*Instance, error)

	// Starts a previously stopped instance based on its UUID. Does nothing for an
	// instance that is already running.
	//
	// See: https://docs.kraft.cloud/002-rest-api-v1-instances.html#start
	StartByUUID(ctx context.Context, uuid string, waitTimeoutMS int) (*Instance, error)

	// Starts a previously stopped instance based on its name. Does nothing for an
	// instance that is already running.
	//
	// See: https://docs.kraft.cloud/002-rest-api-v1-instances.html#start
	StartByName(ctx context.Context, name string, waitTimeoutMS int) (*Instance, error)

	// DeleteByUUID the specified instance based on its UUID. After this call the
	// UUID of the instance is no longer valid. If the instance is currently
	// running it is force stopped.
	//
	// See: https://docs.kraft.cloud/002-rest-api-v1-instances.html#delete
	DeleteByUUID(ctx context.Context, uuid string) error

	// DeleteByName deletes the specified instance based on its name. After this
	// call the UUID of the instance is no longer valid. If the instance is
	// currently running it is force stopped.
	//
	// See: https://docs.kraft.cloud/002-rest-api-v1-instances.html#delete
	DeleteByName(ctx context.Context, name string) error

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

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

func NewInstancesClientFromOptions

func NewInstancesClientFromOptions(opts *options.Options) InstancesService

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

type NetworkInterface

type NetworkInterface struct {
	// UUID of the network interface.
	UUID string `json:"uuid,omitempty"`

	// Name of the network interface.
	Name string `json:"name,omitempty"`

	// Private IPv4 of network interface in CIDR notation.
	PrivateIP string `json:"private_ip,omitempty"`

	// MAC address of the network interface.
	MAC string `json:"mac,omitempty"`
}

NetworkInterface holds interface data returned by the Instance API.