test_linux_containers/README.md

# Overview

The Ansible collection `theliberatededge.test_linux_containers`
helps with automating various scenarios based on
[Linux containers](https://linuxcontainers.org/).

# 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. [LXD](https://ubuntu.com/lxd) 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. Python 3 has been set up correctly on the machine.
5. [Ansible](https://pypi.org/project/ansible/) 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,i-1-test-linux-container
```

## Run the launch_linux_container playbook

Substitute the missing variable valuess and run the playbook
for launching Debian Bookworm linux containers.

Variables
- `lte_container_name` stands for the desired container name that
will be visible when running `lxc ls`.
- `lte_container_root_pwd` is the password that will be set for
the `root` user in the container named `lte_container_name`.

```
LC_ALL=C.UTF-8 ansible-playbook \
    theliberatededge.test_linux_containers.launch_linux_container \
        -e "lte_container_name=<container name> lte_container_root_pwd=<password>"
```

Once the playbook finishes execution, you should be able to
connect to the newly launched container as user `root` via
ssh.

## 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: Launch Linux Container
  hosts: all
  gather_facts: false
- name: imports and executes the playbook under test
  ansible.builtin.import_playbook:
    theliberatededge.test_linux_containers.launch_linux_container.yml
  vars:
    lte_debian_version: bookworm
    lte_container_name: <container 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](https://docs.github.com/en/get-started/quickstart/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. [LXD](https://ubuntu.com/lxd) 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. Python 3 has been set up correctly on the machine.
5. [Pipenv](https://github.com/pypa/pipenv) has been installed on the machine.
6. [git](https://git-scm.com/) has been installed on the machine.

### 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
```

```
pipenv install
```

```
pipenv install --dev
```

```
pipenv shell
```

## Lint Ansible artifacts

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

```
cd test_linux_containers
```

Lint all YAML documents.

```
yamllint .
```

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

```
LC_ALL=C.UTF-8 ansible-lint .
```

## YAML code formatting

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

```
cd test_linux_containers
```

Format all YAML documents.

```
yamlfix .
```

## 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
```

Install locally a snapshot version of `theliberatededge.test_linux_containers`
that will be used as the foundation for automated testing.

```
LC_ALL=C.UTF-8 ansible-galaxy install -r requirements-test.yml --force
```

Execute all existing Ansible Molecule scenarios.

```
cd extensions
```

```
LC_ALL=C.UTF-8 \
LTE_CONTAINER_NAME=<container name> \
LTE_CONTAINER_ROOT_PWD=<password> \
    molecule test --all
```