generated from the-liberated-edge/wikijs
230 lines
6.8 KiB
Markdown
230 lines
6.8 KiB
Markdown
# 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. [incus](https://linuxcontainers.org/incus/docs/main/) 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
|
|
```
|
|
|
|
## 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 `incus 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. [incus](https://linuxcontainers.org/incus/docs/main/) 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.
|
|
7. [Task](https://github.com/go-task/task) has been installed and has been
|
|
available in the `$PATH` environment variable for the current user.
|
|
|
|
### 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.
|
|
|
|
```
|
|
task lint-yml
|
|
```
|
|
|
|
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
|
|
```
|
|
|
|
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
|
|
```
|