generated from the-liberated-edge/wikijs
adds docu on getting started and contributing
This commit is contained in:
emo
parent
280eced725
commit
3787c67f39
223
README.md
223
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=<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 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: <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. Every git pull request has been linked to exactly one project issue. The
|
||||
issue number prefixes the pull request title, e.g. `i-1 <issue title>`.
|
||||
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=<container name> \
|
||||
LTE_CONTAINER_ROOT_PWD=<password> \
|
||||
molecule test --all
|
||||
```
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user