Skip to content

Commit 9beb329

Browse files
mariolenzmariolenz
authored
VCSIM removal part 4 (#1294)
VCSIM removal part 4 Depends-On: ansible/ansible-zuul-jobs#1511 SUMMARY This is a follow-up PR to #1293. I wanted to remove VCSIM from the Developer Guide but was asked to move it to the collection (ansible/ansible#77585). I'll start with this and then check if VCSIM mentioned somewhere else in the documentation. ISSUE TYPE Docs Pull Request COMPONENT NAME ADDITIONAL INFORMATION Reviewed-by: Sandra McCann <samccann@redhat.com> Reviewed-by: Gonéri Le Bouder <goneri@lebouder.net> Reviewed-by: Mario Lenz <m@riolenz.de>
1 parent 55b173a commit 9beb329

File tree

9 files changed

+276
-38
lines changed

9 files changed

+276
-38
lines changed

‎changelogs/fragments/1294-remove_vcsim.yml

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
major_changes:
2+
- Drop VCSIM as a test target (https://github.com/ansible-collections/community.vmware/pull/1294).

‎docs/docsite/extra-docs.yml

+3
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,6 @@ sections:
33
- title: Scenario Guide
44
toctree:
55
- scenario_guide
6+
- title: Developer Guide
7+
toctree:
8+
- dev_guide

‎docs/docsite/rst/dev_guide.rst

+239
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
.. _ansible_collections.community.vmware.docsite.vmware_ansible:
2+
3+
****************************************
4+
Guidelines for VMware module development
5+
****************************************
6+
7+
The Ansible VMware collection (on `Galaxy <https://galaxy.ansible.com/community/vmware>`_, source code `repository <https://github.com/ansible-collections/community.vmware>`_) is maintained by the VMware Working Group. For more information see the `team community page <https://github.com/ansible/community/wiki/VMware>`_.
8+
9+
.. contents::
10+
:local:
11+
12+
Testing with your own infrastructure
13+
====================================
14+
15+
You can target a regular VMware environment. This paragraph explains step by step how you can run the test-suite yourself.
16+
17+
Requirements
18+
------------
19+
20+
- 2 ESXi hosts (6.5 or 6.7)
21+
- with 2 NIC, the second ones should be available for the test
22+
- a VCSA host
23+
- a NFS server
24+
- Python dependencies:
25+
- `pyvmomi <https://github.com/vmware/pyvmomi/tree/master/pyVmomi>`_
26+
- `requests <https://2.python-requests.org/en/master/>`_
27+
28+
If you want to deploy your test environment in a hypervisor, both `VMware or Libvirt <https://github.com/goneri/vmware-on-libvirt>`_ work well.
29+
30+
NFS server configuration
31+
^^^^^^^^^^^^^^^^^^^^^^^^
32+
33+
Your NFS server must expose the following directory structure:
34+
35+
.. code-block:: shell
36+
37+
$ tree /srv/share/
38+
/srv/share/
39+
├── isos
40+
│ ├── base.iso
41+
│ ├── centos.iso
42+
│ └── fedora.iso
43+
└── vms
44+
2 directories, 3 files
45+
46+
On a Linux system, you can expose the directory over NFS with the following export file:
47+
48+
.. code-block:: shell
49+
50+
$ cat /etc/exports
51+
/srv/share 192.168.122.0/255.255.255.0(rw,anonuid=1000,anongid=1000)
52+
53+
.. note::
54+
55+
With this configuration all the new files will be owned by the user with the UID and GID 1000/1000.
56+
Adjust the configuration to match your user's UID/GID.
57+
58+
The service can be enabled with:
59+
60+
.. code-block:: shell
61+
62+
$ sudo systemctl enable --now nfs-server
63+
64+
65+
Configure your installation
66+
---------------------------
67+
68+
Prepare a configuration file that describes your set-up. The file
69+
should be called :file:`test/integration/cloud-config-vcenter.ini` and based on
70+
:file:`test/lib/ansible_test/config/cloud-config-vcenter.ini.template`. For instance, if you have deployed your lab with
71+
`vmware-on-libvirt <https://github.com/goneri/vmware-on-libvirt>`_:
72+
73+
.. code-block:: ini
74+
75+
[DEFAULT]
76+
vcenter_username: administrator@vsphere.local
77+
vcenter_password: !234AaAa56
78+
vcenter_hostname: vcenter.test
79+
vmware_validate_certs: false
80+
esxi1_hostname: esxi1.test
81+
esxi1_username: root
82+
esxi1_password: root
83+
esxi2_hostname: test2.test
84+
esxi2_username: root
85+
esxi2_password: root
86+
87+
Using an HTTP proxy
88+
-------------------
89+
Hosting test infrastructure behind an HTTP proxy is supported. You can specify the location of the proxy server with the two extra keys:
90+
91+
.. code-block:: ini
92+
93+
vmware_proxy_host: esxi1-gw.ws.testing.ansible.com
94+
vmware_proxy_port: 11153
95+
96+
In addition, you may need to adjust the variables of the following `var files <https://github.com/ansible-collections/community.vmware/tree/main/tests/integration/targets/prepare_vmware_tests/vars>`_ to match the configuration of your lab. If you use vmware-on-libvirt to prepare your lab, you do not have anything to change.
97+
98+
Run the test-suite
99+
------------------
100+
101+
Once your configuration is ready, you can trigger a run with the following command:
102+
103+
.. code-block:: shell
104+
105+
source hacking/env-setup
106+
VMWARE_TEST_PLATFORM=static ansible-test integration --python 3.7 vmware_host_firewall_manager
107+
108+
``vmware_host_firewall_manager`` is the name of the module to test.
109+
110+
``vmware_guest`` is much larger than any other test role and is rather slow. You can enable or disable some of its test playbooks in `main.yml <https://github.com/ansible-collections/community.vmware/tree/main/tests/integration/targets/vmware_guest/defaults/main.yml>`_.
111+
112+
113+
Unit-test
114+
=========
115+
116+
The VMware modules have limited unit-test coverage. You can run the test suite with the
117+
following commands:
118+
119+
.. code-block:: shell
120+
121+
source hacking/env-setup
122+
ansible-test units --venv --python 3.7 '.*vmware.*'
123+
124+
Code style and best practice
125+
============================
126+
127+
datacenter argument with ESXi
128+
-----------------------------
129+
130+
The ``datacenter`` parameter should not use ``ha-datacenter`` by default. This is because the user may
131+
not realize that Ansible silently targets the wrong data center.
132+
133+
esxi_hostname should not be mandatory
134+
-------------------------------------
135+
136+
Depending upon the functionality provided by ESXi or vCenter, some modules can seamlessly work with both. In this case,
137+
``esxi_hostname`` parameter should be optional.
138+
139+
.. code-block:: python
140+
141+
if self.is_vcenter():
142+
esxi_hostname = module.params.get('esxi_hostname')
143+
if not esxi_hostname:
144+
self.module.fail_json("esxi_hostname parameter is mandatory")
145+
self.host = self.get_all_host_objs(cluster_name=cluster_name, esxi_host_name=esxi_hostname)[0]
146+
else:
147+
self.host = find_obj(self.content, [vim.HostSystem], None)
148+
if self.host is None:
149+
self.module.fail_json(msg="Failed to find host system.")
150+
151+
Example should use the fully qualified collection name (FQCN)
152+
-------------------------------------------------------------
153+
154+
Use FQCN for examples within module documentation. For instance, you should use ``community.vmware.vmware_guest`` instead of just
155+
``vmware_guest``.
156+
157+
This way, the examples do not depend on the ``collections`` directive of the
158+
playbook.
159+
160+
Functional tests
161+
----------------
162+
163+
Writing new tests
164+
^^^^^^^^^^^^^^^^^
165+
166+
If you are writing a new collection of integration tests, there are a few VMware-specific things to note beyond
167+
the standard Ansible :ref:`integration testing<testing_integration>` process.
168+
169+
The test-suite uses a set of common, pre-defined vars located `in prepare_vmware_tests <https://github.com/ansible-collections/community.vmware/tree/main/tests/integration/targets/test/integration/targets/prepare_vmware_tests/>`_ role.
170+
The resources defined there are automatically created by importing that role at the start of your test:
171+
172+
.. code-block:: yaml
173+
174+
- import_role:
175+
name: prepare_vmware_tests
176+
vars:
177+
setup_datacenter: true
178+
179+
This will give you a ready to use cluster, datacenter, datastores, folder, switch, dvswitch, ESXi hosts, and VMs.
180+
181+
No need to create too much resources
182+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
183+
184+
Most of the time, it's not necessary to use ``with_items`` to create multiple resources. By avoiding it,
185+
you speed up the test execution and you simplify the clean up afterwards.
186+
187+
VM names should be predictable
188+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
189+
190+
If you need to create a new VM during your test, you can use ``test_vm1``, ``test_vm2`` or ``test_vm3``. This
191+
way it will be automatically clean up for you.
192+
193+
Avoid the common boiler plate code in your test playbook
194+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
195+
196+
From Ansible 2.10, the test suite uses `modules_defaults`. This module
197+
allow us to preinitialize the following default keys of the VMware modules:
198+
199+
- hostname
200+
- username
201+
- password
202+
- validate_certs
203+
204+
For example, the following block:
205+
206+
.. code-block:: yaml
207+
208+
- name: Add a VMware vSwitch
209+
community.vmware.vmware_vswitch:
210+
hostname: '{{ vcenter_hostname }}'
211+
username: '{{ vcenter_username }}'
212+
password: '{{ vcenter_password }}'
213+
validate_certs: 'no'
214+
esxi_hostname: 'esxi1'
215+
switch_name: "boby"
216+
state: present
217+
218+
should be simplified to just:
219+
220+
.. code-block:: yaml
221+
222+
- name: Add a VMware vSwitch
223+
community.vmware.vmware_vswitch:
224+
esxi_hostname: 'esxi1'
225+
switch_name: "boby"
226+
state: present
227+
228+
229+
Typographic convention
230+
======================
231+
232+
Nomenclature
233+
------------
234+
235+
We try to enforce the following rules in our documentation:
236+
237+
- VMware, not VMWare or vmware
238+
- ESXi, not esxi or ESXI
239+
- vCenter, not vcenter or VCenter

‎docs/docsite/rst/vmware_scenarios/vmware_external_doc_links.rst

-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@ Other useful VMware resources
55
*****************************
66

77
* `VMware API and SDK Documentation <https://www.vmware.com/support/pubs/sdk_pubs.html>`_
8-
* `VCSIM test container image <https://quay.io/repository/ansible/vcenter-test-container>`_
98
* `Ansible VMware community wiki page <https://github.com/ansible/community/wiki/VMware>`_
109
* `VMware's official Guest Operating system customization matrix <https://partnerweb.vmware.com/programs/guestOS/guest-os-customization-matrix.pdf>`_
1110
* `VMware Compatibility Guide <https://www.vmware.com/resources/compatibility/search.php>`_

‎plugins/modules/vmware_datastore_info.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -235,7 +235,7 @@ def build_datastore_list(self, datastore_list):
235235
datastore_summary['vmfs_blockSize'] = host_mount_info.volume.blockSize
236236
datastore_summary['vmfs_version'] = host_mount_info.volume.version
237237
datastore_summary['vmfs_uuid'] = host_mount_info.volume.uuid
238-
# vcsim does not return uncommitted
238+
# uncommitted is optional / not always set
239239
if not summary.uncommitted:
240240
summary.uncommitted = 0
241241
datastore_summary['uncommitted'] = summary.uncommitted

‎plugins/modules/vmware_dvs_portgroup_info.py

+19-24
Original file line numberDiff line numberDiff line change
@@ -247,15 +247,12 @@ def gather_dvs_portgroup_info(self):
247247
)
248248

249249
if self.module.params['show_teaming_policy']:
250-
# govcsim does not have uplinkTeamingPolicy, remove this check once
251-
# PR https://github.com/vmware/govmomi/pull/1524 merged.
252-
if dvs_pg.config.defaultPortConfig.uplinkTeamingPolicy:
253-
teaming_policy = dict(
254-
policy=dvs_pg.config.defaultPortConfig.uplinkTeamingPolicy.policy.value,
255-
inbound_policy=dvs_pg.config.defaultPortConfig.uplinkTeamingPolicy.reversePolicy.value,
256-
notify_switches=dvs_pg.config.defaultPortConfig.uplinkTeamingPolicy.notifySwitches.value,
257-
rolling_order=dvs_pg.config.defaultPortConfig.uplinkTeamingPolicy.rollingOrder.value,
258-
)
250+
teaming_policy = dict(
251+
policy=dvs_pg.config.defaultPortConfig.uplinkTeamingPolicy.policy.value,
252+
inbound_policy=dvs_pg.config.defaultPortConfig.uplinkTeamingPolicy.reversePolicy.value,
253+
notify_switches=dvs_pg.config.defaultPortConfig.uplinkTeamingPolicy.notifySwitches.value,
254+
rolling_order=dvs_pg.config.defaultPortConfig.uplinkTeamingPolicy.rollingOrder.value,
255+
)
259256

260257
if self.module.params['show_uplinks'] and \
261258
dvs_pg.config.defaultPortConfig.uplinkTeamingPolicy and \
@@ -264,21 +261,19 @@ def gather_dvs_portgroup_info(self):
264261
standby_uplinks = dvs_pg.config.defaultPortConfig.uplinkTeamingPolicy.uplinkPortOrder.standbyUplinkPort
265262

266263
if self.params['show_port_policy']:
267-
# govcsim does not have port policy
268-
if dvs_pg.config.policy:
269-
port_policy = dict(
270-
block_override=dvs_pg.config.policy.blockOverrideAllowed,
271-
ipfix_override=dvs_pg.config.policy.ipfixOverrideAllowed,
272-
live_port_move=dvs_pg.config.policy.livePortMovingAllowed,
273-
network_rp_override=dvs_pg.config.policy.networkResourcePoolOverrideAllowed,
274-
port_config_reset_at_disconnect=dvs_pg.config.policy.portConfigResetAtDisconnect,
275-
security_override=dvs_pg.config.policy.securityPolicyOverrideAllowed,
276-
shaping_override=dvs_pg.config.policy.shapingOverrideAllowed,
277-
traffic_filter_override=dvs_pg.config.policy.trafficFilterOverrideAllowed,
278-
uplink_teaming_override=dvs_pg.config.policy.uplinkTeamingOverrideAllowed,
279-
vendor_config_override=dvs_pg.config.policy.vendorConfigOverrideAllowed,
280-
vlan_override=dvs_pg.config.policy.vlanOverrideAllowed
281-
)
264+
port_policy = dict(
265+
block_override=dvs_pg.config.policy.blockOverrideAllowed,
266+
ipfix_override=dvs_pg.config.policy.ipfixOverrideAllowed,
267+
live_port_move=dvs_pg.config.policy.livePortMovingAllowed,
268+
network_rp_override=dvs_pg.config.policy.networkResourcePoolOverrideAllowed,
269+
port_config_reset_at_disconnect=dvs_pg.config.policy.portConfigResetAtDisconnect,
270+
security_override=dvs_pg.config.policy.securityPolicyOverrideAllowed,
271+
shaping_override=dvs_pg.config.policy.shapingOverrideAllowed,
272+
traffic_filter_override=dvs_pg.config.policy.trafficFilterOverrideAllowed,
273+
uplink_teaming_override=dvs_pg.config.policy.uplinkTeamingOverrideAllowed,
274+
vendor_config_override=dvs_pg.config.policy.vendorConfigOverrideAllowed,
275+
vlan_override=dvs_pg.config.policy.vlanOverrideAllowed
276+
)
282277

283278
if self.params['show_vlan_info']:
284279
vlan_info = self.get_vlan_info(dvs_pg.config.defaultPortConfig.vlan)

‎plugins/modules/vmware_guest.py

+1-2
Original file line numberDiff line numberDiff line change
@@ -1959,8 +1959,7 @@ def configure_vapp_properties(self, vm_obj):
19591959

19601960
if vm_obj:
19611961
# VM exists
1962-
# This is primarily for vcsim/integration tests, unset vAppConfig was not seen on my deployments
1963-
orig_spec = vm_obj.config.vAppConfig if vm_obj.config.vAppConfig else new_vmconfig_spec
1962+
orig_spec = vm_obj.config.vAppConfig
19641963

19651964
vapp_properties_current = dict((x.id, x) for x in orig_spec.property)
19661965
vapp_properties_to_change = dict((x['id'], x) for x in self.params['vapp_properties'])

‎testing.md

+1-3
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,4 @@ $ VMWARE_TEST_PLATFORM=static ansible-test integration --diff --no-temp-workdir
4040

4141
## More Information
4242

43-
* [Container image with govcsim](https://github.com/ansible/vcenter-test-container)
44-
45-
* [Developer guide for testing with govcsim](https://docs.ansible.com/ansible/latest/dev_guide/platforms/vmware_guidelines.html#testing-with-govcsim)
43+
* [Developer guide for testing](https://docs.ansible.com/ansible/latest/dev_guide/platforms/vmware_guidelines.html#testing-with-your-own-infrastructure)

‎tests/integration/cloud-config-vcenter.ini.sample

+10-7
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,12 @@
1-
; VMWARE_TEST_PLATFORM=static ansible-test integration --diff --no-temp-workdir --python 3.8 --allow-disabled -vvv --allow-destructive zuul/vmware/govcsim/
1+
; VMWARE_TEST_PLATFORM=static ansible-test integration --python 3.8
22
[DEFAULT]
3-
vmware_user: user
4-
vmware_password: pass
5-
vmware_host: localhost
3+
vcenter_hostname: vcenter.test
4+
vcenter_username: user
5+
vcenter_password: pass
66
vmware_validate_certs: false
7-
vcsim: true
8-
vcsim_with: systemd
9-
DBUS_SESSION_BUS_ADDRESS: unix:path=/run/user/1000/bus
7+
esxi1_hostname: esxi1.test
8+
esxi1_username: root
9+
esxi1_password: pass
10+
esxi2_hostname: test2.test
11+
esxi2_username: root
12+
esxi2_password: pass

0 commit comments

Comments
 (0)