Commit b91209b6 authored by Maciej Delmanowski's avatar Maciej Delmanowski

[debops.resources] Implement support for commands

parent ce216d6c
......@@ -92,6 +92,11 @@ Added
.. __: https://wiki.debian.org/LTS
- [debops.resources] New :ref:`resources__ref_commands` variables can be used
to define simple shell commands or scripts that will be executed at the end
of the :ref:`debops.resources` role. Useful to start new services, but it
shouldn't be used as a replacement for a fully-fledged Ansible roles.
Changed
~~~~~~~
......
debops.resources - Manage custom file resources through Ansible inventory
Copyright (C) 2016-2017 Maciej Delmanowski <drybjed@gmail.com>
Copyright (C) 2016-2017 DebOps https://debops.org/
Copyright (C) 2016-2019 Maciej Delmanowski <drybjed@gmail.com>
Copyright (C) 2016-2019 DebOps https://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
......
......@@ -287,5 +287,43 @@ resources__group_delayed_paths: []
# Paths managed on specific hosts in Ansible inventory.
resources__host_delayed_paths: []
# ]]]
# Custom shell commands [[[
# -------------------------
# The variables below let you define shell commands (or even small shell
# scripts) to execute on the remote hosts as the ``root`` UNIX account. You
# need to ensure idempotency by yourself. This is not a replacement for
# a normal Ansible role.
#
# See :ref:`resources__ref_commands` for more details.
# .. envvar:: resources__commands [[[
#
# List of shell commands which should be executed on all hosts in the Ansible
# inventory.
resources__commands: []
# ]]]
# .. envvar:: resources__group_commands [[[
#
# List of shell commands which should be executed on hosts in a specific
# Ansible inventory group.
resources__group_commands: []
# ]]]
# .. envvar:: resources__host_commands [[[
#
# List of shell commands which should be executed on specific hosts in the
# Ansible inventory.
resources__host_commands: []
# ]]]
# .. envvar:: resources__combined_commands [[[
#
# Variable which combines all other shell command variables and is used in the
# role tasks.
resources__combined_commands: '{{ resources__commands
+ resources__group_commands
+ resources__host_commands }}'
# ]]]
# ]]]
......@@ -276,6 +276,17 @@
((item.path|d() or item.dest|d() or item.name|d()) or item))
tags: [ 'role::resources:paths' ]
# Execute custom shell commands [[[1
# This is not an alternative to a fully-fledged Ansible role.
- name: Execute shell commands
include_tasks: 'shell_commands.yml'
loop: '{{ q("flattened", resources__combined_commands) | parse_kv_items }}'
loop_control:
label: '{{ {"name": item.name} }}'
when: resources__enabled|bool and
item.name|d() and item.state|d('present') not in [ 'absent', 'ignore' ]
no_log: '{{ item.no_log | d(False) }}'
# DebOps post-hook [[[1
- name: Post hooks
include: '{{ lookup("task_src", "resources/post_main.yml") }}'
---
- name: '{{ item.name }}'
shell: '{{ item.script | d(item.shell | d(item.command)) }}' # noqa 305
args:
chdir: '{{ item.chdir | d(omit) }}'
creates: '{{ item.creates | d(omit) }}'
removes: '{{ item.removes | d(omit) }}'
executable: '{{ item.executable | d("/bin/bash") }}'
when: item.name|d() and item.state not in [ 'absent', 'ignore' ]
no_log: '{{ item.no_log | d(False) }}'
......@@ -396,3 +396,93 @@ Parameters related to ACL
Optional. If not specified or ``present``, the ACL entry will be created.
If ``absent``, the ACL entry will be removed. The ``query`` state doesn't
make sense in this context and shouldn't be used.
.. _resources__ref_commands:
resources__commands
-------------------
The ``resources__*_commands`` variables can be used to define shell commands or
small scripts which should be executed on the remote hosts. This can be useful
to, for example, start a :command:`systemd` service created previously using
the :ref:`resources__ref_files` variables.
This is not a replacement for a fully-fledged Ansible role. The interface is
extremely limited, and you need to ensure idempotency inside of the script or
command you are executing. The :ref:`debops.resources` role can be executed at
different points in the main playbook, which you should also take into account.
Examples
~~~~~~~~
Set up a simple example :command:`systemd` service and start it:
.. code-block:: yaml
resources__files:
- content: |
[Unit]
Description=Example Service
[Service]
Type=simple
ExecStart=/bin/true
RemainAfterExit=yes
[Install]
WantedBy=multi-user.target
dest: '/etc/systemd/system/example.service'
mode: '0644'
resources__commands:
- name: 'Reload systemd and start example service'
shell: |
if ! systemctl is-active example.service ; then
systemctl daemon-reload
systemctl start example.service
fi
Syntax
~~~~~~
Each shell command entry is defined by a YAML dictionary with specific
parameters:
``name``
Required. A name of a given shell command displayed during Ansible execution,
not used for anything else in the task. Multiple configuration entries with
the same ``name`` parameter are merged together.
``script`` / ``shell`` / ``command``
Required. String or YAML text block that contains the command or script to
execute on the remote host. The contents will be passed to the ``shell``
Ansible module.
``chdir``
Optional. Specify the path to the directory on the remote host where the
script should be executed.
``creates``
Optional. Specify the path of the file on the remote host - if it's present,
the ``shell`` module will not execute the script.
``removes``
Optional. Specify the path of the file on the remote host - if it's absent,
the ``shell`` module will not execute the script.
``executable``
Optional. Specify the command interpreter to use. If not specified,
``/bin/bash`` will be used by default.
``state``
Optional. If not specified or ``present``, the shell command will be executed
as normal by the role. If ``absent``, the shell command will not be executed
by the role. If ``ignore``, the configuration entry will not be evaluated by
the role during execution. This can be used to conditionally activate and
deactivate different shell commands on the Ansible level.
``no_log``
Optional, boolean. If ``True``, Ansible will not display the task contents or
record them in the log. It's useful to avoid recording sensitive data like
passwords.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment