Ansible Role: LXD Test Environment (lxd-testenv)

Table of Contents

• Ansible Role: LXD Test Environment (lxd-testenv)
  • Table of Contents
  • Overview
  • Limitations
  • WARNINGS
  • Requirements
  • Role Variables
  • "Bootstrap" vs "Configure" phases/tasks
  • Variables specific to the LXD host
  • Variables specific to LXD containers created by this role
  • Dependencies
  • Example Playbooks
  • Setup test environment
  • Teardown/Remove test environment
  • Installing the role
  • Create requirements.yml file
    • Specific stable release version
    • Latest from the master branch
  • Use requirements.yml file to install role
    • Option 1: Within your home directory
    • Option 2: Within a roles directory in the same location as your playbooks
    • Option 3: System-wide for all users
  • License
  • Author Information
  • References

Overview

Ansible role used to generate or teardown a LXD container test environment. This role is intended to be used as a base for testing other roles and playbooks.

Example playbooks for both use cases are provided.

Limitations

• Tested on Ubuntu 16.04+ with LXD 2.0 and 3.0 LTS series
  • support for other distros and LXD versions may be added in a future release

Future versions of this role are intended to better handle these issues.

WARNINGS

• Do not use this role on production systems. It lacks sufficient testing to be relied upon for anything more than local/isolated testing purposes.

Requirements

• Ubuntu 16.04 or newer
• LXD packages installed (tested with 2.0 and 3.0 LTS series)
• Equivalent of sudo lxd init already run
  • note: the atc0005.lxd-host role role is intended to handle this, though as of this writing that role is still incomplete

Role Variables

• The state variable is set outside of the role to act as a control flag for either building up a test environment or tearing it down.

  • valid values are create or remove

• Role variables are set within default/main.yml.

• Though most variables are intended for use solely at either LXD host or LXD container level, setting them at higher levels of precedence (e.g., playbook task variable) will override variables of the same name set at lower levels (e.g., group_vars/all.yml or host_vars/ansible-centos-1.yml). This follows established Ansible variable precedence behavior.

The playbooks found in the ansible-playbook-lxd-testenv repo have most of the common variables listed here directly within the playbooks in an effort to make it easy to override default values.

"Bootstrap" vs "Configure" phases/tasks

This role makes a distinction between the Bootstrap and Configure phases and offers boolean flags to control whether tasks applicable to those phases are run within certain containers.

Bootstrap tasks perform the bare-minimum changes to LXD containers in order to run native Ansible modules against them (which includes basic fact gathering).

Configure tasks perform non-essential, but expected provisioning tasks that are normally applied when standing up a fresh system. Some examples:

• service status changes
• package installations
• creation of service accounts and groups
• global environment changes

Variables specific to the LXD host

These variables are intended to be set at the playbook or role level and not per Ansible "host" or LXD container.

Variables specific to LXD containers created by this role

This role exposes both flags as options that can be set for one or all containers in order to provision containers in the desired state for further work. For example, you may wish to provision a fresh container with minimal changes in order to test basic configuration changes provided by another playbook or tool.

Current shell command for the lxd_containers_default_python_install_command variable:

if [ -f /usr/bin/apt-get ]; then
  apt-get install -y python python-apt;
fi
if [ -f /usr/bin/yum ]; then
  yum install -y python;
fi

If not set elsewhere and if Python 2.x is not found on the system as /usr/bin/python, the above command is used in an attempt to install Python 2 for further Ansible management steps.

Dependencies

An existing installation of LXD packages and initial configuration via sudo lxd init. The atc0005.lxd-host role is intended to serve that purpose in the future once it is ready.

See Requirements section for additional items.

Example Playbooks

Setup test environment

WARNING: Review known Limitations before using this role.

- name: Configure base LXD host
  hosts: localhost

  # Rely on this setting to be specified in host_vars or group_vars files. If
  # we lock in the 'local' option here then that rules out setting up any
  # remote hosts as LXD hosts.
  # connection: local

  # Should be fine to gather facts for just the future LXD host
  gather_facts: yes

  tasks:

    # Stub role for now. Later work will have it install required packages
    # needed in order to configure host system for running LXD containers
    - name: Apply lxd-host role to install LXD packages, perform initial setup
      import_role:
        name: atc0005.lxd-host

