Overview

The Ansible collection theliberatededge.test_linux_containers helps with automating various scenarios based on Linux containers.

Getting started

This section describes the ways in which engineers could benefit from utilising the Ansible collection theliberatededge.test_linux_containers.

Prerequisites

1. You have access to a machine running a Linux distribution of your choice.
2. incus has been installed and initialised on this machine, so that containers can be launched. It will effectively be used as a container hypervisor.
3. Your user has been granted permissions to manage Linux containers.
4. OpenSSH client and sshpass have been installed on the local machine.
5. Python 3 has been set up correctly on the machine.
6. Ansible has been installed.
7. pigz has been installed.

Install the Ansible collection theliberatededge.test_linux_containers

Install or update theliberatededge.test_linux_containers on your Linux machine using ansible-galaxy.

ansible-galaxy collection install -U --force \
    git+https://git.theliberatededge.org/the-liberated-edge/test_linux_containers.git

Run the launch_linux_container playbook

Substitute the missing variable valuess and run the playbook for creating and publishing Debian Bookworm linux container images to a locally running incus image server.

Variables

• lte_image_name stands for the desired Linux container image.
• lte_container_root_pwd is the password that will be set for the root user in the containers created out of the lte_image_name Linux container image.

LC_ALL=C.UTF-8 ansible-playbook \
    theliberatededge.test_linux_containers.image_published_locally \
        -e "lte_image_name=<image name> lte_container_root_pwd=<password>"

Once the playbook finishes execution, you should be able to launch new containers refering to the newly published image name.

incus launch <image_name> <container_name>

Include playbook or role from the collection

Reusing Ansible roles and playbooks is quite straight forward and follows the practices established by Ansible. Below you will find a sample playbook.

Similarly to executing the playbook via CLI, one needs to assign the missing values to the variables first.

---
- name: Create and publish locally container image
  hosts: all
  gather_facts: false
- name: Imports and executes the playbook
  ansible.builtin.import_playbook:
    theliberatededge.test_linux_containers.image_publlished_locally.yml
  vars:
    lte_debian_version: bookworm
    lte_image_name: <image name>
    lte_container_root_pwd: <password>

How to contribute

This section describes what you need to do in order to contribute to this project if you want to work on our code base. It is all about setting up your local development environment and the ways of working that we have established.

Development workflow

Our team uses Github flow to release changes.

Definition of Done

We are a small team and for us squeezing and saving any second is key. This is the way we could manage better our scarce resources. Therefore, we have been experimenting with and adopting industry practices which help us do more with less.

Every change that we merge in the main branch complies to the following list of requirements or checklist.

1. Every change request is represented as a git pull request. Merging changes directly in the main branch is prohibited and guarded by a branch protection rule in our source control system.
2. All commits as part of a feature branch have been squashed into a single commit that has been merged in the main branch.
3. Every git pull request has been linked to exactly one project issue. The issue number prefixes the pull request title, e.g. i-1 <pull request title>. been resolved. Merging without a code review approval is only acceptable when reviewers are not available.
4. The change has been tested by Ansible Molecule scenarios. Our team adopted an approach resembling Test Driven Development for the sake of automated regression testing.
5. All automated tests have been passing successfully consistently. We have zero tolerance on test flakiness.
6. Source code has been linted with yamllint and ansible-lint. Any errors have been fixed.
7. All YAML documents have been formated with yamlfix.
8. User facing changes have been documented appropriately.

Development environment setup

Prerequisites

Before you could set up your local development environment you will need to make sure that the list of prerequisites below has been satisfied.

1. You have access to a machine running a Linux distribution of your choice.
2. incus has been installed and initialised on this machine, so that containers can be launched. It will effectively be used as a container hypervisor.
3. Your user has been granted permissions to manage Linux containers, i.e. your user is a member of the group incus-admin.
4. OpenSSH client and sshpass have been installed on the local machine.
5. Python 3 has been set up correctly on the machine.
6. Pipenv has been installed on the machine.
7. git has been installed on the machine.
8. Task has been installed and has been available in the $PATH environment variable for the current user.
9. pigz has been installed.

Initialize collection project locally

All dependencies and dev dependencies will be installed in a Python 3 virtual environment, which will be activated for you.

git clone \
    https://git.theliberatededge.org/the-liberated-edge/test_linux_containers.git

cd test_linux_containers

Prior to any further development one needs to initialise the project by running the following commands on the command line.

task init-project pipenv-shell

These tasks will perform the following steps.

1. Create a Python virtual environment through pipenv.
2. Any Python dependencies described in Pipfile.lock, such as Ansible, will be downloaded and installed.
3. Any Python development dependencies described in Pipfile.lock, such as linters and code formatters, will be downloaded and installed.
4. The virtual environment will be activated.

From this point on, the project is properly initialised for development.

Lint Ansible artifacts

Navigate to the root folder of the local copy of this git repository.

cd test_linux_containers

Lint all YAML documents.

task lint-yml

Note that this task will trigger formatting of all YAML documents in the repository as a prerequisite to linting.

Use ansible-lint to verify good practices relevant to Ansible.

task lint-ansible

Note that this task depends on lint-yml, which means that linting YML will happen before linting the Ansible code base. Linting the Ansible code base will only be triggered when linting all YML documents in the repository has been successful.

YAML code formatting

Navigate to the root folder of the local copy of this git repository.

cd test_linux_containers

Format all YAML documents.

task format-yml

Execute Ansible Molecule scenarios

In order to run all existing Ansible Molecule scenarios, one needs to follow the steps below.

Navigate to the root folder of the local copy of this git repository.

cd test_linux_containers

Run the following task to execute all of the Ansible Molecule test scenarios in the project.

LTE_CONTAINER_ROOT_PWD=<password> task test-all

LTE_CONTAINER_ROOT_PWD is an environment variable denoting the password of the root user in the testing container.