Add HA functionality description to README.md

README.md

@@ -240,7 +240,7 @@ Type: `bool`
 
 ### `mssql_tls_enable`
 
-Use the variables starting with `mssql_tls` to configure SQL Server to encrypt
+Use the variables with the `mssql_tls_` prefix to configure SQL Server to encrypt
 connections using TLS certificates.
 
 You are responsible for creating and securing TLS certificate and private
@@ -269,30 +269,30 @@ Default: `null`
 
 Type: `bool`
 
-### `mssql_tls_cert`
+#### `mssql_tls_cert`
 
 Path to the certificate file to copy to SQL Server.
 
 Default: `null`
 
 Type: `str`
 
-### `mssql_tls_private_key`
+#### `mssql_tls_private_key`
 
 Path to the private key file to copy to SQL Server.
 
 Default: `null`
 Type: `str`
 
-### `mssql_tls_version`
+#### `mssql_tls_version`
 
 TLS version to use.
 
 Default: `1.2`
 
 Type: `str`
 
-### `mssql_tls_force`
+#### `mssql_tls_force`
 
 Set to `true` to replace the existing certificate and private key files on host
 if they exist at `/etc/pki/tls/certs/` and `/etc/pki/tls/private/` respectively.
@@ -327,6 +327,155 @@ Default: `{{ __mssql_client_repository }}`
 
 Type: `string`
 
+### `mssql_ha_configure`
+
+Use the variables with the `mssql_ha_` prefix to configure SQL Server for high availability.
+
+Set to `true` to configure for high availability. Setting to `false` does not
+remove configuration for high availability.
+
+When set to `true`, the role performs the following tasks:
+1. Include the fedora.linux_system_roles.firewall role to configure firewall:
+1.1. Open the firewall port set with the `mssql_ha_listener_port` variable.
+1.2. Enable the `high-availability` service in firewall.
+2. Configure SQL Server for high availability:
+2.1. Enable AlwaysOn Health events.
+2.2. Create certificate on the primary replica and distribute to other replicas.
+2.3. Configure endpoint and availability group.
+2.4. Configure the pacemaker user.
+3. Include the fedora.linux_system_roles.ha_cluster role to configure pacemaker.
+
+Default: `false`
+
+Type: `bool`
+
+#### `mssql_ha_replica_type`
+
+A host variable that specifies the type of the replica to be configured on this host.
+
+See [`Setting Up SQL Server and Configuring for High Availability`](#Setting-Up-SQL-Server-and-Configuring-for-High-Availability) for an example inventory.
+
+You must set the `mssql_ha_replica_type` variable to `primary` for exactly one host.
+
+The available values are: `primary`, `synchronous`, `witness`.
+
+Default: no
+
+Type: `bool`
+
+#### `mssql_ha_firewall_configure`
+
+Whether to configure firewall for high availability or not.
+
+Default: `true`
+
+Type: `bool`
+
+#### `mssql_ha_listener_port`
+
+The TCP port to be used for high availability.
+
+Default: `5022`
+
+Type: `int`
+
+#### `mssql_ha_cert_name`
+
+The name of the certificate used for high availability configuration.
+
+Default: `null`
+
+Type: `str`
+
+#### `mssql_ha_master_key_password`
+
+The password to set for the master key used with the certificate.
+
+Default: `null`
+
+Type: `str`
+
+#### `mssql_ha_private_key_password`
+
+The password to set for the private key used with the certificate.
+
+Default: `null`
+
+Type: `str`
+
+#### `mssql_ha_reset_cert`
+
+Whether to reset certificates used for high availability or not.
+
+Default: `false`
+
+Type: `bool`
+
+#### `mssql_ha_endpoint_name`
+
+The name of the endpoint to be configured.
+
+Default: `null`
+
+Type: `string`
+
+
+#### `mssql_ha_ag_name`
+
+The name of the availability group to be configured.
+
+Default: `null`
+
+Type: `string`
+
+#### `mssql_ha_db_name`
+
+The name of the database to be replicated. This database must exist in SQL Server.
+
+Default: `null`
+
+Type: `string`
+
+#### `mssql_ha_db_backup_path`
+
+The path to back up replicated database to.
+
+Default: `/var/opt/mssql/data/{{ mssql_ha_db_name }}.bak`
+
+Type: `string`
+
+#### `mssql_ha_login`
+
+The user to be created for pacemaker in SQL Server.
+
+Default: `null`
+
+Type: `string`
+
+#### `mssql_ha_login_password`
+
+The password for the mssql_ha_login user in SQL Server.
+
+Default: `null`
+
+Type: `string`
+
+#### `mssql_ha_hacluster_password`
+
+The password for the cluster to be created in pacemaker.
+
+Default: `null`
+
+Type: `string`
+
+#### `mssql_ha_virtual_ip`
+
+A floating virtual IP address for accessing the master SQL Server node to be created in pacemaker.
+
+Default: `null`
+
+Type: `string`
+
 ## Example Playbooks
 
 This section outlines example playbooks that you can use as a reference.
@@ -417,6 +566,56 @@ use TLS encryption.
     - microsoft.sql.server
 ```
 
+### Setting Up SQL Server and Configuring for High Availability
+
+This example shows how to use the role to set up SQL Server and configure it for high availability.
+
+You must set the `mssql_ha_replica_type` variable for each host that you want to configure, for example in the inventory file.
+
+Example inventory file with `mssql_ha_replica_type` set for each host:
+
+```yaml
+all:
+  hosts:
+    host1:
+      mssql_ha_replica_type: primary
+    host2:
+      mssql_ha_replica_type: synchronous
+    host3:
+      mssql_ha_replica_type: witness
+```
+
+When the `mssql_ha_replica_type` variable is set for all hosts, you can execute a playbook.
+
+Example playbook:
+
+```yaml
+- hosts: all
+  vars:
+    mssql_accept_microsoft_odbc_driver_17_for_sql_server_eula: true
+    mssql_accept_microsoft_cli_utilities_for_sql_server_eula: true
+    mssql_accept_microsoft_sql_server_standard_eula: true
+    mssql_password: "p@55w0rD"
+    mssql_edition: Evaluation
+    mssql_ha_configure: true
+    mssql_ha_firewall_configure: true
+    mssql_ha_listener_port: 5022
+    mssql_ha_cert_name: mssql_cert
+    mssql_ha_master_key_password: "p@55w0rD1"
+    mssql_ha_private_key_password: "p@55w0rD2"
+    mssql_ha_reset_cert: false
+    mssql_ha_endpoint_name: hadr_endpoint
+    mssql_ha_ag_name: ag1
+    mssql_ha_db_name: ExampleDB
+    mssql_ha_db_backup_path: /var/opt/mssql/data/{{ mssql_ha_db_name }}.bak
+    mssql_ha_login: pacemakerLogin
+    mssql_ha_login_password: "p@55w0rD3"
+    mssql_ha_hacluster_password: "p@55w0rD4"
+    mssql_ha_virtual_ip: 192.168.1.254
+  roles:
+    - microsoft.sql.server
+```
+
 ## License
 
 MIT

defaults/main.yml

@@ -25,15 +25,15 @@ mssql_server_repository: "{{ __mssql_server_repository }}"
 mssql_client_repository: "{{ __mssql_client_repository }}"
 mssql_ha_configure: false
 mssql_ha_firewall_configure: true
-mssql_ha_db_name: null
-mssql_ha_db_backup_path: /var/opt/mssql/data/{{ mssql_ha_db_name }}.bak
 mssql_ha_listener_port: 5022
 mssql_ha_cert_name: null
 mssql_ha_private_key_password: null
 mssql_ha_master_key_password: null
 mssql_ha_reset_cert: false
 mssql_ha_endpoint_name: null
 mssql_ha_ag_name: null
+mssql_ha_db_name: null
+mssql_ha_db_backup_path: /var/opt/mssql/data/{{ mssql_ha_db_name }}.bak
 mssql_ha_login: null
 mssql_ha_login_password: null
 mssql_ha_hacluster_password: null

tasks/main.yml

@@ -577,7 +577,7 @@
 
     # This is required because `any_errors_fatal: true` does not work within
     # blocks that have rescue or always sections
-    - name: Set a fact to indicate successfull set up on the primary replica
+    - name: Set a fact to indicate successful set up on the primary replica
       delegate_to: localhost
       set_fact:
         __mssql_primary_successful: true
@@ -602,6 +602,7 @@
   when:
     - mssql_ha_configure | bool
     - mssql_ha_replica_type in ['synchronous', 'witness']
+  any_errors_fatal: true
   block:
     - name: Fail if the primary node failed
       delegate_to: localhost

templates/configure_ag.j2

@@ -170,7 +170,7 @@ removing this replica re-create it';
       ALTER AVAILABILITY GROUP {{ mssql_ha_ag_name }} MODIFY REPLICA ON
         N'{{ hostvars[item]['ansible_hostname'] }}' WITH (
 {%       if key == 'allow_connections' %}
-         {{ value.sql_setting_name }}
+          {{ value.sql_setting_name }}
 {%       else %}
           {{ value.sql_setting_name }} = {{ value.setting_value }}
 {%       endif %}

templates/configure_endpoint.j2

@@ -27,12 +27,12 @@ BEGIN
     ALTER ENDPOINT {{ mssql_ha_endpoint_name }}
       AS TCP (LISTENER_PORT = {{ mssql_ha_listener_port }});
     PRINT 'The LISTENER_PORT setting for the {{ mssql_ha_endpoint_name }} \
-endpoint updated successfully';
+endpoint updated to {{ mssql_ha_listener_port }} successfully';
   END
   ELSE
   BEGIN
     PRINT 'The LISTENER_PORT setting for the {{ mssql_ha_endpoint_name }} \
-endpoint is already correct, skipping';
+endpoint is already set to {{ mssql_ha_listener_port }}, skipping';
   END
   IF NOT EXISTS (
     SELECT name, role_desc FROM sys.database_mirroring_endpoints
@@ -43,12 +43,12 @@ endpoint is already correct, skipping';
     ALTER ENDPOINT {{ mssql_ha_endpoint_name }}
       FOR DATABASE_MIRRORING (ROLE = {{ __mssql_ha_endpoint_role }});
     PRINT 'The ROLE setting for the {{ mssql_ha_endpoint_name }} \
-endpoint updated successfully';
+endpoint updated to {{ __mssql_ha_endpoint_role }} successfully';
   END
   ELSE
   BEGIN
     PRINT 'The ROLE setting for the {{ mssql_ha_endpoint_name }} \
-endpoint is already correct, skipping';
+endpoint is already set to {{ __mssql_ha_endpoint_role }}, skipping';
   END
   IF NOT EXISTS (
     SELECT endp.name as endpoint_name,

tests/tests_configure_ha_cluster.yml

@@ -64,17 +64,18 @@
     - name: Run on all hosts to configure HA cluster
       vars:
         mssql_ha_configure: true
-        mssql_ha_ag_name: ag1
-        mssql_ha_db_backup_path: /var/opt/mssql/data/{{ mssql_ha_db_name }}.bak
+        mssql_ha_firewall_configure: true
+        mssql_ha_listener_port: 5022
         mssql_ha_cert_name: mssql_cert
         mssql_ha_master_key_password: "p@55w0rD1"
         mssql_ha_private_key_password: "p@55w0rD2"
-        mssql_ha_listener_port: 5022
-        mssql_ha_endpoint_name: Hadr_endpoint
+        mssql_ha_reset_cert: false
+        mssql_ha_endpoint_name: hadr_endpoint
+        mssql_ha_ag_name: ag1
+        mssql_ha_db_backup_path: /var/opt/mssql/data/{{ mssql_ha_db_name }}.bak
         mssql_ha_login: pacemakerLogin
         mssql_ha_login_password: "p@55w0rD3"
         mssql_ha_hacluster_password: "p@55w0rD4"
         mssql_ha_virtual_ip: 192.168.1.254
-        # mssql_ha_reset_cert: true
       include_role:
         name: linux-system-roles.mssql