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 ¶
- func IsStatus(err error, status int) bool
- type Client
- func (c *Client) Exec(ctx context.Context, instance string, command []string, stdin io.Reader, ...) (int, error)
- func (c *Client) Get(ctx context.Context, path string, q url.Values, out any) (string, error)
- func (c *Client) Send(ctx context.Context, method, path string, body any, etag string) error
- func (c *Client) Upgrade(ctx context.Context, path, protocol string) (io.ReadWriteCloser, error)
- func (c *Client) UseTarget(member string) *Client
- func (c *Client) Wait(ctx context.Context, id string) (*Operation, error)
- type ClusterMember
- type ImageAlias
- type ImageAliasesEntry
- type ImagePut
- type ImagesPost
- type ImagesPostSource
- type Instance
- type InstanceExecPost
- type InstanceFull
- type InstancePut
- type InstanceSource
- type InstanceState
- type InstanceStateCPU
- type InstanceStateMemory
- type InstanceStateNetwork
- type InstanceStateNetworkAddress
- type InstanceStatePut
- type InstanceType
- type InstancesPost
- type Network
- type NetworkACL
- type NetworkACLPost
- type NetworkACLPut
- type NetworkACLRule
- type NetworkACLsPost
- type NetworkPut
- type Operation
- type Profile
- type ProfilePut
- type Resources
- type ResourcesCPU
- type ResourcesMemory
- type Server
- type ServerEnvironment
- type StatusError
- type StoragePool
- type StorageVolume
- type StorageVolumePut
- type StorageVolumesPost
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
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 ¶
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) Send ¶
Send sends a request and, when Incus answers with an operation, waits for it to end.
func (*Client) Upgrade ¶
Upgrade opens path as a raw connection speaking protocol, as Incus serves SFTP.
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 ImageAliasesEntry ¶
ImageAliasesEntry is an image alias.
type ImagesPost ¶
type ImagesPost struct {
ImagePut
Source *ImagesPostSource `json:"source"`
Aliases []ImageAlias `json:"aliases,omitempty"`
}
ImagesPost creates an image.
type ImagesPostSource ¶
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 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 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 ¶
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 ¶
StatusError is an error Incus answered with.
func (*StatusError) Error ¶
func (e *StatusError) Error() string
type StoragePool ¶
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.