feat: Install and configure NGINX Plus HA keepalived package (#764)

* And add validation support for NGINX modules while at it

CHANGELOG.md

@@ -10,9 +10,10 @@ BREAKING CHANGES:
 
 FEATURES:
 
+- Add support for installing and configuring the NGINX Plus HA keepalived package.
+- Add validation tasks to check the Ansible version, the Jinja2 version, whether the required Ansible collections for this role are installed, and whether you are trying to install a valid NGINX module.
 - Add support for installing NGINX Open Source on Alpine Linux 3.20.
 - Add support for installing NGINX Agent on Ubuntu noble.
-- Add validation tasks to check the Ansible version, the Jinja2 version, and whether the required Ansible collections for this role are installed.
 - Bump the minimum version of Ansible supported to `2.16`, whilst clarifying that Ansible `2.18` is not supported at this stage.
 - Bump the Ansible `community.general` collection to `9.2.0`, `community.crypto` collection to `2.21.1` and `community.docker` collection to `3.11.0`.
 
@@ -28,6 +29,7 @@ TESTS:
 MAINTENANCE:
 
 - Installing certain NGINX modules on Alpine Linux 3.17 no longer requires installing `nginx-plus-module-ndk` as a separate step.
+- Add an `ansible_managed` comment to the various templated configs deployed by the role.
 
 CI/CD:
 

defaults/main/keepalived.yml

@@ -0,0 +1,15 @@
+---
+# Install NGINX Plus HA keepalived package
+nginx_keepalived_enable: false
+
+# Configure NGINX Plus HA keepalived
+nginx_keepalived_conf_enable: false
+nginx_keepalived_conf:
+  - virtual_router_id: 1
+    primary_dev: eth0
+    priority: 101
+    primary_ip: 192.168.100.100
+    secondary_ip:
+      - 192.168.100.101
+    cluster_ip:
+      - 192.168.100.150

handlers/main.yml

@@ -66,3 +66,9 @@
     - logrotate_check['stderr_lines'] != []
     - logrotate_check['rc'] != 0
   listen: (Handler) Run logrotate
+
+- name: (Handler) Start NGINX Plus HA keepalived
+  ansible.builtin.service:
+    name: keepalived
+    state: restarted
+    enabled: true

molecule/plus/converge.yml

@@ -29,3 +29,14 @@
           - set-misc
           - subs-filter
           - xslt
+        nginx_keepalived_enable: true
+        nginx_keepalived_conf_enable: true
+        nginx_keepalived_conf:
+          - virtual_router_id: 1
+            primary_dev: eth0
+            priority: 101
+            primary_ip: 192.168.100.100
+            secondary_ip:
+              - 192.168.100.101
+            cluster_ip:
+              - 192.168.100.150

tasks/main.yml

@@ -74,6 +74,14 @@
     - nginx_state != 'absent'
   tags: nginx_logrotate_config
 
+- name: Install and configure NGINX Plus keepalived HA
+  ansible.builtin.include_tasks: "{{ role_path }}/tasks/modules/install-packages.yml"
+  when:
+    - nginx_keepalived_enable | bool or nginx_keepalived_conf_enable | bool
+    - nginx_type == 'plus'
+    - nginx_state != 'absent'
+  tags: nginx_keepalived
+
 - name: Install NGINX Amplify
   ansible.builtin.include_tasks: "{{ role_path }}/tasks/amplify/install-amplify.yml"
   when: nginx_amplify_enable | bool

tasks/modules/install-packages.yml

@@ -0,0 +1,21 @@
+---
+- name: Install NGINX Plus HA keepalived package
+  ansible.builtin.package:
+    name: nginx-ha-keepalived
+    state: present
+  when:
+    - nginx_keepalived_enable | bool
+    - ansible_facts['os_family'] != 'Alpine'
+    - ansible_facts['distribution'] != 'Amazon'
+  notify: (Handler) Start NGINX Plus HA keepalived
+
+- name: Configure NGINX Plus keepalived HA
+  ansible.builtin.template:
+    src: keepalived/keepalived.conf.tmpl.j2
+    dest: /etc/keepalived/keepalived.conf
+    mode: "0644"
+  when:
+    - nginx_keepalived_conf_enable | bool
+    - ansible_facts['os_family'] != 'Alpine'
+    - ansible_facts['distribution'] != 'Amazon'
+  notify: (Handler) Start NGINX Plus HA keepalived

tasks/validate/validate.yml

@@ -99,3 +99,16 @@
     - nginx_enable | bool
     - (nginx_install_from == "nginx_repository" or nginx_type == "plus")
   ignore_errors: true # noqa ignore-errors
+
+- name: Verify that you are installing a supported NGINX dynamic module
+  ansible.builtin.assert:
+    that: (nginx_modules | difference(nginx_modules_list) == [] if nginx_type == 'opensource') or (nginx_modules | difference(nginx_plus_modules_list) == [] if nginx_type == 'plus')
+    success_msg: The NGINX module(s) you are installing are supported.
+    fail_msg: The NGINX module(s) you are installing are not supported. Please check the README for more details.
+  when:
+    - nginx_enable | bool
+    - nginx_modules is defined
+    - nginx_modules | length > 0
+  delegate_to: localhost
+  become: false
+  ignore_errors: true # noqa ignore-errors

templates/keepalived/keepalived.conf.tmpl.j2

@@ -0,0 +1,45 @@
+{{ ansible_managed | comment }}
+
+global_defs {
+    vrrp_version 3
+}
+
+vrrp_script chk_manual_failover {
+    script "/usr/lib/keepalived/nginx-ha-manual-failover"
+    interval 10
+    weight 50
+}
+
+vrrp_script chk_nginx_service {
+    script "/usr/lib/keepalived/nginx-ha-check"
+    interval 3
+    weight 50
+}
+
+{% for vrrp in nginx_keepalived_conf %}
+vrrp_instance VI_{{ vrrp['virtual_router_id'] }} {
+    interface {{ vrrp['primary_dev'] }}
+    priority {{ vrrp['priority'] }}
+    virtual_router_id {{ vrrp['virtual_router_id'] }}
+    advert_int 1
+    accept
+    garp_master_refresh 5
+    garp_master_refresh_repeat 1
+    unicast_src_ip {{ vrrp['primary_ip'] }}
+    unicast_peer {
+{% for ip in vrrp['secondary_ip'] %}
+        {{ ip }}
+{% endfor %}
+    }
+    virtual_ipaddress {
+{% for ip in vrrp['cluster_ip'] %}
+        {{ ip }}
+{% endfor %}
+    }
+    track_script {
+        chk_nginx_service
+        chk_manual_failover
+    }
+    notify "/usr/lib/keepalived/nginx-ha-notify"
+}
+{% endfor %}

vars/main.yml

@@ -153,4 +153,4 @@ openssl_version: 3.0.7
 nginx_modules_list: [geoip, image-filter, njs, perl, xslt]
 
 # Supported NGINX Plus dynamic modules
-nginx_plus_modules_list: [auth-spnego, brotli, encrypted-session, geoip, geoip2, headers-more, image-filter, lua, ndk, njs, opentracing, passenger, perl, prometheus, rtmp, set-misc, subs-filter, xslt]
+nginx_plus_modules_list: [auth-spnego, brotli, encrypted-session, geoip, geoip2, ha-keepalived, headers-more, image-filter, lua, ndk, njs, opentracing, passenger, perl, prometheus, rtmp, set-misc, subs-filter, xslt]