Merge pull request #161 from mmoster/dev

Pull request for 2 Node Cluster Setup

docs/getting_started/README.md

@@ -0,0 +1,98 @@
+# Examples and Tips
+
+In this folder you find sample files, a few additional tips for using the provided ansible roles, as well as references to further information.
+
+- [Examples and Tips](#examples-and-tips)
+  - [How to run playbooks](#how-to-run-playbooks)
+    - [Inventory and variable parameters](#inventory-and-variable-parameters)
+    - [Security parameters](#security-parameters)
+    - [Other useful options](#other-useful-options)
+
+## How to run playbooks
+
+Playbook execution requires a minimum set of parameters, depending on the ansible configuration settings and the environment to be used in.
+
+The parameters shown in the below examples can all be combined according to the respective needs. The example commands are kept short for readability.
+
+Simplest example:
+
+```bash
+ansible-playbook sap_hana_cluster_deploy.yml
+```
+
+_The parameter examples in the following sections can be combined according to the individual environment and needs._
+
+### Inventory and variable parameters
+
+Examples with different ways to use inventory and target system parameters:
+
+```bash
+
+ansible-playbook -i /path/to/inventory-file -l node1,node2 sap_hana_cluster_deploy.yml
+ansible-playbook -l ~node[12] sap_hana_cluster_deploy.yml
+
+ansible-playbook [...] -e 'my_variable=value'
+ansible-playbook [...] -e @path/to/vars-file.yml
+ansible-playbook [...] -e @path/to/vars-file.yml -e 'additional_variable=value'
+```
+
+- `-i` provide path to inventory host file
+- `-l` limit the target hosts to the name(s).
+  Prefix with `~` to use regex for host name patterns.
+- `-e` (`--extra-vars`) allows to define variables on command execution.
+  Variables can also be included from a file using the `@filename` notation.
+  `-e` can be used multiple times.
+  These extra-vars will overwrite the same variable names defined in the playbook or included files. See [variable precedence documentation](https://docs.ansible.com/ansible/latest/user_guide/playbooks_variables.html#variable-precedence-where-should-i-put-a-variable).
+
+### Security parameters
+
+Examples showing some typical privilege escalation options:
+
+```bash
+ansible-playbook [...] -k
+ansible-playbook [...] -k -K
+ansible-playbook [...] -u target-user -k -K
+```
+
+- `-u` is used to target a different remote user than the current user on the ansible control node.
+- `-k` will prompt for the remote user's login password.
+- `-K` will prompt for the remote user's sudo password. This is needed when `become` is used to run tasks as another user or root. Instead of sudo the privilege escalation method can also be changed (please see official ansible documentation).
+
+Example if encrypted files or variables are used in a play:
+
+```bash
+ansible-playbook [...] --ask-vault
+```
+
+This will prompt for the vault password, which was provided during creation of the ansible-vault encrypted contents.
+
+Please see [secure-your-passwords](secure-your-passwords.md) for more information.
+
+### Other useful options
+
+There are also other very useful parameters for individual use cases.
+
+```bash
+ansible-playbook [...] --list-hosts
+
+ansible-playbook [...] --list-tasks
+
+ansible-playbook [...] -t tasks-tagged-name-a
+ansible-playbook [...] -t tasks-tagged-name-a,tasks-tagged-name-b
+
+ansible-playbook [...] --start-at-task "Name of task to start with and proceed"
+
+ansible-playbook [...] -C
+ansible-playbook [...] --step
+```
+
+These are not all available options, but ones that may help getting familiar with the tasks and changes the playbook would execute. Especially for a collection of complex roles this could help keeping an overview and defining steps, if desired.
+
+- `--list-hosts` helps verifying the hosts that are going to be targeted. The playbook is not run.
+- `--list-tasks` displays the tasks the playbook is going to run. Tasks from dynamically included files will not be visible and only accessed during runtime.
+- `-t` or `--tags` limits the tasks to be executed to those with the tag name(s) provided.
+  Tags are displayed in square brackets in the `--list-tasks` overview.
+- `--start-at-task` will run the playbook starting with this named task. If there are duplicate task names it will start at the first in the list (see `--list-tasks`).
+  Be careful to choose a task which covers pre-requisites, i.e. tasks that discover information which is used in subsequent tasks have to be run to fulfill conditionals.
+- `-C` attempts a dry-run of the playbook without applying actual changes. This is limited to simple tasks that do not require other changes already been done in previous tasks.
+- `--step` this executes the playbook but will prompt for every task to be run or skipped. At the prompt it can also be told to continue and not ask again, however. Useful to slow down execution and review each tasks result before proceeding with the next task.

docs/getting_started/sample-playbook_deploy-2-node-sap-hana-cluster.yml

@@ -0,0 +1,79 @@
+---
+# This playbook will 
+# - prepare and install SAP HANA on 2 target nodes
+# - set up SAP HANA System Replication (HSR)
+# - install and configure a basic pacemaker cluster
+# - configure the SAP HANA DB resource with a service VIP
+
+# To use this playbook in your test environment
+# please update the "vars" parameters with values
+# corresponding to your individual naming standards
+# and infrastructure (e.g. IP definitions matching your network).
+
+# Prerequisite:
+# - target nodes are registered with subscription-manager and 
+#   subscribed to "RHEL for SAP Solutions"
+
+- name: "Install SAP HANA and configure it in a 2-node pacemaker cluster"
+  hosts: node1, node2
+  become: true
+
+  vars:
+    sap_domain: example.com
+
+    ## general + hana preconfigure
+    # allow reboot handler execution after preconfigure roles
+    sap_general_preconfigure_reboot_ok: no
+    sap_general_preconfigure_fail_if_reboot_required: no
+    sap_hana_preconfigure_reboot_ok: yes
+    sap_hana_preconfigure_fail_if_reboot_required: no
+
+    sap_hana_update_etchosts: yes
+
+    sap_hana_sid: "DB1"
+    sap_hana_instance_number: "00"
+    sap_hana_install_master_password: "my-hana-password"
+
+    ### Cluster Definition
+    sap_hana_cluster_name: cluster1
+    sap_hana_hacluster_password: "my_hacluster-password"
+
+    sap_hana_cluster_nodes:
+      - node_name: node1
+        node_ip: 192.168.1.11
+        node_role: primary
+        hana_site: DC01
+
+      - node_name: node2
+        node_ip: 192.168.1.12
+        node_role: secondary
+        hana_site: DC02
+
+    sap_hana_vip1: 192.168.1.100
+
+    sap_pacemaker_stonith_devices:
+      - name: "rhevm_fence1"
+        agent: "fence_rhevm"
+        parameters: >
+          ip=rhevm-manager.example.com
+          username=rhevm-user@internal
+          password=rhevm-secret
+          pcmk_host_list='node1,node2'
+          power_wait=3
+          ssl=1 ssl_insecure=1 disable_http_filter=1
+
+  roles:
+    # SAP Hana preparation and installation
+    - name: sap_general_preconfigure
+    - name: sap_hana_preconfigure
+    - name: sap_hana_install
+
+    # SAP Hana System Replication setup between 2 nodes
+    - name: sap_ha_install_hana_hsr
+
+    # 2-node Pacemaker Cluster Configuration
+    - name: sap_ha_prepare_pacemaker
+    - name: sap_ha_install_pacemaker
+
+    # SAP Hana Cluster Resources Configuration
+    - name: sap_ha_set_hana

docs/getting_started/secure-your-passwords.md

@@ -0,0 +1,99 @@
+# Simple password security using ansible vault
+
+- [Encrypt a secret string to be used in a variable](#encrypt-a-secret-string-to-be-used-in-a-variable)
+- [Run playbook which uses vault-encrypted content](#run-playbook-which-uses-vault-encrypted-content)
+- [Encrypt an entire file](#encrypt-an-entire-file)
+- [More features and information](#more-features-and-information)
+
+**Always avoid plain text passwords in files or on commandline.**
+
+Since some Ansible automation will require using credentials for various tasks, it is recommended to secure these credentials accordingly.
+
+Ansible vault provides an easy way to comply with security requirements to encrypt secret information.
+The following describes a basic scenario.
+
+## Encrypt a secret string to be used in a variable
+
+_Supported since ansible 2.3._
+
+By temporarily writing the password into a text file you avoid the secret to show up in your command history.
+Enter your secret password as single string in a file and save it. Make sure there is no unwanted whitespace.
+
+```bash
+vi passfile
+```
+
+Use ansible-vault to encrypt the string, which it reads from the file. Adding the variable name will using `-n` will give you the full variable definition that can be copied directly into your `vars:` section of the playbook or the desired place of your variable definition (group_vars, host_vars, etc.).
+
+```bash
+ansible-vault encrypt_string $(cat passfile) -n my_secret_var
+```
+
+Ansible-vault will ask to enter a password which is required to automatically encrypt the value during ansible runtime afterwards.
+
+```text
+New Vault password:
+Confirm New Vault password:
+my_secret_var: !vault |
+          $ANSIBLE_VAULT;1.1;AES256
+          66623764626166333234363863356232376666656634316531363366396331393038396635373138
+          6164613062353931336561393334303661363037326433330a356364613261323134323836306462
+          66643766393834366232333235333563636334336235666631346532393430626665363665666234
+          3431386266383464310a376433646135323663306139333934373431343631613034346235666665
+          3236
+Encryption successful
+```
+
+Save the `my_secret_var` and encrypted value in your variable definitions and include the definition file as usual.
+The variable can as well be referenced and used by other variables for more flexibility.
+
+```yaml
+playbook1_secret_var: "{{ my_secret_var }}"
+```
+
+```yaml
+playbook5_secret_var: "{{ my_secret_var }}"
+```
+
+This way the value is only present and managed in one place and can be used by different playbooks.
+
+**Remove the temporary file which contains the plain-text password!**
+
+```bash
+rm passfile
+```
+
+## Run playbook which uses vault-encrypted content
+
+For the encryption to work during ansible / ansible-playbook execution you have to tell ansible to prompt for the vault password.
+
+```bash
+ansible-playbook tasks_with_secrets.yml [...] --ask-vault
+```
+
+_When encrypting multiple values that will be used together, you have to make sure the vault password is the same for each encrypted string. Ansible can only ask for one vault password._
+
+## Encrypt an entire file
+
+You can also encrypt an entire file, e.g. containing multiple secrets.
+
+However, if variables are defined in the file it will encrypt the variable names as well and makes it harder to identify the source definition of a referenced variable.
+Also, encrypting the entire file will require ansible-vault commands to view or edit the contents of the file. A file containing individually encrypted values can be viewed and edited as any other file without uncovering the actual secret value.
+
+It will prompt for the vault password - either to be created, or to be used for decrypting the existing content.
+
+```bash
+ansible-vault encrypt file_containing_secrets.yml
+
+ansible-vault view file_containing_secrets.yml
+ansible-vault edit file_containing_secrets.yml
+```
+
+Including this file and using it works the same way as any other included file, as long as the vault password is provided to ansible during execution.
+
+## More features and information
+
+Vault encryption can also be done through password-files, scripts or automation software which provides secure ways to manage vault credentials.
+For more complex ways to use ansible vault encryption/decryption please refer to the documentation.
+https://docs.ansible.com/ansible/latest/user_guide/vault.html
+https://docs.ansible.com/ansible/latest/cli/ansible-vault.html