community.general.lxd_container module – Manage LXD instances

Note

This module is part of the community.general collection (version 10.1.0).

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
architecture string	The architecture for the instance (for example x86_64 or i686). See https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get.
client_cert aliases: cert_file path	The client certificate file path. If not specified, it defaults to ${HOME}/.config/lxc/client.crt.
client_key aliases: key_file path	The client certificate key file path. If not specified, it defaults to ${HOME}/.config/lxc/client.key.
config dictionary	The config for the instance (for example {"limits.cpu": "2"}). See https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get. 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 volatile. are ignored for this comparison when ignore_volatile_options=true.
devices dictionary	The devices for the instance (for example { "rootfs": { "path": "/dev/kvm", "type": "unix-char" }}). See https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get.
ephemeral boolean	Whether or not the instance is ephemeral (for example true or false). See https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get. Choices: false true
force_stop boolean	If this is true, the lxd_container forces to stop the instance when it stops or restarts the instance. Choices: false ← (default) true
ignore_volatile_options boolean added in community.general 3.7.0	If set to true, options starting with volatile. are ignored. As a result, they are reapplied for each execution. This default behavior can be changed by setting this option to false. The default value changed from true to false in community.general 6.0.0. Choices: false ← (default) true
name string / required	Name of an instance.
profiles list / elements=string	Profile to be used by the instance.
project string added in community.general 4.8.0	Project of an instance. See https://documentation.ubuntu.com/lxd/en/latest/projects/.
snap_url string	The unix domain socket path when LXD is installed by snap package manager. Default: "unix:/var/snap/lxd/common/lxd/unix.socket"
source dictionary	The source for the instance (for example { "type": "image", "mode": "pull", "server": "https://cloud-images.ubuntu.com/releases/", "protocol": "simplestreams", "alias": "22.04" }). See https://documentation.ubuntu.com/lxd/en/latest/api/ for complete API documentation. Note that protocol accepts two choices: lxd or simplestreams.
state string	Define the state of an instance. Choices: "started" ← (default) "stopped" "restarted" "absent" "frozen"
target string added in community.general 1.0.0	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 lxc cluster list.
timeout integer	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: 30
trust_password string	The client trusted password. You need to set this password on the LXD server before running this module using the following command: lxc config set core.trust_password <some random password>. See https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/. If trust_password is set, this module send a request for authentication before sending any requests.
type string added in community.general 4.1.0	Instance type can be either virtual-machine or container. Choices: "container" ← (default) "virtual-machine"
url string	The unix domain socket path or the https URL for the LXD server. Default: "unix:/var/lib/lxd/unix.socket"
wait_for_container boolean added in community.general 4.4.0	If set to true, the tasks will wait till the task reports a success status when performing container operations. Choices: false ← (default) true
wait_for_ipv4_addresses boolean	If this is true, the lxd_container waits until IPv4 addresses are set to the all network interfaces in the instance after starting or restarting. Choices: false ← (default) true

Attributes

Attribute	Support	Description
check_mode	Support: full added in community.general 6.4.0	Can run in check_mode and return changed status prediction without modifying target.
diff_mode	Support: full added in community.general 6.4.0	Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

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
actions list / elements=string	List of actions performed for the instance. Returned: success Sample: ["create", "start"]
addresses dictionary	Mapping from the network device name to a list of IPv4 addresses in the instance. Returned: when state is started or restarted Sample: {"eth0": ["10.155.92.191"]}
logs list / elements=string	The logs of requests and responses. Returned: when ansible-playbook is invoked with -vvvv. Sample: ["(too long to be placed here)"]
old_state string	The old state of the instance. Returned: when state is started or restarted Sample: "stopped"

Authors

• Hiroaki Nakamura (@hnakamur)

Collection links

• Issue Tracker
• Repository (Sources)
• Ask for help
• Submit a bug report
• Request a feature
• Communication