incus

package
v0.1.5 Latest Latest
Warning

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

 Go to latest Published: Sep 16, 2026 License: Apache-2.0, MIT Imports: 31 Imported by: 0

Documentation

Overview

Package incus implements the compute.Backend seam over the Incus API.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

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

Client is the Incus adapter used by compute.Service.

func New 

func New(ctx context.Context, opts Options) (*Client, error)

New connects to Incus and returns a Client.

func (*Client) AddACLRule 

func (c *Client) AddACLRule(
	ctx context.Context,
	sandbox, network string,
	rule compute.ACLRule,
) (compute.ACLRule, error)

func (*Client) AttachNIC 

func (c *Client) AttachNIC(ctx context.Context, ref compute.Ref, network, nic, ip, mac string) (compute.NIC, error)

AttachNIC adds a nic device on a metadata-resolved network.

func (*Client) BeginCreateInstance 

func (c *Client) BeginCreateInstance(ctx context.Context, req compute.CreateInstance) (compute.PendingInstance, error)

BeginCreateInstance copies the image if needed and accepts the create request.

func (*Client) Close 

func (c *Client) Close() error

Close releases background Incus client resources.

func (*Client) CreateForward 

func (c *Client) CreateForward(
	ctx context.Context,
	sandbox, network string,
	ref compute.Ref,
	port, listenPort int64,
	protocol string,
) (compute.Forward, error)

func (*Client) CreateNetwork 

func (c *Client) CreateNetwork(ctx context.Context, sandbox string, network compute.Network) (compute.Network, error)

CreateNetwork defines a bridge in the default project or an OVN network in the sandbox project.

func (*Client) CreateSandbox 

func (c *Client) CreateSandbox(ctx context.Context, sandbox compute.Sandbox) error

CreateSandbox creates a restricted project and its default network.

func (*Client) CreateSnapshot 

func (c *Client) CreateSnapshot(ctx context.Context, ref compute.Ref, snapshot string) error

CreateSnapshot creates a stateless instance snapshot.

func (*Client) DeleteFile 

func (c *Client) DeleteFile(ctx context.Context, ref compute.Ref, path string) error

DeleteFile removes a guest file through the Incus agent.

func (*Client) DeleteInstance 

func (c *Client) DeleteInstance(ctx context.Context, ref compute.Ref) error

DeleteInstance force-stops and deletes one guest, including snapshots.

func (*Client) DeleteNetwork 

func (c *Client) DeleteNetwork(ctx context.Context, sandbox, name string) error

DeleteNetwork removes an owned network after dependents are gone.

func (*Client) DeleteSandbox 

func (c *Client) DeleteSandbox(ctx context.Context, name string) error

DeleteSandbox removes sandbox resources in dependency order.

Partial failures are returned so the reaper can retry. The project is never deleted while owned networks still exist.

func (*Client) DeleteSnapshot 

func (c *Client) DeleteSnapshot(ctx context.Context, ref compute.Ref, snapshot string) error

DeleteSnapshot deletes one instance snapshot.

func (*Client) DetachNIC 

func (c *Client) DetachNIC(ctx context.Context, ref compute.Ref, nic string) error

DetachNIC removes a NIC device from an instance.

func (*Client) EnsureCatalog 

func (c *Client) EnsureCatalog(ctx context.Context, images []compute.CatalogImage) ([]compute.CatalogImage, error)

EnsureCatalog imports catalog images into the image-build project and returns copies with derived fingerprints.

Lab-built imgoci digest references are fetched, verified, imported, and promoted to a local alias only after a successful smoke launch. A matching agentcompute.digest on the current alias skips import and smoke. Upstream remote:alias references only ensure the Incus remote exists. Returned entries keep the original Reference.

func (*Client) Exec 

func (c *Client) Exec(ctx context.Context, req compute.ExecRequest, stdout, stderr io.Writer) (int64, error)

Exec runs a command and drains stdout/stderr. Cancellation sends SIGKILL over the exec control websocket and then waits a bounded teardown.

func (*Client) ExtendSandbox 

func (c *Client) ExtendSandbox(ctx context.Context, name string, expires time.Time) (compute.Sandbox, error)

ExtendSandbox writes a new expiry with an ETag update.

func (*Client) GetInstance 

func (c *Client) GetInstance(ctx context.Context, ref compute.Ref) (compute.Instance, error)

GetInstance returns observed guest state from GetInstanceFull.

func (*Client) GetNetwork 

func (c *Client) GetNetwork(ctx context.Context, sandbox, name string) (compute.Network, error)

GetNetwork returns one owned agent-facing network.

func (*Client) GetSandbox 

func (c *Client) GetSandbox(ctx context.Context, name string) (compute.Sandbox, error)

GetSandbox returns one owned sandbox.

func (*Client) GetSandboxImage 

func (c *Client) GetSandboxImage(ctx context.Context, sandbox, name string) (compute.CatalogImage, error)

GetSandboxImage returns a published sandbox-local image as a catalog entry.

func (*Client) InstanceForward 

func (c *Client) InstanceForward(
	ctx context.Context,
	ref compute.Ref,
	targetPort int64,
	protocol string,
) (compute.Forward, error)

