vmware.vmware.folder module – Manage VMware vSphere folders

Note

This module is part of the vmware.vmware collection (version 1.11.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install vmware.vmware.

To use it in a playbook, specify: vmware.vmware.folder.

Synopsis

  • Adds or removes VMware vSphere folders. This module does not manage folders inside of datastores.

Parameters

Parameter

Comments

absolute_path

string

The absolute path of the folder to create. The absolute path should include the datacenter and the folder type.

The leading slash is not required. For example the absolute path could be /DC-01/vm/my/folder or DC-01/vm/my/folder

One of relative_path or absolute_path must be specified.

datacenter

aliases: datacenter_name

string

The name of the datacenter where the folder should be created.

Only used if the relative_path option is used.

folder_type

string

The type of folder that should be created.

The folder type controls what resources can be held in the folder, as well as the path where the folder is created.

For example, a folder at path /DC-01/vm/my/folder has folder type ‘vm’.

Only used if the relative_path option is used.

Choices:

  • "vm"

  • "host"

  • "datastore"

  • "network"

hostname

string

The hostname or IP address of the vSphere vCenter server.

If the value is not specified in the task, the value of environment variable VMWARE_HOST will be used instead.

password

aliases: pass, pwd

string

The password of the vSphere vCenter server.

If the value is not specified in the task, the value of environment variable VMWARE_PASSWORD will be used instead.

port

integer

The port number of the vSphere vCenter server.

If the value is not specified in the task, the value of environment variable VMWARE_PORT will be used instead.

Default: 443

proxy_host

string

The address of a proxy that will receive all HTTPS requests and relay them.

The format is a hostname or a IP.

If the value is not specified in the task, the value of environment variable VMWARE_PROXY_HOST will be used instead.

proxy_port

integer

The port of the HTTP proxy that will receive all HTTPS requests and relay them.

If the value is not specified in the task, the value of environment variable VMWARE_PROXY_PORT will be used instead.

relative_path

string

The relative path of the folder to create. The relative path should include neither the datacenter nor the folder type.

For example the relative path for the folder /DC-01/vm/my/folder is my/folder

One of relative_path or absolute_path must be specified.

remove_vm_data

boolean

Only used if state is absent

If true, any VMs in the folder tree will be completely removed. This includes any disks or data associated with the VM.

If false, any VMs in the folder tree are deregistered. This means they are removed from the vSphere inventory but their data is not deleted.

Choices:

  • false ← (default)

  • true

state

string

Create present or remove absent a vSphere folder.

When state is present, all folders in the specified path will be created if they are missing.

When state is absent, all content inside the folder will be deleted. See remove_vm_data

Choices:

  • "absent"

  • "present" ← (default)

username

aliases: admin, user

string

The username of the vSphere vCenter server.

If the value is not specified in the task, the value of environment variable VMWARE_USER will be used instead.

validate_certs

boolean

Allows connection when SSL certificates are not valid. Set to false when certificates are not trusted.

If the value is not specified in the task, the value of environment variable VMWARE_VALIDATE_CERTS will be used instead.

Choices:

  • false

  • true ← (default)

Notes

Note

  • All modules require API write access and hence are not supported on a free ESXi license.

  • All variables and VMware object names are case sensitive.

  • Modules may rely on the ‘requests’ python library, which does not use the system certificate store by default. You can specify the certificate store by setting the REQUESTS_CA_BUNDLE environment variable. Example: ‘export REQUESTS_CA_BUNDLE=/path/to/your/ca_bundle.pem’

Examples

- name: Create Folder Using A Relative Path (/DC01/datastore/my/test/folder)
  vmware.vmware.folder:
    hostname: "https://vcenter"
    username: "username"
    password: "password"
    validate_certs: false
    datacenter: DC01
    relative_path: my/test/folder
    folder_type: datastore

# This is the same as the example above, but shows how to do it using different params.
- name: Create A Folder Using An Absolute Path
  vmware.vmware.folder:
    hostname: "https://vcenter"
    username: "username"
    password: "password"
    validate_certs: false
    absolute_path: /DC01/datastore/my/test/folder


- name: Delete The Folder and All Of Its Contents
  vmware.vmware.folder:
    hostname: "https://vcenter"
    username: "username"
    password: "password"
    validate_certs: false
    absolute_path: /DC01/datastore/my
    state: absent
    remove_vm_data: true


- name: Delete A VM Folder But Keep The VM Data Disks
  vmware.vmware.folder:
    hostname: "https://vcenter"
    username: "username"
    password: "password"
    validate_certs: false
    absolute_path: /DC01/vm/sql
    state: absent
    remove_vm_data: false

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

folder

dictionary

Identifying information about the folder

Returned: When state is present

Sample: {"folder": {"moid": "group-c111111", "name": "example-folder"}}

Authors

  • Ansible Cloud Team (@ansible-collections)