community.general.lxd_container module – Manage LXD instances
Note
This module is part of the community.general collection (version 9.5.1).
You might already have this collection installed if you are using the ansible
package.
It is not included in ansible-core
.
To check whether it is installed, run ansible-galaxy collection list
.
To install it, use: ansible-galaxy collection install community.general
.
To use it in a playbook, specify: community.general.lxd_container
.
Synopsis
Management of LXD containers and virtual machines.
Parameters
Parameter |
Comments |
---|---|
The architecture for the instance (for example |
|
The client certificate file path. If not specified, it defaults to |
|
The client certificate key file path. If not specified, it defaults to |
|
The config for the instance (for example If the instance already exists and its “config” values in metadata obtained from the LXD API https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get are different, then this module tries to apply the configurations https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_put. The keys starting with |
|
The devices for the instance (for example |
|
Whether or not the instance is ephemeral (for example Choices:
|
|
If this is Choices:
|
|
If set to This default behavior can be changed by setting this option to The default value changed from Choices:
|
|
Name of an instance. |
|
Profile to be used by the instance. |
|
Project of an instance. See https://documentation.ubuntu.com/lxd/en/latest/projects/. |
|
The unix domain socket path when LXD is installed by snap package manager. Default: |
|
The source for the instance (for example See https://documentation.ubuntu.com/lxd/en/latest/api/ for complete API documentation. Note that |
|
Define the state of an instance. Choices:
|
|
For cluster deployments. Will attempt to create an instance on a target node. If the instance exists elsewhere in a cluster, then it will not be replaced or moved. The name should respond to same name of the node you see in |
|
A timeout for changing the state of the instance. This is also used as a timeout for waiting until IPv4 addresses are set to the all network interfaces in the instance after starting or restarting. Default: |
|
The client trusted password. You need to set this password on the LXD server before running this module using the following command: If trust_password is set, this module send a request for authentication before sending any requests. |
|
Instance type can be either Choices:
|
|
The unix domain socket path or the https URL for the LXD server. Default: |
|
If set to Choices:
|
|
If this is Choices:
|
Attributes
Attribute |
Support |
Description |
---|---|---|
Support: full added in community.general 6.4.0 |
Can run in |
|
Support: full added in community.general 6.4.0 |
Will return details on what has changed (or possibly needs changing in |
Notes
Note
Instances can be a container or a virtual machine, both of them must have unique name. If you attempt to create an instance with a name that already existed in the users namespace the module will simply return as “unchanged”.
There are two ways to run commands inside a container or virtual machine, using the command module or using the ansible lxd connection plugin bundled in Ansible >= 2.1, the later requires python to be installed in the instance which can be done with the command module.
You can copy a file from the host to the instance with the Ansible ansible.builtin.copy and ansible.builtin.template module and the community.general.lxd connection plugin. See the example below.
You can copy a file in the created instance to the localhost with
command=lxc file pull instance_name/dir/filename filename
. See the first example below.linuxcontainers.org has phased out LXC/LXD support with March 2024 (https://discuss.linuxcontainers.org/t/important-notice-for-lxd-users-image-server/18479). Currently only Ubuntu is still providing images.
Examples
# An example for creating a Ubuntu container and install python
- hosts: localhost
connection: local
tasks:
- name: Create a started container
community.general.lxd_container:
name: mycontainer
ignore_volatile_options: true
state: started
source:
type: image
mode: pull
server: https://cloud-images.ubuntu.com/releases/
protocol: simplestreams
alias: "22.04"
profiles: ["default"]
wait_for_ipv4_addresses: true
timeout: 600
- name: Check python is installed in container
delegate_to: mycontainer
ansible.builtin.raw: dpkg -s python
register: python_install_check
failed_when: python_install_check.rc not in [0, 1]
changed_when: false
- name: Install python in container
delegate_to: mycontainer
ansible.builtin.raw: apt-get install -y python
when: python_install_check.rc == 1
# An example for creating an Ubuntu 14.04 container using an image fingerprint.
# This requires changing 'server' and 'protocol' key values, replacing the
# 'alias' key with with 'fingerprint' and supplying an appropriate value that
# matches the container image you wish to use.
- hosts: localhost
connection: local
tasks:
- name: Create a started container
community.general.lxd_container:
name: mycontainer
ignore_volatile_options: true
state: started
source:
type: image
mode: pull
# Provides current (and older) Ubuntu images with listed fingerprints
server: https://cloud-images.ubuntu.com/releases
# Protocol used by 'ubuntu' remote (as shown by 'lxc remote list')
protocol: simplestreams
# This provides an Ubuntu 14.04 LTS amd64 image from 20150814.
fingerprint: e9a8bdfab6dc
profiles: ["default"]
wait_for_ipv4_addresses: true
timeout: 600
# An example of creating a ubuntu-minial container
- hosts: localhost
connection: local
tasks:
- name: Create a started container
community.general.lxd_container:
name: mycontainer
ignore_volatile_options: true
state: started
source:
type: image
mode: pull
# Provides Ubuntu minimal images
server: https://cloud-images.ubuntu.com/minimal/releases/
protocol: simplestreams
alias: "22.04"
profiles: ["default"]
wait_for_ipv4_addresses: true
timeout: 600
# An example for creating container in project other than default
- hosts: localhost
connection: local
tasks:
- name: Create a started container in project mytestproject
community.general.lxd_container:
name: mycontainer
project: mytestproject
ignore_volatile_options: true
state: started
source:
protocol: simplestreams
type: image
mode: pull
server: https://cloud-images.ubuntu.com/releases/
alias: "22.04"
profiles: ["default"]
wait_for_ipv4_addresses: true
timeout: 600
# An example for deleting a container
- hosts: localhost
connection: local
tasks:
- name: Delete a container
community.general.lxd_container:
name: mycontainer
state: absent
type: container
# An example for restarting a container
- hosts: localhost
connection: local
tasks:
- name: Restart a container
community.general.lxd_container:
name: mycontainer
state: restarted
type: container
# An example for restarting a container using https to connect to the LXD server
- hosts: localhost
connection: local
tasks:
- name: Restart a container
community.general.lxd_container:
url: https://127.0.0.1:8443
# These client_cert and client_key values are equal to the default values.
#client_cert: "{{ lookup('env', 'HOME') }}/.config/lxc/client.crt"
#client_key: "{{ lookup('env', 'HOME') }}/.config/lxc/client.key"
trust_password: mypassword
name: mycontainer
state: restarted
# Note your container must be in the inventory for the below example.
#
# [containers]
# mycontainer ansible_connection=lxd
#
- hosts:
- mycontainer
tasks:
- name: Copy /etc/hosts in the created container to localhost with name "mycontainer-hosts"
ansible.builtin.fetch:
src: /etc/hosts
dest: /tmp/mycontainer-hosts
flat: true
# An example for LXD cluster deployments. This example will create two new container on specific
# nodes - 'node01' and 'node02'. In 'target:', 'node01' and 'node02' are names of LXD cluster
# members that LXD cluster recognizes, not ansible inventory names, see: 'lxc cluster list'.
# LXD API calls can be made to any LXD member, in this example, we send API requests to
#'node01.example.com', which matches ansible inventory name.
- hosts: node01.example.com
tasks:
- name: Create LXD container
community.general.lxd_container:
name: new-container-1
ignore_volatile_options: true
state: started
source:
type: image
mode: pull
alias: "22.04"
target: node01
- name: Create container on another node
community.general.lxd_container:
name: new-container-2
ignore_volatile_options: true
state: started
source:
type: image
mode: pull
alias: "22.04"
target: node02
# An example for creating a virtual machine
- hosts: localhost
connection: local
tasks:
- name: Create container on another node
community.general.lxd_container:
name: new-vm-1
type: virtual-machine
state: started
ignore_volatile_options: true
wait_for_ipv4_addresses: true
profiles: ["default"]
source:
protocol: simplestreams
type: image
mode: pull
server: [...] # URL to the image server
alias: debian/11
timeout: 600
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
---|---|
List of actions performed for the instance. Returned: success Sample: |
|
Mapping from the network device name to a list of IPv4 addresses in the instance. Returned: when state is started or restarted Sample: |
|
The logs of requests and responses. Returned: when ansible-playbook is invoked with -vvvv. Sample: |
|
The old state of the instance. Returned: when state is started or restarted Sample: |