You've already forked cookiecutter-ansible-role
56 lines
2.9 KiB
Markdown
56 lines
2.9 KiB
Markdown
# Ansible Role Cookiecutter #
|
|
|
|
This is a [cookiecutter project] for creating [Ansible roles]. It includes tests using [Molecule] and [YAML Lint] to work with [Woodpecker CI].
|
|
|
|
To use this, first install `cookiecutter`, then run `cookiecutter git+https://hub.cybercinch.nz/guisea/cookiecutter-ansible-role` and answer the prompts.
|
|
|
|
## Development Workflow ##
|
|
|
|
Molecule uses Docker by default to spin up local containers for testing. I have created [several containers] work well for testing Ansible roles. Feel free to use them or change to your own in `molecule/default/molecule.yml`.
|
|
|
|
To test your role, you first need to install Molecule by running `pip install molecule`, or using your package manager of choice. You may also `pip install molecule[docker]` to also install the `docker` Python library, or `pip install molecule[lint]` to install `ansible-lint`, `yamllint`, and `flake8`.
|
|
|
|
Next, run `molecule test`. This will run the entire default test scenario, which creates a test container, runs the linters, runs the role twice, then destroys the container.
|
|
|
|
I frequently find I want to interact with the test instance rather than destroying it. To create a test instance, run your role, then leave the container running, run `molecule converge`. You can then interact with the container using `molecule login`. To rerun your role against the existing container, just run `molecule converge` again.
|
|
|
|
Once you are done with the container, run `molecule destroy` to remove it.
|
|
|
|
### Customizing the Test ###
|
|
|
|
The default scenario runs `molecule/default/converge.yml`. You can customize this playbook to suit your needs.
|
|
|
|
The `molecule.yml` file is setup to accept three environment variables:
|
|
|
|
`MOLECULE_DISTRIBUTION`: controls the distribution to test against
|
|
`MOLECULE_COMMAND`: the command to run inside the container
|
|
`MOLECULE_PLAYBOOK`: the name of the playbook to run
|
|
|
|
Valid values for `MOLECULE_DISTRIBUTION` based on how I name my test containers are:
|
|
- centos7
|
|
- centos8 (the default)
|
|
- ubuntu16
|
|
- ubuntu18
|
|
- ubuntu20
|
|
- debian9
|
|
- debian10
|
|
- fedora30
|
|
- fedora31
|
|
|
|
For example, to test your role on Debian 10, run `env MOLECULE_DISTRIBUTION=debian10 molecule test`.
|
|
|
|
|
|
## Thanks ##
|
|
|
|
A special thank you to [Jeff Geerling] for being a trailblazer with Molecule (and Ansible role testing in general). I would be lost without his amazing work.
|
|
|
|
[cookiecutter project]: https://github.com/audreyr/cookiecutter
|
|
[Ansible roles]:https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html
|
|
[molecule]: https://molecule.readthedocs.io
|
|
[Ansible Lint]: https://docs.ansible.com/ansible-lint/
|
|
[YAML Lint]:https://yamllint.readthedocs.io/en/stable/
|
|
[Woodpecker CI]: https://woodpecker-ci.org/
|
|
[several containers]: https://quay.io/user/samdoran
|
|
[Jeff Geerling]: https://www.jeffgeerling.com/blog/2018/testing-your-ansible-roles-molecule
|
|
[linting behavior changed]: https://molecule.readthedocs.io/en/latest/configuration.html#lint
|