lxd_container - Manage LXD Containers

New in version 2.2.

Synopsis
Options
Examples
Return Values
Notes
- Status

Synopsis

Management of LXD containers

Options

parameter	required	default	choices	comments
architecture	no			The architecture for the container (e.g. "x86_64" or "i686"). See https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-1
cert_file	no	"{}/.config/lxc/client.crt" .format(os.environ["HOME"])		The client certificate file path.
config	no			The config for the container (e.g. {"limits.cpu": "2"}). See https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-1 If the container already exists and its "config" value in metadata obtained from GET /1.0/containers/<name> https://github.com/lxc/lxd/blob/master/doc/rest-api.md#10containersname are different, they this module tries to apply the configurations. The key starts with 'volatile.' are ignored for this comparison. Not all config values are supported to apply the existing container. Maybe you need to delete and recreate a container.
devices	no			The devices for the container (e.g. { "rootfs": { "path": "/dev/kvm", "type": "unix-char" }). See https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-1
ephemeral	no			Whether or not the container is ephemeral (e.g. true or false). See https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-1
force_stop	no			If this is true, the `lxd_container` forces to stop the container when it stops or restarts the container.
key_file	no	"{}/.config/lxc/client.key" .format(os.environ["HOME"])		The client certificate key file path.
name	yes			Name of a container.
source	no			The source for the container (e.g. { "type": "image", "mode": "pull", "server": "https://images.linuxcontainers.org", "protocol": "lxd", "alias": "ubuntu/xenial/amd64" }). See https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-1
state	no	started	started stopped restarted absent frozen	Define the state of a container.
timeout	no	30		A timeout for changing the state of the container. This is also used as a timeout for waiting until IPv4 addresses are set to the all network interfaces in the container after starting or restarting.
trust_password	no			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.
url	no	unix:/var/lib/lxd/unix.socket		The unix domain socket path or the https URL for the LXD server.
wait_for_ipv4_addresses	no			If this is true, the `lxd_container` waits until IPv4 addresses are set to the all network interfaces in the container after starting or restarting.

Examples

# An example for creating a Ubuntu container and install python
- hosts: localhost
  connection: local
  tasks:
    - name: Create a started container
      lxd_container:
        name: mycontainer
        state: started
        source:
          type: image
          mode: pull
          server: https://images.linuxcontainers.org
          protocol: lxd
          alias: ubuntu/xenial/amd64
        profiles: ["default"]
        wait_for_ipv4_addresses: true
        timeout: 600

    - name: check python is installed in container
      delegate_to: mycontainer
      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
      raw: apt-get install -y python
      when: python_install_check.rc == 1

# An example for deleting a container
- hosts: localhost
  connection: local
  tasks:
    - name: Delete a container
      lxd_container:
        name: mycontainer
        state: absent

# An example for restarting a container
- hosts: localhost
  connection: local
  tasks:
    - name: Restart a container
      lxd_container:
        name: mycontainer
        state: restarted

# An example for restarting a container using https to connect to the LXD server
- hosts: localhost
  connection: local
  tasks:
    - name: Restart a container
      lxd_container:
        url: https://127.0.0.1:8443
        # These cert_file and key_file values are equal to the default values.
        #cert_file: "{{ lookup('env', 'HOME') }}/.config/lxc/client.crt"
        #key_file: "{{ 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"
      fetch:
        src: /etc/hosts
        dest: /tmp/mycontainer-hosts
        flat: true

Return Values

Common return values are documented here Return Values, the following are the fields unique to this module:

name	description	returned	type	sample
actions	List of actions performed for the container.	success	list	["create", "start"]
addresses	Mapping from the network device name to a list of IPv4 addresses in the container	when state is started or restarted	dict	{'eth0': ['10.155.92.191']}
logs	The logs of requests and responses.	when ansible-playbook is invoked with -vvvv.	list	(too long to be placed here)
old_state	The old state of the container	when state is started or restarted	string	stopped

Notes

Note

Containers must have a unique name. If you attempt to create a container with a name that already existed in the users namespace the module will simply return as “unchanged”.
There are two ways to can run commands in containers, 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 container which can be done with the command module.
You can copy a file from the host to the container with the Ansible copy and template module and the lxd connection plugin. See the example below.
You can copy a file in the creatd container to the localhost with command=lxc file pull container_name/dir/filename filename. See the first example below.

Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.4/lxd_container_module.html