Help us shape the future of Go! Take the 2026 Go Developer Survey

incusapi

package
v0.17.2 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: AGPL-3.0 Imports: 14 Imported by: 0

Documentation

Overview

Package incusapi is the part of the Incus REST API the Incus runtime uses: the types, with Incus's own JSON names, and a client for them.

It is ours rather than Incus's Go client because the Go vulnerability database records every Incus advisory against the whole lxc/incus module, server flaws included, with no fixed version, so depending on any of it made every call reachable and the build red on every release (notes-incus-runtime.md, As built). The API is plain JSON over HTTPS or a unix socket, with websockets for exec and an HTTP upgrade for SFTP. Only the fields the adapter reads or writes are here; Incus ignores what a request leaves out and the client ignores what a response adds.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsStatus

func IsStatus(err error, status int) bool

IsStatus reports whether err is an answer from Incus with that status.

Types

type Client

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

Client talks to one Incus server, in one project.

func ConnectHTTPS

func ConnectHTTPS(address, serverCertPEM string, client tls.Certificate, project string) (*Client, error)

ConnectHTTPS is a client over HTTPS, presenting a client certificate and accepting only the server certificate given, as PEM, whatever name it carries: Incus servers present self-signed certificates, so they are pinned rather than verified against an authority.

func ConnectUnix

func ConnectUnix(path, project string) *Client

ConnectUnix is a client over the server's unix socket. Nothing is contacted until the first request.

func (*Client) Exec

func (c *Client) Exec(ctx context.Context, instance string, command []string, stdin io.Reader, stdout, stderr io.Writer) (int, error)

Exec runs command in an instance with its stdio on the readers and writers given, and returns its exit status once it ends and its output is copied. stdin may be nil.

func (*Client) Get

func (c *Client) Get(ctx context.Context, path string, q url.Values, out any) (string, error)

Get decodes a sync GET into out and returns its ETag.

func (*Client) Send

func (c *Client) Send(ctx context.Context, method, path string, body any, etag string) error

Send sends a request and, when Incus answers with an operation, waits for it to end.

func (*Client) Upgrade

func (c *Client) Upgrade(ctx context.Context, path, protocol string) (io.ReadWriteCloser, error)

Upgrade opens path as a raw connection speaking protocol, as Incus serves SFTP.

func (*Client) UseTarget

func (c *Client) UseTarget(member string) *Client

UseTarget is the same client, sending requests to one cluster member.

func (*Client) Wait

func (c *Client) Wait(ctx context.Context, id string) (*Operation, error)

Wait waits for an operation to end, and returns it, or its error.

type ClusterMember

type ClusterMember struct {
	ServerName   string   `json:"server_name"`
	Status       string   `json:"status"`
	Architecture string   `json:"architecture"`
	Groups       []string `json:"groups"`
}

ClusterMember is one member of a cluster.

type ImageAlias

type ImageAlias struct {
	Name string `json:"name"`
}

ImageAlias names an image.

type ImageAliasesEntry

type ImageAliasesEntry struct {
	Name   string `json:"name"`
	Target string `json:"target"`
}

ImageAliasesEntry is an image alias.

type ImagePut

type ImagePut struct {
	Properties map[string]string `json:"properties,omitempty"`
}

ImagePut is an image's writable part.

type ImagesPost

type ImagesPost struct {
	ImagePut
	Source  *ImagesPostSource `json:"source"`
	Aliases []ImageAlias      `json:"aliases,omitempty"`
}

ImagesPost creates an image.

type ImagesPostSource

type ImagesPostSource struct {
	Type string `json:"type"`
	Name string `json:"name"`
}

ImagesPostSource is where a new image comes from.

type Instance

type Instance struct {
	InstancePut
	Name     string `json:"name"`
	Type     string `json:"type"`
	Status   string `json:"status"`
	Location string `json:"location"`
	Project  string `json:"project"`
}

Instance is an instance.

func (*Instance) Writable

func (i *Instance) Writable() InstancePut

Writable is the instance's writable part, as PUT takes it.

type InstanceExecPost

type InstanceExecPost struct {
	Command     []string `json:"command"`
	WaitForWS   bool     `json:"wait-for-websocket"`
	Interactive bool     `json:"interactive"`
}

InstanceExecPost runs a command in an instance.

type InstanceFull

type InstanceFull struct {
	Instance
	State *InstanceState `json:"state"`
}

InstanceFull is an instance with its state.

type InstancePut

type InstancePut struct {
	Description string                       `json:"description,omitempty"`
	Profiles    []string                     `json:"profiles"`
	Config      map[string]string            `json:"config"`
	Devices     map[string]map[string]string `json:"devices"`
}

InstancePut is an instance's writable part.

type InstanceSource

type InstanceSource struct {
	Type        string `json:"type"`
	Server      string `json:"server,omitempty"`
	Protocol    string `json:"protocol,omitempty"`
	Alias       string `json:"alias,omitempty"`
	Fingerprint string `json:"fingerprint,omitempty"`
}

InstanceSource is where a new instance comes from.

type InstanceState

type InstanceState struct {
	Status  string                          `json:"status"`
	CPU     InstanceStateCPU                `json:"cpu"`
	Memory  InstanceStateMemory             `json:"memory"`
	Network map[string]InstanceStateNetwork `json:"network"`
}

InstanceState is what an instance is doing now.

type InstanceStateCPU

type InstanceStateCPU struct {
	Usage int64 `json:"usage"`
}

InstanceStateCPU is CPU time used, in nanoseconds.

type InstanceStateMemory

type InstanceStateMemory struct {
	Usage int64 `json:"usage"`
}

InstanceStateMemory is memory used, in bytes.

