Extend upstream Ansible roles without maintaining a fork

Problem

Forking upstream Ansible roles makes upgrades and maintenance harder.

Why it happens

Custom logic is mixed directly into third-party roles, making future upstream updates risky.

Recommended approach

Pin upstream roles to reviewed versions, then keep organization-specific configuration, validation, pre-tasks, post-tasks, restart behavior, and documentation in local wrapper roles.

Example structure

Example structure:

roles/
  upstream/wazuh_ansible
  local/wazuh_manager_config
  local/wazuh_custom_rules
  local/wazuh_agent_deploy

Use this when

• Large community roles
• Internal standards
• Wrapper playbooks
• Maintainable automation

Avoid this when

• The upstream role is unmaintained, unsafe, or fundamentally incompatible with the target architecture

Wrapper playbook pattern

Keep upstream installation and organization-owned configuration as separate responsibilities:

- name: Deploy and configure Wazuh agents
  hosts: wazuh_agents
  become: true
  roles:
    - role: wazuh.wazuh_agent
      tags: [install]
    - role: local.wazuh_agent_config
      tags: [configure]

The local role can validate prerequisites, select inventory-owned files, deploy custom configuration, notify handlers, run health checks, and record operational notes without editing the downloaded collection.

Pin upstream dependencies

collections:
  - name: wazuh.wazuh
    version: "<reviewed-version>"

Commit the dependency file and test upgrades intentionally. An unpinned dependency can change task behavior during an otherwise unrelated deployment.

Keep the boundary explicit

Upstream role responsibilities:

• Package installation and supported baseline configuration
• Vendor-supported variables and platform handling
• Generic service lifecycle

Wrapper responsibilities:

• Inventory conventions and environment selection
• Organization-specific files, rules, and certificates
• Preflight validation and post-deployment checks
• Integration with local secrets and restart policy

Avoid reaching into private task files inside the upstream role. Those filenames are not a stable interface and can change between releases.

Upgrade workflow

1. Update the pinned version in a branch
2. Review the upstream changelog and variable changes
3. Run syntax and lint checks
4. Test one representative host per supported platform
5. Verify idempotence with a second run
6. Validate service health and rollback
7. Promote through environments

References

• Ansible roles
• Installing collections with a requirements file