Release 1.0.3 - Refactor Tailscale systemd override architecture (#28)

* Release 1.0.3 - Refactor Tailscale systemd override architecture

Refactor Tailscale role systemd service override handling for better
maintainability and correct systemd directive placement. Consolidate
two separate override templates into one, move configuration defaults
to Ansible variables, and fix Unit vs Service section handling.

Key changes:
- Consolidated config-override.conf.j2 and override.conf.j2 templates
- Moved ExecStart override to tailscale_service_override in defaults
- Fixed systemd directive section placement (Unit vs Service)
- Added cleanup task for legacy config-override.conf
- Updated argument_specs.yml with detailed documentation
- Improved code readability with YAML multiline formatting

* Fix line length in argument_specs.yml

Break long ExecStart line into multiple lines to comply with
yamllint line-length rule (max 160 characters).

Author: sbaerlocher

CHANGELOG.md

@@ -7,6 +7,25 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [1.0.3] - 2026-02-02
+
+### Changed
+
+- **Tailscale Role** - Refactored systemd service override architecture
+    - Consolidated `config-override.conf.j2` and `override.conf.j2` into single unified template
+    - Moved ExecStart override logic from template to [defaults/main.yml](roles/tailscale/defaults/main.yml:19-27)
+    - Fixed Unit vs Service section directive handling in systemd overrides
+    - Added automatic cleanup task for legacy `config-override.conf` file
+    - Updated [argument_specs.yml](roles/tailscale/meta/argument_specs.yml:47-68) with detailed documentation and examples
+    - Improved YAML formatting with multiline syntax for better readability
+
+### Fixed
+
+- **Tailscale Role** - Fixed systemd directive placement errors
+    - Unit directives (After, Wants, PartOf, ReloadPropagatedFrom) now correctly placed in `[Unit]` section
+    - Service directives (ExecStart, Environment, etc.) correctly placed in `[Service]` section
+    - Resolves systemd warning: "Unknown key name in section 'Service'"
+
 ## [1.0.2] - 2026-02-02
 
 ### Fixed
@@ -281,7 +300,8 @@ For detailed configuration examples, see the [Alloy role README](roles/alloy/REA
 
 See: <https://github.com/arillso/ansible.agent/releases>
 
-[Unreleased]: https://github.com/arillso/ansible.agent/compare/1.0.2...HEAD
+[Unreleased]: https://github.com/arillso/ansible.agent/compare/1.0.3...HEAD
+[1.0.3]: https://github.com/arillso/ansible.agent/compare/1.0.2...1.0.3
 [1.0.2]: https://github.com/arillso/ansible.agent/compare/1.0.1...1.0.2
 [1.0.1]: https://github.com/arillso/ansible.agent/compare/1.0.0...1.0.1
 [1.0.0]: https://github.com/arillso/ansible.agent/releases/tag/1.0.0

galaxy.yml

@@ -9,7 +9,7 @@ namespace: arillso
 name: agent
 
 # The version of the collection. Must be compatible with semantic versioning
-version: 1.0.2
+version: 1.0.3
 
 # The path to the Markdown (.md) readme file. This path is relative to the root of the collection
 readme: README.md

roles/tailscale/README.md

@@ -16,7 +16,9 @@ Installs and configures Tailscale VPN for secure mesh networking with support fo
 
 For detailed documentation including all variables, examples, and usage instructions, see:
 
-**<https://guide.arillso.io/collections/arillso/agent/tailscale_role.html>**
+**[Complete Documentation][docs]**
+
+[docs]: https://guide.arillso.io/collections/arillso/agent/tailscale_role.html?utm_source=github&utm_medium=readme&utm_campaign=documentation&utm_content=tailscale_role
 
 ## Quick Start
 

roles/tailscale/defaults/main.yml

@@ -16,7 +16,15 @@ tailscale_tags: []
 tailscale_reset_authentication: false
 
 tailscale_preferences: {}
-tailscale_service_override: {}
+tailscale_service_override:
+    ExecStart:
+        - ""
+        - >-
+            /usr/sbin/tailscaled
+            --state=/var/lib/tailscale/tailscaled.state
+            --socket=/run/tailscale/tailscaled.sock
+            --port=${PORT}
+            --config={{ tailscale_config_file }}
 
 tailscale_server_url: ""
 tailscale_locked: ""

roles/tailscale/meta/argument_specs.yml

@@ -47,8 +47,26 @@ argument_specs:
             tailscale_service_override:
                 type: "dict"
                 required: false
-                default: {}
-                description: "Dictionary of systemd service override parameters"
+                default:
+                    ExecStart:
+                        - ""
+                        - >-
+                            /usr/sbin/tailscaled --state=/var/lib/tailscale/tailscaled.state
+                            --socket=/run/tailscale/tailscaled.sock --port=${PORT}
+                            --config=/etc/tailscale/config.json
+                description: |
+                    Dictionary of systemd service override parameters for tailscaled.service.
+                    Default includes ExecStart override to enable daemon config file support.
+
+                    Supports both Unit and Service section directives:
+                    - Unit directives: After, Before, Wants, Requires, PartOf, Conflicts, etc.
+                    - Service directives: ExecStart, ExecStartPre, Environment, etc.
+
+                    Examples:
+                    - Override ExecStart: tailscale_service_override: {ExecStart: ["", "/custom/path"]}
+                    - Add environment: tailscale_service_override: {Environment: {VAR: "value"}}
+                    - Add dependencies: tailscale_service_override: {After: ["network.target"]}
+                    - Disable config: tailscale_service_override: {} (empty dict)
 
             # Authentication
             tailscale_auth_key:

roles/tailscale/tasks/configure.yml

@@ -56,17 +56,30 @@
   notify: reload tailscale config
   tags: [tailscale, config, daemon]
 
-- name: Configure systemd service to use daemon config file
+- name: Create Tailscale systemd override directory
+  ansible.builtin.file:
+      path: /etc/systemd/system/tailscaled.service.d
+      state: directory
+      mode: "0755"
+      owner: root
+      group: root
+  become: true
+  when: >
+      (tailscale_config_enabled | default(true) | bool and _tailscale_has_config | bool) or
+      (tailscale_service_override | length > 0)
+  tags: [tailscale, config, systemd]
+
+- name: Configure Tailscale systemd service override
   ansible.builtin.template:
-      src: etc/systemd/system/tailscaled.service.d/config-override.conf.j2
-      dest: /etc/systemd/system/tailscaled.service.d/config-override.conf
+      src: etc/systemd/system/tailscaled.service.d/override.conf.j2
+      dest: /etc/systemd/system/tailscaled.service.d/override.conf
       mode: "0644"
       owner: root
       group: root
   become: true
-  when:
-      - tailscale_config_enabled | default(true) | bool
-      - _tailscale_has_config | bool
+  when: >
+      (tailscale_config_enabled | default(true) | bool and _tailscale_has_config | bool) or
+      (tailscale_service_override | length > 0)
   notify:
       - reload systemd
       - restart tailscaled
@@ -86,31 +99,6 @@
   no_log: "{{ tailscale_no_log_auth_key | default(true) }}"
   tags: [tailscale, config, auth]
 
-- name: Create Tailscale systemd override directory
-  ansible.builtin.file:
-      path: /etc/systemd/system/tailscaled.service.d
-      state: directory
-      mode: "0755"
-      owner: root
-      group: root
-  become: true
-  when: tailscale_service_override | length > 0
-  tags: [tailscale, config, systemd]
-
-- name: Configure Tailscale systemd service override
-  ansible.builtin.template:
-      src: etc/systemd/system/tailscaled.service.d/override.conf.j2
-      dest: /etc/systemd/system/tailscaled.service.d/override.conf
-      mode: "0644"
-      owner: root
-      group: root
-  become: true
-  when: tailscale_service_override | length > 0
-  notify:
-      - reload systemd
-      - restart tailscaled
-  tags: [tailscale, config, systemd]
-
 # Reset authentication if requested
 - name: Reset Tailscale configuration (logout and re-authenticate)
   when: tailscale_reset_authentication | default(false) | bool

roles/tailscale/templates/etc/systemd/system/tailscaled.service.d/config-override.conf.j2

@@ -1,8 +1,34 @@
 # Tailscale Systemd Service Override Template
-# Template for systemd service override configuration
+# Consolidated override configuration for daemon config and custom settings
+# Reference: https://tailscale.com/kb/1654/tailscaled-config-file
+{% set unit_directives = ['After', 'Before', 'Wants', 'Requires', 'PartOf', 'Conflicts', 'ReloadPropagatedFrom', 'BindsTo', 'Requisite', 'OnFailure', 'PropagatesReloadTo', 'JoinsNamespaceOf'] %}
+{% set unit_settings = {} %}
+{% set service_settings = {} %}
+{% for key, value in tailscale_service_override.items() %}
+{% if key in unit_directives %}
+{% set _ = unit_settings.update({key: value}) %}
+{% else %}
+{% set _ = service_settings.update({key: value}) %}
+{% endif %}
+{% endfor %}
+
+{% if unit_settings %}
+[Unit]
+{% for section, settings in unit_settings.items() %}
+{% if settings is iterable and settings is not string %}
+# {{ section }} list values
+{% for item in settings %}
+{{ section }}={{ item }}
+{% endfor %}
+{% else %}
+{{ section }}={{ settings }}
+{% endif %}
+{% endfor %}
 
+{% endif %}
 [Service]
-{% for section, settings in tailscale_service_override.items() %}
+{% if service_settings %}
+{% for section, settings in service_settings.items() %}
 {% if section == 'Environment' and settings is mapping %}
 # Environment variables
 {% for key, value in settings.items() %}
@@ -44,3 +70,4 @@ ExecStartPre={{ command }}
 {{ section }}={{ settings }}
 {% endif %}
 {% endfor %}
+{% endif %}