pyincus

Description

This library was written to be able to use Incus with Python. There are some solutions out there but they either lack features or they are limiting in what our projects requires.

The library uses the Incus client installed on your machine to work. Meaning that you need to manually create remotes in your Incus for this library to work. This way, it's possible to use this library for remotes that requires more than just a certificate or a password.

Usage

Incus

The object Incus contains the methods to run commands on the system. It is also there that you can set the variable cwd in case you are running your code in a directory where you don't have the permission to write. You can also use the check() method to see if the library match the version of Incus.

Methods

• check() - Check Incus version. Raises IncusVersionException if the version does not match.
• run(cmd: str, **kwargs) - Execute cmd on the operation system and returns a dictionary {"data":result, "error":error}. kwargs is passed to subprocess.run().

Attributes

• cwd - Subprocess variable. Changes the execution path.
• remotes - Empty instance of Remote object to gain access to methods like list, get and exists.

Examples

import pyincus

pyincus.incus.cwd = "/"
pyincus.incus.check()

Model

Every object following this one inherite from Model and therefore can use any attribute or method from this object unless overridden.

Methods

• exists(name: str) - Return True if the object exists and False if not.
• list(filter: str) - filter is only used for Instance and NetworkForward. Returns a list of objects depending on the object that used this method.
• refresh() - Refresh the attributes.

Attributes

• attributes - Contains every variable from Incus object.
• name - Read only attribute associated to the Incus object.
• parent - Read only attribute associated to the Incus object.

Remote

Methods

• get(name: str) - Get a specific Remote object.
• rename(name: str) - Equivalent to incus remote rename

Attributes

• incus - Incus object.
• projects - Empty instance of Project object to gain access to methods like list, get and exists.
• addr - Read only attribute associated to the Incus object. Address of the remote object.
• project - Read only attribute associated to the Incus object. Default project name for the remote.
• public - Read only attribute associated to the Incus object. If the remote is public or private.

Examples

import pyincus

# List remotes locally installed on your computer.
print(pyincus.remotes.list())

# Check if the remote exists
if(pyincus.remotes.exists(name="local")):
	# Fetch the remote
	remote = pyincus.remotes.get(name="local")

	print(remote.name)

Project

Methods

• get(name: str) - Get a specific Project object.
• rename(name: str) - Equivalent to incus project rename

Attributes

• acls -
• incus - Incus object.
• remote - Remote object.
• instances - Empty instance of Instance object to gain access to methods like list, get and exists.
• networks - Empty instance of Network object to gain access to methods like list, get and exists.
• config - Attribute associated to the Incus object. Project configuration.
• description - Attribute associated to the Incus object. Project description.
• usedBy - Read only attribute associated to the Incus object. Project used by what other object.

Examples

import pyincus

remote = pyincus.remotes.get(name="local")

# List projects of a given remote.
print(remote.projects.list())

# Check if the project exists
if(remote.projects.exists(name="default")):
	# Fetch the project
	project = remote.projects.get(name="default")

	print(project.name)

Instance

Methods

• get(name: str) - Get a specific Instance object.
• validateImageName(image: str) - Used to validate the image name for Incus compatibility.
• copy(source: str, name: str=None, *, snapshotName: str=None, remoteSource: str=None, remoteDestination: str=None, projectSource: str=None, projectDestination: str=None, config: dict=None, device: dict=None, profile: str=None, mode: str='pull', storage: str=None, allowInconsistent: bool=False, empty: bool=False, instanceOnly: bool=False, noProfile: bool=False, refresh: bool=False, stateless: bool=False, vm: bool=False) - Equivalent to incus copy command.
• delete(force: bool=True) - Equivalent to incus delete command.
• exec(cmd: str) - Equivalent to incus exec command.
• init(image: str, name: str, *, remoteSource: str=None, config: dict=None, device: dict=None, profile: str=None, network: str=None, storage: str=None, empty: bool=False, noProfile: bool=False, vm: bool=False) - Equivalent to incus init command.
• launch(image: str, name: str, *, remoteSource: str=None, config: dict=None, device: dict=None, profile: str=None, network: str=None, storage: str=None, empty: bool=False, noProfile: bool=False, vm: bool=False) - Equivalent to incus launch command.
• pause() - Equivalent to incus pause command.
• rename(name: str) - Equivalent to incus rename command.
• restart(*, force: bool=True, timeout: int=-1) - Equivalent to incus restart command.
• restore(self, name: str, *, stateful: bool=False) - Equivalent to incus restore command.
• save(config: dict=None, devices: dict=None, profiles: list=None, description: str=None) - Equivalent to yaml | incus config edit command.
• snapshot(name: str, *, reuse: bool=False, stateful: bool=False) - Equivalent to incus snapshot command.
• start() - Equivalent to incus start command.
• stop(*, force: bool=True, timeout: int=-1) - Equivalent to incus stop command.

Attributes

• incus - Incus object.
• remote - Remote object.
• project - Project object.
• architecture - Read only attribute associated to the Incus object. Instance architecture.
• backups - Read only attribute associated to the Incus object. Instance backups.
• config - Attribute associated to the Incus object. Instance configuration.
• createdAt - Read only attribute associated to the Incus object. Instance created at.
• description - Attribute associated to the Incus object. Instance description.
• devices - Attribute associated to the Incus object. Instance devices.
• ephemeral - Read only attribute associated to the Incus object. Instance if ephemeral.
• expandedConfig - Read only attribute associated to the Incus object. Instance expanded configuration.
• expandedDevices - Read only attribute associated to the Incus object. Instance expanded devices.
• lastUsedAt - Read only attribute associated to the Incus object. Instance last used at.
• location - Read only attribute associated to the Incus object. Instance location.
• profiles - Attribute associated to the Incus object. A list of instance profiles.
• snapshots - Read only attribute associated to the Incus object. A list of instance snapshots.
• state - Read only attribute associated to the Incus object. Instance state.
• stateful - Read only attribute associated to the Incus object. Instance stateful.
• status - Read only attribute associated to the Incus object. Instance state.
• statusCode - Read only attribute associated to the Incus object. Instance status code.
• type - Read only attribute associated to the Incus object. Instance type.

