Skip to content

Changes in HA doc #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Mar 24, 2025
Merged

Changes in HA doc #9

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7921deb
Changes in HA doc
dennispadia Mar 18, 2025
859bb0c
Update repository URL in documentation
hdamecharla Mar 19, 2025
d701f95
Refine language and clarity in the High Availability documentation
devanshjainms Mar 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
193 changes: 117 additions & 76 deletions docs/HIGH_AVAILABILITY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,36 +1,75 @@
# SAP High Availability Testing

## Overview
A key component of the SAP Testing Automation framework is the SAP High Availability (HA) Testing. This helps in ensuring that an SAP system deployment complies to SAP on Azure best practices and guidelines.

One key component of the SAP Testing Automation framework is the SAP High Availability (HA) Testing Framework, which is designed to ensure that your SAP deployments meet strict reliability and availability requirements.
The SAP High Availability Testing scenario executes a series of tests designed to simulate real-world failures, ensuring the system's recovery capabilities. Leveraging Ansible, the framework orchestrates various test cases, including node crashes, network disruptions, and storage failures, to validate the effectiveness of recovery mechanisms. Additionally, the framework captures comprehensive logs and generates detailed reports on the test outcomes.

The SAP High Availability Testing component operates by executing a series of carefully designed test scenarios that simulate real-world failure conditions and validate system recovery capabilities. By leveraging Ansible's powerful automation features, it orchestrates complex test scenarios across multiple components, while maintaining detailed logs and generating comprehensive reports of test outcomes.
## Supported Configurations

### Linux distribution

Currently SAP Testing Automation Framework is supported for below Linux distros and version.

| Distribution | Supported Release |
|--------------|-------------------|
| SUSE Linux Enterpise Server (SLES) | 15 SP4, 15 SP5, 15 SP6 |
| Red Hat Enterprise Linux (RHEL) | 8.8, 8.10, 9.2, 9.4 |

### High Availability configuration pattern

| Component | Type | Cluster Type | Storage |
|-----------|------|--------------|---------|
| SAP Central Services | ENSA1 or ENSA2 | Azure Fencing Agent | Azure Files or ANF |
| SAP HANA | Scale-up | Azure Fencing Agent | Azure Managed Disk or ANF |
| SAP HANA | Scale-up | ISCSI (SBD device) | Azure Managed Disk or ANF |

For SAP Central Services on SLES, both the simple mount approach and the classic method are supported.

## Technical Requirements for running Automation Framework

To run the SAP Testing Automation Framework, you must meet certain prerequisites and follow techincal requirements.

### SAP System Deployment on Microsoft Azure

