diff --git a/README.md b/README.md index 9bf44d2..9bc260b 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,222 @@ -# Ansible Collection - theliberatededge.test_linux_containers +# Overview -Documentation for the collection. +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= lte_container_root_pwd=" +``` + +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 values to the missing variables. + +``` +--- +- 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: + lte_container_root_pwd: +``` + +# 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. Every git pull request has been linked to exactly one project issue. The +issue number prefixes the pull request title, e.g. `i-1 `. +3. The change has been thoroughly reviewed and all discovered issues have +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 and avoidance. +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 issues +have been resolved. +7. 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= \ +LTE_CONTAINER_ROOT_PWD= \ + molecule test --all +```