community.general.lxd_container – Manage LXD Containers¶
Note
This plugin is part of the community.general collection (version 2.5.1).
To install it use: ansible-galaxy collection install community.general
.
To use it in a playbook, specify: community.general.lxd_container
.
Parameters¶
Parameter | Choices/Defaults | Comments |
---|---|---|
architecture
string
|
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
path
|
The client certificate file path.
If not specified, it defaults to
${HOME}/.config/lxc/client.crt .aliases: cert_file |
|
client_key
path
|
The client certificate key file path.
If not specified, it defaults to
${HOME}/.config/lxc/client.key .aliases: key_file |
|
config
dictionary
|
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
dictionary
|
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
|
|
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
|
|
If this is true, the
lxd_container forces to stop the container when it stops or restarts the container. |
name
string
/ required
|
Name of a container.
|
|
profiles
list
/ elements=string
|
Profile to be used by the container
|
|
snap_url
string
|
Default: "unix:/var/snap/lxd/common/lxd/unix.socket"
|
The unix domain socket path when LXD is installed by snap package manager.
|
source
dictionary
|
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
string
|
|
Define the state of a container.
|
target
string
added in 1.0.0 of community.general
|
For cluster deployments. Will attempt to create a container on a target node. If container exists elsewhere in a cluster, then container will not be replaced or moved. The name should respond to same name of the node you see in
lxc cluster list . |
|
timeout
integer
|
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
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.
|
|
url
string
|
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
|
|
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 ansible.builtin.copy and ansible.builtin.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
community.general.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
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
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
community.general.lxd_container:
name: mycontainer
state: absent
# An example for restarting a container
- hosts: localhost
connection: local
tasks:
- name: Restart a container
community.general.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
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
state: started
source:
type: image
mode: pull
alias: ubuntu/xenial/amd64
target: node01
- name: Create container on another node
community.general.lxd_container:
name: new-container-2
state: started
source:
type: image
mode: pull
alias: ubuntu/xenial/amd64
target: node02
Return Values¶
Common return values are documented here, the following are the fields unique to this module:
Authors¶
Hiroaki Nakamura (@hnakamur)