Merge pull request #5 from nextlayer-ansible/develop

Add changelog, documentation and tests

.github/workflows/tox.yml

@@ -20,7 +20,7 @@ jobs:
   tests:
     name: ${{ matrix.tox_env }}
     runs-on: ubuntu-22.04
-    timeout-minutes: 60
+    timeout-minutes: 15
     strategy:
       fail-fast: false
       matrix:
@@ -30,13 +30,13 @@ jobs:
           - tox_env: packaging
             python-version: "3.9"
           - tox_env: py38
-            PREFIX: PYTEST_REQPASS=2
+            PREFIX: PYTEST_REQPASS=4
             python-version: "3.8"
           - tox_env: py39
-            PREFIX: PYTEST_REQPASS=2
+            PREFIX: PYTEST_REQPASS=4
             python-version: "3.9"
           - tox_env: py310
-            PREFIX: PYTEST_REQPASS=2
+            PREFIX: PYTEST_REQPASS=4
             python-version: "3.10"
 
     steps:

.gitignore

@@ -103,3 +103,6 @@ venv.bak/
 # mypy
 .mypy_cache/
 pip-wheel-metadata
+
+# JetBrains
+.idea/

CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+---
+
+## [0.5.0] - 2023-06-17
+
+### Added
+
+- Add test scenarios
+- Add documentation and examples
+
+### Changed
+- Use canonical/setup-lxd Github action to set up LXD
+
+### Fixed
+- Hardcoded "security.nesting" key from config in create.yml should be removed (#1)
+- Fix destroy playbook for virtual-machines
+
+## [v0.4.0a0] - 2022-02-18
+
+### Changed
+- Update driver to match latest requirements (#25) @bonddim
+- Update ansible connection options (#26) @bonddim
+
+### Fixed
+- Fix functional tests after pytest-helpers-namespace drop (#17) @bonddim
+
+## [0.3] - 2021-06-22
+
+### Changed
+- Added retries to create and destroy playbooks (#14) @bonddim
+- Switch from freenode to libera.chat (#15) @bonddim
+
+## [0.2] - 2021-03-02
+
+### Changed
+- Updated plugin to use newer molecule APIs (#7) @bonddim
+
+## [0.1] - 2020-10-29
+
+### Changed
+- Made driver compatible with molecule 3.2 (#6) @ssbarnea
+

Makefile

@@ -8,6 +8,7 @@ help:
 	@echo
 	@echo "  make lint                 run all linters"
 	@echo
+	@echo "  make test                 run all tests. Allows passing arguments to tox."
 	@echo "  make test-py38            run tests with python 3.8"
 	@echo "  make test-py39            run tests with python 3.9"
 	@echo "  make test-py310           run tests with python 3.10"
@@ -24,15 +25,15 @@ $(RUN_VENV_BIN)/activate: setup.cfg tox.ini pyproject.toml
 	. $(RUN_VENV_BIN)/activate && python3 --version
 
 # Allow to pass-through arguments to ansible-playbook
-ifeq (tox,$(firstword $(MAKECMDGOALS)))
+ifeq (test,$(firstword $(MAKECMDGOALS)))
   # use the rest as arguments for "good"
   RUN_ARGS := $(wordlist 2,$(words $(MAKECMDGOALS)),$(MAKECMDGOALS))
   # ...and turn them into do-nothing targets
   $(eval $(RUN_ARGS):;@:)
 endif
 
-.PHONY: tox
-tox: $(RUN_VENV_BIN)/activate
+.PHONY: test
+test: $(RUN_VENV_BIN)/activate
 	. $(RUN_VENV_BIN)/activate && tox $(RUN_ARGS)
 
 .PHONY: lint

README.md

@@ -1,18 +1,32 @@
 # Molecule LXD Plugin
 
-[![PyPI Package](https://badge.fury.io/py/molecule-lxd.svg)](https://badge.fury.io/py/molecule-lxd)
+[![CI](https://github.com/nextlayer-ansible/molecule-lxd/actions/workflows/tox.yml/badge.svg)](https://github.com/nextlayer-ansible/molecule-lxd/actions/workflows/tox.yml)
 [![Python Black Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)
 [![Ansible Code of Conduct](https://img.shields.io/badge/Code%20of%20Conduct-Ansible-silver.svg)](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html)
 [![Repository License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](LICENSE)
 
-Molecule LXD allows using [LXD](https://linuxcontainers.org/lxd/) to provision containers or virtual machines as test resources for [molecule](https://ansible.readthedocs.io/projects/molecule/).
+*Molecule LXD* allows using [LXD](https://linuxcontainers.org/lxd/) to provision containers or virtual-machines as test resources for [molecule](https://ansible.readthedocs.io/projects/molecule/).
 
 This project is a maintained fork of [ansible-community/molecule-lxd](https://github.com/ansible-community/molecule-lxd), which was archived on January 8, 2023.
 
+## Features
+
+- Use Linux-Containers and Virtual-Machines as test resources for molecule.  
+- Configures molecule to connect to the test resources.
+- Supports local and remote LXD environments.
+
+## Documentation
+
+A [Quickstart-Tutorial](docs/quickstart.md), [examples](docs/examples.md) and more can be found in the [documentation](docs/index.md).
+
+## Changelog
+
+Notable changes to this project are documented in the [CHANGELOG](CHANGELOG.md).
+
 ## License
 
 The [MIT](https://github.com/ansible/molecule/blob/master/LICENSE) License.
 
-The logo is licensed under the [Creative Commons NoDerivatives 4.0 License](https://creativecommons.org/licenses/by-nd/4.0/).
+The Molecule logo is licensed under the [Creative Commons NoDerivatives 4.0 License](https://creativecommons.org/licenses/by-nd/4.0/).
 
 If you have some other use in mind, contact us.

docs/development.md

@@ -0,0 +1,56 @@
+# Development
+
+## Requirements
+
+```sh
+sudo apt install make python3-venv
+```
+
+## Testing
+
+*Molecule LXD* has a few codestyle, unit and functional tests. It uses [Tox](https://tox.readthedocs.io/en/latest/)
+factors to generate a matrix of python x unit/functional tests.
+Please note, that you have to set up python on your own.
+
+### Run all tests
+
+```sh
+make test
+```
+
+### Run linter
+
+```sh
+make lint
+```
+
+### Run tests for a specific python version
+
+```sh
+make test-py39
+```
+
+## Makefile
+
+Use the Makefile target `help` to get all options:
+
+```sh
+make help
+```
+
+Output:
+
+```text
+Usage:
+  make help                 show this message
+  make clean                remove intermediate files
+
+  make lint                 run all linters
+
+  make test                 run all tests. Allows passing arguments to tox.
+  make test-py38            run tests with python 3.8
+  make test-py39            run tests with python 3.9
+  make test-py310           run tests with python 3.10
+
+  make build                build the package
+```

docs/examples.md

@@ -0,0 +1,74 @@
+# Examples
+
+## Minimal
+
+```yaml
+driver:
+  name: lxd
+
+platforms:
+  - name: instance
+    source_alias: ubuntu/jammy/amd64
+```
+
+## Container
+
+```yaml
+driver:
+  name: lxd
+
+platforms:
+  - name: instance
+    groups:
+      - my_group
+    source:
+      alias: ubuntu/jammy/amd64
+      type: image
+      mode: pull
+      server: https://images.linuxcontainers.org
+      protocol: simplestreams
+    config:
+      security.nesting: "true"
+      security.syscalls.intercept.mknod: "true"
+      security.syscalls.intercept.setxattr: "true"
+```
+
+## Virtual-Machine
+
+```yaml
+driver:
+  name: lxd
+
+platforms:
+  - name: instance
+    groups:
+      - my_group
+    source_alias: focal
+    type: virtual-machine
+    config:
+      limits.cpu: "2"
+      limits.memory: 2GB
+      user.user-data: |
+        #cloud-config
+        growpart:
+          mode: auto
+          devices:
+            - '/'
+            - '/dev/sda'
+            - '/dev/sda2'
+          ignore_growroot_disabled: false
+    devices:
+      config:
+        source: cloud-init:config
+        type: disk
+      eth0:
+        nictype: bridged
+        parent: lxdbr0
+        type: nic
+      root:
+        path: /
+        pool: default
+        size: 5GB
+        type: disk
+```
+

docs/index.md

@@ -0,0 +1,23 @@
+# Molecule LXD
+
+*Molecule LXD* is a driver plugin for the [Ansible](https://docs.ansible.com/ansible/latest/index.html) test
+runner [molecule](https://ansible.readthedocs.io/projects/molecule/) and allows
+using [LXD](https://linuxcontainers.org/lxd/) to provision containers or virtual-machines as test resources by using
+the [Ansible LXD container module](https://docs.ansible.com/ansible/latest/collections/community/general/lxd_container_module.html).
+The plugin supports local and remote LXD environments, and configures molecule to connect to the test resources using
+the [Ansible LXD connection plugin](https://docs.ansible.com/ansible/latest/collections/community/general/lxd_connection.html).
+
+## Topics
+
+- [Quickstart](quickstart.md)
+- [Requirements](requirements.md)
+- [Platform Options](platform-options.md)
+- [Examples](examples.md)
+- [Development](development.md)
+- [Changelog](../CHANGELOG.md)
+
+## Further reading
+
+- [Molecule Documentation](https://molecule.readthedocs.io/)
+- [LXD Getting-Started-Guide](https://linuxcontainers.org/lxd/getting-started-cli/)
+- [LXD Documentation](https://linuxcontainers.org/lxd/docs/latest/)