From 44538ed503b308e9557d244aa4bd22cee15faf13 Mon Sep 17 00:00:00 2001 From: Marcel Mamula Date: Fri, 1 Aug 2025 10:05:23 +0200 Subject: [PATCH 1/3] doc: readme update to align with project again --- .ansible-lint | 6 +- .gitignore | 3 + README.md | 120 ++++++- docs/CONTRIBUTORS.md | 6 +- docs/README.md | 100 ------ roles/sap_vm_preconfigure/README.md | 1 + roles/sap_vm_provision/PLATFORM_GUIDANCE.md | 148 ++++----- roles/sap_vm_provision/README.md | 351 ++++++++++++-------- roles/sap_vm_temp_vip/INPUT_PARAMETERS.md | 66 ---- roles/sap_vm_temp_vip/README.md | 87 ++++- roles/sap_vm_verify/README.md | 1 + 11 files changed, 472 insertions(+), 417 deletions(-) delete mode 100644 docs/README.md delete mode 100644 roles/sap_vm_temp_vip/INPUT_PARAMETERS.md diff --git a/.ansible-lint b/.ansible-lint index 9ce20e42..743bf739 100644 --- a/.ansible-lint +++ b/.ansible-lint @@ -2,12 +2,14 @@ # Collection wide lint-file # DO NOT CHANGE exclude_paths: + - .ansible/ - .cache/ - .github/ #- docs/ + - changelogs/ # Changelog files are missing '---' required in normal yml files. + - roles/sap_vm_preconfigure # Role is WIP + # TODO: Remove when ansible-lint issues are resolved (Issue #101). - roles/sap_hypervisor_node_preconfigure - #- roles/sap_vm_provision - - roles/sap_vm_preconfigure enable_list: - yaml diff --git a/.gitignore b/.gitignore index 3469fb09..b2722776 100644 --- a/.gitignore +++ b/.gitignore @@ -62,3 +62,6 @@ __pycache__/ *.tfstate *.tfstate.* .terraform.lock.hcl + +# Ignore ansible workspace +.ansible diff --git a/README.md b/README.md index 3fb6980d..7df9c436 100644 --- a/README.md +++ b/README.md @@ -2,36 +2,128 @@ ![Ansible Lint](https://github.com/sap-linuxlab/community.sap_infrastructure/actions/workflows/ansible-lint.yml/badge.svg?branch=main) -This Ansible Collection executes various SAP Infrastructure related tasks, creating resources needed for hosts of SAP Systems. +## Description +This Ansible Collection provides a set of Ansible Roles designed to automate various infrastructure-related tasks for SAP systems. It focuses on creating and configuring the necessary resources on different infrastructure platforms, including cloud hyperscalers and hypervisors. -These Ansible Roles are often run first and combined with other Ansible Collections to provide end-to-end automation. +These roles are typically used as a foundational step in end-to-end automation workflows, often in conjunction with other Ansible Collections that handle higher-level configurations, such as SAP application deployments. -Various Infrastructure Platforms (Cloud Hyperscalers and Hypervisors) are compatible and tested with this Ansible Collection. +The included roles cover a range of tasks, such as: +- Provisioning Virtual Machines on target infrastructure platforms, using `Ansible` or `Terraform`. + - This also includes provisioning of High Availability resources (Routing, Load Balancers, etc.), where applicable. +- Assigning temporary Virtual IP Addresses for application installation, before they are managed by a cluster. +- Pre-configuring hypervisor nodes for hosting virtual machines for SAP systems. +- Pre-configuring virtual machines (`Work in Progress`). +- Verifying provisioned virtual machines (`Work in Progress`). -**Please read the [full documentation](./docs#readme) for how-to guidance, requirements, and all other details. Summary documentation is below:** +## Requirements +**Please read the detailed documentation for each Ansible Role to understand their specific requirements.** +Always follow official [Ansible Documentation](https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix) for compatibility matrix between Control and Managed nodes. -## Contents +### Control Nodes +Supported Operating systems: +- Any operating system with required Python and Ansible versions. + +Component versions: +| Component | Version | +| --- | --- | +| Python | 3.11 or higher | +| ansible-core | 2.16 or higher | + +**NOTE:** We recommend using the latest version of components.
+Each minor version of `ansible-core` can bring Security fixes (CVE) that can affect functionality. Examples: +- `CVE-2023-5764` changed `assert` functionality in `2.14.12`, `2.15.8` and `2.16.1`. +- `CVE-2024-11079` changed `hostvars` functionality in `2.16.14`, `2.17.7` and `2.18.1`. + +### Managed Nodes +Supported Operating systems: +- SUSE Linux Enterprise Server for SAP applications (SLE4SAP): 15 SP5-SP7 and 16 +- Red Hat Enterprise Linux for SAP Solutions (RHEL4SAP): 8.x, 9.x and 10.x + +**NOTE: Operating system needs to have access to required package repositories either directly or via a subscription registration.** + +Component versions: +| Component | Version | +| --- | --- | +| Python | 3.6 or higher | + + +## Installation Instructions + +### Installation +Install this collection with Ansible Galaxy command: +```console +ansible-galaxy collection install community.sap_infrastructure +``` + +Optionally you can include collection in requirements.yml file and include it together with other collections using: `ansible-galaxy collection install -r requirements.yml`.
+**NOTE: This is not recommended for this collection, because you will need only specific subset of collections for your chosen Infrastructure Platform.**
+ +Requirements file need to be maintained in following format: +```yaml +collections: + - name: community.sap_infrastructure +``` + +### Upgrade +Installed Ansible Collection will not be upgraded automatically when Ansible package is upgraded. + +To upgrade the collection to the latest available version, run the following command: +```console +ansible-galaxy collection install community.sap_infrastructure --upgrade +``` + +You can also install a specific version of the collection if you encounter issues with the latest version. Please report such issues in the affected Role repository. +For example, to install version 1.1.0: +``` +ansible-galaxy collection install community.sap_infrastructure:==1.1.0 +``` + +See [Installing collections](https://docs.ansible.com/ansible/latest/collections_guide/collections_installing.html) for more details on installation methods. -Within this Ansible Collection, there are various Ansible Roles and no custom Ansible Modules. ### Ansible Roles +All included roles can be executed independently or as part of [ansible.playbooks_for_sap](https://github.com/sap-linuxlab/ansible.playbooks_for_sap) playbooks. | Name | Summary | | :--- | :--- | -| [sap_hypervisor_node_preconfigure](https://github.com/sap-linuxlab/community.sap_infrastructure/tree/main/roles/sap_hypervisor_node_preconfigure)
`Beta` | Vendor-specific configuration preparation tasks for Hypervisor nodes hosting Virtual Machines running SAP Systems | -| ~~[sap_vm_preconfigure](https://github.com/sap-linuxlab/community.sap_infrastructure/tree/main/roles/sap_vm_preconfigure)~~
`WIP` | ~~Vendor-specific configuration preparation tasks for Virtual Machines running SAP Systems~~ | -| [sap_vm_provision](https://github.com/sap-linuxlab/community.sap_infrastructure/tree/main/roles/sap_vm_provision) | Provision Virtual Machines to different Infrastructure Platforms; with optional Ansible to Terraform to provision minimal landing zone (partial compatibility via [Terraform Modules for SAP](https://github.com/sap-linuxlab/terraform.modules_for_sap)) | -| [sap_vm_temp_vip](https://github.com/sap-linuxlab/community.sap_infrastructure/tree/main/roles/sap_vm_temp_vip)
`Beta` | Temporary Virtual IP (VIP) assigned to OS Network Interface prior to Linux Pacemaker ownership | -| ~~[sap_vm_verify](https://github.com/sap-linuxlab/community.sap_infrastructure/tree/main/roles/sap_vm_verify)~~
`WIP` | ~~Verification of Virtual Machine state and readiness to perform SAP Software installation~~ | +| [sap_hypervisor_node_preconfigure](https://github.com/sap-linuxlab/community.sap_infrastructure/tree/main/roles/sap_hypervisor_node_preconfigure)`Beta` | Vendor-specific configuration preparation tasks for Hypervisor nodes hosting Virtual Machines running SAP Systems | +| ~~[sap_vm_preconfigure](https://github.com/sap-linuxlab/community.sap_infrastructure/tree/main/roles/sap_vm_preconfigure)~~`WIP` | ~~Vendor-specific configuration preparation tasks for Virtual Machines running SAP Systems~~ | +| [sap_vm_provision](https://github.com/sap-linuxlab/community.sap_infrastructure/tree/main/roles/sap_vm_provision) | Provision Virtual Machines to different Infrastructure Platforms; with optional Ansible to Terraform to provision minimal landing zone. | +| [sap_vm_temp_vip](https://github.com/sap-linuxlab/community.sap_infrastructure/tree/main/roles/sap_vm_temp_vip)
| Temporary Virtual IP (VIP) assigned to OS Network Interface prior to Linux Pacemaker ownership | +| ~~[sap_vm_verify](https://github.com/sap-linuxlab/community.sap_infrastructure/tree/main/roles/sap_vm_verify)~~ `WIP` | ~~Verification of Virtual Machine state and readiness to perform SAP Software installation~~ | -## License +## Testing +This Ansible Collection has been tested across different operating systems, SAP products, and scenarios. + +Prior to each release, basic scenarios are executed to confirm functionality is working as expected, including SAP S/4HANA installation. + +**NOTE: It is not possible for the project maintainers to test every combination of Infrastructure Platform, Operating System and SAP Software for every release.** + -- [Apache 2.0](./LICENSE) +## Contributing +For information on how to contribute, please see our [contribution guidelines](https://sap-linuxlab.github.io/initiative_contributions/). ## Contributors +You can find list of Contributors at [/docs/contributors](./docs/CONTRIBUTORS.md). + + +## Support +You can report any issues using [GitHub Issues](https://github.com/sap-linuxlab/community.sap_infrastructure/issues). + -Contributors to the Ansible Roles within this Ansible Collection, are shown within [/docs/contributors](./docs/CONTRIBUTORS.md). +## Release Notes and Roadmap +The release notes for this collection can be found in the [CHANGELOG file](https://github.com/sap-linuxlab/community.sap_infrastructure/blob/main/CHANGELOG.rst). + + +## Further Information + +### Variable Precedence Rules +Please follow [Ansible Precedence guidelines](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_variables.html#variable-precedence-where-should-i-put-a-variable) on how to pass variables when using this collection. + + +## License +[Apache 2.0](https://github.com/sap-linuxlab/community.sap_infrastructure/blob/main/LICENSE) diff --git a/docs/CONTRIBUTORS.md b/docs/CONTRIBUTORS.md index d4e76f06..f3a3c18d 100644 --- a/docs/CONTRIBUTORS.md +++ b/docs/CONTRIBUTORS.md @@ -5,8 +5,12 @@ - **Sean Freeman** - Developer of Ansible Collection and sap_vm_provision Ansible Role - **Red Hat** - Red Hat for SAP CoP - - **Janine Fuchs** - Developer of Ansible parallelisation and OVirt capability for sap_vm_provision Ansible Role + - **Janine Fuchs** - Developer of Ansible parallelization and OVirt capability for sap_vm_provision Ansible Role - **Nils Koenig** - Developer of sap_hypervisor_node_preconfigure and KubeVirt capability for sap_vm_provision Ansible Role +- **SUSE** + - SUSE SAP Emerging Technology Solutions + - **Marcel Mamula** - Developer of Ansible Collection + # New contributors diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index e1c0c9a7..00000000 --- a/docs/README.md +++ /dev/null @@ -1,100 +0,0 @@ -# Documentation of community.sap_infrastructure Ansible Collection - -## Introduction - -The `sap_infrastructure` Ansible Collection executes various SAP Infrastructure related tasks, creating resources needed for hosts of SAP Systems. - -These Ansible Roles are often run first and combined with other Ansible Collections to provide end-to-end automation. - - -## Functionality - -This Ansible Collection provides a variety of tasks related to SAP Infrastructure (networks, storage, compute). The code structure and logic has been separated to support a flexible execution of different steps for various Infrastructure Platforms and hosting options. - -At a high-level, the key functionality of this Ansible Collection includes: - -- Preconfigure Hypervisor nodes ready to host Virtual Machines running SAP Systems -- Preconfigure Virtual Machines with specific tasks for the Infrastructure Platform -- Provision Virtual Machines - - on target Infrastructure Platform, using Ansible or Ansible to Terraform (to perform minimal landing zone setup of an Infrastructure Platform) - - with High Availability resources if required for the Infrastructure Platform (e.g. Routing and Load Balancers on Cloud Hyperscalers) -- Assignment of Temporary Virtual IP required for High Availability installations on selected Infrastructure Platforms - - -Compatibility is available within the Ansible Collection for various Infrastructure Platforms: - -- Cloud Hyperscalers - AWS EC2 VS, GCP CE VM, IBM Cloud VS, IBM Power VS from IBM Cloud, MS Azure VM -- Hypervisors - IBM PowerVM VM, OVirt VM, KubeVirt VM, VMware VM - - -## Execution - -An Ansible Playbook is the file created and executed by an end-user, which imports from Ansible Collections to perform various activities on the target hosts. - -The Ansible Playbook can call either an Ansible Role, or directly call the individual Ansible Modules: - -- **Ansible Roles** (runs multiple Ansible Modules) -- **Ansible Modules** (and adjoining Python/Bash Functions) - -It is strongly recommended to execute these Ansible Roles in accordance to best practice Ansible usage, where an Ansible Playbook is executed from a host and Ansible will login to a target host to perform the activities. - -> If an Ansible Playbook is executed from the target host itself (similar to logging in and running a shell script), this is known as an Ansible Playbook 'localhost execution' and is not recommended as it has limitations on SAP Software installations (particularly installations across multiple hosts). - -At a high-level, complex executions with various interlinked activities are run in parallel or sequentially using the following execution structure: - -``` -Ansible Playbook --> source Ansible Collection --> execute Ansible Task ----> run Ansible Role ------> run Ansible Module (e.g. built-in Ansible Module for Shell) -``` - -### Execution examples - -There are various methods to execute the Ansible Collection, dependent on the use case. - -For more information, see [sample Ansible Playbooks in `/playbooks`](../playbooks/). - - -## Requirements and Dependencies - -### Execution/Controller host - Operating System requirements - -Execution of Ansible Playbooks using this Ansible Collection have been tested with: -- Python 3.9.7 and above (i.e. CPython distribution) -- Ansible Core 2.12.0 and above _(included with optional installation of Ansible Community Edition 5.0 and above)_ -- OS: macOS with Homebrew, RHEL, SLES, and containers in Task Runners (e.g. Azure DevOps) - -#### Ansible Core version - -This Ansible Collection was designed for maximum backwards compatibility, with full compatibility starting from Ansible Core 2.12.0 and above. - -**Note 1:** Ansible 2.9 was the last release before the Ansible project was split into Ansible Core and Ansible Community Edition, and was before Ansible Collections functionality was introduced. This Ansible Collection should execute when Ansible 2.9 is used, but it is not recommended and errors should be expected (and will not be resolved). - -**Note 2:** Ansible Core versions prior to 2.14.12 , 2.15.8 , and 2.16.1 where `CVE-2023-5764` (templating inside `that` statement of `assert` Ansible Tasks) security fix was addressed, will work after `v1.3.4` of this Ansible Collection. Otherwise an error similar to the following will occur: - -```yaml -fatal: [host01]: FAILED! => - msg: 'The conditional check ''13 <= 128'' failed. The error was: Conditional is marked as unsafe, and cannot be evaluated.' -``` - - -## Testing - -Various Infrastructure Platforms and SAP Software solutions have been extensively tested. - -Prior to each release, basic scenarios are executed to confirm functionality is working as expected; including SAP S/4HANA installation. - -Important note: it is not possible for the project maintainers to test every Infrastructure Platform setup and all SAP Software for each OS, if an error is identified please raise a [GitHub Issue](/../../issues/). - - -### Ansible Roles Lint Status - -| Role Name | Ansible Lint Status | -| :--- | :--- | -| [sap_hypervisor_node_preconfigure](https://github.com/sap-linuxlab/community.sap_infrastructure/tree/main/roles/sap_hypervisor_node_preconfigure) | [![Ansible Lint for sap_hypervisor_node_preconfigure](https://github.com/sap-linuxlab/community.sap_infrastructure/actions/workflows/ansible-lint-sap_hypervisor_node_preconfigure.yml/badge.svg)](https://github.com/sap-linuxlab/community.sap_infrastructure/actions/workflows/ansible-lint-sap_hypervisor_node_preconfigure.yml) | -| [sap_vm_preconfigure](https://github.com/sap-linuxlab/community.sap_infrastructure/tree/main/roles/sap_vm_preconfigure) | [![Ansible Lint for sap_vm_preconfigure](https://github.com/sap-linuxlab/community.sap_infrastructure/actions/workflows/ansible-lint-sap_vm_preconfigure.yml/badge.svg)](https://github.com/sap-linuxlab/community.sap_infrastructure/actions/workflows/ansible-lint-sap_vm_preconfigure.yml) | -| [sap_vm_provision](https://github.com/sap-linuxlab/community.sap_infrastructure/tree/main/roles/sap_vm_provision) | [![Ansible Lint for sap_vm_provision](https://github.com/sap-linuxlab/community.sap_infrastructure/actions/workflows/ansible-lint-sap_vm_provision.yml/badge.svg)](https://github.com/sap-linuxlab/community.sap_infrastructure/actions/workflows/ansible-lint-sap_vm_provision.yml) | -| [sap_vm_temp_vip](https://github.com/sap-linuxlab/community.sap_infrastructure/tree/main/roles/sap_vm_temp_vip) | [![Ansible Lint for sap_vm_temp_vip](https://github.com/sap-linuxlab/community.sap_infrastructure/actions/workflows/ansible-lint-sap_vm_temp_vip.yml/badge.svg)](https://github.com/sap-linuxlab/community.sap_infrastructure/actions/workflows/ansible-lint-sap_vm_temp_vip.yml) | -| [sap_vm_verify](https://github.com/sap-linuxlab/community.sap_infrastructure/tree/main/roles/sap_vm_verify) | [![Ansible Lint for sap_vm_verify](https://github.com/sap-linuxlab/community.sap_infrastructure/actions/workflows/ansible-lint-sap_vm_verify.yml/badge.svg)](https://github.com/sap-linuxlab/community.sap_infrastructure/actions/workflows/ansible-lint-sap_vm_verify.yml) | diff --git a/roles/sap_vm_preconfigure/README.md b/roles/sap_vm_preconfigure/README.md index 03289ca4..738b1eda 100644 --- a/roles/sap_vm_preconfigure/README.md +++ b/roles/sap_vm_preconfigure/README.md @@ -1,6 +1,7 @@ `WIP` # sap_vm_preconfigure +![Ansible Lint for sap_vm_preconfigure](https://github.com/sap-linuxlab/community.sap_infrastructure/actions/workflows/ansible-lint-sap_vm_preconfigure.yml/badge.svg) Ansible Role for Vendor-specific configuration preparation tasks for Virtual Machines running SAP Systems. diff --git a/roles/sap_vm_provision/PLATFORM_GUIDANCE.md b/roles/sap_vm_provision/PLATFORM_GUIDANCE.md index f4e6f876..bde5b138 100644 --- a/roles/sap_vm_provision/PLATFORM_GUIDANCE.md +++ b/roles/sap_vm_provision/PLATFORM_GUIDANCE.md @@ -5,31 +5,31 @@ Table of Contents: - [Recommended Infrastructure Platform authorizations](#recommended-infrastructure-platform-authorizations) - [Recommended Infrastructure Platform configuration](#recommended-infrastructure-platform-configuration) -## Key note - Connectivity - -The Ansible Control Node AKA Controller (i.e. device where Ansible Playbook is executed), must be able to directly call the platform's API endpoints. For example: +## Key note - Cloud Connectivity +The Ansible Control Node AKA Execution Node (i.e. device where Ansible Playbook is executed), must be able to directly call the platform's API endpoints. For example: - AWS EC2 API endpoint `ec2.us-east-1.amazonaws.com` -- VMware vSphere REST API endpoint `.:443` - -By default, a Cloud account will use Public internet endpoints which should be accessible in most cases. The Cloud account may utilise Private endpoints for security, as would an On-Premise Hypervisor. Examples include: - -- running an Ansible Playbook from a personal laptop, then the personal laptop acts as the Ansible Control Node and can access the platform's APIs using a Client-to-Site VPN Client (such as OpenVPN Connect) to provision Virtual Machines for deploying SAP software -- running an Ansible Playbook from an existing host (e.g. VM) inside the platform's private network, then the existing host acts as the Ansible Control Node and can access the platform's APIs to provision Virtual Machines for deploying SAP software - -The subsequent provisioned Virtual Machine, must be accessible too - this can utilise a Bastion for SSH Proxy connection, which is common for Cloud IaaS. - -The Ansible Control Node AKA Controller (i.e. device where Ansible Playbook is executed), must be able to SSH to the Ansible Target Node (i.e. Virtual Machine) using: +- VMware vSphere REST API endpoint `.:443` -- DEFAULT: SSH Proxy connection from Ansible control node, via Bastion host, to target node (`sap_vm_provision_bastion_execution: true`); with SSH Private Keys for the host and the bastion (`sap_vm_provision_ssh_host_private_key_file_path: "/path"` and `sap_vm_provision_ssh_bastion_private_key_file_path: "/path"`) -- Direct SSH connection from Ansible control node to target node (`sap_vm_provision_bastion_execution: false`); with SSH Private Key for the host (`sap_vm_provision_ssh_host_private_key_file_path: "/path"`). +By default, a Cloud account will use Public internet endpoints which should be accessible in most cases. +The Cloud account may utilize Private endpoints for security, as would an On-Premise Hypervisor. Examples include: +- Connection from a public device (e.g. Personal laptop). + - It can access Private endpoint using direct Cloud VPN solution or Client-to-Site VPN Client (e.g. OpenVPN Connect) to connect to Company network, which has access to Private endpoint. +- Connection from an existing host in private network in on-premise. + - It can access Private endpoint directly if on-premise network is connected with Cloud (e.g. Site-to-Site VPN, AWS Direct Connect, Azure ExpressRoute, etc.). +- Connection from an existing host in private network in Cloud. + - It can access Private endpoint directly. +By default, this Ansible Role utilizes Bastion host as SSH Proxy for connection to provisioned hosts, which is recommended method for Security. +This behavior is controlled by variable `sap_vm_provision_bastion_execution`: +- `true`: SSH Proxy connection from Ansible control node, via Bastion host, to target node with SSH Private Keys for the host `sap_vm_provision_ssh_bastion_private_key_file_path` and the bastion `sap_vm_provision_ssh_host_private_key_file_path`. +- `false`: Direct SSH connection from Ansible control node to target node with SSH Private Key for the host `sap_vm_provision_ssh_host_private_key_file_path`. -## Required resources when Ansible provisioning VMs -The following does not apply if Ansible to Terraform is used. +## Infrastructure Prerequisites for Ansible provisioning method +**NOTE:** The following does not apply if `sap_vm_provision_iac_type: ansible_to_terraform` is used. -See below for the drop-down list of required environment resources on an Infrastructure Platform resources when Ansible is used to provision Virtual Machines. +See below for the drop-down list of required environment resources on an Infrastructure Platform.
Amazon Web Services (AWS): @@ -41,7 +41,7 @@ See below for the drop-down list of required environment resources on an Infrast - Route53 (Private DNS) - Internet Gateway (SNAT) - EFS (NFS) -- Bastion host (AWS EC2 VS) +- Bastion host (AWS EC2 VS) - This becomes optional, if `sap_vm_provision_bastion_execution` is set to `false`. - Key Pair for hosts
@@ -56,7 +56,7 @@ See below for the drop-down list of required environment resources on an Infrast - Cloud NAT (SNAT) - DNS Managed Zone (Private DNS) - Filestore (NFS) or NFS server -- Bastion host (GCP CE VM) +- Bastion host (GCP CE VM) - This becomes optional, if `sap_vm_provision_bastion_execution` is set to `false`. @@ -72,7 +72,7 @@ See below for the drop-down list of required environment resources on an Infrast - Storage Account - Azure Files (aka. File Storage Share, NFS) - Private Endpoint Connection -- Bastion host (MS Azure VM) +- Bastion host (MS Azure VM) - This becomes optional, if `sap_vm_provision_bastion_execution` is set to `false`. - Key Pair for hosts @@ -88,7 +88,7 @@ See below for the drop-down list of required environment resources on an Infrast - Private DNS - Public Gateway (SNAT) - File Share (NFS) -- Bastion host (IBM Cloud VS) +- Bastion host (IBM Cloud VS) - This becomes optional, if `sap_vm_provision_bastion_execution` is set to `false`. - Key Pair for hosts @@ -102,7 +102,7 @@ See below for the drop-down list of required environment resources on an Infrast - Cloud Connection (from secure enclave to IBM Cloud) - Private DNS Zone - Public Gateway (SNAT) -- Bastion host (IBM Cloud VS or IBM Power VS) +- Bastion host (IBM Cloud VS or IBM Power VS) - This becomes optional, if `sap_vm_provision_bastion_execution` is set to `false`. - Key Pair for hosts (in IBM Power Workspace) @@ -121,7 +121,7 @@ See below for the drop-down list of required environment resources on an Infrast
Red Hat OpenShift Virtualization (kubevirt_vm) -- IMPORTANT: The playbook has to run with the environment variable `ANSIBLE_JINJA2_NATIVE=true` otherwise you will see an unmarshalling error when the VM is created. On Ansible Automation Platform Controller (AAPC) you have to set this in Settings --> Job Settings --> Extra Environment Variables, e.g. +- IMPORTANT: The playbook has to run with the environment variable `ANSIBLE_JINJA2_NATIVE=true` otherwise you will see an `unmarshalling` error when the VM is created. On Ansible Automation Platform Controller (AAPC) you have to set this in Settings --> Job Settings --> Extra Environment Variables, e.g. ``` { "ANSIBLE_JINJA2_NATIVE": "true", @@ -163,16 +163,12 @@ See below for the drop-down list of required environment resources on an Infrast - Datastore - Content Library - VM Template -
- ## Recommended Infrastructure Platform authorizations - See below for the drop-down list of recommended authorizations for each Infrastructure Platform. -
Amazon Web Services (AWS): @@ -191,53 +187,52 @@ aws iam attach-group-policy --group-name 'ag-sap-automation' --policy-arn arn:aw It is recommended to create new AWS IAM Policy with detailed actions to improve security. ```json { - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "VisualEditor0", - "Effect": "Allow", - "Action": [ - "ec2:DescribeImages", - "ec2:DescribeInstances", - "ec2:DescribeTags", - "ec2:DescribeInstanceAttribute", - "ec2:DescribeSubnets", - "ec2:DescribeSecurityGroups", - "ec2:RunInstances", - "ec2:CreateTags", - "ec2:DescribeInstanceStatus", - "ec2:ModifyInstanceAttribute", - "ec2:DescribeRouteTables", - "route53:ListHostedZones", - "route53:ListResourceRecordSets", - "route53:ChangeResourceRecordSets", - "route53:GetChange", - "ec2:DescribeVolumes", - "ec2:CreateVolume", - "ec2:DeleteVolume", - "ec2:AttachVolume", - "ec2:DetachVolume", - "ec2:TerminateInstances", - "ec2:CreateRoute", - "iam:GetRole", - "iam:CreateRole", - "iam:ListInstanceProfilesForRole", - "iam:CreateInstanceProfile", - "iam:AddRoleToInstanceProfile", - "iam:ListAttachedRolePolicies", - "iam:ListRoleTags", - "iam:PutRolePolicy", - "iam:GetInstanceProfile", - "iam:PassRole", - "ec2:AssociateIamInstanceProfile", - "ec2:ReplaceRoute" - ], - "Resource": "*" - } - ] + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "VisualEditor0", + "Effect": "Allow", + "Action": [ + "ec2:DescribeImages", + "ec2:DescribeInstances", + "ec2:DescribeTags", + "ec2:DescribeInstanceAttribute", + "ec2:DescribeSubnets", + "ec2:DescribeSecurityGroups", + "ec2:RunInstances", + "ec2:CreateTags", + "ec2:DescribeInstanceStatus", + "ec2:ModifyInstanceAttribute", + "ec2:DescribeRouteTables", + "route53:ListHostedZones", + "route53:ListResourceRecordSets", + "route53:ChangeResourceRecordSets", + "route53:GetChange", + "ec2:DescribeVolumes", + "ec2:CreateVolume", + "ec2:DeleteVolume", + "ec2:AttachVolume", + "ec2:DetachVolume", + "ec2:TerminateInstances", + "ec2:CreateRoute", + "iam:GetRole", + "iam:CreateRole", + "iam:ListInstanceProfilesForRole", + "iam:CreateInstanceProfile", + "iam:AddRoleToInstanceProfile", + "iam:ListAttachedRolePolicies", + "iam:ListRoleTags", + "iam:PutRolePolicy", + "iam:GetInstanceProfile", + "iam:PassRole", + "ec2:AssociateIamInstanceProfile", + "ec2:ReplaceRoute" + ], + "Resource": "*" + } + ] } ``` -
@@ -303,7 +298,6 @@ dns.resourceRecordSets.get dns.resourceRecordSets.list dns.resourceRecordSets.update ``` -
@@ -381,7 +375,6 @@ It is recommended to create new Azure custom role with detailed actions to impro ``` Note: MS Azure VMs provisioned will contain Hyper-V Hypervisor virtual interfaces using eth* on the OS, and when Accelerated Networking (AccelNet) is enabled for the MS Azure VM then the Mellanox SmartNIC/DPU SR-IOV Virtual Function (VF) may use enP* on the OS. For further information, see [MS Azure - How Accelerated Networking works](https://learn.microsoft.com/en-us/azure/virtual-network/accelerated-networking-how-it-works). During High Availability executions, failures may occur and may require additional variable 'sap_ha_pacemaker_cluster_vip_client_interface' to be defined. -
@@ -416,14 +409,12 @@ Alternatively, use the IBM Cloud web console: - `[OPTIONAL]` IAM Services > All Identity and Access enabled services > click All resources as scope + Platform Access as Viewer + Resource group access as Administrator - `[OPTIONAL]` Account Management > Identity and Access Management > click Platform access as Editor - `[OPTIONAL]` Account Management > IAM Access Groups Service > click All resources as scope + Platform Access as Editor -
IBM PowerVC: The recommended [IBM PowerVC Security Role](https://www.ibm.com/docs/en/powervc/latest?topic=security-managing-roles) is 'Administrator assistant' (admin_assist), because the 'Virtual machine manager' (vm_manager) role is not able to create IBM PowerVM Compute Template (required for setting OpenStack extra_specs specific to the IBM PowerVM hypervisor infrastructure platform, such as Processing Units). Note that the 'Administrator assistant' does not have the privilege to delete Virtual Machines. -
@@ -442,8 +433,6 @@ Issues were resolved by following [Troubleshooting SLES pay-as-you-go registrati ``` Cloud NAT parameter "minimum ports per VM instance" has to be increased to higher than 160 (Recommended higher). ``` - -
@@ -495,7 +484,6 @@ When VMware vCenter and vSphere clusters with VMware NSX virtualized network ove - For outbound internet connectivity, use SNAT configuration (e.g. rule added on NSX Gateway) set for the Subnet which the VMware VM Template is attached to. Alternatively, use a Web Forward Proxy. N.B. When VMware vCenter and vSphere clusters with direct network subnet IP allocations to the VMXNet network adapter (no VMware NSX network overlays), the above actions may not be required. -
diff --git a/roles/sap_vm_provision/README.md b/roles/sap_vm_provision/README.md index cd1d2216..bd63fbc6 100644 --- a/roles/sap_vm_provision/README.md +++ b/roles/sap_vm_provision/README.md @@ -1,139 +1,134 @@ + # sap_vm_provision Ansible Role + +![Ansible Lint for sap_vm_provision](https://github.com/sap-linuxlab/community.sap_infrastructure/actions/workflows/ansible-lint-sap_vm_provision.yml/badge.svg) -Ansible Role to provision Virtual Machines to host SAP Software. +## Description + +The Ansible Role `sap_vm_provision` is used to provision Virtual Machines to host SAP Software. +The provisioning methods are: +- `Ansible` - Used with existing minimal landing zone. +- `Terraform` - Used to provision minimal landing zone. Partially compatible with [Terraform Modules for SAP](https://github.com/sap-linuxlab/terraform.modules_for_sap). -This Ansible Role will provision Virtual Machines to different Infrastructure Platforms; with optional Ansible to Terraform to provision minimal landing zone (partial compatibility via [Terraform Modules for SAP](https://github.com/sap-linuxlab/terraform.modules_for_sap)). +This Ansible Role follows requirements and best practices of each Infrastructure Platform, while providing near-homogenous setup across all of them. + -Primarily, this Ansible Role was designed to be executed end-to-end (i.e. Provision host/s, configure OS for SAP Software, install SAP Software, instantiate the SAP System); such as the [Ansible Playbooks for SAP](https://github.com/sap-linuxlab/ansible.playbooks_for_sap). + + - -## Functionality - -The provisioned hosts by the Ansible Role provide a near-homogenous setup across different Infrastructure Platforms, while following requirements and best practices defined by each vendor. - -A series of choices is provided by the Ansible Role: -- Infrastructure-as-Code type (Ansible or Ansible to Terraform) -- Infrastructure Platform -- Host Specification Dictionary, containing 1..n Plans -- Host OS Image Dictionary - -Dependent on the choices made by the end user, host/s will be provisioned to the target Infrastructure Platform. - -## Scope - -The code modularity and commonality of provisioning enables a wide gamut of SAP Software Solution Scenarios to be deployed to many Infrastructure Platforms with differing configuration. - -### Available Infrastructure Platforms - -- AWS EC2 Virtual Server instance/s -- Google Cloud Compute Engine Virtual Machine/s -- IBM Cloud, Intel Virtual Server/s -- IBM Cloud, Power Virtual Server/s -- Microsoft Azure Virtual Machine/s -- IBM PowerVM Virtual Machine/s _(formerly LPAR/s)_ -- OVirt Virtual Machine/s (e.g. Red Hat Enterprise Linux KVM) -- KubeVirt Virtual Machine/s (e.g. SUSE Rancher with Harvester HCI) `[Experimental]` -- Red Hat OpenShift Virtualization `[Experimental]` -- VMware vSphere Virtual Machine/s `[Beta]` - -### Known issues - -- VMware REST API combined with cloud-init is unstable, `userdata` configuration may not execute and provisioning will fail - - -## Requirements - -### Target Infrastructure Platform + +## Prerequisites (Control Node) +The prerequisites are listed only for Control Node, because Managed Nodes are provisioned during runtime. For a list of requirements and recommended authorizations on each Infrastructure Platform, please see the separate [Infrastructure Platform Guidance](./PLATFORM_GUIDANCE.md) document and the drop-down for each different Infrastructure Platform. -### Target hosts - -**OS Versions:** -- Red Hat Enterprise Linux 8.0+ -- SUSE Linux Enterprise Server 15 SP0+ - -### Execution/Controller host - -**Dependencies:** -- OS Packages - - Python 3.9.7+ (i.e. CPython distribution) - - IBM Cloud CLI _(when High Availability on IBM Cloud)_ - - Terraform 1.0.0-1.5.5 _(when Ansible to Terraform, or legacy Ansible Collection for IBM Cloud)_ -- Python Packages - - `requests` 2.0+ - - `passlib` 1.7+ - - `jmespath` 1.0.1+ - - `boto3` for Amazon Web Services - - `google-auth` for Google Cloud - - `https://raw.githubusercontent.com/ansible-collections/azure/dev/requirements-azure.txt` for Microsoft Azure - - `openstacksdk` for IBM PowerVM - - `ovirt-engine-sdk-python` for OVirt - - `aiohttp` for VMware - - `kubernetes` for Kubernetes based platforms such as Red Hat OpenShift Virtualization -- Ansible - - Ansible Core 2.12.0+ - - Ansible Collections: - - `amazon.aws` - - `azure.azcollection` - - `cloud.common` - - `cloud.terraform` - - `community.aws` - - `google.cloud` - - `ibm.cloudcollection` - - _(legacy, to be replaced with `ibm.cloud` in future)_ - - `kubevirt.core` for kubevirt_vm or Red Hat OpenShift Virtualization - - `openstack.cloud` - - `ovirt.ovirt` - - `vmware.vmware_rest` _(requires `cloud.common`)_ - -TODO: Split up above dependencies per platform. - +### Base Prerequisites +For list of all collection prerequisites, please see [Ansible Collection Readme](https://github.com/sap-linuxlab/community.sap_infrastructure/blob/main/README.md#equirements) +- Operating System packages: + - Python 3.11 or higher + - Terraform 1.0.0 to 1.5.5 _(when Ansible to Terraform, or legacy Ansible Collection for IBM Cloud)_ +- Python libraries and modules: + - `ansible-core` 2.16 or higher + - `requests` 2.0 or higher + - `passlib` 1.7 or higher + - `jmespath` 1.0.1 or higher +- Ansible Collections: + - `cloud.common` + - `cloud.terraform` When `Ansible to Terraform` is used. + +### Amazon Web Services (AWS) Prerequisites +- Python libraries and modules: + - `boto3` +- Ansible Collections: + - `amazon.aws` + - `community.aws` - Optional, as AWS is moving Ansible Modules from `community.aws` to `amazon.aws`. + +### Google Cloud (GCP) Prerequisites +- Python libraries and modules: + - `google-auth` +- Ansible Collections: + - `google.cloud` + +### Microsoft Azure Prerequisites +- Python libraries and modules: + - The list is maintained at [Azure Collection github](https://github.com/ansible-collections/azure/blob/dev/requirements.txt) + - Installation steps: + - Download file [in raw format](https://raw.githubusercontent.com/ansible-collections/azure/refs/heads/dev/requirements.txt) + - Install using pip `pip3 install -r requirements.txt` + - **NOTE:** Some requirements can be in conflict with other Infrastructure Platforms. We recommend installing Microsoft Azure a separate Python Virtual Environment. +- Ansible Collections: + - `azure.azcollection` + +### IBM Cloud Prerequisites +- Operating System packages: + - IBM Cloud CLI +- Ansible Collections: + - `ibm.cloudcollection` _(legacy, to be replaced with `ibm.cloud` in future)_ + +### IBM PowerVC Prerequisites +- Python libraries and modules: + - `openstacksdk` + +### KubeVirt Prerequisites +- Python libraries and modules: + - `kubernetes` +- Ansible Collections: + - `kubevirt.core` + +### OVirt Prerequisites +- Python libraries and modules: + - `ovirt-engine-sdk-python` +- Ansible Collections: + - `ovirt.ovirt` + +### VMware Prerequisites +- Python libraries and modules: + - `aiohttp` +- Ansible Collections: + - `vmware.vmware_rest` + ## Execution - -### Sample execution - -For further information, see the [sample Ansible Playbooks in `/playbooks`](../playbooks/). - -### Suggested execution sequence - -Prior to execution of this Ansible Role, there are no Ansible Roles suggested to be executed first. - -### Summary of execution flow - -- Define target Host/s Specifications with a 'plan' name (e.g. `test1_256gb_memory` containing 1 host of 256GB Memory for SAP HANA and 1 host for SAP NetWeaver); append to the Host Specification Dictionary -- Define target Host OS Image Dictionary, or use defaults provided for each Cloud Hyperscaler. -- Execute with chosen: - - Infrastructure-as-Code method (Ansible or Ansible to Terraform) using variable `sap_vm_provision_iac_type` - - Infrastructure Platform target using variable `sap_vm_provision_iac_platform` - - Selected plan using variable `sap_vm_provision_host_specification_plan` referring to the definition in the Host Specification Dictionary - - Variables specific to each Infrastructure Platform (e.g. `sap_vm_provision_aws_access_key`) - - Include files from subdirectory based upon chosen method and target (e.g. `/tasks/platform_ansible_to_terraform/aws_ec2_vs/`) -- Provision host/s -- Add hosts to Ansible Inventory Groups defined by the Host Specification Dictionary `sap_host_type` variable _(e.g. hana_primary, hana_secondary, nwas_ascs, nwas_ers, nwas_pas, nwas_aas, anydb_primary, anydb_secondary)_
- **NOTE:** Group names can be customized using `sap_vm_provision_group_*` variables in `vars/default.yml` (e.g. `sap_vm_provision_group_hana_primary`, `sap_vm_provision_group_nwas_ascs`, etc.). -- Perform additional tasks for host/s (e.g. DNS Records, /etc/hosts, register OS for Packages, register Web Forward Proxy) -- Set variables if other Ansible Roles are to be executed (e.g. variables for Ansible Roles in the `sap_install` Ansible Collection) -- Perform any tasks for High Availability (execution dependent on hosts in Ansible Inventory Groups) -- **POST:** Re-execute Ansible Role with variable `sap_vm_provision_iac_post_deployment: true` to update High Availability configurations using Load Balancer (i.e. LB Health Check Port moved to Linux Pacemaker listener) - - -### Required structure in Ansible Playbook - -_**CRITICAL NOTE**_ - -To provide parallelisation of provisioning, the following structure must be used to dynamically create an Ansible Inventory Group for the requested hostnames. Without this necessary pre-task, the Ansible Role will not function. - -> Design decision note: This required structure avoids the Ansible Role using a sequential loop, where each host will execute all Ansible Tasks before the next host is provisioned; or using an async loop which hides all Ansible Task output from the end user. - -This required structure will: - -- In the first Ansible Play using `localhost`, dynamically create an Ansible Inventory with the hostnames listed parsed from the Ansible Dictionary (variable named `sap_vm_provision_XYZ_host_specifications_dictionary` dependent on the Infrastructure Platform) -- In the second Ansible Play use the dynamic Ansible Inventory `sap_vm_provision_target_inventory_group`, create an Ansible Play Batch containing each target host in the dynamic Ansible Inventory, which will then execute all proceeding Ansible Tasks in parallel for each target host. - -**Structure to execute sap_vm_provision:** - + +A series of choices are deciding Ansible Role behavior: +- Infrastructure-as-Code Type `sap_vm_provision_iac_type` - Defines the provisioning method. +- Infrastructure Platform `sap_vm_provision_iac_platform` - Defines the target Infrastructure Platform. +- Host Specification Dictionary - Defines the definition of provisioned SAP system hosts. + +### Supported Infrastructure Platforms +- AWS EC2 Virtual Server instance +- Google Cloud Compute Engine Virtual Machines +- IBM Cloud, Intel Virtual Servers +- IBM Cloud, Power Virtual Servers +- Microsoft Azure Virtual Machines +- IBM PowerVM Virtual Machines _(formerly LPAR)_ +- OVirt Virtual Machines `[Experimental]` +- KubeVirt Virtual Machines `[Experimental]` (e.g. Red Hat OpenShift Virtualization) +- VMware vSphere Virtual Machines `[Experimental]` + + +### Execution Flow + +1. Assert that required inputs were provided. +2. Load Infrastructure Platform specific variables. +3. Provision hosts on selected Infrastructure Platform. +4. Create Ansible Inventory during runtime, based on the variable `sap_host_type` defined in Host Specification Dictionary. +5. Configure hosts (e.g. DNS Records, `/etc/hosts`, register OS for Packages, register Web Forward Proxy). +6. Provision High Availability resources, when required. +7. Set variables if other Ansible Roles are to be executed (e.g. variables for Ansible Roles in the `sap_install` Ansible Collection). +8. Remove temporary High Availability configurations (i.e. LB Health Check Port moved to Linux Pacemaker listener) when executed with variable `sap_vm_provision_iac_post_deployment: true`. + + +### Example + +The playbooks using this Ansible Role are required to dynamically crate Ansible Inventory group during runtime, which will allow parallel provisioning of resources. + +**Reasoning behind this concept:** This required structure avoids the Ansible Role using a sequential loop, where each host will execute all Ansible Tasks before the next host is provisioned; or using an async loop which hides all Ansible Task output from the end user. + +For more examples on how to use this role in different installation scenarios, refer to the [ansible.playbooks_for_sap](https://github.com/sap-linuxlab/ansible.playbooks_for_sap) playbooks. +- These playbooks include Parallelization concept explained above. + +Example for `aws_ec2_vs`: ```yaml - name: Ansible Play to create dynamic inventory group for provisioning hosts: localhost @@ -144,8 +139,7 @@ This required structure will: ansible.builtin.add_host: name: "{{ item }}" group: sap_vm_provision_target_inventory_group - # Adjust var name in loop (i.e. replace _XYZ_ to the correct Ansible Dictionary) - loop: "{{ sap_vm_provision_XYZ_host_specifications_dictionary[sap_vm_provision_host_specification_plan].keys() }}" + loop: "{{ sap_vm_provision_aws_ec2_vs_host_specifications_dictionary[sap_vm_provision_host_specification_plan].keys() }}" - name: Ansible Play to provision hosts for SAP hosts: sap_vm_provision_target_inventory_group # Ansible Play target hosts pattern, use dynamic Inventory Group @@ -156,7 +150,7 @@ This required structure will: ansible.builtin.include_role: name: community.sap_infrastructure.sap_vm_provision -- name: Ansible Play for verify provisioned hosts for SAP +- name: Ansible Play for remaining tasks on provisioned hosts hosts: all tasks: @@ -164,31 +158,94 @@ This required structure will: ansible.builtin.debug: var: groups ``` +Explanation of workflow: +1. First play: `Ansible Play to create dynamic inventory group for provisioning` + - Control Node will create new Ansible Inventory group `sap_vm_provision_target_inventory_group` with hosts defined in the variable `sap_vm_provision_aws_ec2_vs_host_specifications_dictionary` under chosen plan `sap_vm_provision_host_specification_plan`. +2. Second play: `Ansible Play to provision hosts for SAP` + - Provisioning tasks are virtually executed on non-existent hosts, but Ansible Role executes provisioning with `delegate_to` Control Node. + - Configuration tasks after provisioning are executed on newly provisioned hosts. +3. Third play: `Ansible Play for remaining tasks on provisioned hosts` + - Example of how newly provisioned hosts can be targeted with additional tasks (e.g. SAP Installation). + +For further information, see the [sample Ansible Playbooks in `/playbooks`](../playbooks/). + -### Design assumptions with execution impact + + + +## Further Information - For Hyperscaler Cloud Service Providers that use Resource Groups (IBM Cloud, Microsoft Azure): - Virtual Machine and associated resources (Disks, Network Interfaces, Load Balancer etc.) will be provisioned to the same Resource Group as the targeted network/subnet. - Optional: Private DNS may be allocated to another Resource Group, and an optional variable is provided for this. - Virtual Disk with defined IOPS is only possible on AWS, Google Cloud, IBM Cloud -### Tags to control execution - -There are no tags used to control the execution of this Ansible Role - +### Known issues +- VMware REST API combined with cloud-init is unstable, `userdata` configuration may not execute and provisioning will fail + ## License - + Apache 2.0 - - -## Authors - -Sean Freeman -Nils Koenig (nkoenig@redhat.com) kubevirt_vm / Red Hat OpenShift Virtualization - ---- - -## Ansible Role Input Variables - -Please first check the [/defaults parameters file](./defaults/main.yml). + + +## Maintainers + +- [Sean Freeman](https://github.com/sean-freeman) +- [Marcel Mamula](https://github.com/marcelmamula) +- [Nils Koenig](https://github.com/newkit) - kubevirt_vm / Red Hat OpenShift Virtualization + + +## Role Variables + +The list of all available variables: [/defaults parameters file](./defaults/main.yml). + +**Following key variables are required.** + +### sap_vm_provision_iac_type +- _Type:_ `string`
+- _Choices:_ `ansible , ansible_to_terraform`
+ +Defines the provisioning method.
+ +### sap_vm_provision_iac_platform +- _Type:_ `string`
+- _Choices:_ `aws_ec2_vs , gcp_ce_vm , ibmcloud_vs , ibmcloud_powervs , msazure_vm , ibmpowervm_vm , kubevirt_vm , ovirt_vm , vmware_vm`
+ +Defines the target Infrastructure Platform.
+ +### Host Specification Dictionary +- _Type:_ `dict`
+- _Default:_ Default value is defined, but it has to be customized to represent required SAP system.
+ +Defines the definition of provisioned SAP system hosts.
+This variable name is unique for each Infrastructure Platform. Example: `sap_vm_provision_aws_ec2_vs_host_specifications_dictionary` for `aws_ec2_vs`.
+Customization options:
+- Adjust existing plan or add new (Selected by variable `sap_vm_provision_host_specification_plan`). +- Adjust number of hosts and their sizing. +- Adjust the variable `sap_host_type` to customize Ansible Inventory groups. **NOTE:** Group names can be customized using `sap_vm_provision_group_*` variables in `vars/default.yml` (e.g. `sap_vm_provision_group_hana_primary`, `sap_vm_provision_group_nwas_ascs`, etc.). +- Adjust filesystems (size, type, source, etc.).yes + +### Host OS Image Dictionary +- _Type:_ `list`
+- _Default:_ Defined for each supported Cloud platform. + +Defines list of predefined OS Images for each supported Cloud Platform. +This variable name is unique for each Infrastructure Platform. Example: `sap_vm_provision_aws_ec2_vs_host_os_image_dictionary` for `aws_ec2_vs`.
+Chosen OS Image is selected by variable unique variable for each Infrastructure Platform. Example: `sap_vm_provision_aws_ec2_vs_host_os_image` for `aws_ec2_vs`.
+Customization options:
+- Adjust existing or add new OS images that are available. + +### Credentials + +Each Infrastructure Platform has list of required variables defined in [/defaults parameters file](./defaults/main.yml). +Example for `aws_ec2_vs`: +- `sap_vm_provision_aws_access_key` +- `sap_vm_provision_aws_secret_access_key` +- `sap_vm_provision_aws_region` +- `sap_vm_provision_aws_vpc_availability_zone` +- `sap_vm_provision_aws_vpc_subnet_id` +- `sap_vm_provision_aws_vpc_sg_names` +- `sap_vm_provision_aws_key_pair_name_ssh_host_public_key` + + diff --git a/roles/sap_vm_temp_vip/INPUT_PARAMETERS.md b/roles/sap_vm_temp_vip/INPUT_PARAMETERS.md deleted file mode 100644 index 6ef41929..00000000 --- a/roles/sap_vm_temp_vip/INPUT_PARAMETERS.md +++ /dev/null @@ -1,66 +0,0 @@ -## Input Parameters for sap_vm_temp_vip Ansible Role - -### sap_vm_temp_vip_default_ip - -- _Type:_ `string` -- _Default:_ `ansible_default_ipv4.address` - -IP Address of default network interface is obtained from Ansible Facts and it is used for calculation of missing input parameters. - -### sap_vm_temp_vip_default_netmask - -- _Type:_ `string` -- _Default:_ `ansible_default_ipv4.netmask` - -Netmask of default network interface is obtained from Ansible Facts and it is used for calculation of missing input parameters. - -### sap_vm_temp_vip_default_prefix - -- _Type:_ `string` -- _Default:_ `ansible_default_ipv4.prefix` - -Prefix of default network interface is obtained from Ansible Facts and it is used for calculation of missing input parameters. - -### sap_vm_temp_vip_default_broadcast - -- _Type:_ `string` -- _Default:_ `ansible_default_ipv4.broadcast` - -Broadcast of default network interface is obtained from Ansible Facts and it is used for calculation of missing input parameters.
-This parameter is empty on some cloud platforms and VIP is created without broadcast if attempt to calculate fails. - -### sap_vm_temp_vip_default_interface - -- _Type:_ `string` -- _Default:_ `ansible_default_ipv4.interface` or `eth0` - -Default Network Interface name is obtained from Ansible Facts and it is used for calculation of missing input parameters.
-Ensure to use correct Network Interface if default interface from Ansible Facts does not represent desired Network Interface. - -### sap_vm_temp_vip_hana_primary -- _Type:_ `string` -- _Default:_ `sap_ha_pacemaker_cluster_vip_hana_primary_ip_address` - -Mandatory for SAP HANA cluster setup.
-VIP address is by default assigned from `sap_ha_pacemaker_cluster_vip_hana_primary_ip_address` input parameter used by [sap_ha_pacemaker_cluster](https://github.com/sap-linuxlab/community.sap_install/tree/main/roles/sap_ha_pacemaker_cluster) role. - -### sap_vm_temp_vip_nwas_abap_ascs -- _Type:_ `string` -- _Default:_ `sap_ha_pacemaker_cluster_vip_nwas_abap_ascs_ip_address` - -Mandatory for SAP ASCS/ERS cluster setup.
-VIP address is by default assigned from `sap_ha_pacemaker_cluster_vip_nwas_abap_ascs_ip_address` input parameter used by [sap_ha_pacemaker_cluster](https://github.com/sap-linuxlab/community.sap_install/tree/main/roles/sap_ha_pacemaker_cluster) role. - -### sap_vm_temp_vip_nwas_abap_ers -- _Type:_ `string` -- _Default:_ `sap_ha_pacemaker_cluster_vip_nwas_abap_ers_ip_address` - -Mandatory for SAP ASCS/ERS cluster setup.
-VIP address is by default assigned from `sap_ha_pacemaker_cluster_vip_hana_primary_ip_address` input parameter used by [sap_ha_pacemaker_cluster](https://github.com/sap-linuxlab/community.sap_install/tree/main/roles/sap_ha_pacemaker_cluster) role. - -### sap_vm_temp_vip_anydb_primary -- _Type:_ `string` - -Mandatory for SAP AnyDB cluster setup. - - \ No newline at end of file diff --git a/roles/sap_vm_temp_vip/README.md b/roles/sap_vm_temp_vip/README.md index e7df2c42..9ef9d3c2 100644 --- a/roles/sap_vm_temp_vip/README.md +++ b/roles/sap_vm_temp_vip/README.md @@ -1,10 +1,11 @@ # sap_vm_temp_vip Ansible Role +![Ansible Lint for sap_vm_temp_vip](https://github.com/sap-linuxlab/community.sap_infrastructure/actions/workflows/ansible-lint-sap_vm_temp_vip.yml/badge.svg) ## Description -Ansible role `sap_vm_temp_vip` is used to enable installation of SAP Application and Database on High Availability clusters provisioned by [sap_vm_provision](https://github.com/sap-linuxlab/community.sap_infrastructure/tree/main/roles/sap_vm_provision) role. +The Ansible role `sap_vm_temp_vip` is used to enable installation of SAP Application and Database on High Availability clusters provisioned by [sap_vm_provision](https://github.com/sap-linuxlab/community.sap_infrastructure/tree/main/roles/sap_vm_provision) role. Installation of cluster environment requires temporary assignment of Virtual IP (VIP) before executing installation roles [sap_hana_install](https://github.com/sap-linuxlab/community.sap_install/tree/main/roles/sap_hana_install) and [sap_swpm](https://github.com/sap-linuxlab/community.sap_install/tree/main/roles/sap_swpm). - This is temporary and it will be replaced by Cluster VIP resource once cluster is configured by [sap_ha_pacemaker_cluster](https://github.com/sap-linuxlab/community.sap_install/tree/main/roles/sap_ha_pacemaker_cluster) role. @@ -12,21 +13,33 @@ Installation of cluster environment requires temporary assignment of Virtual IP This role does not update `/etc/hosts` or DNS records, as these steps are performed by the [sap_vm_provision](https://github.com/sap-linuxlab/community.sap_infrastructure/tree/main/roles/sap_vm_provision) role. + +## Dependencies +- `community.sap_infrastructure` + - Roles: + - `sap_vm_provision` + - Reason: This role is expected to run after provisioning of resources by Ansible Role [sap_vm_provision](https://github.com/sap-linuxlab/community.sap_infrastructure/tree/main/roles/sap_vm_provision). + + + ## Prerequisites Environment: - Assign hosts to correct groups, which are also used in other roles in our project - Supported cluster groups: `hana_primary, hana_secondary, anydb_primary, anydb_secondary, nwas_ascs, nwas_ers` - -Role dependency: -- [sap_vm_provision](https://github.com/sap-linuxlab/community.sap_infrastructure/tree/main/roles/sap_vm_provision), for creating required resources: DNS, Load Balancers and Health Checks. ## Execution -Role can be execute separately or as part of [ansible.playbooks_for_sap](https://github.com/sap-linuxlab/ansible.playbooks_for_sap) playbooks. + +### Recommended +It is recommended to execute this role together with other roles in this collection, in the following order:
+1. [sap_vm_provision](https://github.com/sap-linuxlab/community.sap_infrastructure/tree/main/roles/sap_vm_provision) +2. *`sap_vm_temp_vip`* + + ### Execution Flow 1. Assert that required inputs were provided. @@ -61,6 +74,8 @@ Role can be execute separately or as part of [ansible.playbooks_for_sap](https:/ +## Further Information +For more examples on how to use this role in different installation scenarios, refer to the [ansible.playbooks_for_sap](https://github.com/sap-linuxlab/ansible.playbooks_for_sap) playbooks. ## License @@ -74,5 +89,63 @@ Apache 2.0 - [Marcel Mamula](https://github.com/marcelmamula) -## Role Input Parameters -All input parameters used by role are described in [INPUT_PARAMETERS.md](https://github.com/sap-linuxlab/community.sap_infrastructure/blob/main/roles/sap_vm_temp_vip/INPUT_PARAMETERS.md) +## Role Variables + +### sap_vm_temp_vip_default_ip +- _Type:_ `string` +- _Default:_ `ansible_default_ipv4.address` + +Specifies the IP Address of the default network interface. + +### sap_vm_temp_vip_default_netmask +- _Type:_ `string` +- _Default:_ `ansible_default_ipv4.netmask` + +Specifies the Netmask of the default network interface. + +### sap_vm_temp_vip_default_prefix +- _Type:_ `string` +- _Default:_ `ansible_default_ipv4.prefix` + +Specifies the prefix of the default network interface. + +### sap_vm_temp_vip_default_broadcast +- _Type:_ `string` +- _Default:_ `ansible_default_ipv4.broadcast` + +Specifies the broadcast of the default network interface.
+This parameter is empty on some cloud platforms and VIP is created without broadcast if attempt to calculate fails. + +### sap_vm_temp_vip_default_interface +- _Type:_ `string` +- _Default:_ `ansible_default_ipv4.interface` or `eth0` + +Specifies the default network interface name.
+Ensure to use correct network interface if default interface from Ansible Facts does not represent desired network interface. + +### sap_vm_temp_vip_hana_primary +- _Type:_ `string` +- _Default:_ `sap_ha_pacemaker_cluster_vip_hana_primary_ip_address` + +This variable is mandatory for SAP HANA cluster setup.
+The VIP address is by default assigned from `sap_ha_pacemaker_cluster_vip_hana_primary_ip_address` input parameter used by Ansible Role [sap_ha_pacemaker_cluster](https://github.com/sap-linuxlab/community.sap_install/tree/main/roles/sap_ha_pacemaker_cluster). + +### sap_vm_temp_vip_nwas_abap_ascs +- _Type:_ `string` +- _Default:_ `sap_ha_pacemaker_cluster_vip_nwas_abap_ascs_ip_address` + +This variable is mandatory for SAP ASCS/ERS cluster setup.
+The VIP address is by default assigned from `sap_ha_pacemaker_cluster_vip_nwas_abap_ascs_ip_address` input parameter used by Ansible Role [sap_ha_pacemaker_cluster](https://github.com/sap-linuxlab/community.sap_install/tree/main/roles/sap_ha_pacemaker_cluster). + +### sap_vm_temp_vip_nwas_abap_ers +- _Type:_ `string` +- _Default:_ `sap_ha_pacemaker_cluster_vip_nwas_abap_ers_ip_address` + +This variable is mandatory for SAP ASCS/ERS cluster setup.
+The VIP address is by default assigned from `sap_ha_pacemaker_cluster_vip_hana_primary_ip_address` input parameter used by Ansible Role [sap_ha_pacemaker_cluster](https://github.com/sap-linuxlab/community.sap_install/tree/main/roles/sap_ha_pacemaker_cluster). + +### sap_vm_temp_vip_anydb_primary +- _Type:_ `string` + +This variable is mandatory for SAP AnyDB cluster setup. + diff --git a/roles/sap_vm_verify/README.md b/roles/sap_vm_verify/README.md index 34f98e71..39baee84 100644 --- a/roles/sap_vm_verify/README.md +++ b/roles/sap_vm_verify/README.md @@ -1,6 +1,7 @@ `WIP` # sap_vm_verify Ansible Role +![Ansible Lint for sap_vm_verify](https://github.com/sap-linuxlab/community.sap_infrastructure/actions/workflows/ansible-lint-sap_vm_verify.yml/badge.svg) Ansible Role for verification of Virtual Machine state and readiness to perform SAP Software installation. From f66f372d23beaeaa0d463c7cc0a4886519d3cd2e Mon Sep 17 00:00:00 2001 From: Marcel Mamula Date: Fri, 1 Aug 2025 10:08:40 +0200 Subject: [PATCH 2/3] fix codespell typo equirements --- roles/sap_vm_provision/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/roles/sap_vm_provision/README.md b/roles/sap_vm_provision/README.md index bd63fbc6..41aeb5e9 100644 --- a/roles/sap_vm_provision/README.md +++ b/roles/sap_vm_provision/README.md @@ -23,7 +23,7 @@ The prerequisites are listed only for Control Node, because Managed Nodes are pr For a list of requirements and recommended authorizations on each Infrastructure Platform, please see the separate [Infrastructure Platform Guidance](./PLATFORM_GUIDANCE.md) document and the drop-down for each different Infrastructure Platform. ### Base Prerequisites -For list of all collection prerequisites, please see [Ansible Collection Readme](https://github.com/sap-linuxlab/community.sap_infrastructure/blob/main/README.md#equirements) +For list of all collection prerequisites, please see [Ansible Collection Readme](https://github.com/sap-linuxlab/community.sap_infrastructure/blob/main/README.md#requirements) - Operating System packages: - Python 3.11 or higher - Terraform 1.0.0 to 1.5.5 _(when Ansible to Terraform, or legacy Ansible Collection for IBM Cloud)_ From 3a927fd86cc7876b25b5a4a50defb72b0ce03ca8 Mon Sep 17 00:00:00 2001 From: Marcel Mamula Date: Wed, 6 Aug 2025 14:52:40 +0200 Subject: [PATCH 3/3] fix: typo in readme --- roles/sap_vm_provision/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/roles/sap_vm_provision/README.md b/roles/sap_vm_provision/README.md index 41aeb5e9..b1cc74db 100644 --- a/roles/sap_vm_provision/README.md +++ b/roles/sap_vm_provision/README.md @@ -121,7 +121,7 @@ A series of choices are deciding Ansible Role behavior: ### Example -The playbooks using this Ansible Role are required to dynamically crate Ansible Inventory group during runtime, which will allow parallel provisioning of resources. +The playbooks using this Ansible Role are required to dynamically create Ansible Inventory group during runtime, which will allow parallel provisioning of resources. **Reasoning behind this concept:** This required structure avoids the Ansible Role using a sequential loop, where each host will execute all Ansible Tasks before the next host is provisioned; or using an async loop which hides all Ansible Task output from the end user.