|
1 | | -# community.sap_launchpad Ansible Collection  |
| 1 | +# community.sap_launchpad Ansible Collection |
2 | 2 |
|
3 | | -This Ansible Collection executes basic SAP.com Support operations tasks. |
| 3 | + |
4 | 4 |
|
5 | | -## Functionality |
| 5 | +## Description |
6 | 6 |
|
7 | | -This Ansible Collection executes basic SAP.com Support operations tasks, including: |
| 7 | +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. |
8 | 8 |
|
9 | | -- **Software Center Catalog** |
10 | | - - Search and Download of SAP software center catalog files |
11 | | - - Search and Extraction of SAP software center catalog information |
12 | | -- **Maintenance Planner** |
13 | | - - Lookup and download files from an existing 'New Implementation' MP Transaction and Stack, using SAP software center's download basket |
| 9 | +Included role and modules cover range of options: |
| 10 | +- Preparation of environment before download. |
| 11 | +- Download of specific SAP Software files. |
| 12 | +- Download of alternative SAP Software files if specific was not available. |
| 13 | +- Download of SAP Software files from existing Maintenance Plan transaction. |
| 14 | +- Download of Stack file from existing Maintenance Plan transaction. |
| 15 | +- Register Systems and License Keys |
| 16 | +- Query registered Systems |
14 | 17 |
|
15 | | -## Contents |
16 | 18 |
|
17 | | -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: |
18 | | -- **Ansible Roles** (runs multiple Ansible Modules) |
19 | | -- **Ansible Modules** (and adjoining Python Functions) |
| 19 | +## Requirements |
20 | 20 |
|
21 | | -For further information regarding the development, code structure and execution workflow please read the [Development documentation](./docs/DEVELOPMENT.md). |
| 21 | +### Control Nodes |
| 22 | +| Type | Version | |
| 23 | +| :--- | :--- | |
| 24 | +| Operating system | Any operating system with required Python and Ansible versions | |
| 25 | +| Python | 3.11 or higher | |
| 26 | +| Ansible | 9.9 or higher | |
| 27 | +| Ansible-core | 2.16 or higher | |
22 | 28 |
|
23 | | -Within this Ansible Collection, there are various Ansible Modules. |
24 | 29 |
|
25 | | -#### Ansible Modules |
| 30 | +### Managed Nodes |
| 31 | +| Type | Version | |
| 32 | +| :--- | :--- | |
| 33 | +| Operating system | SUSE Linux Enterprise Server 15 SP5+, 16 <br> Red Hat Enterprise Linux 8.x, 9.x, 10.x | |
| 34 | +| Python | 3.11 or higher (SUSE) <br> 3.9 or higher (Red Hat) | |
26 | 35 |
|
27 | | -| Name                    | Summary | |
28 | | -| :-- | :-- | |
29 | | -| [sap_launchpad.software_center_download](./docs/module_software_center_download.md) | search for files and download | |
30 | | -| [sap_launchpad.maintenance_planner_files](./docs/module_maintenance_planner_files.md) | maintenance planner files retrieval | |
31 | | -| [sap_launchpad.maintenance_planner_stack_xml_download](./docs/module_maintenance_planner_stack_xml_download.md) | maintenance planner stack xml download | |
| 36 | +**NOTE: Operating system needs to have access to required package repositories either directly or via subscription registration.** |
32 | 37 |
|
33 | | -## Execution |
34 | 38 |
|
35 | | -### Credentials - SAP User ID |
| 39 | +## Installation Instructions |
36 | 40 |
|
37 | | -SAP software installation media must be obtained from SAP directly, and requires valid license agreements with SAP in order to access these files. |
| 41 | +### Installation |
| 42 | +Install this collection with Ansible Galaxy command: |
| 43 | +```console |
| 44 | +ansible-galaxy collection install community.sap_launchpad |
| 45 | +``` |
38 | 46 |
|
39 | | -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. |
| 47 | +Optionally you can include collection in requirements.yml file and include it together with other collections using: `ansible-galaxy collection install -r requirements.yml` |
| 48 | +Requirements file need to be maintained in following format: |
| 49 | +```yaml |
| 50 | +collections: |
| 51 | + - name: community.sap_launchpad |
| 52 | +``` |
40 | 53 |
|
41 | | -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: |
42 | | -- the SAP User ID |
43 | | -- the password for login with the SAP Universal ID |
| 54 | +### Upgrade |
| 55 | +Installed Ansible Collection will not be upgraded automatically when Ansible package is upgraded. |
44 | 56 |
|
45 | | -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. |
| 57 | +To upgrade the collection to the latest available version, run the following command: |
| 58 | +```console |
| 59 | +ansible-galaxy collection install community.sap_launchpad --upgrade |
| 60 | +``` |
46 | 61 |
|
47 | | -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---). |
| 62 | +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. |
| 63 | +Example of downgrading collection to version 1.0.0: |
| 64 | +``` |
| 65 | +ansible-galaxy collection install community.sap_launchpad:==1.0.0 |
| 66 | +``` |
48 | 67 |
|
49 | | -### Execution examples |
| 68 | +See [Installing collections](https://docs.ansible.com/ansible/latest/collections_guide/collections_installing.html) for more details on installation methods. |
50 | 69 |
|
51 | | -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: |
52 | 70 |
|
53 | | -| Execution Scenario | Use Case | Target | |
54 | | -| --- | --- | --- | |
55 | | -| Ansible Playbook <br/>-> source Ansible Collection <br/>-> execute Ansible Task <br/>--> run Ansible Module <br/>---> run Python/Bash Functions | Simple executions with a few activities | Localhost or Remote | |
56 | | -| Ansible Playbook <br/>-> source Ansible Collection <br/>-> execute Ansible Task <br/>--> run Ansible Role <br/>---> run Ansible Module <br/>----> run Python/Bash Functions <br/>--> run Ansible Role<br/>---> ... | Complex executions with various interlinked activities;<br/> run in parallel or sequentially | Localhost or Remote | |
57 | | -| Python/Bash Functions | Simple testing or non-Ansible use cases | Localhost | |
| 71 | +## Contents |
58 | 72 |
|
59 | | ---- |
| 73 | +### Ansible Modules |
| 74 | +| Name | Summary | |
| 75 | +| :-- | :-- | |
| 76 | +| [sap_launchpad.software_center_download](./docs/module_software_center_download.md) | Search and download SAP Software file | |
| 77 | +| [sap_launchpad.maintenance_planner_files](./docs/module_maintenance_planner_files.md) | Get list of files from Maintenance Planner | |
| 78 | +| [sap_launchpad.maintenance_planner_stack_xml_download](./docs/module_maintenance_planner_stack_xml_download.md) | Get stack file from Maintenance Planner | |
60 | 79 |
|
61 | | -## Requirements, Dependencies and Testing |
| 80 | +### Ansible Roles |
| 81 | +| Name | Summary | |
| 82 | +| :-- | :-- | |
| 83 | +| [sap_software_download](./roles/sap_software_download/README.md) | Prepare environment and download SAP Software files or Maintenance Plan transaction files | |
62 | 84 |
|
63 | | -### Operating System requirements |
64 | 85 |
|
65 | | -Designed for Linux operating systems, e.g. RHEL. |
| 86 | +## Testing |
| 87 | +This Ansible Collection was tested across different Operating Systems and SAP products. |
66 | 88 |
|
67 | | -This role has not been tested and amended for SAP NetWeaver Application Server instantiations on IBM AIX or Windows Server. |
| 89 | +| Type | Version | |
| 90 | +| :--- | :--- | |
| 91 | +| Operating system | SUSE Linux Enterprise Server 15 SP5+, 16 <br> Red Hat Enterprise Linux 8.x, 9.x, 10.x | |
| 92 | +| Python | 3.11, 3.12 | |
| 93 | +| Ansible | 9, 10, 11 | |
| 94 | +| Ansible-core | 2.16, 2.17, 2.18 | |
68 | 95 |
|
69 | | -Assumptions for executing this role include: |
70 | | -- Registered OS License and OS Package repositories are available (from the relevant content delivery network of the OS vendor) |
71 | | -- 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. |
72 | 96 |
|
73 | | -### Python requirements |
| 97 | +## Contributing |
| 98 | +You can find more information about ways you can contribute at [sap-linuxlab website](https://sap-linuxlab.github.io/initiative_contributions/). |
74 | 99 |
|
75 | | -Execution/Controller/Management host: |
76 | | -- Python 3 |
77 | 100 |
|
78 | | -Target host: |
79 | | -- Python 3, with Python Modules `beautifulsoup4 lxml requests` (see [Execution examples with code samples](./docs/EXEC_EXAMPLES.md)) |
| 101 | +## Support |
| 102 | +You can report any issues using [Issues](https://github.com/sap-linuxlab/community.sap_launchpad/issues) section. |
80 | 103 |
|
81 | | -### Testing on execution/controller host |
82 | 104 |
|
83 | | -**Tests with Ansible Core release versions:** |
84 | | -- Ansible Core 2.11.5 community edition |
| 105 | +## Release Notes and Roadmap |
| 106 | +You can find the release notes of this collection in [Changelog file](./CHANGELOG.rst) |
85 | 107 |
|
86 | | -**Tests with Python release versions:** |
87 | | -- Python 3.9.7 (i.e. CPython distribution) |
88 | 108 |
|
89 | | -**Tests with Operating System release versions:** |
90 | | -- RHEL 8.4 |
91 | | -- macOS 11.6 (Big Sur), with Homebrew used for Python 3.x via PyEnv |
| 109 | +## Further Information |
92 | 110 |
|
93 | | -### Testing on target/remote host |
| 111 | +### Credentials - SAP S-User |
94 | 112 |
|
95 | | -**Tests with Operating System release versions:** |
96 | | -- RHEL 8.2 for SAP |
| 113 | +SAP software files must be obtained from SAP directly, and requires valid license agreements with SAP in order to access these files. |
97 | 114 |
|
98 | | -**Tests with Python release versions:** |
99 | | -- Python 3.6.x (i.e. CPython distribution), default for RHEL 8.x and SLES 15.x |
100 | | -- Python 3.8.x (i.e. CPython distribution) |
| 115 | +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. |
101 | 116 |
|
102 | | -## License |
| 117 | +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: |
| 118 | +- the SAP User ID |
| 119 | +- the password for login with the SAP Universal ID |
103 | 120 |
|
104 | | -- [Apache 2.0](./LICENSE) |
| 121 | +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. |
105 | 122 |
|
106 | | -## Contributors |
| 123 | +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---). |
| 124 | + |
| 125 | +**Multi Factor Authentication is not supported.** |
107 | 126 |
|
108 | | -Contributors to the Ansible Roles within this Ansible Collection, are shown within [/docs/contributors](./docs/CONTRIBUTORS.md). |
| 127 | +### Variable Precedence Rules |
| 128 | +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. |
| 129 | + |
| 130 | +## License |
| 131 | +[Apache 2.0](./LICENSE) |
0 commit comments