| 1 |
# VMWare Rest |
| 2 |
|
| 3 |
# Development Guide |
| 4 |
|
| 5 |
See [Ansible Using collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html) for more details. |
| 6 |
|
| 7 |
## How To: Generate Collection Modules |
| 8 |
|
| 9 |
1. Get the OpenAPI spec from VCenter |
| 10 |
a. Clone https://github.com/vmware/vmware-openapi-generator |
| 11 |
b. Run `python vmsgen.py -vc 'your_vcenter_ip_or_hostname' -o gen_out --insecure --oas 2 --deprecate-slash-rest --fetch-authentication-metadata` from within the checked out repo |
| 12 |
c. validate the directory `gen_out` has the spec files. Note `--oas 2` generates version 2 spec files. Version 3 seems bugged https://github.com/vmware/vmware-openapi-generator/issues/73 |
| 13 |
|
| 14 |
2. Add/Replace the spec in this repo |
| 15 |
a. in `config/api_specifications` there are directories corresponding to VCenter versions. If the version you are generating a spec for does not exist, create it. |
| 16 |
b. Copy the files you generated in step 1 (`gen_out/*.json`) to the directory matching your VCenter version in `config/api_specifications` |
| 17 |
|
| 18 |
3. Configure the content builder tool manifest |
| 19 |
a. Update the `config/MANIFEST.yml`. The `plugins.api_object_path` property should be whatever version of VCenter you generated the specs for |
| 20 |
b. **Note**: the property `plugins.module_version` should always be `1.0.0` |
| 21 |
c. For more information on the command and input arguments, please refer to the tool's [README](https://github.com/ansible-community/ansible.content_builder#resource-module-scaffolding-generated-using-openapi-based-json). |
| 22 |
|
| 23 |
4. Install Extra Pip Requirements |
| 24 |
a. Run from the root of the repo: `pip install -r config/requirements.txt` |
| 25 |
b. These requirements are taken from the content builder tool repo |
| 26 |
|
| 27 |
4. Run the content builder tool |
| 28 |
a. Install the tool, if needed: `ansible-galaxy collection install git+https://github.com/ansible-community/ansible.content_builder.git` |
| 29 |
b. Run the tool from the root of the repo: `ansible-playbook config/generate.yml` |
| 30 |
|
| 31 |
5. Copy the new content to the repo |
| 32 |
a. Once the playbook finishes successfully, you can view the new content in `config/output` |
| 33 |
b. Copy the contents of `config/output` to the proper places in this repo |
| 34 |
c. The main things to copy will be `plugins`, `tests`, and `runtime`. The other generated files probably dont need to replace the existing files |
| 35 |
|
| 36 |
6. Update check mode |
| 37 |
a. The non-info modules in this collection do not support check mode. Unfortunately the generation method is not flexible enough to handle this (or updating it takes too much effort ATM). |
| 38 |
b. The easiest way to do this is in a code editor like VSCode. Do a find and replace for `supports_check_mode=True` and change it to False, and exclude `*_info.py` |
| 39 |
|
| 40 |
#### (Optional) Update the `RETURN Block` of the vmware modules using the test-suite |
| 41 |
|
| 42 |
The `generate.yml` playbook will copy the old blocks to the new modules. You can refresh the blocks if you introduce a new API version. |
| 43 |
|
| 44 |
**Note** The steps below will run a playbook that stops all of the VMs in a vcenter. It will also potentially wipe out the examples and return values in each module, so please review changes carefully. |
| 45 |
|
| 46 |
Create `/tmp/inventory-vmware_rest` like: |
| 47 |
``` |
| 48 |
[vmware_rest] |
| 49 |
localhost ansible_connection=local |
| 50 |
|
| 51 |
[vmware_rest:vars] |
| 52 |
vcenter_hostname=your_hostname |
| 53 |
vcenter_username=your_admin |
| 54 |
vcenter_password=your_pass |
| 55 |
``` |
| 56 |
|
| 57 |
Run: |
| 58 |
``` |
| 59 |
mkdir -p ~/.ansible/collections/ansible_collections/goneri/utils |
| 60 |
git clone https://github.com/goneri/ansible-collection-goneri.utils.git ~/.ansible/collections/ansible_collections/goneri/utils |
| 61 |
cd ~/.ansible/collections/ansible_collections/vmware/vmware_rest/tests/integration/targets/vcenter_vm_scenario1 |
| 62 |
./refresh_RETURN_block.sh |
| 63 |
cd ~/.ansible/collections/ansible_collections/goneri/utils |
| 64 |
./scripts/inject_RETURN.py ~/.ansible/collections/ansible_collections/vmware/vmware_rest/manual/source/vmware_rest_scenarios/task_outputs ~/.ansible/collections/ansible_collections/vmware/vmware_rest --config-file config/inject_RETURN.yaml |
| 65 |
``` |
| 66 |
|
| 67 |
## More Details on Content Builder |
| 68 |
|
| 69 |
To use the content builder tool, you need to provide a YAML file that contains all the information needed to generate a vmware module. You can find the necessary files, such as the [api specification](https://github.com/ansible-collections/vmware.vmware_rest/tree/main/config/api_specifications) and the [modules.yaml](https://github.com/ansible-collections/vmware.vmware_rest/tree/main/config/modules.yaml), in the repository. You can copy these files to your local path and customize them as per your requirements. After that, you must specify the path of these files in the input yaml file against the api_object_path and resource parameter. If you want to generate both examples and modules, set the action parameter to `generate_all`. If you only want to generate examples, use `action: generate_examples`, and for only modules, use `action: generate_modules`. For more information on the command and input arguments, please refer to the tool's [README](https://github.com/ansible-community/ansible.content_builder#resource-module-scaffolding-generated-using-openapi-based-json). |
| 70 |
|
| 71 |
Once the modules are generated in the location mentioned in `collection:path`, you can follow the below steps to refresh the RETURN block in the module documentaion. |