Add docs and tests to the environment capabilities

Systemd service units may require additional environment settings to
be effective. This patch adds two new variables to the systemd_service
role which will allow operators to add environment variables to a
given service as needed. These options be be supplied globally or
from within a service definition.

Documentation on how these options are used has been added to the
defaults file.

A test has been added to ensure we're exercising the new capability.

Change-Id: If4ea993b7173ac3218f051a1d4f0fba9aeb838ea
Signed-off-by: Kevin Carter <kevin@cloudnull.com>

defaults/main.yml

@@ -67,6 +67,27 @@ systemd_default_service_type: simple
 #  This option can also be defined for specific service entries under "systemd_services".
 # systemd_lock_path: "/var/lock/service1"
 
+# Global Environment variables for system services.
+#  This option will provide the operator a way to set additional environment options
+#  used within the execution of a given service. Environment variables can be passed
+#  into the service using ADHOC options or through a given environment file. If both
+#  options are specified, and a collision occurs options will be set in the order in
+#  which they are read (top to bottom) with a given file being processed last.
+#
+#  If the `systemd_environment_file` is defined a file will be read into the systemd service
+#  unit, the contents of the file will be added to the execution environment of the service.
+#
+# The `systemd_environment_file` option is a string. The full path to a given file must be used.
+#  systemd_environment_file: "/etc/default/default-file"
+#
+# The `systemd_environmen`t option is a hash. each item in the hash is expected to be a sting
+# Example
+#   systemd_environment:
+#     VAR1: "word1 word2"
+#     VAR2: "word3"
+#     VAR3: "$word 5 6"
+systemd_environment: {}
+
 # The systemd services dictionary is a set of services that will be created. The dictionary
 #  can contain the following options:
 #  `service_name` -- (required) used to define the name of the service. This is typically the name of the executable.
@@ -79,6 +100,8 @@ systemd_default_service_type: simple
 #  `program_accounting` -- (optional) Case sensitive Key=Value pairs for service Accounting
 #  `enabled` -- (optional) Set the enabled state of the service.
 #  `state` -- (optional) Set the running state of the service.
+#  `environment` -- (optional) set additional environment settings, this option is a hash of strings.
+#  `environment_file` -- (optional) set additional environment settings through a given file. this option is a string.
 
 # Under the service dictionary the "timer" key can be added which will enable a given service
 #  as a timer (Legacy cron job).
@@ -91,6 +114,21 @@ systemd_default_service_type: simple
 
 #  Examples:
 #   systemd_services:
+#     - service_name: ServiceU
+#       config_overrides: {}  # This is used to add in arbitratry unit file options
+#       execstarts:
+#         - ServiceU
+#           environment_file: "/etc/default/default-file"
+#
+#     - service_name: ServiceV
+#       config_overrides: {}  # This is used to add in arbitratry unit file options
+#       execstarts:
+#         - ServiceV
+#           environment:
+#             VAR1: "word1 word2"
+#             VAR2: "word3"
+#             VAR3: "$word 5 6"
+#
 #     - service_name: ServiceW
 #       config_overrides: {}  # This is used to add in arbitratry unit file options
 #       execstarts:

templates/systemd-service.j2

@@ -16,10 +16,12 @@ Type={{ service_type }}
 User={{ item.systemd_user_name | default(systemd_user_name) }}
 Group={{ item.systemd_group_name | default(systemd_group_name) }}
 
-{% if item.environment is defined %}
+{% for key, value in (item.environment | default(systemd_environment)).items() %}
-{% for key, value in item.environment.items() | default({}) %}
 Environment="{{ key }}={{ value }}"
 {% endfor %}
+
+{% if (item.environment_file is defined) or (systemd_environment_file is defined) %}
+EnvironmentFile={{ item.environment_file | default(systemd_environment_file) }}
 {% endif %}
 
 {% set _execstarts = item.execstarts %}

tests/test.yml

@@ -25,7 +25,12 @@
         - service_name: "test simple service0"
           execstarts: "/bin/bash -c 'while true; do sleep 2 && echo test simple service; done'"
           enabled: yes
-        - service_name: "test oneshot service0"
+        - service_name: "test simple service0 with env vars"
+          execstarts: "/bin/bash -c 'while true; do sleep 2 && echo $ENV_VAR1; done'"
+          enabled: yes
+          environment:
+            ENV_VAR1: "testing"
+        - service_name: "test oneshot service1"
           config_overrides:
             Unit:
               Description: Test oneshot service
@@ -67,7 +72,8 @@
       changed_when: false
       with_items:
         - test_simple_service0
-        - test_oneshot_service0
+        - test_simple_service0_with_env_vars
+        - test_oneshot_service1
         - test_timer_service0.timer
         - test_timer_service1.timer
       tags: