instance

Documentation

Overview

Package instance manages instances on KraftCloud.

Index

• Constants
• type CreateInstanceRequest
• type CreateInstanceServicesRequest
• type Instance
  • func (c *Instance) GetFieldByPrettyTag(tag string) string
• type InstanceStopRequest
• type InstancesService
  • func NewInstancesClient(opts ...kraftcloud.Option) InstancesService
  • func NewInstancesClientFromOptions(opts *kraftcloud.Options) InstancesService
• type NetworkInterface

Constants

const (
	// DefaultHandler sets the connection handler. The API only accepts "tls" for
	// now.
	DefaultHandler = "tls"

	// 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"`

	// Description of exposed network services.
	Services []CreateInstanceServicesRequest `json:"services,omitempty"`

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

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

	// Key/value pairs to be set as environment variables at boot time.
	// Values must be strings.
	Env map[string]string `json:"env,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 CreateInstanceServicesRequest

type CreateInstanceServicesRequest struct {
	// Public-facing Port
	Port int `json:"port,omitempty"`

	// Port that the image listens on.
	InternalPort int `json:"internal_port,omitempty"`

	// Connection handlers. Must be [ "tls" ].
	Handlers []string `json:"handlers,omitempty"`
}

CreateInstanceServicesRequest contains the description of an exposed network service.

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

type Instance

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

	// Publicly accessible DNS name of the instance.
	DNS string `json:"dns,omitempty" pretty:"DNS"`

	// 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" pretty:"PrivateIP"`

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

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

	// 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" pretty:"Image"`

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

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

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

	// UUID of the service group that the instance is part of.
	ServiceGroup string `json:"service_group,omitempty" pretty:"Service Group"`

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

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

	// 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) GetFieldByPrettyTag

func (c *Instance) GetFieldByPrettyTag(tag string) string

type InstanceStopRequest

type InstanceStopRequest struct {
	// Timeout for draining connections in milliseconds. The instance does not
	// receive new connections in the draining phase. The instance is stopped when
	// the last connection has been closed or the timeout expired.
	DrainTimeoutMS int64 `json:"drain_timeout_ms,omitempty"`
}

InstanceStopRequest carries the data used by stop instance requests.

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

type InstancesService

type InstancesService interface {
	kraftcloud.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)

	// Status returns the current status and the configuration of an instance.
	//
	// See: https://docs.kraft.cloud/002-rest-api-v1-instances.html#status
	Status(ctx context.Context, uuid 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)

	// Stops the specified instance, 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
	Stop(ctx context.Context, uuid string, drainTimeoutMS int64) (*Instance, error)

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

	// Deletes the specified instance. 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
	Delete(ctx context.Context, uuid string) error

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

func NewInstancesClient

func NewInstancesClient(opts ...kraftcloud.Option) InstancesService

NewInstancesClient instantiates a client which interfaces with KraftCloud's instances API.

func NewInstancesClientFromOptions

func NewInstancesClientFromOptions(opts *kraftcloud.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"`

	// 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.