Documentation

lxd_container - Manage LXD Containers

New in version 2.2.

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


                            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.

                            Support

                            This module is community maintained without core committer oversight.

                            For more information on what this means please read Module Support

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