Examples

import pyincus

remote = pyincus.remotes.get(name="local")
project = remote.projects.get(name="default")

# List instances of a given project.
print(project.instances.list())

# Check if the instance exists
if(project.instances.exists(name="test")):
	# Fetch the instance
	instance = project.instances.get(name="test")

	print(instance.name)

	# If the state of the instance is running, pause it.
	if(instance.state.lower() == "running"):
		instance.pause()
	
	# If the state of the instance is frozen, stop it.
	if(instance.state.lower() == "frozen"):
		instance.stop()

	# Delete the instance.
	instance.delete()

# Create and start an instance.
instance = project.instances.launch(image="ubuntu/22.04", name="test", remoteSource="images", config={"description":"Test description"})

# Get expanded devices, which are the devices coming from the profile.
devices = {"eth0": **instance.expandedDevices["eth0"]}

# Set static IPv4.
devices["eth0"]["ipv4.address"] = "10.0.0.1"

# Set the devices.
instance.devices = devices

# Create a snapshot.
instance.snapshot(name="my-snapshot-name")

# List that the snapshot is created.
print(instance.snapshots)

# Restore the instance snapshot.
instance.restore(name="my-snapshot-name")

Network

Methods

• get(name: str) - Get a specific Network object.

Attributes

• incus - Incus object.
• remote - Remote object.
• project - Project object.
• forwards - Empty instance of NetworkForward object to gain access to methods like list, get and exists.
• config - Read only attribute associated to the Incus object. Network configuration.
• description - Read only attribute associated to the Incus object. Network description.
• locations - Read only attribute associated to the Incus object. Network locations
• managed - Read only attribute associated to the Incus object. Network managed.
• status - Read only attribute associated to the Incus object. Network status.
• type - Read only attribute associated to the Incus object. Network type.
• usedBy - Read only attribute associated to the Incus object. Network used by what other object.

Examples

import pyincus

remote = pyincus.remotes.get(name="local")
project = remote.projects.get(name="default")

# List networks of a given project.
print(project.networks.list())

# Check if the network exists
if(project.networks.exists(name="test")):
	# Fetch the network
	network = project.networks.get(name="test")

	print(network.name)

NetworkACL

Methods

• create(name: str, *, description: str=None, egress: list=None, ingress: list=None) - Equivalent to incus network acl create
• delete() - Equivalent to incus network acl delete
• get(name: str) - Get a specific NetworkACL object.
• rename(name: str) - Equivalent to incus network acl rename
• save(description: str=None, egress: list=None, ingress: list=None) - Equivalent to yaml | incus network acl edit
• validateGress(gress: list) - Validate egress or ingress.

Attributes

• incus - Incus object.
• remote - Remote object.
• project - Project object.
• config - Read only attribute associated to the Incus object.
• description - Attribute associated to the Incus object. ACL description.
• egress - Attribute associated to the Incus object. A list of every egress rules.
• ingress - Attribute associated to the Incus object. A list of every ingress rules.
• possibleActions - Read only attribute. List all possible values for the attribute action.
• possibleProtocols - Read only attribute. List all possible values for the attribute protocol.
• possibleRuleKeys - Read only attribute. List all possible keys for an ACL.
• possibleStates - Read only attribute. List all possible values for the attribute state.
• usedBy - Read only attribute associated to the Incus object. Network ACL used by what other object.

Examples

import pyincus

remote = pyincus.remotes.get(name="local")
project = remote.projects.get(name="default")

# List instances of a given project.
print(project.instances.list())

# Check if the instance exists
if(project.instances.exists(name="test")):
	# Fetch the instance
	instance = project.instances.get(name="test")

	print(instance.name)

NetworkForward

Methods

• addPort(*, protocol: str, listenPorts: str, targetAddress: str, targetPorts: str=None) - Add a port forward.
• exists(listeAddress: str) - Return True if the object exists and False if not.
• get(listenAddress: str) - Get a specific NetworkForward object.
• list() - List all port forwards.
• refresh() - Refresh the attributes.
• removePort(*, protocol: str, listenPorts: str) - Remove a port forward.
• save(description: str=None) - Update the description of a network forward.
• validatePortList(ports: str | int) - Validate that each port range in the list are valid. Each individual ports and port ranges must be split by a comma.

Attributes

• incus - Incus object.
• remote - Remote object.
• project - Project object.
• network - Network object.
• config - Read only attribute associated to the Incus object. Network forward configuration.
• description - Attribute associated to the Incus object. Network forward description.
• listenAddress - Read only attribute associated to the Incus object. Name of the network forward as they don't work by name but by address.
• ports - Read only attribute associated to the Incus object. List all port forwards.
• possibleProtocols - Read only attribute. List all possible values for the attribute protocol.

Examples

import pyincus

remote = pyincus.remotes.get(name="local")
project = remote.projects.get(name="default")
network = project.networks.get(name="test")

# List forwards of a given network.
print(network.forwards.list())

# Check if the forward exists
if(network.forwards.exists(listenAddress="10.0.0.1")):
	# Fetch the forward
	forward = network.forwards.get(listenAddress="10.0.0.1")

	print(forward.name)

	forward.addPort(protocol="tcp", listenPorts="80,443,9000-9005", targetAddress="10.0.0.2")
	
	forward.removePort(protocol="tcp", listenPorts="80,443,9000-9005")