diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..7ac6fe5 --- /dev/null +++ b/.gitignore @@ -0,0 +1,6 @@ +## For quick testing. +## Generated by https://github.com/ypid/ypid-ansible-common/blob/master/bin/sphinx-debops-role-build +docs/Makefile +docs/_build/ +docs/conf.py +docs/defaults.rst diff --git a/CHANGES.rst b/CHANGES.rst index 4a01962..1b95364 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,10 +1,30 @@ Changelog ========= -v0.1.0 ------- +**debops.resources** -*Released: 2016-06-21* +This project adheres to `Semantic Versioning `_ +and `human-readable changelog `_. + +The current role maintainer is drybjed. + + +`debops.resources master`_ - unreleased +--------------------------------------- + +.. _debops.resources master: https://github.com/debops/ansible-resources/compare/v0.1.0...master + +Added +~~~~~ + +- Added custom delayed paths to allow to create symlinks to files created by this + role. [ypid] + +debops.resources v0.1.0 - 2016-06-21 +------------------------------------ + +Added +~~~~~ - Initial release. [drybjed] diff --git a/COPYRIGHT b/COPYRIGHT new file mode 100644 index 0000000..7629545 --- /dev/null +++ b/COPYRIGHT @@ -0,0 +1,16 @@ +debops.resources - Manage custom file resources through Ansible inventory + +Copyright (C) 2016 Maciej Delmanowski +Copyright (C) 2016 DebOps Project http://debops.org/ + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License version 3, as +published by the Free Software Foundation. + +This program is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see https://www.gnu.org/licenses/ diff --git a/defaults/main.yml b/defaults/main.yml index de2fd52..87ab20f 100644 --- a/defaults/main.yml +++ b/defaults/main.yml @@ -7,11 +7,10 @@ # .. contents:: Sections # :local: # -# .. Role configuration [[[1 -# -# ---------------------- -# Role configuration -# ---------------------- +# .. include:: includes/all.rst + +# Role configuration [[[ +# ------------------ # .. envvar:: resources__enabled # @@ -27,17 +26,15 @@ resources__enabled: True # By default, path is relative to the Ansible inventory. resources__src: '{{ inventory_dir | realpath + "/../resources/" }}' +# .. ]]] -# .. Manage custom paths [[[1 -# -# ----------------------- -# Manage custom paths -# ----------------------- +# Manage custom paths [[[ +# ------------------- # These lists allow you to manage file and directory paths on remote hosts -# using Ansible ``file`` module. By default role treats specified paths as +# using `Ansible file module`_. By default role treats specified paths as # directory names which should be present on the remote host. You can use all -# parameters supported by the ``file`` module. +# parameters supported by the `Ansible file module`_. # # See :ref:`resources__ref_paths` for more details. @@ -58,16 +55,14 @@ resources__group_paths: [] # Paths managed on specific hosts in Ansible inventory. resources__host_paths: [] +# .. ]]] -# .. Manage custom remote resources [[[1 -# -# ---------------------------------- -# Manage custom remote resources -# ---------------------------------- +# Manage custom remote resources [[[ +# ------------------------------ # These lists allow you to specify remote resources to download to the hosts -# using ``get_url`` Ansible module. You can download files over HTTP, HTTPS, -# FTP and use all options supported by the module. +# using the `Ansible get_url module`. You can download files over HTTP, HTTPS, +# FTP and use all options supported by this module. # # See :ref:`resources__ref_urls` for more details. @@ -88,16 +83,14 @@ resources__group_urls: [] # Manage online resources on specific hosts in Ansible inventory. resources__host_urls: [] +# .. ]]] -# .. Manage custom archives [[[1 -# -# -------------------------- -# Manage custom archives -# -------------------------- +# Manage custom archives [[[ +# ---------------------- # These lists allow you to unpack archives stored on Ansible Controller to -# remote hosts using ``unarchive`` Ansible module. You can use all of the -# parameters supported by the ``unarchive`` module. +# remote hosts using the `Ansible unarchive module`_. You can use all of the +# parameters supported by this module. # # See :ref:`resources__ref_archives` for more details. @@ -118,17 +111,15 @@ resources__group_archives: [] # Manage archives on specific hosts in Ansible inventory. resources__host_archives: [] +# .. ]]] -# .. Manage custom files [[[1 -# -# ----------------------- -# Manage custom files -# ----------------------- +# Manage custom files [[[ +# ------------------- # These lists allow you to manage file contents on remote hosts, either by # copying files from Ansible Controller, or providing the contents directly in -# Ansible inventory. You can use all parameters supported by the ``copy`` -# Ansible module. +# Ansible inventory. You can use all parameters supported by the `Ansible copy +# module`_. # # See :ref:`resources__ref_files` for more details. @@ -149,3 +140,37 @@ resources__group_files: [] # Manage file contents on specific hosts in Ansible inventory. resources__host_files: [] + +# Manage custom delayed paths [[[ +# ------------------------------- + +# These lists allow you to manage file and directory paths on remote hosts +# using the `Ansible file module`_. +# The lists can be used exactly the same as +# :regexp:`resources__(?:group_|host_)?paths` from the `Manage custom paths`_ section. +# The only difference is that the custom delayed paths are handled after all +# non delayed resources. +# This allows to create symbolic links to files provided by +# :regexp:`resources__(?:group_|host_)?files` for example. +# +# See :ref:`resources__ref_paths` for more details. + +# .. envvar:: resources__delayed_paths +# +# Paths managed on all hosts in Ansible inventory. +resources__delayed_paths: [] + + +# .. envvar:: resources__group_delayed_paths +# +# Paths managed on hosts in a specific group in Ansible inventory. +resources__group_delayed_paths: [] + + +# .. envvar:: resources__host_delayed_paths +# +# Paths managed on specific hosts in Ansible inventory. +resources__host_delayed_paths: [] + +# .. ]]] + diff --git a/docs/copyright.rst b/docs/copyright.rst index 67d4a48..6d45870 100644 --- a/docs/copyright.rst +++ b/docs/copyright.rst @@ -1,29 +1,5 @@ Copyright ========= -:: +.. literalinclude:: ../COPYRIGHT - Copyright (C) 2016 Maciej Delmanowski - Copyright (C) 2016 DebOps Project http://debops.org/ - [see Credits for more details] - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License version 3, as - published by the Free Software Foundation. - - This program is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see https://www.gnu.org/licenses/ - -Credits -------- - -* Maciej Delmanowski - - * creator of the DebOps Project - - * current project maintainer diff --git a/docs/defaults-detailed.rst b/docs/defaults-detailed.rst index 9c3e6a6..f78e999 100644 --- a/docs/defaults-detailed.rst +++ b/docs/defaults-detailed.rst @@ -1,6 +1,8 @@ Default variable details ======================== +.. include:: includes/all.rst + Some of ``debops.resources`` default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them. @@ -16,7 +18,7 @@ resources__paths These lists can be used to create directories, symlinks, set permissions and ownership, etc. Each element of the list is a YAML dictionary with a set of -parameters. See the documentation of the ``file`` Ansible module for details +parameters. See the documentation of the `Ansible file module`_ for details about what parameters can be used and their format. Here's are additional details for certain parameters: @@ -106,11 +108,11 @@ resources__archives These lists can be used to unpack archives located on Ansible Controller to remote hosts. Each element of the list is a YAML dictionary with parameters -recognized by the ``unarchive`` Ansible Module. For details about their use, +recognized by the `Ansible unarchive module`_. For details about their use, see the module documentation. The ``resources__src`` variable can be used to point the role to a custom, -cental location, by default located in the DebOps project directory. +central location, by default located in the DebOps project directory. Here are some more important parameters: @@ -142,11 +144,11 @@ resources__files These lists can be used to manage content or copy files from Ansible Controller to remote hosts. Each element of a list is a YAML dictionary with parameters -used by the ``copy`` Ansible module. See its documentation for parameter usage +used by the `Ansible copy module`_. See its documentation for parameter usage and syntax. The ``resources__src`` variable can be used to point the role to a custom, -cental location, by default located in the DebOps project directory. +central location, by default located in the DebOps project directory. Here are some more important parameters: diff --git a/docs/getting-started.rst b/docs/getting-started.rst index 059fcd9..3eabd5e 100644 --- a/docs/getting-started.rst +++ b/docs/getting-started.rst @@ -63,3 +63,6 @@ Available role tags: ``role::resources:files`` Manage file contents on the remote hosts. +``role::resources:delayed_paths`` + Manage delayed paths on the remote hosts. + diff --git a/docs/includes/all.rst b/docs/includes/all.rst new file mode 100644 index 0000000..73b2598 --- /dev/null +++ b/docs/includes/all.rst @@ -0,0 +1 @@ +.. include:: includes/global.rst diff --git a/docs/includes/global.rst b/docs/includes/global.rst new file mode 100644 index 0000000..559f208 --- /dev/null +++ b/docs/includes/global.rst @@ -0,0 +1,80 @@ +.. vim: foldmarker=[[[,]]]:foldmethod=marker +.. This file is possible copied to multiple git repositories. +.. The source of this file is https://github.com/ypid/ypid-ansible-common/blob/master/template_role/docs/includes/global.rst +.. All changes are intended to be made to the source file and then the source +.. file should be copied to the downstream repositories as needed. + +.. Ansible core [[[ + +.. _Ansible: https://www.ansible.com/ +.. _`Ansible copy module`: https://docs.ansible.com/ansible/copy_module.html +.. _`Ansible file module`: https://docs.ansible.com/ansible/file_module.html +.. _`Ansible get_url module`: https://docs.ansible.com/ansible/get_url_module.html +.. _`Ansible unarchive module`: https://docs.ansible.com/ansible/unarchive_module.html + +.. ]]] + +.. Projects [[[ + +.. _DebOps: http://debops.org/ +.. _Debian: https://en.wikipedia.org/wiki/Debian +.. _GNU: https://en.wikipedia.org/wiki/GNU_Project +.. _Linux: https://en.wikipedia.org/wiki/Linux +.. _PfSense: https://en.wikipedia.org/wiki/PfSense +.. _FreeBSD: https://en.wikipedia.org/wiki/FreeBSD +.. _`Debian Backports`: http://backports.debian.org/ + +.. _yaml2rst: https://github.com/htgoebel/yaml2rst +.. _LUKS: https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup +.. _dm-crypt: https://en.wikipedia.org/wiki/Dm-crypt +.. _cryptsetup: https://gitlab.com/cryptsetup/cryptsetup +.. _X2go: http://wiki.x2go.org/ +.. _Wine: https://en.wikipedia.org/wiki/Wine_%28software%29 +.. _ownCloud: https://owncloud.org/ +.. _`Let's Encrypt`: https://letsencrypt.org/ + +.. _Opsi: https://en.wikipedia.org/wiki/Opsi +.. _paedML Linux: https://www.lmz-bw.de/technische-unterstuetzung/kundenportal/linux.html +.. _linuxmuster.net: https://linuxmuster.net/ +.. _Univention Corporate Server: https://en.wikipedia.org/wiki/Univention_Corporate_Server + +.. ]]] + +.. IT [[[ + +.. _OCSP: https://en.wikipedia.org/wiki/Online_Certificate_Status_Protocol +.. _DHCP: https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol +.. _`OCSP stapling`: https://en.wikipedia.org/wiki/OCSP_stapling + +.. _PKI: https://en.wikipedia.org/wiki/Public_key_infrastructure +.. _HSTS: https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security +.. _Semantic Versioning: http://semver.org/ + +.. ]]] + +.. DebOps project links [[[ + +.. _debops.apt: https://github.com/debops/ansible-apt +.. _debops.apt_preferences: https://github.com/debops/ansible-apt_preferences +.. _debops.reprepro: https://github.com/debops/ansible-reprepro +.. _debops.apt_cacher_ng: https://github.com/debops/ansible-apt_cacher_ng +.. _debops.pki: https://github.com/debops/ansible-pki +.. _debops.owncloud: https://github.com/debops/ansible-owncloud +.. _debops.grub: https://github.com/debops/ansible-grub + +.. _`DebOps Documentation`: http://docs.debops.org/en/latest/ +.. _`DebOps Contrib`: https://github.com/debops-contrib/debops-contrib +.. _`DebOps Contrib playbooks`: https://github.com/debops-contrib/debops-contrib-playbooks + +.. ]]] + +.. Ansible links of ypid [[[ + +.. _ypid: https://wiki.debops.org/wiki:user:ypid +.. _ypid-ansible-common: https://github.com/ypid/ypid-ansible-common/ +.. _ypid.packages: https://github.com/ypid/ansible-packages +.. _ypid.opsi: https://github.com/ypid/ansible-opsi +.. _ypid.paedml_linux: https://github.com/ypid/ansible-paedml_linux +.. _ypid.copy: https://github.com/ypid/ansible-copy + +.. ]]] diff --git a/tasks/main.yml b/tasks/main.yml index 5b11c2f..baafefa 100644 --- a/tasks/main.yml +++ b/tasks/main.yml @@ -1,5 +1,7 @@ --- +# .. vim: foldmarker=[[[,]]]:foldmethod=marker +# Manage custom paths [[[ - name: Manage paths on remote hosts file: path: '{{ (item.path | d(item.dest | d(item.name))) | d(item) }}' @@ -22,7 +24,9 @@ when: (resources__enabled|bool and ((item.path|d() or item.dest|d() or item.name|d()) or item)) tags: [ 'role::resources:paths' ] +# .. ]]] +# Manage custom remote resources [[[ - name: Download online resources to remote hosts get_url: url: '{{ item.url | d(item.src) }}' @@ -47,7 +51,9 @@ when: (resources__enabled|bool and (item.url|d() or item.src|d()) and (item.dest|d() or item.name|d() or item.path|d())) tags: [ 'role::resources:urls' ] +# .. ]]] +# Manage custom archives [[[ - name: Unpack archives to remote hosts unarchive: src: '{{ item.src }}' @@ -72,7 +78,9 @@ when: (resources__enabled|bool and item.src|d() and (item.dest|d() or item.name|d() or item.path|d())) tags: [ 'role::resources:archives' ] +# .. ]]] +# Manage custom files [[[ - name: Copy files to remote hosts copy: dest: '{{ item.dest | d(item.path | d(item.name)) }}' @@ -115,3 +123,30 @@ (item.state|d() == 'absent')) tags: [ 'role::resources:files' ] +# .. ]]] + +# Manage custom delayed paths [[[ +- name: Manage delayed paths on remote hosts + file: + path: '{{ (item.path | d(item.dest | d(item.name))) | d(item) }}' + state: '{{ item.state | d("directory") }}' + owner: '{{ item.owner | d(omit) }}' + group: '{{ item.group | d(omit) }}' + mode: '{{ item.mode | d(omit) }}' + selevel: '{{ item.selevel | d(omit) }}' + serole: '{{ item.serole | d(omit) }}' + setype: '{{ item.setype | d(omit) }}' + seuser: '{{ item.seuser | d(omit) }}' + follow: '{{ item.follow | d(omit) }}' + force: '{{ item.force | d(omit) }}' + src: '{{ item.src | d(omit) }}' + recurse: '{{ item.recurse | d(omit) }}' + with_flattened: + - '{{ resources__delayed_paths }}' + - '{{ resources__group_delayed_paths }}' + - '{{ resources__host_delayed_paths }}' + when: (resources__enabled|bool and + ((item.path|d() or item.dest|d() or item.name|d()) or item)) + tags: [ 'role::resources:paths' ] +# .. ]]] +