From 34b5d65e9b98adfdc15a8c35b9f997547fd2bfd7 Mon Sep 17 00:00:00 2001 From: Bertrand Lanson Date: Sun, 10 Mar 2024 20:23:53 +0100 Subject: [PATCH] feat(docs): update readme --- README.md | 96 +++++++++++++++++++++++++++-- defaults/main.yml | 2 +- molecule/default_vagrant/verify.yml | 2 +- 3 files changed, 93 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 9070100..28edba1 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ deploy_keepalived ========= > This repository is only a mirror. Development and testing is done on a private gitea server. -A brief description of the role goes here. +This role lets you install and configure keepalived on debian-based systems. It can either deploy it natively, or within a docker container. Requirements ------------ @@ -11,17 +11,103 @@ None. Role Variables -------------- -Available variables are listed below, along with default values. A sample file for the default values is available in `default/deploy_keepalived.yml.sample` in case you need it for any `group_vars` or `host_vars` configuration. +Available variables are listed below, along with default values. ```yaml -your_defaults_here: default_value # by default, set to default_value +deploy_keepalived_deploy_method: host # by default, set to host ``` -A quick description of the variable, what it does, and how to use it. +This variable defines the method of deployment of keepalived. The `host` method installs the binary directly on the host, and runs keepalived as a systemd service. The `docker` method install keepalived as a docker container. + +```yaml +deploy_keepalived_version: "latest" # by default, set to latest +``` +This variable sets the version of keepalived to install. Please note that not all versions are available. For the `host` deploy method, `2.2.3`, `2.2.4`, `2.2.7`, and `2.2.8` are officially supported (`2.2.0`,`2.2.1` and `2.2.2` require different compilation dependencies that I couldn't make work, while `2.2.5` and `2.2.6` are "false " releases, as no source code is available. Older versions might work, but are not tested.) For the `docker` deploy method, only `2.2.3`, `2.2.4`, `2.2.7`, and `2.2.8` are available. You can also use `2.2` or `2` on `docker` deployment, to stick to the latest minor or patch version. The `latest` is however recomended, and works on both `host` and `docker` deployment method. + +```yaml +deploy_keepalived_start_service: true # by default, set to true +``` +This variable defines if the keepalived service should be started once it has been configured. This is usefull in case you're using this role to build golden images, in which case you might want to only enable the service, to have it start on the next boot (when the image is launched). + +```yaml +deploy_keepalived_env_variables: {} # by default, set to {} +``` +This value is a list of key/value that will populate the keepalived.env (for `host` deployment method) or /etc/default/keepalived (for `docker` deploy method) file. + +```yaml +deploy_keepalived_vrrp_instance_name: "{{ ansible_hostname }}" # by default, set to {{ ansible_hostname }} +``` +This value sets the name of the vrrp instance. Defaults to the hostname of the machine. + +```yaml +deploy_keepalived_interface: "{{ ansible_default_ipv4.interface }}" # by default, set to {{ ansible_default_ipv4.interface }} +``` +This defines the interface for the vrrp instance. Defaults to the primary network interface. + +```yaml +deploy_keepalived_state: "BACKUP" # by default, set to BACKUP +``` +This variable sets the initial state of the vrrp instance. Defaults to backup, to avoid multi-master issues in cluster setups. + +```yaml +deploy_keepalived_router_id: 50 # by default, set to 50 +``` +Arbitrary router id of the vrrp instance, defaults to 50 + +```yaml +deploy_keepalived_priority: 100 # by default, set to 100 +``` +Sets the initial priority of the instance. + +```yaml +deploy_keepalived_advert_interval: 1 # by default, set to 1 +``` +Interval in second, at which the keepalived instance advertise itself to its peers. + +```yaml +deploy_keepalived_unicast_source: "{{ ansible_default_ipv4.address }}" # by default, set to {{ ansible_default_ipv4 }} +``` +The source ip to communicate with other vrrp peers. Defaults to the address of the primary interface, but isn't needed if no peers are set. + +```yaml +deploy_keepalived_unicast_peers: [] # by default, set to [] +``` +List of unicast peers to advertise to. By default, no peers are set. + +```yaml +deploy_keepalived_auth_passwd: "password" +``` +The password for communicating to/from peers. You should really change it.. + +```yaml +deploy_keepalived_virtual_ips: # by default, set to ["192.168.1.100/32"] + - 192.168.1.100/32 +``` +List of virtual IPs to set on the host if it has the MASTER state. Refer to the [documentation](https://manpages.debian.org/unstable/keepalived/keepalived.conf.5.en.html) for more information on the syntax. + +```yaml +deploy_keepalived_notify_script: notify.sh # by default, set to notify.sh +``` +Path to the notify script. The default one is located in `files/notify.sh`, but you can put any name here. This script is expected to be in `/etc/keepalived/scripts.d` on the host (keep reading to see how to copy your own scripts). + +```yaml +deploy_keepalived_custom_scripts_src: # by default, unset +``` +Path to a local scripts directory. The content of the directory will be copied over to `/etc/keepalived/scripts.d` on the host, and will override the default `notify.sh` script if it encounters name conflict (if you also copy a custom `notify.sh`). This lets you copy notify scripts, as well as any other scripts you may need. + +```yaml +deploy_keepalived_extra_container_volumes: [] +``` +Extra volumes to mount to the container if using the `docker` deploy method. +By default, `/etc/keepalived` (host) will be mounted to `/etc/keepalived` (container) + + Dependencies ------------ -None. +`ednz_cloud.manage_apt_packages` to install build dependencies for keepalived. + +`ednz_cloud.docker_systemd_service` if installing keepalived in a container. Example Playbook ---------------- diff --git a/defaults/main.yml b/defaults/main.yml index cceab2c..b649924 100644 --- a/defaults/main.yml +++ b/defaults/main.yml @@ -1,7 +1,7 @@ --- # defaults file for deploy_keepalived deploy_keepalived_deploy_method: "host" -deploy_keepalived_version: "2.2.8" +deploy_keepalived_version: "latest" deploy_keepalived_start_service: true deploy_keepalived_env_variables: {} diff --git a/molecule/default_vagrant/verify.yml b/molecule/default_vagrant/verify.yml index 28e9654..4f2382c 100644 --- a/molecule/default_vagrant/verify.yml +++ b/molecule/default_vagrant/verify.yml @@ -111,7 +111,7 @@ --cap-add "NET_RAW" \ --cap-add "NET_BROADCAST" \ --volume "/etc/keepalived:/etc/keepalived" \ - ednxzu/keepalived:2.2.8 + ednxzu/keepalived:latest ExecStop=/usr/bin/docker stop keepalived SyslogIdentifier=keepalived Restart=always