- The SAP system must be hosted on Microsoft Azure Infrastructure-as-a-Service (IaaS).
- The SAP system deploymed should follow SAP on Azure best practices as outlined in:
- [SAP HANA high availability on Azure Virtual Machine](https://learn.microsoft.com/azure/sap/workloads/sap-high-availability-guide-start).
- [SAP Netweaver high availability on Azure Virtual Machine](https://learn.microsoft.com/azure/sap/workloads/sap-high-availability-guide-start)

In summary, SAP High Availability testing is an integral part of the overall SAP Testing Automation Framework, complementing other testing modules to provide a robust, end-to-end validation of your SAP environments.
### Management server

### Core Framework
The SAP Testing Automation Framework requires a jumpbox or management server with the following setup:

- **Ansible Playbooks**: Automated test execution and system validation
- **Test Scripts**: Helper utilities for test case management
- **WORKSPACES**: System-specific configuration and credentials management
- **Reporting Engine**: Generates detailed HTML test reports
- **Operating System**: Ubuntu 22.04 LTS.
- **Location**: Must be deployed on Azure.

> [!NOTE]
> Currently, only Ubuntu 22.04 LTS is supported for running the SAP Testing Automation Framework.

### System Requirements
### Azure RBAC

#### Required Components
For the framework to access the properties of the Azure Load Balancer in a high availability SAP system on Azure, the management server must have a Reader role assigned to the Load Balancer. This can be done using either a system-assigned or user-assigned managed identity.

1. **SAP System on Azure Cloud**
- The SAP system must be deployed on Azure infrastructure.
- Configured with supported high availability patterns to ensure system reliability.
- Network connectivity to the testing infrastructure must be established.
#### Configuring access using system-assigned managed identity

2. **Ubuntu Jump Host**
- **Operating System**: Ubuntu 22.04 LTS.
- **Location**: Deployed in Azure.
- **Network**: Must be connected to the SAP system's virtual network.
- **Permissions**: Requires a System Assigned/User Assigned managed identity with Reader Role at the subscription level.
1. Enable system managed identity on the management server by following the steps in [Configure managed identities on Azure VMs](https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/how-to-configure-managed-identities?pivots=qs-configure-portal-windows-vm#system-assigned-managed-identity).
1. Open the Azure Load Balancer used for the high availability deployment of your SAP system on Azure.
1. In the Azure Load Balancer panel, go to Access control (IAM).
1. Follow steps 5 to 10 from [Use managed identity to access Azure Resource](https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/how-to-configure-managed-identities?pivots=qs-configure-portal-windows-vm#system-assigned-managed-identity) to complete the configuration.

#### Optional Components
#### Configuring access using user-assigned managed identity

1. Create user-assigned managed identity as described in [manage user-assigned managed identities](https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/how-manage-user-assigned-managed-identities?pivots=identity-mi-methods-azp#create-a-user-assigned-managed-identity)
1. Assign user-assigned managed identity to management server as described in [configure managed identities on Azure VMs](https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/how-to-configure-managed-identities?pivots=qs-configure-portal-windows-vm#assign-a-user-assigned-managed-identity-to-an-existing-vm)
1. Open the Azure Load Balancer used for the high availability deployment of your SAP system on Azure.
1. In the Azure Load Balancer panel, go to Access control (IAM).
1. Assign the required role to the user-assigned managed identity by following the steps in [assign roles using Azure portal](https://learn.microsoft.com/azure/role-based-access-control/role-assignments-portal).

### Network Connectivity

The management server must have network connectivity to the SAP system to perform tests and validations. You can establish this connection by peering the networks as outlined in [manage a virtual network peering](https://learn.microsoft.com/azure/virtual-network/virtual-network-manage-peering?tabs=peering-portal).

### Analytics Integration (optional)

- **Analytics Integration** [Telemetry Setup Information](./TELEMETRY_SETUP.md)
- Azure Log Analytics
Expand All @@ -40,35 +79,40 @@ In summary, SAP High Availability testing is an integral part of the overall SAP

### 1. Environment Setup

To set up your environment, follow these steps:
To set up your enviroment in management server, follow these steps:

A. **Login to the Ubuntu Jump Host**:
Ensure you are logged into the Ubuntu Jump Host that is connected to the SAP system's virtual network.
1.1. **Login to the Ubuntu management server**:

B. **Clone the repository**:
Ensure you are logged into the Ubuntu management server that is connected to the SAP system's virtual network.

```bash
git clone https://github.com/devanshjainms/sap-automation-qa.git
cd sap-automation-qa
```
1.2. **Clone the repository**:

C. **Run the initial setup script**:
```bash
# sudo to root
sudo su -

```bash
./scripts/setup.sh
```
# Clone the repository
git clone https://github.com/Azure/sap-automation-qa.git
cd sap-automation-qa
```

1.3. **Run the initial setup script**:

```bash
./scripts/setup.sh
```

### 2. Configuration

#### A. Test Environment Configuration
#### 2.1. Test Environment Configuration

1. Navigate to the root directory
2.1.1. Navigate to the root directory

```bash
cd sap-automation-qa
```

2. Update `vars.yaml` with your test parameters. This file contains the variables used in the test cases:
2.1.2. Update `vars.yaml` with your test parameters. This file contains the variables used in the test cases:

```yaml
# The type of test to be executed. Supported values are:
Expand All @@ -81,6 +125,7 @@ TEST_TYPE: "SAPFunctionalTests"
sap_functional_test_type: "DatabaseHighAvailability" # or "CentralServicesHighAvailability"

# The name of the SAP system configuration for which you want to execute the test cases.
# It would be the name of the folder under 'WORKSPACE/SYSTEM/' where it could find hosts.yaml, sap-parameters.yaml files of the SAP system configuration
SYSTEM_CONFIG_NAME: "DEV-WEEU-SAP01-X00"

# The type of authentication to be used for the telemetry data destination. Supported values are: VMPASSWORD and SSHKEY
Expand All @@ -104,7 +149,7 @@ adx_database_name: "your-adx-database-name"
ade_client_id: "your-adx-client-id"
```

#### B. System Configuration (WORKSPACES)
#### 2.2. System Configuration (WORKSPACES)

Create your system workspace. This directory contains the configuration files specific to your SAP system, necessary for connecting to the system and executing test scenarios. The `WORKSPACE/SYSTEM/` directory holds sub-directories, each representing a different [SAP system](./WORKSPACES/SYSTEM/DEV-WEEU-SAP01-X00).

Expand All @@ -114,11 +159,13 @@ mkdir ENV-REGION-VNET-SID
cd ENV-REGION-VNET-SID
```

#### Required Files
The system workspace should include the following files, containing all necessary details about the SAP system.

2.2.1. **hosts.yaml** - System [Inventory file](https://docs.ansible.com/ansible/latest/inventory_guide/intro_inventory.html) (required)

i. **hosts.yaml** - System [Inventory file](https://docs.ansible.com/ansible/latest/inventory_guide/intro_inventory.html) (required)
This file contains the connection details for the SAP system hosts and is used as an inventory file by the Ansible framework to connect to the SAP system. You can find the inventory file in the path [hosts.yaml](../WORKSPACES/SYSTEM/DEV-WEEU-SAP01-X00/hosts.yaml).

This file contains the connection properties of the SAP system hosts. This file acts as a inventory file for the ansible framework to connect to the SAP system. [Example of a inventory file](./WORKSPACES/SYSTEM/DEV-WEEU-SAP01-X00/hosts.yaml):
Here is an example of the hosts.yaml file format:

```yaml
X00_DB:
Expand All @@ -129,7 +176,7 @@ X00_DB:
ansible_connection: "ssh"
connection_type: "key"
virtual_host: "VIRTUAL_HOSTNAME0"
become_user: "root"
become_user: "USERNAME1" #Username with root privilege
os_type: "linux"
vm_name: "AZURE_VM_NAME0"
hostname1:
Expand All @@ -138,37 +185,43 @@ X00_DB:
ansible_connection: "ssh"
connection_type: "key"
virtual_host: "VIRTUAL_HOSTNAME1"
become_user: "root"
become_user: "USERNAME1" #Username with root privilege
os_type: "linux"
vm_name: "AZURE_VM_NAME1"
vars:
node_tier: "hana" # or "ers", "scs"
```

X00 is the SAP SID of the SAP system, followed by the host type (DB, ASCS, PAS, etc.). You should provide the SAP SID of the SAP system, regardless of whether you are testing Database High Availability or Central Services High Availability. The `hosts.yaml` file contains the following information:
In the file:

- X00 represents the SAP SID (System ID) of the SAP system, followed by the host type (e.g., DB, ASCS, PAS). You must provide the SAP SID of the system, regardless of whether you are testing Database High Availability or Central Services High Availability.

The file includes the following details:

- **ansible_host**: The IP address of the host.
- **ansible_user**: The user to connect to the host.
- **ansible_connection**: The connection type.
- **connection_type**: The type of connection. Applicable only when using SSH key for connection; when using a password, this should not be specified.
- **ansible_user**: The user for connecting to the host.
- **ansible_connection**: The connection type (usually "ssh").
- **connection_type**: The connection type, used when connecting via SSH key (not needed for password-based connections).
- **virtual_host**: The virtual host name of the SCS/DB host.
- **become_user**: The user with root privileges.
- **os_type**: The operating system type (Linux/Windows).
- **become_user**: The user with root privileges. For example, user "azureadm" must be able to change to root without password.
- **os_type**: The operating system type (e.g., Linux or Windows).
- **vm_name**: The computer name of the Azure VM.
- **node_tier**: This defines the type of node tier. Supported values: hana, ers, scs.
- **node_tier**: The type of node tier. Supported values: hana, ers, scs.

2.2.2. **sap-parameters.yaml** - SAP Configuration (required)

ii. **sap-parameters.yaml** - SAP Configuration (required)
This file contains the SAP system configuration parameters. The parameters are used by the test scenarios to validate the system's high availability configuration. You can find the inventory file in the path [sap-parameters.yaml](../WORKSPACES/SYSTEM/DEV-WEEU-SAP01-X00/sap-parameters.yaml).

This file contains the SAP system configuration parameters. The parameters are used by the test scenarios to validate the system's high availability configuration. [Example of a SAP parameters file](./WORKSPACES/SYSTEM/DEV-WEEU-SAP01-X00/sap-parameters.yaml):
Here is an example of the sap-parameters.yaml file format:

```yaml
# The SAP and Database SID of the SAP system.
sap_sid: "your-sap-sid"
db_sid: "your-db-sid"

# Boolean indicating if the SCS and database is configured as highly available.
scs_high_availability: false
db_high_availability: false
scs_high_availability: true
db_high_availability: true

# The high availability configuration of the SCS and DB instance. Supported values are:
# - AFA (for Azure Fencing Agent)
Expand All @@ -191,37 +244,25 @@ platform: "HANA"
NFS_provider: "ANF" # or "AFS"
```

iii. Optional Files
2.2.3. Credential Files

The required credential files depend on the authentication method used to connect to the SAP system:

- **ssh_key.ppk**: SSH private key (if not using Key Vault)
- **password**: Host credentials (if not using SSH keys)
1. SSH Key Authentication: If connecting via SSH key, place the private key inside `WORKSPACE/SYSTEM/<DIRECTORY>` and name the file "ssh_key.ppk".
1. Username and Password Authentication: If connecting using a username and password, create a password file by running the following command. It takes the username from hosts.yaml file.

```bash
echo "password" > WORKSPACE/SYSTEM/<DIRECTORY>/password
```

### 3. Test Execution

To execute the script, run following command:

```bash
./scripts/sap_automation_qa.sh
```

## Supported Configurations

### High Availability Patterns

| Component | Database | Cluster Type | Storage |
|-----------|----------|--------------|----------|
| Central Services | N/A | Azure Fencing Agent | ANF/AFS |
| HANA Database | HANA | Azure Fencing Agent | ANF/AFS |
| HANA Database | HANA | SBD | ANF/AFS |

### Storage Solutions

- **ANF**: Azure NetApp Files
- **AFS**: Azure File Share

### Cluster Types

- **AFA**: Azure Fencing Agent
- **ISCSI**: SBD devices

## Troubleshooting

Test results and logs can be found in:
Expand Down
Loading