type InstanceStateNetwork

type InstanceStateNetwork struct {
	Addresses []InstanceStateNetworkAddress `json:"addresses"`
	Hwaddr    string                        `json:"hwaddr"`
}

InstanceStateNetwork is one interface as the guest reports it.

type InstanceStateNetworkAddress

type InstanceStateNetworkAddress struct {
	Family  string `json:"family"`
	Address string `json:"address"`
	Netmask string `json:"netmask"`
	Scope   string `json:"scope"`
}

InstanceStateNetworkAddress is one address on an interface.

type InstanceStatePut

type InstanceStatePut struct {
	Action  string `json:"action"`
	Timeout int    `json:"timeout"`
	Force   bool   `json:"force"`
}

InstanceStatePut starts or stops an instance.

type InstanceType

type InstanceType string

InstanceType is "virtual-machine" or "container".

const (
	InstanceTypeVM        InstanceType = "virtual-machine"
	InstanceTypeContainer InstanceType = "container"
	InstanceTypeAny       InstanceType = ""
)

type InstancesPost

type InstancesPost struct {
	InstancePut
	Name   string         `json:"name"`
	Type   InstanceType   `json:"type"`
	Source InstanceSource `json:"source"`
}

InstancesPost creates an instance.

type Network

type Network struct {
	NetworkPut
	Name    string   `json:"name"`
	Type    string   `json:"type"`
	Managed bool     `json:"managed"`
	Project string   `json:"project"`
	UsedBy  []string `json:"used_by"`
}

Network is a network.

func (*Network) Writable

func (n *Network) Writable() NetworkPut

Writable is the network's writable part, as PUT takes it.

type NetworkACL

type NetworkACL struct {
	NetworkACLPost
	NetworkACLPut
}

NetworkACL is an ACL.

type NetworkACLPost

type NetworkACLPost struct {
	Name string `json:"name"`
}

NetworkACLPost names an ACL.

type NetworkACLPut

type NetworkACLPut struct {
	Description string            `json:"description,omitempty"`
	Ingress     []NetworkACLRule  `json:"ingress"`
	Egress      []NetworkACLRule  `json:"egress"`
	Config      map[string]string `json:"config"`
}

NetworkACLPut is an ACL's writable part.

type NetworkACLRule

type NetworkACLRule struct {
	Action          string `json:"action"`
	Source          string `json:"source,omitempty"`
	Destination     string `json:"destination,omitempty"`
	Protocol        string `json:"protocol,omitempty"`
	SourcePort      string `json:"source_port,omitempty"`
	DestinationPort string `json:"destination_port,omitempty"`
	Description     string `json:"description,omitempty"`
	State           string `json:"state"`
}

NetworkACLRule is one rule of an ACL.

type NetworkACLsPost

type NetworkACLsPost struct {
	NetworkACLPost
	NetworkACLPut
}

NetworkACLsPost creates an ACL.

type NetworkPut

type NetworkPut struct {
	Description string            `json:"description,omitempty"`
	Config      map[string]string `json:"config"`
}

NetworkPut is a network's writable part.

type Operation

type Operation struct {
	ID         string                     `json:"id"`
	Status     string                     `json:"status"`
	StatusCode int                        `json:"status_code"`
	Err        string                     `json:"err"`
	Metadata   map[string]json.RawMessage `json:"metadata"`
}

Operation is a background operation.

type Profile

type Profile struct {
	ProfilePut
	Name string `json:"name"`
}

Profile is a profile.

type ProfilePut

type ProfilePut struct {
	Config  map[string]string            `json:"config"`
	Devices map[string]map[string]string `json:"devices"`
}

ProfilePut is a profile's writable part.

type Resources

type Resources struct {
	CPU    ResourcesCPU    `json:"cpu"`
	Memory ResourcesMemory `json:"memory"`
}

Resources is a server's hardware.

type ResourcesCPU

type ResourcesCPU struct {
	Total uint64 `json:"total"`
}

ResourcesCPU counts CPU threads.

type ResourcesMemory

type ResourcesMemory struct {
	Used  uint64 `json:"used"`
	Total uint64 `json:"total"`
}

ResourcesMemory is memory in bytes.

type Server

type Server struct {
	APIExtensions []string          `json:"api_extensions"`
	Environment   ServerEnvironment `json:"environment"`
}

Server is GET /1.0.

type ServerEnvironment

type ServerEnvironment struct {
	Architectures   []string `json:"architectures"`
	Project         string   `json:"project"`
	ServerClustered bool     `json:"server_clustered"`
	ServerVersion   string   `json:"server_version"`
}

ServerEnvironment is the server's read-only environment.

type StatusError

type StatusError struct {
	Status  int
	Message string
}

StatusError is an error Incus answered with.

func (*StatusError) Error

func (e *StatusError) Error() string

type StoragePool

type StoragePool struct {
	Name   string `json:"name"`
	Driver string `json:"driver"`
}

StoragePool is a storage pool.

type StorageVolume

type StorageVolume struct {
	StorageVolumePut
	Name        string   `json:"name"`
	Type        string   `json:"type"`
	ContentType string   `json:"content_type"`
	UsedBy      []string `json:"used_by"`
	Location    string   `json:"location"`
}

StorageVolume is a storage volume.

type StorageVolumePut

type StorageVolumePut struct {
	Description string            `json:"description,omitempty"`
	Config      map[string]string `json:"config"`
}

StorageVolumePut is a volume's writable part.

type StorageVolumesPost

type StorageVolumesPost struct {
	StorageVolumePut
	Name        string `json:"name"`
	Type        string `json:"type"`
	ContentType string `json:"content_type"`
}

StorageVolumesPost creates a volume.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL