From 8764c180531257983d8227bb6e119f4655319338 Mon Sep 17 00:00:00 2001 From: Sergei Petrosian Date: Tue, 17 May 2022 18:30:05 +0200 Subject: [PATCH] Add HA functionality description to README.md --- README.md | 209 ++++++++++++++++++++++++++- defaults/main.yml | 4 +- tasks/main.yml | 3 +- templates/configure_ag.j2 | 2 +- templates/configure_endpoint.j2 | 8 +- tests/tests_configure_ha_cluster.yml | 11 +- 6 files changed, 219 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 4aab2227..3bb81b0a 100644 --- a/README.md +++ b/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,7 +269,7 @@ Default: `null` Type: `bool` -### `mssql_tls_cert` +#### `mssql_tls_cert` Path to the certificate file to copy to SQL Server. @@ -277,14 +277,14 @@ 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. @@ -292,7 +292,7 @@ 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 diff --git a/defaults/main.yml b/defaults/main.yml index ab36aa4b..96320427 100644 --- a/defaults/main.yml +++ b/defaults/main.yml @@ -25,8 +25,6 @@ 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 @@ -34,6 +32,8 @@ 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 diff --git a/tasks/main.yml b/tasks/main.yml index ff59f746..28792842 100644 --- a/tasks/main.yml +++ b/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 diff --git a/templates/configure_ag.j2 b/templates/configure_ag.j2 index 80a55883..fb5da08b 100644 --- a/templates/configure_ag.j2 +++ b/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 %} diff --git a/templates/configure_endpoint.j2 b/templates/configure_endpoint.j2 index 85d439b0..7e82ebd9 100644 --- a/templates/configure_endpoint.j2 +++ b/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, diff --git a/tests/tests_configure_ha_cluster.yml b/tests/tests_configure_ha_cluster.yml index 7004bb0a..f4e29a91 100644 --- a/tests/tests_configure_ha_cluster.yml +++ b/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