- name: Setup LXD test environment
  hosts: all

  # Rely on this setting to be specified in host_vars or group_vars files. If
  # we lock in the 'local' option here then that rules out setting up any
  # remote hosts as Docker hosts.
  # connection: local

  # This is handled by the earlier atc0005.lxd-host role play
  gather_facts: no

  tasks:

    # Default role settings handle creation; we have to explicitly enable
    # container/settings removal tasks
    - name: Apply lxd-testenv role to create test environment
      import_role:
        name: atc0005.lxd-testenv
      vars:
        # Valid values: "create" and "remove"
        state: "create"

        # Note: Other values can be set here to override role defaults.
        # See the README file for details.

Teardown/Remove test environment

WARNING: Review known Limitations before using this role.

- name: Tear down our LXD test environment
  hosts: all

  # Rely on this setting to be specified in host_vars or group_vars files. If
  # we lock in the 'local' option here then that rules out connecting via SSH
  # later, perhaps as a means of validating earlier playbook tasks.
  # connection: local

  # Fact gathering is not needed for container and settings removal
  gather_facts: no

  tasks:

    - name: Apply lxd-testenv role
      import_role:
        name: atc0005.lxd-testenv
      vars:
        # Valid values: "create" and "remove"
        state: "remove"
        lxd_host_remove_container_settings: true
        lxd_host_remove_containers: true

Installing the role

Create requirements.yml file

Note: This role is not yet available via Ansible Galaxy, so for now you will need to install it via a requirements.yml file.

Specific stable release version

Note: The version numbers listed below are for illustration only. See the releases section of this site to determine the latest available version.

---

# This stub role is referenced by the lxd-testenv setup playbook,
# so we're using an early tag/release to satisfy those requirements
- name: "atc0005.lxd-host"
  src: https://github.com/atc0005/ansible-role-lxd-host.git"
  version: "v0.1-alpha"

- name: "atc0005.lxd-testenv"
  src: https://github.com/atc0005/ansible-role-lxd-testenv.git"
  version: "v1.1"

...

Latest from the master branch

Example requirements.yml file that uses the latest from the master branch:

---

# This stub role is referenced by the lxd-testenv setup playbook,
# so we're including that there to satisfy those requirements.
# Referencing the master branch for this role to match the same branch
# reference for the atc0005.lxd-testenv repo.
- name: "atc0005.lxd-host"
  src: https://github.com/atc0005/ansible-role-lxd-host.git"
  version: "master"

- name: "atc0005.lxd-testenv"
  src: https://github.com/atc0005/ansible-role-lxd-testenv.git"
  version: "master"

...

Use requirements.yml file to install role

• Because ansible-galaxy does not yet natively support updating existing roles, the example installation instructions provided below include the --force parameter to force pulling in the latest updates as directed by the requirements.yml file.

Option 1: Within your home directory

• ansible-galaxy install -r requirements.yml --force

Option 2: Within a roles directory in the same location as your playbooks

• ansible-galaxy install -r requirements.yml -p roles --force

Option 3: System-wide for all users

• sudo ansible-galaxy install -r requirements.yml --force

License

MIT

Author Information

This role was created in 2019 by Adam Chalkley as part of building an on-demand development environment toolkit managed by Ansible.

References

• https://github.com/atc0005/ansible-playbook-lxd-testenv

• https://github.com/atc0005/ansible-playbooks

• https://github.com/atc0005/ansible-role-lxd-host

• https://github.com/atc0005/ansible-role-lxd-testenv

• https://github.com/atc0005/ansible-role-docker-host

• https://linuxcontainers.org/lxd/getting-started-cli/

• https://docs.ansible.com/ansible/latest/modules/lxd_container_module.html

  • https://github.com/lxc/lxd/blob/master/doc/rest-api.md

• https://docs.ansible.com/ansible/latest/modules/lxd_profile_module.html

• Setting up trust relationship between LXD client and LXD server

  • https://lxd.readthedocs.io/en/latest/security/#managing-trusted-clients
  • https://stgraber.org/2016/04/18/lxd-api-direct-interaction/