diff --git a/CHANGELOG.rst b/CHANGELOG.rst index ea6fdcd..137fc0d 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -1,36 +1,77 @@ =================================== -community.sap_launchpad Release Notes +community.sap\_launchpad Release Notes =================================== .. contents:: Topics +v1.2.0 +====== + +Release Summary +--------------- + +Enhancements to Modules and introduction of new Ansible Role. + +Minor Changes +------------- +- sap_software_download: New Ansible Role with enhanced logic for downloading software using Ansible Module software_center_download (https://github.com/sap-linuxlab/community.sap_launchpad/pull/32) +- sap_software_download: Download stack XML option (https://github.com/sap-linuxlab/community.sap_launchpad/pull/35) +- software_center_download: Add option to search for latest packages (https://github.com/sap-linuxlab/community.sap_launchpad/pull/28) +- maintenance_planner modules: Add option to use Display ID instead of name (https://github.com/sap-linuxlab/community.sap_launchpad/pull/31) +- Collection Readme update and preparation for 1.2.0 release (https://github.com/sap-linuxlab/community.sap_launchpad/pull/34) -v1.1.0 +Bugfixes +-------- + +- fix: cache gigya sdk build number (https://github.com/sap-linuxlab/community.sap_launchpad/pull/33) + + +v1.1.1 ====== Release Summary --------------- -| Release Date: 2023-11-28 -| Community contribution Ansible Module systems_info to query registered systems in me.sap.com -| Community contribution Ansible Module license_keys to create systems and license keys on me.sap.com/licensekey +Various bug fixes +Bugfixes +-------- +- Append logic for Account Temporarily Locked Out +- Fix errors in the example file -v1.0.1 + +v1.1.0 (2023-11-28) ====== Release Summary --------------- -| Release Date: 2023-09-14 -| Fix for handling old password prompt +Community contribution with new Ansible Modules `systems_info` and `license_keys`` + +Minor Changes +------------- + +- Create/update systems and license keys (https://github.com/sap-linuxlab/community.sap_launchpad/pull/16) + + +v1.0.1 (2023-09-14) +====== + +Release Summary +--------------- + +Various bug fixes + +Bugfixes +-------- + +- Fix for handling old password prompt -v1.0.0 +v1.0.0 (2023-08-22) ====== Release Summary --------------- -| Release Date: 2023-08-22 -| Initial Release on Galaxy +Initial Release on Galaxy diff --git a/README.md b/README.md index 3217a6a..11d1a40 100644 --- a/README.md +++ b/README.md @@ -1,108 +1,131 @@ -# community.sap_launchpad Ansible Collection ![Ansible Lint](https://github.com/sap-linuxlab/community.sap_launchpad/actions/workflows/ansible-lint.yml/badge.svg?branch=main) +# community.sap_launchpad Ansible Collection -This Ansible Collection executes basic SAP.com Support operations tasks. +![Ansible Lint](https://github.com/sap-linuxlab/community.sap_launchpad/actions/workflows/ansible-lint.yml/badge.svg?branch=main) -## Functionality +## Description -This Ansible Collection executes basic SAP.com Support operations tasks, including: +This Ansible Collection provides roles and modules to automate interaction with SAP Launchpad API, primarily focusing on downloading software and files from the SAP Software Download Center and Maintenance Planner. -- **Software Center Catalog** - - Search and Download of SAP software center catalog files - - Search and Extraction of SAP software center catalog information -- **Maintenance Planner** - - Lookup and download files from an existing 'New Implementation' MP Transaction and Stack, using SAP software center's download basket +Included role and modules cover range of options: +- Preparation of environment before download. +- Download of specific SAP Software files. +- Download of alternative SAP Software files if specific was not available. +- Download of SAP Software files from existing Maintenance Plan transaction. +- Download of Stack file from existing Maintenance Plan transaction. +- Register Systems and License Keys +- Query registered Systems -## Contents -An Ansible Playbook can call either an Ansible Role, or the individual Ansible Modules for handling the API calls to various SAP Support Portal API capabilities: -- **Ansible Roles** (runs multiple Ansible Modules) -- **Ansible Modules** (and adjoining Python Functions) +## Requirements -For further information regarding the development, code structure and execution workflow please read the [Development documentation](./docs/DEVELOPMENT.md). +### Control Nodes +| Type | Version | +| :--- | :--- | +| Operating system | Any operating system with required Python and Ansible versions | +| Python | 3.11 or higher | +| Ansible | 9.9 or higher | +| Ansible-core | 2.16 or higher | -Within this Ansible Collection, there are various Ansible Modules. -#### Ansible Modules +### Managed Nodes +| Type | Version | +| :--- | :--- | +| Operating system | SUSE Linux Enterprise Server 15 SP5+, 16
Red Hat Enterprise Linux 8.x, 9.x, 10.x | +| Python | 3.11 or higher (SUSE)
3.9 or higher (Red Hat) | -| Name                    | Summary | -| :-- | :-- | -| [sap_launchpad.software_center_download](./docs/module_software_center_download.md) | search for files and download | -| [sap_launchpad.maintenance_planner_files](./docs/module_maintenance_planner_files.md) | maintenance planner files retrieval | -| [sap_launchpad.maintenance_planner_stack_xml_download](./docs/module_maintenance_planner_stack_xml_download.md) | maintenance planner stack xml download | +**NOTE: Operating system needs to have access to required package repositories either directly or via subscription registration.** -## Execution -### Credentials - SAP User ID +## Installation Instructions -SAP software installation media must be obtained from SAP directly, and requires valid license agreements with SAP in order to access these files. +### Installation +Install this collection with Ansible Galaxy command: +```console +ansible-galaxy collection install community.sap_launchpad +``` -An SAP Company Number (SCN) contains one or more Installation Number/s, providing licences for specified SAP Software. When an SAP User ID is created within the SAP Customer Number (SCN), the administrator must provide SAP Download authorizations for the SAP User ID. +Optionally you can include collection in requirements.yml file and include it together with other collections using: `ansible-galaxy collection install -r requirements.yml` +Requirements file need to be maintained in following format: +```yaml +collections: + - name: community.sap_launchpad +``` -When an SAP User ID (e.g. S-User) is enabled with and part of an SAP Universal ID, then the `sap_launchpad` Ansible Collection **must** use: -- the SAP User ID -- the password for login with the SAP Universal ID +### Upgrade +Installed Ansible Collection will not be upgraded automatically when Ansible package is upgraded. -In addition, if a SAP Universal ID is used then the recommendation is to check and reset the SAP User ID ‘Account Password’ in the [SAP Universal ID Account Manager](https://account.sap.com/manage/accounts), which will help to avoid any potential conflicts. +To upgrade the collection to the latest available version, run the following command: +```console +ansible-galaxy collection install community.sap_launchpad --upgrade +``` -For further information regarding connection errors, please see the FAQ section [Errors with prefix 'SAP SSO authentication failed - '](./docs/FAQ.md#errors-with-prefix-sap-sso-authentication-failed---). +You can also install a specific version of the collection, when you encounter issues with latest version. Please report these issues in affected Role repository if that happens. +Example of downgrading collection to version 1.0.0: +``` +ansible-galaxy collection install community.sap_launchpad:==1.0.0 +``` -### Execution examples +See [Installing collections](https://docs.ansible.com/ansible/latest/collections_guide/collections_installing.html) for more details on installation methods. -There are various methods to execute the Ansible Collection, dependant on the use case. For more information, see [Execution examples with code samples](./docs/EXEC_EXAMPLES.md) and the summary below: -| Execution Scenario | Use Case | Target | -| --- | --- | --- | -| Ansible Playbook
-> source Ansible Collection
-> execute Ansible Task
--> run Ansible Module
---> run Python/Bash Functions | Simple executions with a few activities | Localhost or Remote | -| Ansible Playbook
-> source Ansible Collection
-> execute Ansible Task
--> run Ansible Role
---> run Ansible Module
----> run Python/Bash Functions
--> run Ansible Role
---> ... | Complex executions with various interlinked activities;
run in parallel or sequentially | Localhost or Remote | -| Python/Bash Functions | Simple testing or non-Ansible use cases | Localhost | +## Contents ---- +### Ansible Modules +| Name | Summary | +| :-- | :-- | +| [sap_launchpad.software_center_download](./docs/module_software_center_download.md) | Search and download SAP Software file | +| [sap_launchpad.maintenance_planner_files](./docs/module_maintenance_planner_files.md) | Get list of files from Maintenance Planner | +| [sap_launchpad.maintenance_planner_stack_xml_download](./docs/module_maintenance_planner_stack_xml_download.md) | Get stack file from Maintenance Planner | -## Requirements, Dependencies and Testing +### Ansible Roles +| Name | Summary | +| :-- | :-- | +| [sap_software_download](./roles/sap_software_download/README.md) | Prepare environment and download SAP Software files or Maintenance Plan transaction files | -### Operating System requirements -Designed for Linux operating systems, e.g. RHEL. +## Testing +This Ansible Collection was tested across different Operating Systems and SAP products. -This role has not been tested and amended for SAP NetWeaver Application Server instantiations on IBM AIX or Windows Server. +| Type | Version | +| :--- | :--- | +| Operating system | SUSE Linux Enterprise Server 15 SP5+, 16
Red Hat Enterprise Linux 8.x, 9.x, 10.x | +| Python | 3.11, 3.12 | +| Ansible | 9, 10, 11 | +| Ansible-core | 2.16, 2.17, 2.18 | -Assumptions for executing this role include: -- Registered OS License and OS Package repositories are available (from the relevant content delivery network of the OS vendor) -- Simultaneous Ansible Playbook executions will require amendment of Ansible Variable name `softwarecenter_search_list` shown in execution samples (containing the list of installation media to download). This avoids accidental global variable clashes from occuring in Ansible Playbooks executed from the same controller host with an inline Ansible Inventory against 'all' target hosts. -### Python requirements +## Contributing +You can find more information about ways you can contribute at [sap-linuxlab website](https://sap-linuxlab.github.io/initiative_contributions/). -Execution/Controller/Management host: -- Python 3 -Target host: -- Python 3, with Python Modules `beautifulsoup4 lxml requests` (see [Execution examples with code samples](./docs/EXEC_EXAMPLES.md)) +## Support +You can report any issues using [Issues](https://github.com/sap-linuxlab/community.sap_launchpad/issues) section. -### Testing on execution/controller host -**Tests with Ansible Core release versions:** -- Ansible Core 2.11.5 community edition +## Release Notes and Roadmap +You can find the release notes of this collection in [Changelog file](./CHANGELOG.rst) -**Tests with Python release versions:** -- Python 3.9.7 (i.e. CPython distribution) -**Tests with Operating System release versions:** -- RHEL 8.4 -- macOS 11.6 (Big Sur), with Homebrew used for Python 3.x via PyEnv +## Further Information -### Testing on target/remote host +### Credentials - SAP S-User -**Tests with Operating System release versions:** -- RHEL 8.2 for SAP +SAP software files must be obtained from SAP directly, and requires valid license agreements with SAP in order to access these files. -**Tests with Python release versions:** -- Python 3.6.x (i.e. CPython distribution), default for RHEL 8.x and SLES 15.x -- Python 3.8.x (i.e. CPython distribution) +An SAP Company Number (SCN) contains one or more Installation Number/s, providing licenses for specified SAP Software. When an SAP User ID is created within the SAP Customer Number (SCN), the administrator must provide SAP Download authorizations for the SAP User ID. -## License +When an SAP User ID (e.g. S-User) is enabled with and part of an SAP Universal ID, then the `sap_launchpad` Ansible Collection **must** use: +- the SAP User ID +- the password for login with the SAP Universal ID -- [Apache 2.0](./LICENSE) +In addition, if a SAP Universal ID is used then the recommendation is to check and reset the SAP User ID ‘Account Password’ in the [SAP Universal ID Account Manager](https://account.sap.com/manage/accounts), which will help to avoid any potential conflicts. -## Contributors +For further information regarding connection errors, please see the FAQ section [Errors with prefix 'SAP SSO authentication failed - '](./docs/FAQ.md#errors-with-prefix-sap-sso-authentication-failed---). + +**Multi Factor Authentication is not supported.** -Contributors to the Ansible Roles within this Ansible Collection, are shown within [/docs/contributors](./docs/CONTRIBUTORS.md). +### 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](./LICENSE) diff --git a/docs/CONTRIBUTORS.md b/docs/CONTRIBUTORS.md index 3905cb4..833ab8c 100644 --- a/docs/CONTRIBUTORS.md +++ b/docs/CONTRIBUTORS.md @@ -8,3 +8,6 @@ - **Sean Freeman** - Origin developer of Python API constructs, and project owner - **SVA GmbH - System Vertrieb Alexander GmbH** - **Rainer Leber** - User acceptance testing +- **SUSE** + - SUSE SAP Emerging Technology Solutions + - **Marcel Mamula** - Developer of Ansible Collection diff --git a/docs/EXEC_EXAMPLES.md b/docs/DEVELOPER_NOTES.md similarity index 52% rename from docs/EXEC_EXAMPLES.md rename to docs/DEVELOPER_NOTES.md index 2288d4f..2949687 100644 --- a/docs/EXEC_EXAMPLES.md +++ b/docs/DEVELOPER_NOTES.md @@ -1,61 +1,79 @@ -# Execution examples +# Developer notes for community.sap_launchpad Ansible Collection -## Execution example with Ansible Playbook calling Ansible Module +This document contains details for maintaining Ansible Collection. -**Ansible Playbook YAML, execute Ansible Module** +## Dependencies for all modules +Modules require the following Python modules to be installed on the target node (the machine where SAP software will be downloaded): + +- wheel +- urllib3 +- requests +- beautifulsoup4 +- lxml + +### Installation of dependencies using role `sap_software_download` +Ansible Role `sap_software_download` installs all required dependencies as part of `02_prepare_python_environment.yml` task file. + +### Installation of dependencies with Python Virtual Environment (venv) +It is recommended to install dependencies in venv that can be removed after execution is completed. ```yaml ---- -- hosts: all - - collections: - - community.sap_launchpad - - pre_tasks: - - name: Install Python package manager pip3 to system Python - yum: - name: python3-pip - state: present - - name: Install Python dependencies for Ansible Modules to system Python - pip: +- name: Example play to install prerequisites with Python Virtual Environment + hosts: all + tasks: + - name: Create temporary directory for Python Virtual Environment + ansible.builtin.tempfile: + state: directory + suffix: __sap_software_download_venv + register: __sap_software_download_venv + + - name: Install Python and Python package manager pip + ansible.builtin.package: + name: + - python311 + - python311-pip + state: present + + - name: Install Python modules to Python Virtual Environment + ansible.builtin.pip: name: + - wheel - urllib3 - requests - beautifulsoup4 - lxml + virtualenv: "{{ __sap_software_download_venv.path }}" + virtualenv_command: "python3.11 -m venv" -# Prompt for Ansible Variables - vars_prompt: - - name: suser_id - prompt: Please enter S-User - private: no - - name: suser_password - prompt: Please enter Password - private: yes - -# Define Ansible Variables - vars: - ansible_python_interpreter: python3 - softwarecenter_search_list: - - 'SAPCAR_1324-80000936.EXE' - - 'HCMT_057_0-80003261.SAR' - -# Use task block to call Ansible Module - tasks: - - name: Execute Ansible Module to download SAP software - community.sap_launchpad.software_center_download: - suser_id: "{{ suser_id }}" - suser_password: "{{ suser_password }}" - softwarecenter_search_query: "{{ item }}" - dest: "/tmp/" - loop: "{{ softwarecenter_search_list }}" - loop_control: - label: "{{ item }} : {{ download_task.msg }}" - register: download_task - retries: 1 - until: download_task is not failed + - name: Remove temporary Python Virtual Environment + ansible.builtin.file: + path: "{{ __sap_software_download_venv.path }}" + state: absent ``` -**Execution of Ansible Playbook, with in-line Ansible Inventory set as localhost** +### Installation of dependencies with Python system default +```yaml +- name: Example play to install prerequisites with Python system default + hosts: all + tasks: + - name: Install Python and Python package manager pip + ansible.builtin.package: + name: + - python31 + - python311-pip + state: present + + - name: Install Python modules to Python system default + ansible.builtin.pip: + name: + - wheel + - urllib3 + - requests + - beautifulsoup4 + - lxml +``` + +## Additional execution methods +### Execution of Ansible Playbook, with in-line Ansible Inventory set as localhost ```shell # Install from local source directory for Ansible 2.11+ @@ -68,7 +86,7 @@ ansible-galaxy collection install community.sap_launchpad ansible-playbook --timeout 60 ./community.sap_launchpad/playbooks/sample-download-install-media.yml --inventory "localhost," --connection=local ``` -**Execution of Ansible Playbook, with in-line Ansible Inventory of target/remote hosts** +### Execution of Ansible Playbook, with in-line Ansible Inventory of target/remote hosts ```shell # Install from local source directory for Ansible 2.11+ @@ -93,9 +111,8 @@ ansible-playbook --timeout 60 ./sample-playbook.yml \ --ssh-extra-args="-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o ProxyCommand='ssh -W %h:%p $bastion_user@$bastion_host -p $bastion_port -i $bastion_private_key_file -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null'" ``` -## Execution example with Python environment - -**Setup local Python environment** +## Execution of Python Modules directly +### Setup local Python environment ```shell # Change directory to Python scripts source cd ./plugins @@ -112,7 +129,7 @@ pip3 install beautifulsoup4 lxml requests python3 ``` -**Execute Python Functions** +### Execute Python Functions ```python >>> from module_utils.sap_id_sso import sap_sso_login >>> from module_utils.sap_launchpad_software_center_download_runner import * diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md deleted file mode 100644 index 20caca7..0000000 --- a/docs/DEVELOPMENT.md +++ /dev/null @@ -1,78 +0,0 @@ - -# Development of community.sap_launchpad Ansible Collection - -This Ansible Collection is developed with several design principles and code practices. - -## Code structure - -This Ansible Collection is heavily focused on Ansible Modules to perform required SAP Support API calls. The directory tree structure is shown below: -```code -collection/ -├── docs/ -├── meta/ -├── plugins/ -│ ├── modules/ -│ │ ├── users.py -│ │ ├── software_center_download.py -│ │ ├── software_center_catalog.py -│ │ ├── maintenance_planner_files.py -│ │ ├── maintenance_planner_stack_xml_download.py -│ │ ├── licenses.py -│ │ └── incidents.py -│ └── module_utils/ -│ ├── sap_id_sso.py -│ ├── sap_launchpad_software_center_download_runner.py -│ ├── sap_launchpad_software_center_catalog_runner.py -│ └── sap_launchpad_maintenance_planner_runner.py -├── roles/ -├── playbooks/ -│ ├── sample-download-install-media.yml -│ └── sample-maintenance-planner-download.yml -├── tests/ -├── galaxy.yml -└── README.md -``` - -## Execution logic - -This Ansible Collection is designed to be heavily re-usable for various SAP Support scenarios (both server-side and client-side), and avoid encapsulation of commands within Ansible's syntax; this ensures the scripts (and the sequence of commands) could be re-used manually or re-used by another automation framework. - -It is important to understand the execution flow by an Ansible Playbook to either an Ansible Role (with or without embedded Playbooks), an Ansible Task, or an Ansible Module (and contained Script files). Alternatively it is possible to call the script files manually. - - -See examples below: - -### Ansible Playbook to call many Ansible Roles (and the contained interlinked Ansible Tasks) -```code -# Produce outcome scenario, using many interlinked tasks -- Run: Ansible Playbook - - Run: Ansible Role - - Ansible Task - - Ansible Playbook 1..n - - Ansible Task - - execute custom Ansible Module - - execute specified Python Module Functions - - call APIs or CLIs/binaries - - Ansible Task - - Ansible Playbook 1..n - - Ansible Task - - subsequent OS commands using output from APIs or CLIs/binaries -``` - -### Ansible Playbook to call single set of Ansible Tasks -```code -# Produce outcome scenario, with single set of tasks -- Run: Ansible Playbook - - Ansible Task - - execute custom Ansible Module - - execute specified Python Module Functions - - call APIs or CLIs/binaries -``` - -### Python Shell to call single Python Function -```code -# Produce outcome scenario manually with singular code execution -- Run: Python Shell - - Import Python Module file for APIs or CLIs/binaries - - Execute specificed Python Functions -``` diff --git a/docs/module_maintenance_planner_files.md b/docs/module_maintenance_planner_files.md index 285fdb5..b1340af 100644 --- a/docs/module_maintenance_planner_files.md +++ b/docs/module_maintenance_planner_files.md @@ -1,2 +1,140 @@ # maintenance_planner_files Ansible Module +## Description +The Ansible Module `maintenance_planner_files` is used to obtain list of SAP Software files belonging to Maintenance Plan transaction. + +## Dependencies +This module requires the following Python modules to be installed on the target node (the machine where SAP software will be downloaded): + +- wheel +- urllib3 +- requests +- beautifulsoup4 +- lxml + +Installation instructions are available at [Installation of prerequisites](#installation-of-prerequisites) + +## Execution + +### Example +Obtain list of SAP Software files +```yaml +- name: Obtain list of SAP Software files + community.sap_launchpad.maintenance_planner_files: + suser_id: "Enter SAP S-User ID" + suser_password: "Enter SAP S-User Password" + transaction_name: "Transaction Name or Display ID from Maintenance Planner" + register: __module_results +``` + +Obtain list of SAP Software files using Python Virtual Environment `/tmp/python_venv` +```yaml +- name: Obtain list of SAP Software files using Python Virtual Environment + community.sap_launchpad.maintenance_planner_files: + suser_id: "Enter SAP S-User ID" + suser_password: "Enter SAP S-User Password" + transaction_name: "Transaction Name or Display ID from Maintenance Planner" + register: __module_results + environment: + PATH: "/tmp/python_venv:{{ ansible_env.PATH }}" + PYTHONPATH: "/tmp/python_venv/lib/python3.11/site-packages" + VIRTUAL_ENV: "/tmp/python_venv" + vars: + ansible_python_interpreter: "/tmp/python_venv/bin/python3.11 }}" +``` + +### Output format +#### msg +- _Type:_ `string`
+ +The status of execution. + +#### download_basket +- _Type:_ `list` with elements of type `dictionary`
+ +A Json list of software download links and filenames.
+```yml +- DirectLink: https://softwaredownloads.sap.com/file/0020000001739942021 + Filename: IMDB_SERVER20_060_0-80002031.SAR +- DirectLink: https://softwaredownloads.sap.com/file/0010000001440232021 + Filename: KD75379.SAR +``` + +## Further Information +### Installation of prerequisites +**All preparation steps are included in role `sap_launchpad.sap_software_download`.**
+ +Prerequisite preparation using Python 3.11 Virtual Environment `/tmp/python_venv` (Recommended) +```yaml +--- +- name: Example play to install prerequisites for sap_launchpad + hosts: all + tasks: + - name: Install Python and Python package manager pip + ansible.builtin.package: + name: + - python311 + - python311-pip + state: present + + - name: Pre-Steps - Install Python modules to Python venv + ansible.builtin.pip: + name: + - wheel + - urllib3 + - requests + - beautifulsoup4 + - lxml + virtualenv: "/tmp/python_venv" + virtualenv_command: "python3.11 -m venv" +``` + +Prerequisite preparation using Python 3.11 system default
+```yaml +--- +- name: Example play to install prerequisites for sap_launchpad + hosts: all + tasks: + - name: Install Python and Python package manager pip + ansible.builtin.package: + name: + - python311 + - python311-pip + state: present + + - name: Install Python module packages + ansible.builtin.package: + name: + - python311-wheel + - python311-urllib3 + - python311-requests + - python311-beautifulsoup4 + - python311-lxml + state: present +``` +**NOTE:** Python modules are installed as packages to avoid `externally-managed-environment` error. + +## License +Apache 2.0 + +## Maintainers +Maintainers are shown within [/docs/contributors](./CONTRIBUTORS.md). + +## Module Variables +### suser_id +- _Required:_ `true`
+- _Type:_ `string`
+ +The SAP S-User ID with download authorization for SAP software. + +### suser_password +- _Required:_ `true`
+- _Type:_ `string`
+ +The password for the SAP S-User specified in `suser_id`. + +### transaction_name +- _Required:_ `true`
+- _Type:_ `string`
+ +The name or display ID of a transaction from the SAP Maintenance Planner. diff --git a/docs/module_maintenance_planner_stack_xml_download.md b/docs/module_maintenance_planner_stack_xml_download.md index 066a120..c920652 100644 --- a/docs/module_maintenance_planner_stack_xml_download.md +++ b/docs/module_maintenance_planner_stack_xml_download.md @@ -1,2 +1,137 @@ # maintenance_planner_stack_xml_download Ansible Module +## Description +The Ansible Module `maintenance_planner_stack_xml_download` is used to obtain Stack file belonging to Maintenance Plan transaction. + +## Dependencies +This module requires the following Python modules to be installed on the target node (the machine where SAP software will be downloaded): + +- wheel +- urllib3 +- requests +- beautifulsoup4 +- lxml + +Installation instructions are available at [Installation of prerequisites](#installation-of-prerequisites) + +## Execution + +### Example +Obtain Stack file +```yaml +- name: Obtain Stack file + community.sap_launchpad.maintenance_planner_stack_xml_download: + suser_id: "Enter SAP S-User ID" + suser_password: "Enter SAP S-User Password" + transaction_name: "Transaction Name or Display ID from Maintenance Planner" + dest: "/software" + register: __module_results +``` + +Obtain Stack file using Python Virtual Environment `/tmp/venv` +```yaml +- name: Obtain Stack file using Python Virtual Environment + community.sap_launchpad.maintenance_planner_stack_xml_download: + suser_id: "Enter SAP S-User ID" + suser_password: "Enter SAP S-User Password" + transaction_name: "Transaction Name or Display ID from Maintenance Planner" + dest: "/software" + register: __module_results + environment: + PATH: "/tmp/venv:{{ ansible_env.PATH }}" + PYTHONPATH: "/tmp/venv/lib/python3.11/site-packages" + VIRTUAL_ENV: "/tmp/venv" + vars: + ansible_python_interpreter: "/tmp/venv/bin/python3.11 }}" +``` + +### Output format +#### msg +- _Type:_ `string`
+ +The status of execution. + +## Further Information +### Installation of prerequisites +**All preparation steps are included in role `sap_launchpad.sap_software_download`.**
+ +Prerequisite preparation using Python 3.11 Virtual Environment `/tmp/python_venv` (Recommended) +```yaml +--- +- name: Example play to install prerequisites for sap_launchpad + hosts: all + tasks: + - name: Install Python and Python package manager pip + ansible.builtin.package: + name: + - python311 + - python311-pip + state: present + + - name: Pre-Steps - Install Python modules to Python venv + ansible.builtin.pip: + name: + - wheel + - urllib3 + - requests + - beautifulsoup4 + - lxml + virtualenv: "/tmp/python_venv" + virtualenv_command: "python3.11 -m venv" +``` + +Prerequisite preparation using Python 3.11 system default
+```yaml +--- +- name: Example play to install prerequisites for sap_launchpad + hosts: all + tasks: + - name: Install Python and Python package manager pip + ansible.builtin.package: + name: + - python311 + - python311-pip + state: present + + - name: Install Python module packages + ansible.builtin.package: + name: + - python311-wheel + - python311-urllib3 + - python311-requests + - python311-beautifulsoup4 + - python311-lxml + state: present +``` +**NOTE:** Python modules are installed as packages to avoid `externally-managed-environment` error. + +## License +Apache 2.0 + +## Maintainers +Maintainers are shown within [/docs/contributors](./CONTRIBUTORS.md). + +## Module Variables +### suser_id +- _Required:_ `true`
+- _Type:_ `string`
+ +The SAP S-User ID with download authorization for SAP software. + +### suser_password +- _Required:_ `true`
+- _Type:_ `string`
+ +The password for the SAP S-User specified in `suser_id`. + +### transaction_name +- _Required:_ `true`
+- _Type:_ `string`
+ +The name or display ID of a transaction from the SAP Maintenance Planner. + +### dest +- _Required:_ `true`
+- _Type:_ `string`
+ +The directory where downloaded SAP software files will be stored. diff --git a/docs/module_software_center_download.md b/docs/module_software_center_download.md index 8b7c939..84254a1 100644 --- a/docs/module_software_center_download.md +++ b/docs/module_software_center_download.md @@ -1,2 +1,204 @@ # software_center_download Ansible Module +## Description +The Ansible Module `software_center_download` is used to download SAP Software file from SAP. + +## Dependencies +This module requires the following Python modules to be installed on the target node (the machine where SAP software will be downloaded): + +- wheel +- urllib3 +- requests +- beautifulsoup4 +- lxml + +Installation instructions are available at [Installation of prerequisites](#installation-of-prerequisites) + +## Execution + +### Example +Download SAP Software file +```yaml +- name: Download SAP Software file + community.sap_launchpad.software_center_download: + suser_id: "Enter SAP S-User ID" + suser_password: "Enter SAP S-User Password" + search_query: "Enter SAP Software file name" + dest: "Enter download path (e.g. /software)" +``` + +Download SAP Software file, but search for alternatives if not found +```yaml +- name: Download SAP Software file with alternative + community.sap_launchpad.software_center_download: + suser_id: "Enter SAP S-User ID" + suser_password: "Enter SAP S-User Password" + search_query: "Enter SAP Software file name" + dest: "Enter download path (e.g. /software)" + search_alternatives: true + deduplicate: "last" +``` + +Download list of SAP Software files, but search for alternatives if not found +```yaml +- name: Download list of SAP Software files + community.sap_launchpad.software_center_download: + suser_id: "Enter SAP S-User ID" + suser_password: "Enter SAP S-User Password" + search_query: "{{ item }}" + dest: "Enter download path (e.g. /software)" + search_alternatives: true + deduplicate: "last" + loop: + - "Enter SAP Software file name 1" + - "Enter SAP Software file name 2" + loop_control: + label: "{{ item }} : {{ __module_results.msg | d('') }}" + register: __module_results + retries: 1 + until: __module_results is not failed +``` + +Download SAP Software file using Python Virtual Environment `/tmp/venv` +```yaml +- name: Download list of SAP Software files + community.sap_launchpad.software_center_download: + suser_id: "Enter SAP S-User ID" + suser_password: "Enter SAP S-User Password" + search_query: "{{ item }}" + dest: "Enter download path (e.g. /software)" + loop: + - "Enter SAP Software file name 1" + - "Enter SAP Software file name 2" + loop_control: + label: "{{ item }} : {{ __module_results.msg | d('') }}" + register: __module_results + retries: 1 + until: __module_results is not failed + environment: + PATH: "/tmp/venv:{{ ansible_env.PATH }}" + PYTHONPATH: "/tmp/venv/lib/python3.11/site-packages" + VIRTUAL_ENV: "/tmp/venv" + vars: + ansible_python_interpreter: "/tmp/venv/bin/python3.11 }}" +``` + +### Output format +#### msg +- _Type:_ `string`
+ +The status of execution. + +## Further Information +### Installation of prerequisites +**All preparation steps are included in role `sap_launchpad.sap_software_download`.**
+ +Prerequisite preparation using Python 3.11 Virtual Environment `/tmp/python_venv` (Recommended) +```yaml +--- +- name: Example play to install prerequisites for sap_launchpad + hosts: all + tasks: + - name: Install Python and Python package manager pip + ansible.builtin.package: + name: + - python311 + - python311-pip + state: present + + - name: Pre-Steps - Install Python modules to Python venv + ansible.builtin.pip: + name: + - wheel + - urllib3 + - requests + - beautifulsoup4 + - lxml + virtualenv: "/tmp/python_venv" + virtualenv_command: "python3.11 -m venv" +``` + +Prerequisite preparation using Python 3.11 system default
+```yaml +--- +- name: Example play to install prerequisites for sap_launchpad + hosts: all + tasks: + - name: Install Python and Python package manager pip + ansible.builtin.package: + name: + - python311 + - python311-pip + state: present + + - name: Install Python module packages + ansible.builtin.package: + name: + - python311-wheel + - python311-urllib3 + - python311-requests + - python311-beautifulsoup4 + - python311-lxml + state: present +``` +**NOTE:** Python modules are installed as packages to avoid `externally-managed-environment` error. + +## License +Apache 2.0 + +## Maintainers +Maintainers are shown within [/docs/contributors](./CONTRIBUTORS.md). + +## Module Variables +### suser_id +- _Required:_ `true`
+- _Type:_ `string`
+ +The SAP S-User ID with download authorization for SAP software. + +### suser_password +- _Required:_ `true`
+- _Type:_ `string`
+ +The password for the SAP S-User specified in `suser_id`. + +### search_query +- _Type:_ `string`
+ +The SAP software file name to download. + +### download_link +- _Type:_ `string`
+ +Direct download link to the SAP software.
+Download links can be obtained from SAP Software Center or using module `module_maintenance_planner_files`. + +### download_filename +- _Type:_ `string`
+ +Download filename of the SAP software.
+Download names can be obtained from SAP Software Center or using module `module_maintenance_planner_files`. + +### dest +- _Required:_ `true`
+- _Type:_ `string`
+ +The directory where downloaded SAP software files will be stored. + +### deduplicate +- _Type:_ `string`
+ +Specifies how to handle duplicate file results.
+If multiple files with the same name are found, this setting determines which one to download.
+- `first`: Download the first file found
+- `last`: Download the last file found.
+ +### search_alternatives +- _Type:_ `boolean`
+ +Enables searching for alternative files if the requested file is not found.
+ +### dry_run +- _Type:_ `boolean + +Check availability of SAP Software without downloading.
diff --git a/galaxy.yml b/galaxy.yml index 90db301..02fd643 100644 --- a/galaxy.yml +++ b/galaxy.yml @@ -8,26 +8,26 @@ namespace: community name: sap_launchpad # The version of the collection. Must be compatible with semantic versioning -version: 1.1.0 +version: 1.2.0 # The path to the Markdown (.md) readme file. This path is relative to the root of the collection readme: README.md # A list of the collection's content authors. Can be just the name or in the format 'Full Name (url) authors: - - IBM Lab for SAP Solutions - - IBM Cloud for SAP - - IBM Consulting for SAP - - MatthiasWinzeler + - Sean Freeman + - Sheng Li Zhu + - Matthias Winzeler + - Marcel Mamula ### OPTIONAL but strongly recommended # A short summary description of the collection -description: Collection of Ansible Modules for SAP Launchpad APIs +description: Collection for automation of SAP Launchpad API, such as SAP Software downloads # Either a single license or a list of licenses for content inside of a collection. Ansible Galaxy currently only # accepts L(SPDX,https://spdx.org/licenses/) licenses. This key is mutually exclusive with 'license_file' license: -- Apache-2.0 + - Apache-2.0 # The path to the license file for the collection. This path is relative to the root of the collection. This key is # mutually exclusive with 'license' @@ -35,7 +35,11 @@ license_file: '' # A list of tags you want to associate with the collection for indexing/searching. A tag name has the same character # requirements as 'namespace' and 'name' -tags: [] +tags: + - sap + - download + - application + - tools # Collections that this collection requires to be installed for it to be usable. The key of the dict is the # collection label 'namespace.name'. The value is a version range @@ -59,4 +63,15 @@ issues: https://github.com/sap-linuxlab/community.sap_launchpad/issues # artifact. A pattern is matched from the relative path of the file or directory of the collection directory. This # uses 'fnmatch' to match the files or directories. Some directories and files like 'galaxy.yml', '*.pyc', '*.retry', # and '.git' are always filtered -build_ignore: ['tests', 'internal-*'] +build_ignore: + - 'tests' + - 'roles/*/tests' + - '.git*' + - 'roles/.git*' + - 'roles/*/.git*' + - '.ansible-lint' + - 'roles/*/.ansible-lint' + - '.yamllint*' + - 'roles/*/.yamllint*' + - '.pylintrc*' + - 'bindep*' diff --git a/requirements.yml b/requirements.yml index ed97d53..1d00cb5 100644 --- a/requirements.yml +++ b/requirements.yml @@ -1 +1,4 @@ --- +# There are no requirements defined for collection. +collections: [] +roles: []