InstanceForward observes the scalar forward shape created by net.forward.

func (*Client) ListInstances 

func (c *Client) ListInstances(ctx context.Context, sandbox string) ([]compute.Instance, error)

ListInstances returns guests in a sandbox project.

func (*Client) ListNetworks 

func (c *Client) ListNetworks(ctx context.Context, sandbox string) ([]compute.Network, error)

ListNetworks returns agent-facing networks owned by the sandbox.

Ownership is resolved from network metadata and project reservations, never by parsing physical names.

func (*Client) ListSandboxes 

func (c *Client) ListSandboxes(ctx context.Context) ([]compute.Sandbox, error)

ListSandboxes returns owned sandbox projects.

func (*Client) ListSnapshots 

func (c *Client) ListSnapshots(ctx context.Context, ref compute.Ref) ([]compute.Snapshot, error)

ListSnapshots returns snapshots for one guest.

func (*Client) OpenExec 

func (c *Client) OpenExec(ctx context.Context, req compute.ExecRequest) (io.ReadWriteCloser, error)

OpenExec starts a guest command and returns attached stdin/stdout. Close sends SIGKILL and waits a bounded teardown. The start context does not bound a successful stream.

func (*Client) PeerNetworks 

func (c *Client) PeerNetworks(ctx context.Context, sandbox, network, peer string) error

func (*Client) PinSandbox added in v0.1.5 

func (c *Client) PinSandbox(
	ctx context.Context,
	name string,
	pinned bool,
	subject string,
	since time.Time,
) (compute.Sandbox, error)

PinSandbox persists pin metadata with an ETag update, preserving expiry.

func (*Client) PublishInstance 

func (c *Client) PublishInstance(ctx context.Context, ref compute.Ref, image string) (string, error)

PublishInstance creates a project-local image alias from a guest.

The image stays in the sandbox project. Catalog copies already in the project are left untouched and nothing is published to a remote or the default project.

func (*Client) ReadBinaryFile 

func (c *Client) ReadBinaryFile(ctx context.Context, ref compute.Ref, path string) (io.ReadCloser, error)

ReadBinaryFile opens a guest file without passing bytes through exec or text conversion. The caller must close the stream and enforce its own byte bound.

func (*Client) ReadFile 

func (c *Client) ReadFile(ctx context.Context, req compute.FileReadRequest) (compute.FileReadResult, error)

ReadFile pulls a bounded guest file through the Incus agent.

func (*Client) RemoteImage 

func (c *Client) RemoteImage(ctx context.Context, name string) (incusclient.ImageServer, error)

RemoteImage returns an image server for an existing client remote.

The default images simplestreams remote is ensured in memory and is not written back to the on-disk Incus config.

func (*Client) RemoveACLRule 

func (c *Client) RemoveACLRule(ctx context.Context, sandbox, network, ruleID string) error

func (*Client) RestartInstance 

func (c *Client) RestartInstance(ctx context.Context, ref compute.Ref, force bool) (compute.Instance, error)

RestartInstance restarts a guest and waits until it is running.

func (*Client) RestoreSnapshot 

func (c *Client) RestoreSnapshot(ctx context.Context, ref compute.Ref, snapshot string) error

RestoreSnapshot recreates a guest from a snapshot without relaxing project restrictions.

func (*Client) Scoped 

func (c *Client) Scoped(ctx context.Context, project, target string) incusclient.InstanceServer

Scoped returns a request-scoped Incus client.

Incus WithContext mutates the receiver, so Scoped always clones with UseProject then UseTarget before WithContext.

func (*Client) StartInstance 

func (c *Client) StartInstance(ctx context.Context, ref compute.Ref, force bool) (compute.Instance, error)

StartInstance starts a guest and waits until it is running.

func (*Client) StopInstance 

func (c *Client) StopInstance(ctx context.Context, ref compute.Ref, force bool) (compute.Instance, error)

StopInstance stops a guest and waits until it is stopped.

func (*Client) WaitInstance 

func (c *Client) WaitInstance(ctx context.Context, req compute.WaitRequest) (compute.WaitResult, error)

WaitInstance polls guest state until the requested stage is reached.

func (*Client) WriteFile 

func (c *Client) WriteFile(ctx context.Context, req compute.FileWriteRequest) (compute.FileWriteResult, error)

WriteFile pushes a bounded guest file through the Incus agent.

type Options 

type Options struct {
	// Remote is an existing Incus client remote name from the local config.
	Remote string

	// URL is an explicit daemon URL. When set it overrides Remote.
	URL string

	// ClientCert is a PEM document or path to the client certificate.
	ClientCert string

	// ClientKey is a PEM document or path to the client key.
	ClientKey string

	// ServerCert is a PEM document or path to the remote server certificate.
	ServerCert string

	// Host is the slice-1 cluster member that owns bridge-backed sandboxes.
	Host string

	// Pool is the storage pool used for explicit root disks.
	Pool string

	// OVNUplink is the default-project physical network for sandbox OVN networks.
	OVNUplink string

	// OVNRanges is the external subnet authorization on the physical uplink.
	OVNRanges string
}

Options configures an Incus API client.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.