Debian Codegraph @

ansible_collections/vmware/vmware_rest/README.md

raw
1 # Ansible Collection: vmware.vmware_rest
2
3 This repo hosts the `vmware.vmware_rest` Ansible Collection.
4
5 The **vmware.vmware_rest** collection is part of the **Red Hat Ansible Certified Content for VMware** offering that brings Ansible automation to VMware. This collection brings forward the possibility to manage vSphere resources and automate operator tasks.
6
7 This collection is based upon VMware vSphere REST API interface and does not rely on the VMware SDKs [`Pyvmomi`](https://github.com/vmware/pyvmomi) and [`vSphere Automation SDK for Python`](https://github.com/vmware/vsphere-automation-sdk-python).
8
9 System programmers can enable pipelines to setup, tear down and deploy VMs while system administrators can automate time consuming repetitive tasks inevitably freeing up their time. New VMware users can find comfort in Ansible's familiarity and expedite their proficiency in record time.
10
11 ### Known limitations
12
13 #### VM Template and folder structure
14
15 These modules are based on the [vSphere REST API](https://developer.vmware.com/apis/vsphere-automation/latest/). This API doesn't provide any mechanism to list or clone VM templates when they are stored in a VM folder.
16 To circumvent this limitation, you should store your VM templates in a [Content Library](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-254B2CE8-20A8-43F0-90E8-3F6776C2C896.html).
17
18 #### Slower execution times
19
20 This collection is capable of leveraging a feature of the cloud.common collection called the "turbo server". This is a caching mechanism that speeds up repeated API calls, but it does come with some downsides.
21
22 This collection has used turbo mode up until version 4.8.0. With the release of 4.8.0, turbo mode is disabled by default but can be re-enabled using an environment variable. Read more [here](docs/turbo_mode.md).
23
24
25
26 ## Requirements
27
28 The host running the tasks must have the python requirements described in [requirements.txt](https://github.com/ansible-collections/vmware.vmware_rest/blob/main/requirements.txt)
29 Once the collection is installed, you can install them into a python environment using pip: `pip install -r ~/.ansible/collections/ansible_collections/vmware/vmware_rest/requirements.txt`
30
31 ### vSphere compatibility
32
33 The 3.0.0 version of this collection supports vSphere 7.x.
34 The 4.0.0 version of this collection supports vSphere 8.x.
35
36 ### Ansible version compatibility
37
38 This collection has been tested against following Ansible versions: **>=2.15.0**.
39
40
41 ## Installation
42
43 Before using this collection, you need to install it with the Ansible Galaxy command-line tool:
44
45 ```sh
46 ansible-galaxy collection install vmware.vmware_rest
47 ```
48
49 You can also include it in a requirements.yml file and install it with `ansible-galaxy collection install -r requirements.yml`, using the format:
50
51 ```sh
52 collections:
53 - name: vmware.vmware_rest
54 ```
55
56 Note that if you install the collection from Ansible Galaxy, it will not be upgraded automatically when you upgrade the Ansible package.
57 To upgrade the collection to the latest available version, run the following command:
58
59 ```sh
60 ansible-galaxy collection install vmware.vmware_rest --upgrade
61 ```
62
63 You can also install a specific version of the collection, for example, if you need to install a different version. Use the following syntax to install version 1.0.0:
64
65 ```sh
66 ansible-galaxy collection install vmware.vmware_rest:1.0.0
67 ```
68
69
70 ## Use Cases
71
72 * Use Case Name: Modify vCenter Appliance Configuration
73 * Actors:
74 * System Admin
75 * Description:
76 * A systems administrator can modify the configuration of a running vCenter appliance.
77 * Modules:
78 * `vmware.vmware_rest.appliance_access_consolecli` - Sets the enabled state of the console-based controlled CLI (TTY1)
79 * `vmware.vmware_rest.appliance_access_dcui` - Sets the enabled state of Direct Console User Interface (DCUI TTY2)
80 * `vmware.vmware_rest.appliance_access_shell` - Sets the enabled state of BASH, that is, access to BASH from within the controlled CLI
81 * `vmware.vmware_rest.appliance_access_ssh` - Sets the enabled state of the SSH-based controlled CLI
82 * `vmware.vmware_rest.appliance_networking_dns_domains` - Sets DNS search domains
83 * `vmware.vmware_rest.appliance_networking_dns_hostname` - Sets the Fully Qualified Domain Name
84 * `vmware.vmware_rest.appliance_networking_dns_servers` - Sets the DNS server configuration
85 * `vmware.vmware_rest.appliance_networking_firewall_inbound` - Sets the ordered list of firewall rules to allow or deny traffic from one or more incoming IP addresses
86 * `vmware.vmware_rest.appliance_networking_interfaces_ipv4` - Sets the IPv4 network configuration for specific network interface
87 * `vmware.vmware_rest.appliance_networking_interfaces_ipv6` - Sets the IPv6 network configuration for specific interface
88 * `vmware.vmware_rest.appliance_networking_noproxy` - Sets servers for which no proxy configuration should be applied
89 * `vmware.vmware_rest.appliance_networking_proxy` - Configures which proxy server to use for the specified protocol
90 * `vmware.vmware_rest.appliance_ntp` - Sets the NTP servers
91 * `vmware.vmware_rest.appliance_system_globalfips` - Enables/Disables Global FIPS mode for the appliance
92 * `vmware.vmware_rest.appliance_system_time_timezone` - Sets the time zone
93 * `vmware.vmware_rest.appliance_timesync` - Sets the time synchronization mode
94 * `vmware.vmware_rest.appliance_vmon_service` - Lists the details of services managed by vMon
95
96 * Use Case Name: Manage a Content Library
97 * Actors:
98 * System Admin
99 * Description:
100 * The system administrator can create or manage a content library.
101 * Modules:
102 * `vmware.vmware_rest.content_configuration` - Updates the library configuration
103 * `vmware.vmware_rest.content_locallibrary` - Creates a new local library
104 * `vmware.vmware_rest.content_subscribedlibrary` - Creates a new subscribed library
105
106 * Use Case Name: Manage a VMs Settings
107 * Actors:
108 * System Admin
109 * Description:
110 * The system administrator can manage a VMs settings.
111 * Modules:
112 * `vmware.vmware_rest.vcenter_vm_guest_customization` - Applies a customization specification on the virtual machine
113 * `vmware.vmware_rest.vcenter_vm_guest_filesystem_directories` - Creates a directory in the guest operating system
114 * `vmware.vmware_rest.vcenter_vm_guest_power` - Modifies a virtual machine's power state
115 * `vmware.vmware_rest.vcenter_vm_hardware_adapter_sata` - Adds a virtual SATA adapter to the virtual machine
116 * `vmware.vmware_rest.vcenter_vm_hardware_adapter_scsi` - Adds a virtual SCSI adapter to the virtual machine
117 * `vmware.vmware_rest.vcenter_vm_hardware_boot_device` - Sets the virtual devices that will be used to boot the virtual machine
118 * `vmware.vmware_rest.vcenter_vm_hardware_boot` - Updates the boot-related settings of a virtual machine
119 * `vmware.vmware_rest.vcenter_vm_hardware_cdrom` - Adds a virtual CD-ROM device to the virtual machine
120 * `vmware.vmware_rest.vcenter_vm_hardware_cpu` - Updates the CPU-related settings of a virtual machine
121 * `vmware.vmware_rest.vcenter_vm_hardware_disk` - Adds a virtual disk to the virtual machine
122 * `vmware.vmware_rest.vcenter_vm_hardware_ethernet` - Adds a virtual Ethernet adapter to the virtual machine
123 * `vmware.vmware_rest.vcenter_vm_hardware_memory` - Updates the memory-related settings of a virtual machine
124 * `vmware.vmware_rest.vcenter_vm_hardware_parallel` - Adds a virtual parallel port to the virtual machine
125 * `vmware.vmware_rest.vcenter_vm_hardware` - Updates the virtual hardware settings of a virtual machine
126 * `vmware.vmware_rest.vcenter_vm_hardware_serial` - Adds a virtual serial port to the virtual machine
127 * `vmware.vmware_rest.vcenter_vm_power` - Operates a boot, hard shutdown, hard reset or hard suspend on a guest
128 * `vmware.vmware_rest.vcenter_vm_storage_policy` - Updates the storage policy configuration of a virtual machine and/or its associated virtual hard disks
129 * `vmware.vmware_rest.vcenter_vm_tools_installer` - Connects the VMware Tools CD installer as a CD-ROM for the guest operating system
130 * `vmware.vmware_rest.vcenter_vm_tools` - Updates the properties of VMware Tools
131
132 ## Testing
133
134 All releases will meet the following test criteria.
135
136 * 100% success for [Integration](https://github.com/ansible-collections/vmware.vmware_rest/blob/main/tests/integration) tests.
137 * 100% success for [Sanity](https://docs.ansible.com/ansible/latest/dev_guide/testing/sanity/index.html#all-sanity-tests) tests as part of [ansible-test](https://docs.ansible.com/ansible/latest/dev_guide/testing.html#run-sanity-tests).
138 * 100% success for [ansible-lint](https://ansible.readthedocs.io/projects/lint/) allowing only false positives.
139
140
141 ## Contributing
142
143 This community is currently accepting contributions. We encourage you to open [git issues](https://github.com/ansible-collections/vmware.vmware_rest/issues) for bugs, comments or feature requests.
144 Please feel free to submit a PR to resolve the issue. Modules are generated so changes to them most likely will not be applied directly.
145
146 Refer to the [Ansible community guide](https://docs.ansible.com/ansible/devel/community/index.html).
147
148 ### Development
149
150 This collection can be generated using the [content_builder](https://github.com/ansible-community/ansible.content_builder) tool. Please refer to the [vmware module generation](https://github.com/ansible-collections/vmware.vmware_rest/blob/main/development.md).
151
152
153 ## Communication
154
155 * Join the Ansible forum:
156 * [Get Help](https://forum.ansible.com/c/help/6): get help or help others.
157 * [Posts tagged with 'vmware'](https://forum.ansible.com/tag/vmware): subscribe to participate in collection-related conversations.
158 * [Ansible VMware Automation Working Group](https://forum.ansible.com/g/ansible-vmware): by joining the team you will automatically get subscribed to the posts tagged with ['vmware'](https://forum.ansible.com/tag/vmware).
159 * [Social Spaces](https://forum.ansible.com/c/chat/4): gather and interact with fellow enthusiasts.
160 * [News & Announcements](https://forum.ansible.com/c/news/5): track project-wide announcements including social events.
161
162 * The Ansible [Bullhorn newsletter](https://docs.ansible.com/ansible/devel/community/communication.html#the-bullhorn): used to announce releases and important changes.
163
164 For more information about communication, see the [Ansible communication guide](https://docs.ansible.com/ansible/devel/community/communication.html).
165
166
167 ## Support
168
169 As Red Hat Ansible [Certified Content](https://catalog.redhat.com/software/search?target_platforms=Red%20Hat%20Ansible%20Automation%20Platform), this collection is entitled to [support](https://access.redhat.com/support/) through [Ansible Automation Platform](https://www.redhat.com/en/technologies/management/ansible) (AAP).
170
171 If a support case cannot be opened with Red Hat and the collection has been obtained either from [Galaxy](https://galaxy.ansible.com/ui/) or [GitHub](https://github.com/ansible-collections/vmware.vmware_rest), there is community support available at no charge. Community support is limited to the collection; community support does not include any of the Ansible Automation Platform components or [ansible-core](https://github.com/ansible/ansible).
172
173
174 ## Release Notes and Roadmap
175
176 A list of available releases can be found on the github [release page](https://github.com/ansible-collections/vmware.vmware_rest/releases).
177 A changelog may be found attached to the release, or in the [CHANGELOG.rst](https://github.com/ansible-collections/vmware.vmware_rest/blob/main/CHANGELOG.rst)
178
179 Note, some collections release before an ansible-core version reaches End of Life (EOL), thus the version of ansible-core that is supported must be a version that is currently supported.
180 For AAP users, to see the supported ansible-core versions, review the [AAP Life Cycle](https://access.redhat.com/support/policy/updates/ansible-automation-platform).
181 For Galaxy and GitHub users, to see the supported ansible-core versions, review the [ansible-core support matrix](https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix).
182
183
184 ## Related Information
185
186 The `vmware.vmware` collection offers additional functionality. It is also a certified collection.
187 The `community.vmware` collection offers additional community supported functionality.
188
189 - [Ansible Collection overview](https://github.com/ansible-collections/overview)
190 - [Ansible User guide](https://docs.ansible.com/ansible/latest/user_guide/index.html)
191 - [Ansible Developer guide](https://docs.ansible.com/ansible/latest/dev_guide/index.html)
192
193 ## License Information
194
195 GNU General Public License v3.0 or later
196 See [LICENSE](https://github.com/ansible-collections/vmware.vmware_rest/blob/main/LICENSE) to see the full text.