DEBOPS.KEEPALIVED(5)

NAME
debops.keepalived - Manage keepalived service using Ansible

SYNOPSIS

debops run service/keepalived [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

The keepalived <https://keepalived.org/> service can be used to provide simple load balancing and high availability services in a Linux cluster. The service uses the Virtual Router Redundancy Protocol <https://en.wikipedia.org/wiki/Virtual_Router_Redundancy_Protocol> for communication between the nodes in a cluster and can perform specified actions on the nodes - create or remove IP addresses, start or stop services, and more.

The debops.keepalived Ansible role can be used to install and configure the keepalived service on Debian and Ubuntu hosts. The role allows Jinja expressions to be used in the keepalived.conf(5) <https://manpages.debian.org/keepalived.conf(5)> configuration file to augment generated configuration files as needed.

GETTING STARTED

  Example inventory

To install and configure keepalived on a given host, it should be included in a specific Ansible inventory group:

[debops_all_hosts]
hostname   ansible_host=hostname.example.org
[debops_service_keepalived]
hostname

Of course, installing keepalived on a single host does not provide any benefits, so it's better to create a cluster instead:

[debops_all_hosts]
node1   ansible_host=node1.example.org
node2   ansible_host=node2.example.org
node3   ansible_host=node3.example.org
[debops_service_keepalived]
node1
node2
node3

You can also create multiple separate keepalived clusters in a single Ansible inventory by using separate host groups. Each host group can have its own configuration:

[debops_all_hosts]
node1   ansible_host=node1.example.org
node2   ansible_host=node2.example.org
node3   ansible_host=node3.example.org
node4   ansible_host=node4.example.org
[cluster_group_one]
node1
node2
[cluster_group_two]
node3
node4
[debops_service_keepalived:children]
cluster_group_one
cluster_group_two

Check the Floating IP address using keepalived documentation section to see how the role can be configured to utilize separate inventory groups.

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.keepalived role:

---
- name: Manage Advanced Package Manager
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_keepalived' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: sysctl
      tags: [ 'role::sysctl', 'skip::sysctl' ]
      sysctl__dependent_parameters:
        - '{{ keepalived__sysctl__dependent_parameters }}'
    - role: ferm
      tags: [ 'role::ferm', 'skip::ferm' ]
      ferm__dependent_rules:
        - '{{ keepalived__ferm__dependent_rules }}'
    - role: keepalived
      tags: [ 'role::keepalived', 'skip::keepalived' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::keepalived
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

  Other resources

List of other useful resources related to the debops.keepalived Ansible role:

•   Manual pages: keepalived(8) <https://manpages.debian.org/keepalived(8)>, keepalived.conf(5) <https://manpages.debian.org/keepalived.conf(5)>

•   Lots of configuration examples can be found in the /usr/share/doc/keepalived/samples/ directory, provided with the keepalived APT package.

•   Example of floating IP address configuration with keepalived <https://www.centlinux.com/2018/08/keepalived-configure-floating-ip-centos-7.html>. Based on CentOS, however the service configuration is the same on different operating systems.

•   Example of extending keepalived functionality through scripts <https://tobru.ch/keepalived-check-and-notify-scripts/>.

DEFAULT VARIABLE DETAILS

Some of debops.keepalived default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  keepalived__configuration

The keepalived__*_configuration variables define the contents of the /etc/keepalived/keepalived.conf configuration file. The syntax is fairly simple and consists of blocks of the keepalived.conf(5) <https://manpages.debian.org/keepalived.conf(5)> configuration data which can be enabled or disabled conditionally and allow use of Jinja expressions to generate the desired configuration.

  Examples

  Floating IP address using keepalived

Create a floating IP address configuration distributed among a number of nodes in a specific Ansible inventory group. Each node has a decreasing priority, first node will be elected MASTER by default.

# ansible/inventory/cluster
[debops_all_hosts]
node1   ansible_host=node1.example.org
node2   ansible_host=node2.example.org
node3   ansible_host=node3.example.org
[floating_ip_cluster]
node1
node2
node3
[debops_service_keepalived:children]
floating_ip_cluster

---
# ansible/inventory/group_vars/floating_ip_cluster/keepalived.yml
# Allow communication between keepalived nodes
keepalived__group_allow: [ '192.0.2.0/24' ]
# Name of the cluster Ansible inventory group
keepalived__host_group: 'floating_ip_cluster'
# keepalived configuration for all nodes
keepalived__group_configuration:
  - name: 'vrrp_instance_1'
    raw: |
      vrrp_instance VI_1 {
          state {{ 'MASTER' if (keepalived__host_index | int == 0) else 'BACKUP' }}
          priority {{ (100 - (keepalived__host_index | int * 10)) }}
          interface eth0
          virtual_router_id 51
          advert_int 1
          authentication {
              auth_type PASS
              auth_pass 12345678
          }
          virtual_ipaddress {
              192.0.2.10/24
          }
      }
    state: 'present'

You can find more configuration examples (notably, global_defs options) in the keepalived__default_configuration variable definition.

  Syntax

The keepalived__*_configuration variables are defined using a list of YAML dictionaries. Each dictionary defines a configuration section using specific parameters parsed via the Universal Configuration filters:

name
    Required. Name of a given configuration entry, not used otherwise. Configuration entries with the same name are merged together during execution and can affect each other.

raw Required. YAML text block with keepalived.conf(5) <https://manpages.debian.org/keepalived.conf(5)> configuration options, added as-is in the generated configuration file. You can use Jinja expressions to create more dynamic configuration.

    The raw parameters in merged configuration entries override each other in order of appearance.

comment
    Optional. String or YAML text block with comments about a given configuration section, included in the generated configuration file.

state
    Optional. If not specified or present, a given configuration section will be included in the generated configuration file. If absent, a given configuration section will not be included in the generated configuration file. If ignore, the configuration entry will not be evaluated during role execution.

  keepalived__scripts

Functionality of the keepalived service can be extended via scripts executed at certain events (see keepalived.conf <https://manpages.debian.org/keepalived.conf> manual for more details). The debops.keepalived provides a set of variables which can be used to add or modify scripts (or other files, for example private keys or certificates) stored in the /etc/keepalived/ directory. These files can then be references in the /etc/keepalived/keepalived.conf configuration file to perform various functions.

  Examples

Use a script to start or stop services as needed on keepalived cluster state changes:

keepalived__configuration:
  - name: 'vrrp_vi_1'
    raw: |
      vrrp_instance vi_1 {
          notify /etc/keepalived/vi_1_notify.sh
      }
keepalived__scripts:
 - name: 'vi_1_notify.sh'
   content: |
     #!/bin/bash
     TYPE=$1   # GROUP / INSTANCE
     NAME=$2   # name of group or instance
     STATE=$3  # MASTER / BACKUP / FAULT
     case $STATE in
             "MASTER") systemctl start nginx.service
                       exit 0
                       ;;
             "BACKUP") systemctl stop nginx.service
                       exit 0
                       ;;
             "FAULT")  systemctl stop nginx.service
                       exit 0
                       ;;
             *)        printf "unknown state\n"
                       exit 1
                       ;;
     esac
   state: 'present'

  Syntax

The keepalived__*_scripts variables define additional files that should be included in the /etc/keepalived/ directory through a list of YAML dictionaries with specific parameters:

name or dest
    Required. The name of the script or a file stored in the /etc/keepalived/ directory. The role does not create any required subdirectories automatically; it's best to keep all files and scripts confined in one directory.

src Path of the file located on Ansible Controller which should be copied to the remote host under a specified filename. This parameter shouldn't be used with the content parameter in the same file definition.

content
    YAML text block with the contents of the generated file. This parameter shouldn't be used with the src parameter in the same file definition.

owner
    Optional. Specify the UNIX account which should be the owner of the script or file managed by the role. If not specified, root is used by default.

group
    Optional. Specify the UNIX group which should be the main group of the script or file managed by the role. If not specified, root is used by default.

mode
    Optional. Specify the UNIX permissions mode for the generated file. If not specified, the role will use the 0755 mode by default, meant for executable scripts.

state
    Optional. If not specified or present, a given file is copied or generated to the remote host. If absent, a given file will be removed from the remote host.

AUTHOR
Maciej Delmanowski

COPYRIGHT
2014-2024, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others