Update STAF documentation (#142)

Author: dennispadia

README.md

@@ -13,45 +13,64 @@
 
 The SAP Testing Automation Framework is an open-source orchestration tool designed to validate SAP deployments on Microsoft Azure. It enables you to assess system configurations against SAP on Azure best practices and guidelines, and facilitates automation for various testing scenarios.
 
-> **NOTE**: This repository is currently in public preview and is intended for testing and feedback purposes. As this is an early release, it is not yet production-ready, and breaking changes can be introduced at any time.
-
 ![SAP Testing Automation Framework](./docs/images/sap-testing-automation-framework.png)
 
-## 📊 Key Features
+## 📊 Key Scenarios
 
-- **High Availability Testing** - Thorough validation of the SAP HANA scale-up and SAP Central Services failover mechanism in a two node pacemaker cluster, ensuring the system operates correctly across various test cases.
-  - **Configuration Validation** - Ensures that SAP HANA scale-up and SAP Central Services configurations comply with SAP on Azure best practices and guidelines.
-  - **Functional Testing** - Executes test scenarios on the high availability setup to identify potential issues, whether during a new system deployment or before implementing cluster changes in a production environment.
-- **Configuration Checks** - Validates OS parameters, database settings, Azure resources, and storage configurations against SAP and Azure best practices for supported databases. Performs comprehensive validation including kernel parameters, filesystem mounts, VM sizing, and network setup to ensure compliance with recommended guidelines.
-- **Detailed Reporting** - Generates comprehensive reports, highlighting configuration mismatch or deviations from recommended best practices. Includes failover test outcomes, any failures encountered, and logs with insights to aid in troubleshooting identified issues.
+SAP Testing Automation is designed as a scalable framework to orchestrate and validate a wide spectrum of SAP landscape scenarios through repeatable, policy-driven test modules. The framework currently offers following scenarios -
 
-## 🏆 Purpose
+> [!NOTE]
+>
+> The High Availability testing scenario in the SAP Testing Framework is **generally available (GA)**, while the Configuration Checks scenario is currently in **public preview**.
 
-Testing is crucial for keeping SAP systems running smoothly, especially for critical business operations. This framework helps by addressing key challenges:
+### High Availability Testing 
 
-- **Preventing Risks** - Identifies configuration issues and validates system behavior before problems affect production operations. It simulates system failures like node crashes, network issues, and storage failures to check if recovery mechanisms work properly, helping to catch potential issues early.
-- **Meeting Compliance Requirements** - Provides detailed reports and logs that help with audits and ensure compliance with internal and regulatory standards.
-- **Ensuring Quality** - The framework runs automated tests to verify whether the failover behavior of SAP components functions as expected on Azure across various test scenarios. It also ensures that the cluster and resource configurations are set up correctly, helping to maintain system reliability.
-- **Automating Testing** - Automates validation processes from configuration checks to reporting, saving time and ensuring consistent results.
+In the SAP Testing Automation Framework, thorough validation of high availability SAP HANA scale-up and SAP Central Services failover mechanism in a two node pacemaker cluster can be performed, ensuring the system operates correctly across different situations.
 
-## 🚦 Get Started
+- **High Availability Configuration Validation:** The framework helps to ensure that SAP HANA scale-up and SAP Central Services configurations and load balancer settings are compliant with SAP on Azure high availability configuration guidelines.
+- **Functional Testing:** The framework executes series of real-world scenarios based on the SAP HANA and SAP Central Services high availability setup to identify potential issues, whether during a new system deployment or before implementing cluster changes in a production environment. The test cases are based on what is documented in how-to guides for SAP HANA and SAP Central Services configuration.
+- **Offline configuration validation:** Offline validation is a mode of the framework that validates SAP HANA and SAP Central Services high availability cluster configurations without establishing a live SSH connection to the production cluster. Instead, it analyzes captured cluster information base (CIB) XML files exported from each cluster node.
 
-There are two primary ways to get started with the SAP Testing Automated Framework. Choose the path that best fits your current environment and objectives:
+### Configuration Checks (Preview)
 
-### Option 1: Integration with SAP Deployment Automation Framework (SDAF)
+The framework performs comprehensive configuration checks to ensure that the SAP system and its components are set up according to [SAP on Azure best practice](https://learn.microsoft.com/azure/sap/). This includes validating infrastructure settings, operating system parameter configurations, and network settings, in addition to the cluster configuration, to identify any deviations that could impact system performance or reliability.
 
-If you already have [SDAF](https://github.com/Azure/sap-automation) environment set up, integrating the SAP Testing Automation Framework is a natural extension that allows you to leverage existing deployment pipelines and configurations.
+- **Infrastructure Validation:** This includes validating the underlying infrastructure components, such as virtual machines, load balancer, and other resource configurations, to ensure they meet the requirements for running SAP workloads on Azure.
+- **Storage Configuration Checks:** It validates settings of disks, storage accounts, Azure NetApp Files, including throughput, performance, and stripe size.
+- **Operating System and SAP Parameter Validation:** The framework checks critical operating system parameters and SAP kernel settings to ensure they align with recommended configurations.
+- **Cluster Configuration Validation:** This framework ensures that the high availability cluster resource settings adhere to best practices for high availability and failover scenarios.
 
-### Option 2: Getting Started with High Availability Testing (Standalone)
+The framework generates comprehensive reports, highlighting configuration mismatch or deviations from recommended best practices. For high availability scenarios, the report includes failover test outcomes, any failures encountered, and logs with insights to aid in troubleshooting identified issues.
+
+## 🏆 Purpose
+
+Testing is crucial for keeping SAP systems running smoothly, especially for critical business operations. This framework helps by addressing key challenges:
 
-For users focused solely on validating SAP functionality and configurations, the standalone approach offers a streamlined process to test critical SAP components without the complexity of full deployment integration.
- - For High Availability testing details, see the [High Availability documentation](./docs/HIGH_AVAILABILITY.md).
- - For Configuration Checks and Testing details, see the [Configuration Checks documentation](./docs/CONFIGURATION_CHECKS.md).
+- **Risk Prevention** - The high availability testing helps simulate system failures like node crashes, network issues, and storage failures to check if recovery mechanisms work properly, helping to catch problems before they affect real operations. Configuration validation detects misalignments with SAP on Azure best practices early.
+- **Compliance Requirements** - Many businesses need to prove their SAP systems are reliable. This framework provides detailed reports and logs that help with audits and ensure compliance with internal and regulatory standards.
+- **Quality Assurance** - The framework runs automated tests to verify whether the failover behavior of SAP components functions as expected on Azure across various test scenarios. It also ensures that the cluster and resource configurations are set up correctly, helping to maintain system reliability.
+- **Test Automation** - Manually validating overall SAP systems' configurations and high availability (HA) setup is slow and error-prone. This framework automates the process, from setup to reporting, saving time and ensuring more accurate and consistent results.
 
 ## 🏗️ Architecture and Components
 
 To learn how the framework works, refer to the [architecture and components](./docs/ARCHITECTURE.md) documentation.
 
+## 🚦 Get Started
+
+There are two primary ways to get started with the SAP Testing Automation Framework. You can choose the path that best fits your current environment and objectives:
+
+### Option 1: Standalone Setup of SAP Testing Automation Framework
+
+For users focused solely on validating SAP functionality and configurations, the standalone approach offers a streamlined process to test critical SAP components without the complexity of full deployment integration. For more details on the setup, see following documents to get started -
+
+- Configure management server following the document [Setup Guide for SAP Testing Automation Framework](https://github.com/Azure/sap-automation-qa/blob/main/docs/SETUP.MD).
+  - For high availability testing scenarios, see [High Availability documentation](./docs/HIGH_AVAILABILITY.md).
+  - For Configuration Checks and Testing details, see the [Configuration Checks documentation](./docs/CONFIGURATION_CHECKS.md).
+
+### Option 2: Integration with SAP Deployment Automation Framework (SDAF)
+
+If you already have an [SAP Deployment Automation Framework](https://learn.microsoft.com/azure/sap/automation/deployment-framework) environment set up, integrating the SAP Testing Automation Framework is a natural extension that allows you to leverage existing deployment pipelines and configurations. For more details on the setup, see [Setup Guide for SAP Testing Automation Framework](./docs/SETUP.MD).
+
 ## 🆘Support
 
 For support and questions, please:

docs/CONFIGURATION_CHECKS.md

@@ -17,33 +17,32 @@ Configuration validation serves as a critical quality gate in the SAP deployment
 
 ## Configuration Check Categories
 
-**Azure Compute**
-- VM SKU appropriateness for SAP workloads
-- Accelerated Networking enablement
-- Availability Set/Zone configuration
-- Proximity Placement Group setup
-
-**Storage Configuration**
-- Premium SSD/Ultra Disk usage for critical paths
-- Write Accelerator for log volumes
-- Storage account redundancy settings
-- Disk caching policies
-
-**SAP Database Configuration**
-- SAP HANA: Memory allocation, system replication parameters
-- IBM DB2: Hardware requirements, system language, OS tuning parameters
-
-**Pacemaker Cluster (HANA only)**
-- Resource agent versions and parameters
-- Fencing (STONITH) configuration
-- Resource constraints and colocation rules
-- Cluster communication settings
-
-**SAP HA Resources (HANA only)**
-- Virtual hostname configuration
-- File system mount options
-- Service startup ordering
-- Failover timeout values
+The configuration checks are organized into logical groups that can be executed independently or all at once. The main categories are:
+
+1. **Infrastructure**
+
+      - While not a separate execution category, infrastructure checks are performed as part of the other categories.
+      - **Azure Compute**: VM SKU, Accelerated Networking, Availability Set/Zone, Proximity Placement Group.
+      - **Storage**: Use of Premium SSD/Ultra Disk, Write Accelerator, disk caching policies, and redundancy settings.
+
+2. **Database**
+
+   - Validates SAP HANA or IBM DB2 specific settings.
+   - **SAP HANA**: Checks memory allocation, system replication parameters, and Pacemaker cluster configurations (resource agents, fencing, constraints).
+   - **IBM DB2**: Verifies hardware requirements, system language, and OS tuning parameters.
+
+3. **Central Services**
+
+      - Validates the configuration of ASCS (ABAP SAP Central Services) and ERS (Enqueue Replication Server) instances.
+
+      - Checks for virtual hostname configuration, file system mount options, and service startup ordering.
+
+
+3. **Application Servers**
+      - Validates the configuration of the application server instances.
+
+
+> **Note**: High Availability (HA) configuration checks and functional tests are currently supported only for SAP HANA databases. For IBM DB2 databases, only non-HA configuration checks are available.
 
 
 ### 1. Setup Configuration
@@ -58,18 +57,18 @@ Follow the steps (2.1 - 2.2) in [Setup Guide for SAP Testing Automation Framewor
 
 > **Note**: High Availability (HA) configuration checks and functional tests are currently supported only for SAP HANA databases. For IBM DB2 databases, only non-HA configuration checks are available.
 
-### 3. Required Access and Permissions
+### 3. Required Access and Permissions (required)
+
+Effective configuration validation requires that the management server's managed identity (system or user assigned) has read permissions on all target Azure resources. This allows the framework to inspect the settings of services including, but not limited to, Azure Load Balancers, storage solutions (Managed Disks, Azure Files, Azure NetApp Files), and network infrastructure. Lacking the necessary access will prevent the configuration checks from identifying potential misconfigurations in the environment. For more details on configuring system assigned managed identity vs user assigned managed identity, see [Setup Guide for SAP Testing Automation Framework](./SETUP.MD#configuring-access-using-managed-identity).
 
-Ensure that the managed identity or service principal used by the controller virtual machine has the necessary permissions to access Azure resources and SAP systems for configuration validation.
-1. "Reader" role to the user-assigned managed identity on the resource group containing the SAP VMs and the Azure Load Balancer.
-1. "Reader" role to the user-assigned managed identity on the resource group containing the Azure NetApp Files account (if using Azure NetApp Files as shared storage).
-1. "Reader" role to the user-assigned managed identity on the resource group containing the storage account (if using Azure File Share as shared storage).
-1. "Reader" role to the user-assigned managed identity on the resource group containing the managed disks (if using Azure Managed Disks for SAP HANA data and log volumes).
-1. "Reader" role to the user-assigned managed identity on the resource group containing the shared disks (if using Azure Shared Disks for SBD devices).
+1. Depending on the type of managed identity method you want to use, configure managed identity on management server
+   - [Configuring access using system-assigned managed identity](./SETUP.MD#configuring-access-using-system-assigned-managed-identity).
+   - [Configuring access using user-assigned managed identity](SETUP.MD#configuring-access-using-user-assigned-managed-identity).
+2. Grant the managed identity (system- or user-assigned) the built-in **Reader** role on every resource group that contains SAP system components (VMs, managed disks, load balancers, virtual network, shared storage such as Azure NetApp Files or Azure Files). If everything resides in a single resource group, one assignment there is sufficient; if components are split across multiple resource groups, add a **Reader** role assignment on each resource group to allow the configuration checks to read and validate all infrastructure settings.
 
 ### 4. Azure Login (required)
 
-Ensure that you are logged into Azure CLI on the controller VM with the appropriate subscription context:
+Ensure that you are logged into Azure CLI on the management server VM with the appropriate subscription context:
 
 ```bash
 # Login to Azure using System Assigned Managed Identity
@@ -108,7 +107,7 @@ To execute the script, run following command:
 
 ### 6. Viewing Test Results
 
-After the test execution completes, a detailed HTML report is generated that summarizes the PASS/FAIL status of each test case and includes detailed execution logs for every step of the automation run.
+After the test execution completes, a detailed HTML report is generated. The report provide the summary of each test cases that got executed for each VM.
 
 **To locate and view your test report:**
 
@@ -119,16 +118,17 @@ After the test execution completes, a detailed HTML report is generated that sum
    ```bash
    cd WORKSPACES/SYSTEM/<SYSTEM_CONFIG_NAME>/quality_assurance/
    ```
+   
 2. **Find your report file:**
 
    The report file is named using the following format:
 
    ```
-   CONFIG_{SAP_SID}_{DATABASE_TYPE}_{INVOCATION_ID}.html
+   all_{DISTRO}_{INVOCATION_ID}.html
    ```
 
-   - `SAP_SID`: The SAP system ID (e.g., HN1, NWP)
-   - `DATABASE_TYPE`: The database type (e.g., HANA)
+   - `DISTRO`: Linux distribution (SLES or RHEL)
+
    - `INVOCATION_ID`: A unique identifier (Group invocation ID) for the test run which is logged at the end of test execution. Find example screenshot below:
 
       ![Test Execution Completion Screenshot](./images/execution_screenshot.png)