# lxd_container – Manage LXD Containers

- Synopsis
- Parameters
- Notes
- Examples
- Return Values
- Status

## Synopsis

- Management of LXD containers

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
architecture - |  | 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
client_cert - | Default: "\"{}/.config/lxc/client.crt\" .format(os.environ[\"HOME\"])" | The client certificate file path. aliases: cert_file
client_key - | Default: "\"{}/.config/lxc/client.key\" .format(os.environ[\"HOME\"])" | The client certificate key file path. aliases: key_file

config
-

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 - |  | 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
boolean

Choices:
- no
- yes

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
boolean

Choices:
- no ←
- yes

If this is true, the `lxd_container` forces to stop the container when it stops or restarts the container.

name - / required |  | Name of a container.
snap_url - added in 2.8 | Default: "unix:/var/snap/lxd/common/lxd/unix.socket" | The unix domain socket path when LXD is installed by snap package manager.
source - |  | 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 for complete API documentation. Note that `protocol` accepts two choices: `lxd` or `simplestreams`

state
-

Choices:
- started ←
- stopped
- restarted
- absent
- frozen

Define the state of a container.

timeout - | Default: 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 - |  | 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 - | Default: "unix:/var/lib/lxd/unix.socket" | The unix domain socket path or the https URL for the LXD server.

wait_for_ipv4_addresses
boolean

Choices:
- no ←
- yes

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.

## 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 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 created container to the localhost with command=lxc file pull container_name/dir/filename filename. See the first example below.

## 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 # if you get a 404, try setting protocol: simplestreams
              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 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
          lxd_container:
            name: mycontainer
            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 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 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"
          fetch:
            src: /etc/hosts
            dest: /tmp/mycontainer-hosts
            flat: true

## Return Values

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

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

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

- Hiroaki Nakamura (@hnakamur)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.