Add README and first Ansible role skeleton: role_default

Thanks to @Meissnerim for working on the code, additional review and input.

Author: andreashaerter

LICENSE

@@ -0,0 +1,13 @@
+Copyright 2020 Foundata GmbH, https://foundata.com
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

NOTICE

@@ -0,0 +1,12 @@
+NOTE: Any derivative works that you distribute must include a readable copy of
+      the attribution notices contained in this file (cf. Apache License 2.0;
+      § 4.4).
+
+
+I. Foundata
+
+   This Ansible resource is based on the work of Foundata [1]. If you like it,
+   you might buy them a coffee [2] or have a look at their website.
+
+   [1] https://foundata.com/
+   [2] https://buy-me-a.coffee/ansible-skeletons/

README.md

@@ -0,0 +1,62 @@
+# Ansible (Galaxy) Skeletons
+
+This repository contains different skeletons / blueprints to kickstart the creation of new [roles](https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html) and [collections](https://docs.ansible.com/ansible/devel/dev_guide/developing_collections.html).
+
+
+
+## Table of contents
+
+* [Usage](#usage)
+* [Description of provided skeletons](#description-of-provided-skeletons)
+  * [`role_default`](#role_default)
+* [Author information](#author-information)
+* [License, Copyright](#license-copyright)
+
+
+
+## Usage
+
+1. Clone this repository:
+   ```sh
+   git clone https://github.com/foundata/ansible-skeletons.git
+   ```
+2. Call `ansible-galaxy` and provide the path to the skeleton to use as well as a role name:
+   ```sh
+   ansible-galaxy role init --role-skeleton "./ansible-skeletons/role_default" "name_of_your_role"
+   ```
+   * `name_of_your_role` has to follow [some rules](https://galaxy.ansible.com/docs/contributing/creating_role.html#role-names) and is should consist of `a-z`, `0-9` and `_` only.
+   * Adapt the `--role-skeleton` parameter value if you want to use another skeleton than `role_default`. You can find a description of the available ones below.
+3. Have a look at the created `./name_of_your_role/FIXME.md` to get further instructions.
+
+
+
+## Description of provided skeletons
+
+The following lists gives an overview over the available skeletons. You can also have a look into the sub-directories of this repository to look at their code (even though the source might be partially hard to read. There is [Jinja](https://palletsprojects.com/p/jinja/) code which will be processed by `ansible-galaxy role init` to get the final files).
+
+
+
+### `role_default`
+
+A general purpose skeleton to create new Ansible Galaxy roles. Main features:
+
+* Init tasks to check the execution environment based on the role's meta data
+* Easy management of role parameters and belonging [`assert`](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/assert_module.html) rules for validation (see `{{ role_name }}_required_vars` in [`role_default/vars/main.yml.j2`](./role_default/vars/main.yml.j2) for more information).
+* Separation of logical task groups
+
+
+
+## Author information
+
+This project was created and is maintained by:
+
+* [Andreas Haerter](https://andreashaerter.com/) ([Foundata](https://foundata.com/))
+* [Frederik Meissner](https://meissner.im/) ([Foundata](https://foundata.com/))
+
+If you like it, you might [buy us a coffee](https://buy-me-a.coffee/ansible-skeletons/).
+
+
+
+## License, Copyright
+
+[Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0) if not mentioned otherwise. See [`LICENSE`](./LICENSE) and [`NOTICE`](./NOTICE) for details.

role_default/.gitignore

@@ -0,0 +1,5 @@
+# do not ignore files used to keep empty directories
+!.gitkeep
+
+### Ansible ###
+*.retry

role_default/FIXME.md.j2

@@ -0,0 +1,53 @@
+# FIXME/TODO (you should delete this file after reading / completing the tasks)
+
+A (maybe incomplete but hopefully useful) list of things to do after creating a
+new role based on the skeleton, especially before releasing anything:
+
+1. **Update author information** (and/or company and/or year) in
+   * [`LICENSE`](./LICENSE) → First line
+   * [`meta/main.yml`](./meta/main.yml) → `galaxy_info:` → `author`, `company`
+     and URLs if fitting
+   * The "[`README.md`: Author Information](./README.md#author-information)" section
+2. **Update requirements information** in the "[`README.md`: Requirements](./README.md#requirements)"
+   section and list any pre-requisites that may not be covered by Ansible
+   itself, e.g.:
+   * DNS names to configure, firewall ports to open
+   * [SELinux](https://en.wikipedia.org/wiki/Security-Enhanced_Linux)
+     * has to be disabled.
+     * is supported in "Permissive" mode only.
+     * is supported in "Enforcing" as well as in "Permissive" mode.
+3. **Update dependency information**:
+   * In the "[`README.md`: Dependencies](./README.md#dependencies)" section:
+     * A list of other roles hosted on Galaxy should go here
+     * Plus any details in regards to parameters that may need to be set for
+       other roles or variables that are used from other roles.
+   * [`meta/main.yml`](./meta/main.yml) -> `dependencies:`
+4. **Update compatibility information**:
+   * In the "[`README.md`: Compatibility](./README.md#compatibility)" section:
+     * maybe you want to mention the main platform / first class citizens.
+     * or if things where tested on container / VM / bare metal
+   * [`meta/main.yml`](./meta/main.yml) -> `platforms:`
+     * There is [a list of platforms](https://galaxy.ansible.com/api/v1/platforms/)
+     * The list is paginated. You can also search for e.g. Fedora by adding
+       `?name__icontains=fedora`.
+5. **Tests / [Molecule](https://molecule.readthedocs.io/en/latest/)**: delete the
+   whole `./molecule` directory if you do not want to provide tests at this point
+   in time or:
+   * [`molecule/default/molecule.yml`](./molecule/default/molecule.yml): Define `driver` and `platforms` for your tests
+   * [`molecule/default/tests/`](./molecule/default/tests/): Write test cases (Example: [`molecule/default/tests/test_default.py`](./molecule/default/tests/test_default.py))
+6. **Misc things**
+   * [`meta/main.yml`](./meta/main.yml): Remove unneeded, commented keys. See
+     the following for more information if you are unsure what they do or if
+     you even need more:
+     * <https://galaxy.ansible.com/docs/contributing/creating_role.html#role-metadata>
+     * <https://github.com/ansible/ansible/blob/devel/lib/ansible/playbook/role/metadata.py>
+     * <https://github.com/ansible/ansible/blob/devel/lib/ansible/cli/galaxy.py>
+   * You may want to add a section with useful weblinks to describe what the
+     role is managing or other useful resources:
+     ```markdown
+     ## Further reading
+
+     * [Official Example website](http://example.com/]
+     * [Wikipedia: Example](http://en.wikipedia.org/wiki/Example)
+     ```
+   * Add example playbook(s) to the "[`README.md`: Example Playbook](./README.md#example-playbook)" section

role_default/LICENSE.j2

@@ -0,0 +1,13 @@
+Copyright YYYY {{ company }}, {{ author }} <email@example.com>
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

role_default/NOTICE.j2

@@ -0,0 +1,12 @@
+NOTE: Any derivative works that you distribute must include a readable copy of
+      the attribution notices contained in this file (cf. Apache License 2.0;
+      § 4.4).
+
+
+I. Foundata
+
+   This Ansible role is based on the work of Foundata [1]. If you like it,
+   you might buy them a coffee [2] or have a look at their website.
+
+   [1] https://foundata.com/
+   [2] https://buy-me-a.coffee/ansible-skeletons/

role_default/README.md.j2

@@ -0,0 +1,73 @@
+# `{{ role_name }}`
+
+{{ description }}
+
+
+
+## Table of contents
+
+* [Requirements](#requirements)
+* [Role variables](#role-variables)
+* [Dependencies](#dependencies)
+* [Example playbook](#example-playbook)
+* [Supported tags](#supported-tags)
+* [Compatibility](#compatibility)
+* [License, copyright](#license-copyright)
+* [Author information](#author-information)
+
+
+
+## Requirements
+
+There are no special requirements not covered by Ansible itself.
+
+
+
+## Role variables
+
+See [`defaults/main.yml`](./defaults/main.yml) for all available role parameters and their description. [`vars/main.yml`](./vars/main.yml) contains variables you should not override (but their descrption might be interesting).
+
+Additionally, there are variables read from other roles and/or the global scope (e.g. host or group vars) as follows:
+
+* None right now.
+
+
+
+## Dependencies
+
+See `dependencies` in [`meta/main.yml`](./meta/main.yml).
+
+
+
+## Example playbook
+
+None right now.
+
+
+
+## Supported tags
+
+It might be useful and faster to only call parts of the role by using tags:
+
+* `setup`: Setup tasks like package installations (mostly one-time).
+* `config`: Creates / updates configuration files and related resources.
+* `service`: Creates / updates service related files and manages their state.
+* `always`: Preparation task at start as well as clean-up task during completion. May be called explicitly to force a cleanup (for example leftovers when there was an unexpected interruption).
+
+
+
+## Compatibility
+
+See `platforms` in [`meta/main.yml`](./meta/main.yml).
+
+
+
+## License, copyright
+
+[Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0). See [`LICENSE`](./LICENSE) and [`NOTICE`](./NOTICE) for details.
+
+
+
+## Author information
+
+This role was created by {{author}} and is based on an [Ansible skeleton](https://github.com/foundata/ansible-skeletons) by [Foundata](https://foundata.com/). If you like it, you might [buy them a coffee](https://buy-me-a.coffee/ansible-skeletons/).

role_default/defaults/main.yml.j2

@@ -0,0 +1,43 @@
+# Default values of the role.
+#
+# Easy to override (as they have a low precedence) and most commonly used to
+# enable a user to modify the role behavior. There should be a comment above
+# each value to explain its purpose.
+
+---
+
+# String. Controls if the managed resources shall be "present" or "absent".
+# Defaults to "present". Possible values:
+#
+# * "present": Needed components like software packages will be installed and
+#   configured.
+# * "absent": Modifications (if any) will be reverted as good as possible (e.g.
+#   removal of packages, created users, services, changed log settings, …).
+{{ role_name }}_state: "present"
+
+
+# Boolean. If set to true, any managed package gets upgraded on each Ansible
+# run when the package provider is able to find a newer version than the
+# present one. Defaults to false.
+{{ role_name }}_autoupgrade: false
+
+
+# String. Defines the status of service(s). Defaults to "enabled". Possible
+# values:
+#
+# * "enabled": Service is running and will start automatically at boot.
+# * "disabled": Service is stopped and will not start automatically at boot.
+# * "running": Service is running but will not start automatically at boot.
+#   You can use this to start a service on the first Ansible rather
+#   automatically at boot.
+# * "unmanaged": Service will not be started at boot time and Ansible does not
+#   care whether the service is running or not. Mostly useful when services
+#   are monitored and managed by another system than Ansible.
+#
+# The singular form ("service") is used for the sake of convenience. Of course,
+# the defined status affects all services if more than one is managed.
+{{ role_name }}_service_state: "enabled"
+
+
+# FIXME Description of a very important example parameter
+# {{ role_name }}_example_parameter_variable: true