Debian Codegraph @

ansible_collections/vmware/vmware_rest/docs/development.md

raw
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.