Net::Async::WebService::lxd - REST client (asynchronous) for lxd Linux containers
use IO::Async::Loop; my $loop = IO::Async::Loop->new; use Net::Async::WebService::lxd; my $lxd = Net::Async::WebService::lxd->new( loop => $loop, endpoint => 'https://192.168.0.50:8443', SSL_cert_file => "t/client.crt", SSL_key_file => "t/client.key", SSL_fingerprint => 'sha1$92:DD:63:F8:99:C4:5F:82:59:52:82:A9:09:C8:57:F0:67:56:B0:1B', ); $lxd->create_instance( body => { architecture => 'x86_64', profiles => [ 'default' ], name => 'test1', source => { type => 'image', fingerprint => '6dc6aa7c8c00' }, # image already exists in image store config => {}, } )->get; # wait for it # container is still stopped $lxd->instance_state( name => 'test1', body => { action => "start", force => JSON::false, stateful => JSON::false, timeout => 30, } )->get; # wait for it
The constructor returns a handle to one LXD server. It's address is specified via an endpoint parameter, be it of an HTTPS or of a UNIX socket kind.
If you are working with a non-default LXD project in mind, then you should also provide that project's name with the project parameter. Background operation polling will make use of that. Note, that when invoking any of the methods here, you will still have to specify that project, unless it is the default one, of course.
default
As we are operating under an IO::Async regime here, the handle also needs a loop parameter to the central event loop. The handle will also regularily poll autonomously the server which operations are still running or have completed. The optional parameter polling_time controls how often that will occur; it will default to 1 sec, if not provided.
As LXD can be accessed remotely only via HTTPS, TLS (SSL) parameters must be provided. These will be forwarded directly to IO::Socket::SSL. But, specifically, one should consider to provide:
client certificate, via a proper subset of SSL_cert_file, SSL_key_file, SSL_cert and SSL_key. (Look at the "HINTS" section to generate such a certificate for LXD.)
SSL_cert_file
SSL_key_file
SSL_cert
SSL_key
server fingerprint, via SSL_fingerprint (Look at the "HINTS" section how to figure this out.)
SSL_fingerprint
All methods below are automatically generated from the LXD REST API Spec. They should work with API version 1.0.
Let's dissect method invocations with this example:
my $f = $lxd->instance_state( name => 'test1' ); my $r = $f->get;
All invocations return a Future. Thus they can be combined, sequenced, run in "parallel", etc. If you need to wait for a definite result, then you will block the flow with ->get.
->get
Polling is done behind the scenes and will watch for all operations which either succeeded or failed. Those will mark the associated future as done or failed. Normally, you will never need to use the methods for 'Operations' yourself; they are still offered as fallback.
done
failed
The result of each fully completed invocation is either
the string success, or
success
a Perl HASH ref which reflects the JSON data sent from the LXD server. Note, that Booleans have to be treated special, by using JSON::false and JSON::true. Otherwise, they follow exactly the structure in the specification.
JSON::false
JSON::true
or a HASH ref with keys stdin and stdout if this is a result of the execute_in_instance method.
stdin
stdout
execute_in_instance
If an operation failed, then the associated future will be failed, together with the reason of the failure from the server. If you do not cater with that, then this will - as usual with IO::Async - raise an exception, with the failure as string.
IO::Async
Methods named like the type of server object (e.g. cluster, certificate, image) are normally "getter/setter" methods. The getter obviously returns the state of the object. The method becomes a setter, if the additional body field together with a Perl HASH ref is passed:
cluster
certificate
image
body
my $f = $lxd->instance_state( name => 'test1', body => { action => "start", force => JSON::false, stateful => JSON::false, timeout => 30, } );
That HASH ref also follows the structure outlined in the specification for that particular endpoint.
How a specific object is addressed, is detailed in each method below; usually you provide a name, id, fingerprint, or similar. You may also have to provide a project, if not being the default project.
name
id
fingerprint
project
Methods named like a plural of type of server object (e.g. certificates) normally return a list of identifiers for such objects.
certificates
Many methods request changes in the LXD server. The names are taken from the specification, but are adapted to better reflect what is intended:
Methods which change the state of the remote object usually are called modify_something.
modify
Methods which add a new object to a collection are usually called add_something, or create_something, depending on how it sounds better.
add
create
Methods which remove an object from a collection are usually called delete_something.
delete
add_certificate
Adds a certificate to the trust store. In this mode, the `password` property is always ignored.
description: CertificatesPost represents the fields of a new LXD certificate properties: certificate: description: 'The certificate itself, as PEM encoded X509' example: X509 PEM certificate type: string name: description: Name associated with the certificate example: castiana type: string password: description: Server trust password (used to add an untrusted client) example: blah type: string projects: description: List of allowed projects (applies when restricted) example: - default - foo - bar items: type: string type: array restricted: description: Whether to limit the certificate to listed projects example: true type: boolean token: description: Whether to create a certificate add token example: true type: boolean type: description: Usage type for the certificate (only client currently) example: client type: string type: object
add_certificate_untrusted
Adds a certificate to the trust store as an untrusted user. In this mode, the `password` property must be set to the correct value.
The `certificate` field can be omitted in which case the TLS client certificate in use for the connection will be retrieved and added to the trust store.
The `?public` part of the URL isn't required, it's simply used to separate the two behaviors of this endpoint.
Gets a specific certificate entry from the trust store.
Updates the entire certificate configuration.
description: CertificatePut represents the modifiable fields of a LXD certificate properties: certificate: description: 'The certificate itself, as PEM encoded X509' example: X509 PEM certificate type: string name: description: Name associated with the certificate example: castiana type: string projects: description: List of allowed projects (applies when restricted) example: - default - foo - bar items: type: string type: array restricted: description: Whether to limit the certificate to listed projects example: true type: boolean type: description: Usage type for the certificate (only client currently) example: client type: string type: object
Returns a list of trusted certificates (URLs).
certificates_recursion1
Returns a list of trusted certificates (structs).
delete_certificate
Removes the certificate from the trust store.
modify_certificate
Updates a subset of the certificate configuration.
add_cluster_member
Requests a join token to add a cluster member.
properties: server_name: description: The name of the new cluster member example: lxd02 type: string title: ClusterMembersPost represents the fields required to request a join token to add a member to the cluster. type: object
Gets the current cluster configuration.
Updates the entire cluster configuration.
description: |- ClusterPut represents the fields required to bootstrap or join a LXD cluster. properties: cluster_address: description: The address of the cluster you wish to join example: 10.0.0.1:8443 type: string cluster_certificate: description: The expected certificate (X509 PEM encoded) for the cluster example: X509 PEM certificate type: string cluster_password: description: The trust password of the cluster you're trying to join example: blah type: string enabled: description: Whether clustering is enabled example: true type: boolean member_config: description: List of member configuration keys (used during join) example: [] items: $ref: '#/definitions/ClusterMemberConfigKey' type: array server_address: description: The local address to use for cluster communication example: 10.0.0.2:8443 type: string server_name: description: Name of the cluster member answering the request example: lxd01 type: string type: object
cluster_member
Gets a specific cluster member.
Updates the entire cluster member configuration.
description: ClusterMemberPut represents the the modifiable fields of a LXD cluster member properties: config: additionalProperties: type: string description: Additional configuration information example: scheduler.instance: all type: object description: description: Cluster member description example: AMD Epyc 32c/64t type: string failure_domain: description: Name of the failure domain for this cluster member example: rack1 type: string groups: description: List of cluster groups this member belongs to example: - group1 - group2 items: type: string type: array roles: description: List of roles held by this cluster member example: - database items: type: string type: array type: object
cluster_members
Returns a list of cluster members (URLs).
cluster_members_recursion1
Returns a list of cluster members (structs).
clustering_update_cert
Replaces existing cluster certificate and reloads LXD on each cluster member.
description: ClusterCertificatePut represents the certificate and key pair for all members in a LXD Cluster properties: cluster_certificate: description: The new certificate (X509 PEM encoded) for the cluster example: X509 PEM certificate type: string cluster_certificate_key: description: The new certificate key (X509 PEM encoded) for the cluster example: X509 PEM certificate key type: string type: object
create_cluster_group
Creates a new cluster group.
properties: description: description: The description of the cluster group example: amd64 servers type: string members: description: List of members in this group example: - node1 - node3 items: type: string type: array name: description: The new name of the cluster group example: group1 type: string title: ClusterGroupsPost represents the fields available for a new cluster group. type: object
delete_cluster_member
Removes the member from the cluster.
modify_cluster_member
Updates a subset of the cluster member configuration.
rename_cluster_member
Renames an existing cluster member.
properties: server_name: description: The new name of the cluster member example: lxd02 type: string title: ClusterMemberPost represents the fields required to rename a LXD node. type: object
restore_cluster_member_state
Evacuates or restores a cluster member.
properties: action: description: The action to be performed. Valid actions are "evacuate" and "restore". example: evacuate type: string title: ClusterMemberStatePost represents the fields required to evacuate a cluster member. type: object
cluster_group
Gets a specific cluster group.
Updates the entire cluster group configuration.
properties: description: description: The description of the cluster group example: amd64 servers type: string members: description: List of members in this group example: - node1 - node3 items: type: string type: array title: ClusterGroupPut represents the modifiable fields of a cluster group. type: object
cluster_groups
Returns a list of cluster groups (URLs).
cluster_groups_recursion1
Returns a list of cluster groups (structs).
delete_cluster_group
Removes the cluster group.
modify_cluster_group
Updates the cluster group configuration.
rename_cluster_group
Renames an existing cluster group.
properties: name: description: The new name of the cluster group example: group1 type: string title: ClusterGroupPost represents the fields required to rename a cluster group. type: object
add_images_alias
Creates a new image alias.
description: ImageAliasesPost represents a new LXD image alias properties: description: description: Alias description example: Our preferred Ubuntu image type: string name: description: Alias name example: ubuntu-20.04 type: string target: description: Target fingerprint for the alias example: 06b86454720d36b20f94e31c6812e05ec51c1b568cf3a8abd273769d213394bb type: string type: description: Alias type (container or virtual-machine) example: container type: string type: object
create_image
Adds a new image to the image store.
description: ImagesPost represents the fields available for a new LXD image properties: aliases: description: Aliases to add to the image example: - name: foo - name: bar items: $ref: '#/definitions/ImageAlias' type: array auto_update: description: Whether the image should auto-update when a new build is available example: true type: boolean compression_algorithm: description: Compression algorithm to use when turning an instance into an image example: gzip type: string expires_at: description: When the image becomes obsolete example: 2025-03-23T20:00:00-04:00 format: date-time type: string filename: description: Original filename of the image example: lxd.tar.xz type: string profiles: description: List of profiles to use when creating from this image (if none provided by user) example: - default items: type: string type: array properties: additionalProperties: type: string description: Descriptive properties example: os: Ubuntu release: focal variant: cloud type: object public: description: Whether the image is available to unauthenticated users example: false type: boolean source: $ref: '#/definitions/ImagesPostSource' type: object
delete_image
Removes the image from the image store.
delete_image_alias
Deletes a specific image alias.
Gets a specific image.
Updates the entire image definition.
description: ImagePut represents the modifiable fields of a LXD image properties: auto_update: description: Whether the image should auto-update when a new build is available example: true type: boolean expires_at: description: When the image becomes obsolete example: 2025-03-23T20:00:00-04:00 format: date-time type: string profiles: description: List of profiles to use when creating from this image (if none provided by user) example: - default items: type: string type: array properties: additionalProperties: type: string description: Descriptive properties example: os: Ubuntu release: focal variant: cloud type: object public: description: Whether the image is available to unauthenticated users example: false type: boolean type: object
image_alias
Gets a specific image alias.
Updates the entire image alias configuration.
description: ImageAliasesEntryPut represents the modifiable fields of a LXD image alias properties: description: description: Alias description example: Our preferred Ubuntu image type: string target: description: Target fingerprint for the alias example: 06b86454720d36b20f94e31c6812e05ec51c1b568cf3a8abd273769d213394bb type: string type: object
image_alias_untrusted
Gets a specific public image alias. This untrusted endpoint only works for aliases pointing to public images.
image_export
Download the raw image file(s) from the server. If the image is in split format, a multipart http transfer occurs.
image_export_untrusted
Download the raw image file(s) of a public image from the server. If the image is in split format, a multipart http transfer occurs.
secret
image_untrusted
Gets a specific public image.
images
Returns a list of images (URLs).
filter
images_aliases
Returns a list of image aliases (URLs).
images_aliases_recursion1
Returns a list of image aliases (structs).
images_recursion1
Returns a list of images (structs).
images_recursion1_untrusted
Returns a list of publicly available images (structs).
images_untrusted
Returns a list of publicly available images (URLs).
initiate_image_upload
This generates a background operation including a secret one time key in its metadata which can be used to fetch this image from an untrusted client.
modify_image
Updates a subset of the image definition.
modify_images_alias
Updates a subset of the image alias configuration.
push_image_untrusted
Pushes the data to the target image server. This is meant for LXD to LXD communication where a new image entry is prepared on the target server and the source server is provided that URL and a secret token to push the image content over.
push_images_export
Gets LXD to connect to a remote server and push the image to it.
description: ImageExportPost represents the fields required to export a LXD image properties: aliases: description: List of aliases to set on the image items: $ref: '#/definitions/ImageAlias' type: array certificate: description: Remote server certificate example: X509 PEM certificate type: string secret: description: Image receive secret example: RANDOM-STRING type: string target: description: Target server URL example: https://1.2.3.4:8443 type: string type: object
rename_images_alias
Renames an existing image alias.
description: ImageAliasesEntryPost represents the required fields to rename a LXD image alias properties: name: description: Alias name example: ubuntu-20.04 type: string type: object
update_images_refresh
This causes LXD to check the image source server for an updated version of the image and if available to refresh the local copy with the new version.
connect_instance_console
Connects to the console of an instance.
The returned operation metadata will contain two websockets, one for data and one for control.
properties: height: description: Console height in rows (console type only) example: 24 format: int64 type: integer type: description: Type of console to attach to (console or vga) example: console type: string width: description: Console width in columns (console type only) example: 80 format: int64 type: integer title: InstanceConsolePost represents a LXD instance console request. type: object
create_instance
Creates a new instance on LXD. Depending on the source, this can create an instance from an existing local image, remote image, existing local instance or snapshot, remote migration stream or backup file.
target
properties: architecture: description: Architecture name example: x86_64 type: string config: additionalProperties: type: string description: Instance configuration (see doc/instances.md) example: security.nesting: true type: object description: description: Instance description example: My test instance type: string devices: additionalProperties: additionalProperties: type: string type: object description: Instance devices (see doc/instances.md) example: root: path: / pool: default type: disk type: object ephemeral: description: Whether the instance is ephemeral (deleted on shutdown) example: false type: boolean instance_type: description: 'Cloud instance type (AWS, GCP, Azure, ...) to emulate with limits' example: t1.micro type: string name: description: Instance name example: foo type: string profiles: description: List of profiles applied to the instance example: - default items: type: string type: array restore: description: 'If set, instance will be restored to the provided snapshot name' example: snap0 type: string source: $ref: '#/definitions/InstanceSource' stateful: description: Whether the instance currently has saved state on disk example: false type: boolean type: $ref: '#/definitions/InstanceType' title: InstancesPost represents the fields available for a new LXD instance. type: object
create_instance_backup
Creates a new backup.
properties: compression_algorithm: description: What compression algorithm to use example: gzip type: string container_only: description: 'Whether to ignore snapshots (deprecated, use instance_only)' example: false type: boolean expires_at: description: When the backup expires (gets auto-deleted) example: 2021-03-23T17:38:37.753398689-04:00 format: date-time type: string instance_only: description: Whether to ignore snapshots example: false type: boolean name: description: Backup name example: backup0 type: string optimized_storage: description: Whether to use a pool-optimized binary format (instead of plain tarball) example: true type: boolean title: InstanceBackupsPost represents the fields available for a new LXD instance backup. type: object
create_instance_file
Creates a new file in the instance.
path
create_instance_metadata_template
Creates a new image template file for the instance.
create_instance_snapshot
Creates a new snapshot.
properties: expires_at: description: When the snapshot expires (gets auto-deleted) example: 2021-03-23T17:38:37.753398689-04:00 format: date-time type: string name: description: Snapshot name example: snap0 type: string stateful: description: Whether the snapshot should include runtime state example: false type: boolean title: InstanceSnapshotsPost represents the fields available for a new LXD instance snapshot. type: object
delete_instance
Deletes a specific instance.
This also deletes anything owned by the instance such as snapshots and backups.
delete_instance_backup
Deletes the instance backup.
backup
delete_instance_console
Clears the console log buffer.
delete_instance_files
Removes the file.
delete_instance_log
Removes the log file.
filename
delete_instance_metadata_templates
Removes the template file.
delete_instance_snapshot
Deletes the instance snapshot.
snapshot
Executes a command inside an instance.
The returned operation metadata will contain either 2 or 4 websockets. In non-interactive mode, you'll get one websocket for each of stdin, stdout and stderr. In interactive mode, a single bi-directional websocket is used for stdin and stdout/stderr.
An additional "control" socket is always added on top which can be used for out of band communication with LXD. This allows sending signals and window sizing information through.
properties: command: description: Command and its arguments example: - bash items: type: string type: array cwd: description: Current working directory for the command example: /home/foo/ type: string environment: additionalProperties: type: string description: Additional environment to pass to the command example: FOO: BAR type: object group: description: GID of the user to spawn the command as example: 1000 format: uint32 type: integer height: description: Terminal height in rows (for interactive) example: 24 format: int64 type: integer interactive: description: Whether the command is to be spawned in interactive mode (singled PTY instead of 3 PIPEs) example: true type: boolean record-output: description: Whether to capture the output for later download (requires non-interactive) type: boolean user: description: UID of the user to spawn the command as example: 1000 format: uint32 type: integer wait-for-websocket: description: Whether to wait for all websockets to be connected before spawning the command example: true type: boolean width: description: Terminal width in characters (for interactive) example: 80 format: int64 type: integer title: InstanceExecPost represents a LXD instance exec request. type: object
instance
Gets a specific instance (basic struct).
Updates the instance configuration or trigger a snapshot restore.
properties: architecture: description: Architecture name example: x86_64 type: string config: additionalProperties: type: string description: Instance configuration (see doc/instances.md) example: security.nesting: true type: object description: description: Instance description example: My test instance type: string devices: additionalProperties: additionalProperties: type: string type: object description: Instance devices (see doc/instances.md) example: root: path: / pool: default type: disk type: object ephemeral: description: Whether the instance is ephemeral (deleted on shutdown) example: false type: boolean profiles: description: List of profiles applied to the instance example: - default items: type: string type: array restore: description: 'If set, instance will be restored to the provided snapshot name' example: snap0 type: string stateful: description: Whether the instance currently has saved state on disk example: false type: boolean title: InstancePut represents the modifiable fields of a LXD instance. type: object
instance_backup
Gets a specific instance backup.
instance_backup_export
Download the raw backup file(s) from the server.
instance_backups
Returns a list of instance backups (URLs).
instance_backups_recursion1
Returns a list of instance backups (structs).
instance_console
Gets the console log for the instance.
instance_files
Gets the file content. If it's a directory, a json list of files will be returned instead.
instance_log
Gets the log file.
instance_logs
Returns a list of log files (URLs).
instance_metadata
Gets the image metadata for the instance.
Updates the instance image metadata.
description: ImageMetadata represents LXD image metadata (used in image tarball) properties: architecture: description: Architecture name example: x86_64 type: string creation_date: description: Image creation data (as UNIX epoch) example: 1620655439 format: int64 type: integer expiry_date: description: Image expiry data (as UNIX epoch) example: 1620685757 format: int64 type: integer properties: additionalProperties: type: string description: Descriptive properties example: os: Ubuntu release: focal variant: cloud type: object templates: additionalProperties: $ref: '#/definitions/ImageMetadataTemplate' description: Template for files in the image type: object type: object
instance_metadata_templates
If no path specified, returns a list of template file names. If a path is specified, returns the file content.
instance_recursion1
Gets a specific instance (full struct).
recursion=1 also includes information about state, snapshots and backups.
instance_snapshot
Gets a specific instance snapshot.
Updates the snapshot config.
properties: expires_at: description: When the snapshot expires (gets auto-deleted) example: 2021-03-23T17:38:37.753398689-04:00 format: date-time type: string title: InstanceSnapshotPut represents the modifiable fields of a LXD instance snapshot. type: object
instance_snapshots
Returns a list of instance snapshots (URLs).
instance_snapshots_recursion1
Returns a list of instance snapshots (structs).
instance_state
Gets the runtime state of the instance.
This is a reasonably expensive call as it causes code to be run inside of the instance to retrieve the resource usage and network information.
Changes the running state of the instance.
properties: action: description: 'State change action (start, stop, restart, freeze, unfreeze)' example: start type: string force: description: Whether to force the action (for stop and restart) example: false type: boolean stateful: description: Whether to store the runtime state (for stop) example: false type: boolean timeout: description: How long to wait (in s) before giving up (when force isn't set) example: 30 format: int64 type: integer title: InstanceStatePut represents the modifiable fields of a LXD instance's state. type: object
instances
Returns a list of instances (URLs).
Changes the running state of all instances.
all-projects
properties: state: $ref: '#/definitions/InstanceStatePut' title: InstancesPut represents the fields available for a mass update. type: object
instances_recursion1
Returns a list of instances (basic structs).
instances_recursion2
Returns a list of instances (full structs).
The main difference between recursion=1 and recursion=2 is that the latter also includes state and snapshot information allowing for a single API call to return everything needed by most clients.
migrate_instance
Renames, moves an instance between pools or migrates an instance to another server.
The returned operation metadata will vary based on what's requested. For rename or move within the same server, this is a simple background operation with progress data. For migration, in the push case, this will similarly be a background operation with progress data, for the pull case, it will be a websocket operation with a number of secrets to be passed to the target server.
properties: container_only: description: 'Whether snapshots should be discarded (migration only, deprecated, use instance_only)' example: false type: boolean instance_only: description: Whether snapshots should be discarded (migration only) example: false type: boolean live: description: Whether to perform a live migration (migration only) example: false type: boolean migration: description: Whether the instance is being migrated to another server example: false type: boolean name: description: New name for the instance example: bar type: string pool: description: Target pool for local cross-pool move example: baz type: string project: description: Target project for local cross-project move example: foo type: string target: $ref: '#/definitions/InstancePostTarget' title: InstancePost represents the fields required to rename/move a LXD instance. type: object
migrate_instance_snapshot
Renames or migrates an instance snapshot to another server.
properties: live: description: Whether to perform a live migration (requires migration) example: false type: boolean migration: description: Whether this is a migration request example: false type: boolean name: description: New name for the snapshot example: foo type: string target: $ref: '#/definitions/InstancePostTarget' title: InstanceSnapshotPost represents the fields required to rename/move a LXD instance snapshot. type: object
modify_instance
Updates a subset of the instance configuration
modify_instance_metadata
Updates a subset of the instance image metadata.
modify_instance_snapshot
Updates a subset of the snapshot config.
rename_instance_backup
Renames an instance backup.
properties: name: description: New backup name example: backup1 type: string title: InstanceBackupPost represents the fields available for the renaming of a instance backup. type: object
metrics
Gets metrics of instances.
create_network_acl
Creates a new network ACL.
properties: config: additionalProperties: type: string description: ACL configuration map (refer to doc/network-acls.md) example: user.mykey: foo type: object description: description: Description of the ACL example: Web servers type: string egress: description: List of egress rules (order independent) items: $ref: '#/definitions/NetworkACLRule' type: array ingress: description: List of ingress rules (order independent) items: $ref: '#/definitions/NetworkACLRule' type: array name: description: The new name for the ACL example: bar type: string title: NetworkACLsPost used for creating an ACL. type: object
delete_network_acl
Removes the network ACL.
modify_network_acl
Updates a subset of the network ACL configuration.
properties: config: additionalProperties: type: string description: ACL configuration map (refer to doc/network-acls.md) example: user.mykey: foo type: object description: description: Description of the ACL example: Web servers type: string egress: description: List of egress rules (order independent) items: $ref: '#/definitions/NetworkACLRule' type: array ingress: description: List of ingress rules (order independent) items: $ref: '#/definitions/NetworkACLRule' type: array title: NetworkACLPut used for updating an ACL. type: object
network_acl
Gets a specific network ACL.
Updates the entire network ACL configuration.
network_acl_log
Gets a specific network ACL log entries.
network_acls
Returns a list of network ACLs (URLs).
network_acls_recursion1
Returns a list of network ACLs (structs).
rename_network_acl
Renames an existing network ACL.
properties: name: description: The new name for the ACL example: bar type: string title: NetworkACLPost used for renaming an ACL. type: object
create_network_forward
Creates a new network address forward.
networkName
description: NetworkForwardsPost represents the fields of a new LXD network address forward properties: config: additionalProperties: type: string description: Forward configuration map (refer to doc/network-forwards.md) example: user.mykey: foo type: object description: description: Description of the forward listen IP example: My public IP forward type: string listen_address: description: The listen address of the forward example: 192.0.2.1 type: string ports: description: Port forwards (optional) items: $ref: '#/definitions/NetworkForwardPort' type: array type: object
delete_network_forward
Removes the network address forward.
listenAddress
modify_network_forward
Updates a subset of the network address forward configuration.
description: NetworkForwardPut represents the modifiable fields of a LXD network address forward properties: config: additionalProperties: type: string description: Forward configuration map (refer to doc/network-forwards.md) example: user.mykey: foo type: object description: description: Description of the forward listen IP example: My public IP forward type: string ports: description: Port forwards (optional) items: $ref: '#/definitions/NetworkForwardPort' type: array type: object
network_forward
Gets a specific network address forward.
Updates the entire network address forward configuration.
network_forward_recursion1
Returns a list of network address forwards (structs).
network_forwards
Returns a list of network address forwards (URLs).
create_network_peer
Initiates/creates a new network peering.
description: NetworkPeersPost represents the fields of a new LXD network peering properties: config: additionalProperties: type: string description: Peer configuration map (refer to doc/network-peers.md) example: user.mykey: foo type: object description: description: Description of the peer example: Peering with network1 in project1 type: string name: description: Name of the peer example: project1-network1 type: string target_network: description: Name of the target network example: network1 type: string target_project: description: Name of the target project example: project1 type: string type: object
delete_network_peer
Removes the network peering.
peerName
modify_network_peer
Updates a subset of the network peering configuration.
description: NetworkPeerPut represents the modifiable fields of a LXD network peering properties: config: additionalProperties: type: string description: Peer configuration map (refer to doc/network-peers.md) example: user.mykey: foo type: object description: description: Description of the peer example: Peering with network1 in project1 type: string type: object
network_peer
Gets a specific network peering.
Updates the entire network peering configuration.
network_peer_recursion1
Returns a list of network peers (structs).
network_peers
Returns a list of network peers (URLs).
create_network_zone
Creates a new network zone.
description: NetworkZonesPost represents the fields of a new LXD network zone properties: config: additionalProperties: type: string description: Zone configuration map (refer to doc/network-zones.md) example: user.mykey: foo type: object description: description: Description of the network zone example: Internal domain type: string name: description: The name of the zone (DNS domain name) example: example.net type: string type: object
create_network_zone_record
Creates a new network zone record.
zone
description: NetworkZoneRecordsPost represents the fields of a new LXD network zone record properties: config: additionalProperties: type: string description: Advanced configuration for the record example: user.mykey: foo type: object description: description: Description of the record example: SPF record type: string entries: description: Entries in the record items: $ref: '#/definitions/NetworkZoneRecordEntry' type: array name: description: The record name in the zone example: '@' type: string type: object
delete_network_zone
Removes the network zone.
delete_network_zone_record
Removes the network zone record.
modify_network_zone
Updates a subset of the network zone configuration.
description: NetworkZonePut represents the modifiable fields of a LXD network zone properties: config: additionalProperties: type: string description: Zone configuration map (refer to doc/network-zones.md) example: user.mykey: foo type: object description: description: Description of the network zone example: Internal domain type: string type: object
modify_network_zone_record
Updates a subset of the network zone record configuration.
description: NetworkZoneRecordPut represents the modifiable fields of a LXD network zone record properties: config: additionalProperties: type: string description: Advanced configuration for the record example: user.mykey: foo type: object description: description: Description of the record example: SPF record type: string entries: description: Entries in the record items: $ref: '#/definitions/NetworkZoneRecordEntry' type: array type: object
network_zone
Gets a specific network zone.
Updates the entire network zone configuration.
network_zone_record
Gets a specific network zone record.
Updates the entire network zone record configuration.
network_zone_records
Returns a list of network zone records (URLs).
network_zone_records_recursion1
Returns a list of network zone records (structs).
network_zones
Returns a list of network zones (URLs).
network_zones_recursion1
Returns a list of network zones (structs).
create_network
Creates a new network. When clustered, most network types require individual POST for each cluster member prior to a global POST.
description: NetworksPost represents the fields of a new LXD network properties: config: additionalProperties: type: string description: Network configuration map (refer to doc/networks.md) example: ipv4.address: 10.0.0.1/24 ipv4.nat: true ipv6.address: none type: object description: description: Description of the profile example: My new LXD bridge type: string name: description: The name of the new network example: lxdbr1 type: string type: description: The network type (refer to doc/networks.md) example: bridge type: string type: object
delete_network
Removes the network.
modify_network
Updates a subset of the network configuration.
description: NetworkPut represents the modifiable fields of a LXD network properties: config: additionalProperties: type: string description: Network configuration map (refer to doc/networks.md) example: ipv4.address: 10.0.0.1/24 ipv4.nat: true ipv6.address: none type: object description: description: Description of the profile example: My new LXD bridge type: string type: object
network
Gets a specific network.
Updates the entire network configuration.
networks
Returns a list of networks (URLs).
networks_leases
Returns a list of DHCP leases for the network.
networks_recursion1
Returns a list of networks (structs).
networks_state
Returns the current network state information.
rename_network
Renames an existing network.
description: NetworkPost represents the fields required to rename a LXD network properties: name: description: The new name for the network example: lxdbr1 type: string type: object
delete_operation
Cancels the operation if supported.
operation
Gets the operation state.
operation_wait
Waits for the operation to reach a final state (or timeout) and retrieve its final state.
timeout
operation_wait_untrusted
When accessed by an untrusted user, the secret token must be provided.
operation_websocket
Connects to an associated websocket stream for the operation. This should almost never be done directly by a client, instead it's meant for LXD to LXD communication with the client only relaying the connection information to the servers.
operation_websocket_untrusted
The untrusted endpoint is used by the target server to connect to the source server. Authentication is performed through the secret token.
operations
Returns a dict of operation type to operation list (URLs).
operations_recursion1
Returns a list of operations (structs).
create_profile
Creates a new profile.
description: ProfilesPost represents the fields of a new LXD profile properties: config: additionalProperties: type: string description: Instance configuration map (refer to doc/instances.md) example: limits.cpu: 4 limits.memory: 4GiB type: object description: description: Description of the profile example: Medium size instances type: string devices: additionalProperties: additionalProperties: type: string type: object description: List of devices example: eth0: name: eth0 network: lxdbr0 type: nic root: path: / pool: default type: disk type: object name: description: The name of the new profile example: foo type: string type: object
delete_profile
Removes the profile.
modify_profile
Updates a subset of the profile configuration.
description: ProfilePut represents the modifiable fields of a LXD profile properties: config: additionalProperties: type: string description: Instance configuration map (refer to doc/instances.md) example: limits.cpu: 4 limits.memory: 4GiB type: object description: description: Description of the profile example: Medium size instances type: string devices: additionalProperties: additionalProperties: type: string type: object description: List of devices example: eth0: name: eth0 network: lxdbr0 type: nic root: path: / pool: default type: disk type: object type: object
profile
Gets a specific profile.
Updates the entire profile configuration.
profiles
Returns a list of profiles (URLs).
profiles_recursion1
Returns a list of profiles (structs).
rename_profile
Renames an existing profile.
description: ProfilePost represents the fields required to rename a LXD profile properties: name: description: The new name for the profile example: bar type: string type: object
create_project
Creates a new project.
description: ProjectsPost represents the fields of a new LXD project properties: config: additionalProperties: type: string description: Project configuration map (refer to doc/projects.md) example: features.networks: false features.profiles: true type: object description: description: Description of the project example: My new project type: string name: description: The name of the new project example: foo type: string type: object
delete_project
Removes the project.
modify_project
Updates a subset of the project configuration.
description: ProjectPut represents the modifiable fields of a LXD project properties: config: additionalProperties: type: string description: Project configuration map (refer to doc/projects.md) example: features.networks: false features.profiles: true type: object description: description: Description of the project example: My new project type: string type: object
Gets a specific project.
Updates the entire project configuration.
project_state
Gets a specific project resource consumption information.
projects
Returns a list of projects (URLs).
projects_recursion1
Returns a list of projects (structs).
rename_project
Renames an existing project.
description: ProjectPost represents the fields required to rename a LXD project properties: name: description: The new name for the project example: bar type: string type: object
api
Returns a list of supported API versions (URLs).
Internal API endpoints are not reported as those aren't versioned and should only be used by LXD itself.
events
Connects to the event API using websocket.
type
modify_server
Updates a subset of the server configuration.
description: ServerPut represents the modifiable fields of a LXD server configuration properties: config: additionalProperties: type: object description: Server configuration map (refer to doc/server.md) example: core.https_address: :8443 core.trust_password: true type: object type: object
resources
Gets the hardware information profile of the LXD server.
server
Shows the full server environment and configuration.
Updates the entire server configuration.
server_untrusted
Shows a small subset of the server environment and configuration which is required by untrusted clients to reach a server.
create_storage_pool
Creates a new storage pool. When clustered, storage pools require individual POST for each cluster member prior to a global POST.
description: StoragePoolsPost represents the fields of a new LXD storage pool properties: config: additionalProperties: type: string description: Storage pool configuration map (refer to doc/storage.md) example: volume.block.filesystem: ext4 volume.size: 50GiB type: object description: description: Description of the storage pool example: Local SSD pool type: string driver: description: 'Storage pool driver (btrfs, ceph, cephfs, dir, lvm or zfs)' example: zfs type: string name: description: Storage pool name example: local type: string type: object
create_storage_pool_volume
Creates a new storage volume.
description: StorageVolumesPost represents the fields of a new LXD storage pool volume properties: config: additionalProperties: type: string description: Storage volume configuration map (refer to doc/storage.md) example: size: 50GiB zfs.remove_snapshots: true type: object content_type: description: Volume content type (filesystem or block) example: filesystem type: string description: description: Description of the storage volume example: My custom volume type: string name: description: Volume name example: foo type: string restore: description: Name of a snapshot to restore example: snap0 type: string source: $ref: '#/definitions/StorageVolumeSource' type: description: 'Volume type (container, custom, image or virtual-machine)' example: custom type: string type: object
create_storage_pool_volumes_backup
Creates a new storage volume backup.
volume
description: StoragePoolVolumeBackupsPost represents the fields available for a new LXD volume backup properties: compression_algorithm: description: What compression algorithm to use example: gzip type: string expires_at: description: When the backup expires (gets auto-deleted) example: 2021-03-23T17:38:37.753398689-04:00 format: date-time type: string name: description: Backup name example: backup0 type: string optimized_storage: description: Whether to use a pool-optimized binary format (instead of plain tarball) example: true type: boolean volume_only: description: Whether to ignore snapshots example: false type: boolean type: object
create_storage_pool_volumes_snapshot
Creates a new storage volume snapshot.
description: StorageVolumeSnapshotsPost represents the fields available for a new LXD storage volume snapshot properties: expires_at: description: When the snapshot expires (gets auto-deleted) example: 2021-03-23T17:38:37.753398689-04:00 format: date-time type: string name: description: Snapshot name example: snap0 type: string type: object
create_storage_pool_volumes_type
Creates a new storage volume (type specific endpoint).
delete_storage_pool_volume_type
Removes the storage volume.
delete_storage_pool_volumes_type_backup
Deletes a new storage volume backup.
delete_storage_pool_volumes_type_snapshot
Deletes a new storage volume snapshot.
delete_storage_pools
Removes the storage pool.
migrate_storage_pool_volume_type
Renames, moves a storage volume between pools or migrates an instance to another server.
description: StorageVolumePost represents the fields required to rename a LXD storage pool volume properties: migration: description: Initiate volume migration example: false type: boolean name: description: New volume name example: foo type: string pool: description: New storage pool example: remote type: string project: description: New project name example: foo type: string target: $ref: '#/definitions/StorageVolumePostTarget' volume_only: description: Whether snapshots should be discarded (migration only) example: false type: boolean type: object
modify_storage_pool
Updates a subset of the storage pool configuration.
properties: config: additionalProperties: type: string description: Storage pool configuration map (refer to doc/storage.md) example: volume.block.filesystem: ext4 volume.size: 50GiB type: object description: description: Description of the storage pool example: Local SSD pool type: string title: StoragePoolPut represents the modifiable fields of a LXD storage pool. type: object
modify_storage_pool_volume_type
Updates a subset of the storage volume configuration.
description: StorageVolumePut represents the modifiable fields of a LXD storage volume properties: config: additionalProperties: type: string description: Storage volume configuration map (refer to doc/storage.md) example: size: 50GiB zfs.remove_snapshots: true type: object description: description: Description of the storage volume example: My custom volume type: string restore: description: Name of a snapshot to restore example: snap0 type: string type: object
modify_storage_pool_volumes_type_snapshot
Updates a subset of the storage volume snapshot configuration.
description: StorageVolumeSnapshotPut represents the modifiable fields of a LXD storage volume properties: description: description: Description of the storage volume example: My custom volume type: string expires_at: description: When the snapshot expires (gets auto-deleted) example: 2021-03-23T17:38:37.753398689-04:00 format: date-time type: string type: object
rename_storage_pool_volumes_type_backup
Renames a storage volume backup.
description: StorageVolumeSnapshotPost represents the fields required to rename/move a LXD storage volume snapshot properties: name: description: New snapshot name example: snap1 type: string type: object
rename_storage_pool_volumes_type_snapshot
Renames a storage volume snapshot.
storage_pool
Gets a specific storage pool.
Updates the entire storage pool configuration.
storage_pool_resources
Gets the usage information for the storage pool.
storage_pool_volume_type
Gets a specific storage volume.
Updates the entire storage volume configuration.
storage_pool_volume_type_state
Gets a specific storage volume state (usage data).
storage_pool_volumes
Returns a list of storage volumes (URLs).
storage_pool_volumes_recursion1
Returns a list of storage volumes (structs).
storage_pool_volumes_type
Returns a list of storage volumes (URLs) (type specific endpoint).
storage_pool_volumes_type_backup
Gets a specific storage volume backup.
storage_pool_volumes_type_backup_export
Download the raw backup file from the server.
storage_pool_volumes_type_backups
Returns a list of storage volume backups (URLs).
storage_pool_volumes_type_backups_recursion1
Returns a list of storage volume backups (structs).
storage_pool_volumes_type_recursion1
Returns a list of storage volumes (structs) (type specific endpoint).
storage_pool_volumes_type_snapshot
Gets a specific storage volume snapshot.
Updates the entire storage volume snapshot configuration.
storage_pool_volumes_type_snapshots
Returns a list of storage volume snapshots (URLs).
storage_pool_volumes_type_snapshots_recursion1
Returns a list of storage volume snapshots (structs).
storage_pools
Returns a list of storage pools (URLs).
storage_pools_recursion1
Returns a list of storage pools (structs).
delete_warning
Removes the warning.
uuid
modify_warning
Updates a subset of the warning status.
properties: status: description: 'Status of the warning (new, acknowledged, or resolved)' example: new type: string title: WarningPut represents the modifiable fields of a warning. type: object
warning
Gets a specific warning.
Updates the warning status.
warnings
Returns a list of warnings.
warnings_recursion1
Returns a list of warnings (structs).
Just for the sake of experimentation, I added a sub-package lxd::instance. To add OO-flavour, you simply bless the instance HASH with it:
lxd::instance
my $r = $lxd->instance( name => "my-container" )->get; my $i = bless $r, 'lxd::instance';
From then on, the following methods can operate on it:
restart
start
freeze
unfreeze
stop
state
Well, I'm not a big fan of objects.
I encourage you to look at the 02_instances.t test suite. It will show a complete life cycle for containers.
02_instances.t
Linux::LXC
uses actually the existing lxc client to get the information
https://github.com/jipipayo/Linux-REST-LXD
pretty old, never persued
How to generate an SSL client certificate for LXD
First, I found one client certificate (plus the key) in my installation at:
/root/snap/lxd/common/config/
Alternatively, you can run your own small CA, generate a .crt and .key for a client, and then add it to lxd to trust it.
More on this topic is here
How to find the SSL fingerprint for an LXD server
With recent versions of LXD this is fairly easy:
$ lxc info|grep fingerprint
It is a SHA256 hash, so you will have to prefix it with sha256$ (no blanks) when you pass it to SSL_fingerprint.
sha256$
Alternatively, you can try to find the server certificate and use openssl to derive a fingerprint of your choice.
openssl
Open issues are probably best put onto Github
Robert Barta, <rho at devc.at>
<rho at devc.at>
IO::Async, Net::Async::HTTP, IO::Socket::SSL and friends are amazing.
Copyright 2022 Robert Barta.
This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:
http://www.perlfoundation.org/artistic_license_2_0
Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.
If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.
This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.
This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.
Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
To install Net::Async::WebService::lxd, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::Async::WebService::lxd
CPAN shell
perl -MCPAN -e shell install Net::Async::WebService::lxd
For more information on module installation, please visit the detailed CPAN module installation guide.