diff --git a/.ansible-lint b/.ansible-lint index ee89987..657eb5e 100644 --- a/.ansible-lint +++ b/.ansible-lint @@ -1,3 +1,2 @@ exclude_paths: - - ./meta/version.yml - - ./meta/exception.yml + - ./meta/preferences.yml diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index bd1a0dc..d11d68e 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -7,21 +7,25 @@ about: Create a report to help us improve **Describe the bug** A clear and concise description of what the bug is. -**To Reproduce** -Steps to reproduce the behavior: -1. Run this role: -2. See error +**Playbook** +Please paste the playbook you are using. (Consider `requirements.yml` and +optionally the command you've invoked.) + + +```yaml +YOUR PLAYBOOK HERE +``` + +**Output** +Show at least the error, possible related output, maybe just all the output. **Expected behavior** A clear and concise description of what you expected to happen. -**Error** -Please show the resulting error. If applicable a snippet of the playbook including the role ran with `-vvv` - **Environment** -- Control node OS: [e.g. Debian 9] -- Control node Ansible version: [e.g. 2.6.2] -- Managed node OS: [e.g. CentOS 7] +- Control node OS: [e.g. Debian 9] (`cat /etc/os-release`) +- Control node Ansible version: [e.g. 2.6.2] (`ansible --version`) +- Managed node OS: [e.g. CentOS 7] (`cat /etc/os-release`) **Additional context** Add any other context about the problem here. diff --git a/.github/settings.yml b/.github/settings.yml deleted file mode 100644 index f4b57b3..0000000 --- a/.github/settings.yml +++ /dev/null @@ -1,4 +0,0 @@ ---- -repository: - description: A template to easily create a new role. - homepage: https://robertdebock.nl/ diff --git a/.github/settings.yml.j2 b/.github/settings.yml.j2 new file mode 100644 index 0000000..b0e5607 --- /dev/null +++ b/.github/settings.yml.j2 @@ -0,0 +1,4 @@ +--- +repository: + description: Install and configure {{ role_name }} on your system. + homepage: https://robertdebock.nl/ diff --git a/.gitignore b/.gitignore index 8fc05ab..bd0ae11 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,4 @@ +*.molecule +*.log *.swp .tox diff --git a/.gitignore.j2 b/.gitignore.j2 index 10b26d1..bd0ae11 100644 --- a/.gitignore.j2 +++ b/.gitignore.j2 @@ -1,3 +1,4 @@ -molecule/*/.molecule +*.molecule *.log *.swp +.tox diff --git a/.travis.yml.j2 b/.travis.yml.j2 index ed6e1d8..5144bc7 100644 --- a/.travis.yml.j2 +++ b/.travis.yml.j2 @@ -1,4 +1,7 @@ --- +# +# Ansible managed +# language: python python: @@ -11,24 +14,17 @@ env: global: namespace="robertdebock" matrix: - - image="alpine" + - image="alpine" tag="latest" - image="alpine" tag="edge" - - image="amazonlinux" tag="1" - - image="amazonlinux" - # - namespace="archlinux/" image="base" + - image="debian" tag="latest" + - image="debian" tag="unstable" - image="centos" tag="7" - - image="centos" - - image="debian" - - image="fedora" + - image="centos" tag="latest" + - image="fedora" tag="30" + - image="fedora" tag="latest" - image="fedora" tag="rawhide" - - namespace="opensuse" image="leap" - - image="ubuntu" - -matrix: - allow_failures: - - env: image="alpine" tag="edge" - - env: image="debian" tag="unstable" - - env: image="fedora" tag="rawhide" + - image="opensuse" tag="latest" + - image="ubuntu" tag="latest" cache: - pip diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3209430..0b3b951 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,3 +8,67 @@ You can really make a difference by: I'll try to help and take every contribution seriously. It's a great opportunity for me to learn how you use the role and also an opportunity to get into the habit of contributing to open source software. + +## Step by step + +Here is how you can help, a lot of steps are related to GitHub, not specifically my roles. + +### 1. Make an issue. + +When you spot an issue, [create an issue](https://github.com/robertdebock/swap/issues). + +Making the issue help me and others to find similar problems in the future. + +### 2. Fork the project. + +On the top right side of [the repository on GitHub](https://github.com/robertdebock/swap), click `fork`. This copies everything to your GitHub namespace. + +### 3. Make the changes + +In you own GitHub namespace, make the required changes. + +I typically do that by cloning the repository (in your namespace) locally: + +``` +git clone git@github.com:YOURNAMESPACE/swap.git +``` + +Now you can start to edit on your laptop. + +### 4. Optionally: test your changes + +Install [molecule](https://molecule.readthedocs.io/en/stable/) and [Tox](https://tox.readthedocs.io/): + +``` +pip install molecule tox +``` + +And run `molecule test`. If you want to test a specific distribution, set `image` and optionally `tag`: + +``` +image=centos tag=7 molecule test +``` + +Once it start to work, you can test multiple version of Ansible: + +``` +image=centos tag=7 tox +``` + +### 6. Optionally: Regenerate all dynamic content + +You can use [Ansible Generator](https://github.com/robertdebock/ansible-generator) to regenerate all dynamic content. + +If you don't do it, I'll do it later for you. + +### 7. Make a pull request + +[GitHub](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork) on pull requests. + +In the comment-box, you can [refer to the issue number](https://help.github.com/en/github/writing-on-github/autolinked-references-and-urls) by using #123, where 123 is the issue number. + +### 8. Wait + +Now I'll get a message that you've added some code. Thank you, really. + +CI starts to test your changes. You can follow the progress on Travis. diff --git a/README.md.j2 b/README.md.j2 index 0ce51e8..4b1e271 100644 --- a/README.md.j2 +++ b/README.md.j2 @@ -1,104 +1,149 @@ {{ role_name }} ========= -[![Build Status](https://travis-ci.org/robertdebock/ansible-role-{{ role_name}}.svg?branch=master)](https://travis-ci.org/robertdebock/ansible-role-{{ role_name}}) +Ansible logo + Build status -The purpose of this role is to install and configure {{ role_name }} on your system. + -[Unit tests](https://travis-ci.org/robertdebock/ansible-role-{{ role_name }}) are done on every commit and periodically. +Install and configure {{ role_name }} on your system. -If you find issues, please register them in [GitHub](https://github.com/robertdebock/ansible-role-{{ role_name }}/issues) +Example Playbook +---------------- + +This example is taken from `molecule/resources/playbook.yml` and is tested on each push, pull request and release. +```yaml +--- +- name: Converge + hosts: all + become: yes + gather_facts: yes + + roles: + - role: robertdebock.{{ role_name }}``` -To test this role locally please use [Molecule](https://github.com/metacloud/molecule): +The machine you are running this on, may need to be prepared, I use this playbook to ensure everything is in place to let the role work. +```yaml +--- +- name: Converge + hosts: all + become: yes + gather_facts: no + + roles: + - role: robertdebock.bootstrap ``` -# Docker test: -pip install molecule ara -molecule test -# Vagrant tests -molecule test --scenario-name vagrant + +After running this role, this playbook runs to verify that everything works, this may be a good example how you can use this role. +```yaml +--- +- name: Verify + hosts: all + become: yes + gather_facts: yes + + tasks: + - name: check if connection still works + ping: ``` -There are many scenarios available, please have a look in the `molecule/` directory. -Context --------- -This role is a part of many compatible roles. Have a look at [the documentation of these roles](https://robertdebock.nl/) for further information. +Also see a [full explanation and example](https://robertdebock.nl/how-to-use-these-roles.html) on how to use these roles. -Here is an overview of related roles: -![dependencies](https://raw.githubusercontent.com/robertdebock/drawings/artifacts/{{ role_name }}.png "Dependency") +Role Variables +-------------- + +These variables are set in `defaults/main.yml`: +```yaml +--- +# defaults file for {{ role_name }}``` Requirements ------------ -- A system installed with required packages to run Ansible. Hint: [bootstrap](https://galaxy.ansible.com/robertdebock/bootstrap). - Access to a repository containing packages, likely on the internet. -- A recent version of Ansible. (Tests run on the last 3 release of Ansible.) +- A recent version of Ansible. (Tests run on the current, previous and next release of Ansible.) -Role Variables --------------- +The following roles can be installed to ensure all requirements are met, using `ansible-galaxy install -r requirements.yml`: -- {{ role_name }}_parameter: Description of values. [default: value] +```yaml +--- +- robertdebock.bootstrap -Dependencies ------------- +``` + +Context +------- + +This role is a part of many compatible roles. Have a look at [the documentation of these roles](https://robertdebock.nl/) for further information. + +Here is an overview of related roles: +![dependencies](https://raw.githubusercontent.com/robertdebock/drawings/artifacts/{{ role_name }}.png "Dependency") -- None known. Compatibility ------------- -This role has been tested against the following distributions and Ansible version: - -|distribution|ansible 2.4|ansible 2.5|ansible 2.6|ansible 2.7|ansible devel| -|------------|-----------|-----------|-----------|-----------|-------------| -|alpine-edge*|yes|yes|yes|yes|yes*| -|alpine-latest|yes|yes|yes|yes|yes*| -|archlinux|yes|yes|yes|yes|yes*| -|centos-7|yes|yes|yes|yes|yes*| -|centos-latest|yes|yes|yes|yes|yes*| -|debian-latest|yes|yes|yes|yes|yes*| -|debian-stable|yes|yes|yes|yes|yes*| -|debian-unstable*|yes|yes|yes|yes|yes*| -|fedora-latest|yes|yes|yes|yes|yes*| -|fedora-rawhide*|yes|yes|yes|yes|yes*| -|opensuse-leap|yes|yes|yes|yes|yes*| -|ubuntu-artful|yes|yes|yes|yes|yes*| -|ubuntu-devel*|yes|yes|yes|yes|yes*| -|ubuntu-latest|yes|yes|yes|yes|yes*| - -A single star means the build may fail, it's marked as an experimental build. +This role has been tested on these [container images](https://hub.docker.com/): -Example Playbook ----------------- +|container|tags| +|---------|----| +|alpine|all| +|debian|all| +|el|7, 8| +|fedora|all| +|opensuse|all| +|ubuntu|bionic| + +The minimum version of Ansible required is 2.7 but tests have been done to: + +- The previous version, on version lower. +- The current version. +- The development version. + + + +Testing +------- + +[Unit tests](https://travis-ci.org/robertdebock/ansible-role-{{ role_name }}) are done on every commit, pull request, release and periodically. + +If you find issues, please register them in [GitHub](https://github.com/robertdebock/ansible-role-{{ role_name }}/issues) + +Testing is done using [Tox](https://tox.readthedocs.io/en/latest/) and [Molecule](https://github.com/ansible/molecule): + +[Tox](https://tox.readthedocs.io/en/latest/) tests multiple ansible versions. +[Molecule](https://github.com/ansible/molecule) tests multiple distributions. + +To test using the defaults (any installed ansible version, namespace: `robertdebock`, image: `fedora`, tag: `latest`): ``` ---- -- name: {{ role_name }} - hosts: all - gather_facts: no - become: yes +molecule test - roles: - - role: robertdebock.bootstrap - - role: robertdebock.{{ role_name }} - {{ role_name }}_parameter: value +# Or select a specific image: +image=ubuntu molecule test +# Or select a specific image and a specific tag: +image="debian" tag="stable" tox ``` -To install this role: -- Install this role individually using `ansible-galaxy install robertdebock.{{ role_name }}` +Or you can test multiple versions of Ansible, and select images: +Tox allows multiple versions of Ansible to be tested. To run the default (namespace: `robertdebock`, image: `fedora`, tag: `latest`) tests: -Sample roles/requirements.yml: (install with `ansible-galaxy install -r roles/requirements.yml ``` ---- -- name: robertdebock.bootstrap -- name: robertdebock.{{ role_name }} +tox + +# To run CentOS (namespace: `robertdebock`, tag: `latest`) +image="centos" tox +# Or customize more: +image="debian" tag="stable" tox ``` License ------- -Apache License, Version 2.0 +Apache-2.0 + Author Information ------------------ -[Robert de Bock](https://robertdebock.nl/) +[Robert de Bock](https://robertdebock.nl/) diff --git a/handlers/main.yml.j2 b/handlers/main.yml.j2 index 604cb36..3f4c496 100644 --- a/handlers/main.yml.j2 +++ b/handlers/main.yml.j2 @@ -1,6 +1,2 @@ --- # handlers file for {{ role_name }} -- name: restart {{ role_name }} - service: - name: "{% raw -%}{{{%- endraw %} {{ role_name }}_service {%raw -%}}}{%- endraw %}" - state: restarted diff --git a/molecule/default/molecule.yml.j2 b/molecule/default/molecule.yml.j2 index 6755951..20d6764 100644 --- a/molecule/default/molecule.yml.j2 +++ b/molecule/default/molecule.yml.j2 @@ -20,7 +20,7 @@ provisioner: config_options: defaults: stdout_callback: yaml - bin_ansible_callbacks: true + bin_ansible_callbacks: yes verifier: name: ansible lint: diff --git a/tasks/main.yml.j2 b/tasks/main.yml.j2 index df93e5e..a988065 100644 --- a/tasks/main.yml.j2 +++ b/tasks/main.yml.j2 @@ -1,22 +1,2 @@ --- # tasks file for {{ role_name }} -- name: install {{ role_name }} - package: - name: "{% raw -%}{{{%- endraw %} {{ role_name }}_packages {%raw -%}}}{%- endraw %}" - state: present - register: {{ role_name }}_install_{{ role_name }} - until: {{ role_name }}_install_{{ role_name }} is succeeded - retries: 3 - -- name: configure {{ role_name }} - template: - src: "{% raw -%}{{{%- endraw %} {{ role_name }}_config_file {%raw -%}}}{%- endraw %}.j2" - dest: "{% raw -%}{{{%- endraw %} {{ role_name }}_config_directory {%raw -%}}}{%- endraw %}/{% raw -%}{{{%- endraw %} {{ role_name }}_config_file {%raw -%}}}{%- endraw %}" - notify: - - restart {{ role_name }} - -- name: start and enable {{ role_name }} - service: - name: "{% raw -%}{{{%- endraw %} {{ role_name }}_service {%raw -%}}}{%- endraw %}" - state: started - enabled: yes diff --git a/tox.ini b/tox.ini index f1cb9a1..358cd4f 100644 --- a/tox.ini +++ b/tox.ini @@ -1,3 +1,6 @@ +# +# Ansible managed +# [tox] minversion = 3.7 envlist = py{37}-ansible-{previous,current,next} @@ -11,7 +14,7 @@ deps = docker molecule commands = - molecule test + i=0 ; until [ $i -gt 2 ] ; do molecule test ; ((i++)) ; done setenv = TOX_ENVNAME={envname} MOLECULE_EPHEMERAL_DIRECTORY=/tmp/.molecule/{env:image:fedora}-{env:tag:latest}/{envname} diff --git a/vars/main.yml.j2 b/vars/main.yml.j2 index ca5ce05..092d511 100644 --- a/vars/main.yml.j2 +++ b/vars/main.yml.j2 @@ -1,7 +1,2 @@ --- # vars file for {{ role_name }} -_{{ role_name }}_packages: - default: - - {{ role_name }} - -{{ role_name }}_packages: "{% raw -%}{{{%- endraw %} _{{ role_name }}_packages[ansible_os_family] | default(_{{ role_name }}_packages['default']) {% raw -%}}}{%- endraw %}"