vmware.vmware.tag_categories module – Manage one or more VMware tag categories.

Note

This module is part of the vmware.vmware collection (version 2.9.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.tag_categories.

Synopsis

  • This module allows you to create, update, and delete VMware tag categories.

  • For better performance, use object IDs instead of names when possible.

  • For better performance, manage many tag categories per module call (as opposed to using a loop). See the examples for more details.

Parameters

Parameter

Comments

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.

proxy_protocol

aliases: protocol

string

The proxy connection protocol to use.

This option is used if the correct proxy protocol cannot be automatically determined.

Choices:

  • "http"

  • "https" ← (default)

state

string

Whether ensure the tag categories are present or absent.

Choices:

  • "present" ← (default)

  • "absent"

tag_categories

list / elements=dictionary / required

A list of tag categories to manage.

Providing the ID instead of the name will reduce the number of API calls, and potentially speed up the module execution.

associable_types

list / elements=string

A list of types of vSphere objects that can be assigned to the tag category.

When creating a category, at least one type must be specified. If this is parameter is not set or set an empty list, the category will be created with all types.

Due to a vSphere limitation, this list is additive. In other words, you cannot remove a type once it has been added to the category. Any types specified in this parameter will be added if they are missing.

Choices:

  • "Folder"

  • "DistributedVirtualPortgroup"

  • "VmwareDistributedVirtualSwitch"

  • "Datacenter"

  • "com.vmware.content.Library"

  • "com.vmware.content.library.Item"

  • "Datastore"

  • "StoragePod"

  • "HostNetwork"

  • "Network"

  • "HostSystem"

  • "DistributedVirtualSwitch"

  • "VirtualMachine"

  • "VirtualApp"

  • "ResourcePool"

  • "ClusterComputeResource"

  • "OpaqueNetwork"

Default: []

cardinality

string

Controls if an object can be assigned to multiple tags in the category.

An example of a single cardinality category is “Operating System”, with tags like “Windows”, “Linux”, “Mac OS”.

An example of a multiple cardinality category is “Server”, with tags like “AppServer”, “DatabaseServer”.

If this is not specified when creating a tag category, cardinality MULTIPLE will be used.

You cannot change the cardinality of a tag category from MULTIPLE to SINGLE.

Choices:

  • "SINGLE"

  • "MULTIPLE"

description

string

The description of the tag category.

id

string

The id of the tag category to manage.

At least one of tag_categories[].name or tag_categories[].id must be provided.

Only applicable if the tag category already exists.

name

string

The name of the tag category.

At least one of tag_categories[].name or tag_categories[].id must be provided.

If only the name is provided, it will be used to search for the tag category. If a category cannot be found and state is present, a new category will be created.

If both name and ID are provided, the ID will be used to search for the category. If If a category cannot be found and state is present, an error will be raised. If a category can be found and state is present, the category will be updated to use tag_categories[].name.

This value is required when creating a new tag category.

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. Note having this variable set may cause a ‘false’ value for the ‘validate_certs’ option to be ignored in some cases. Example: ‘export REQUESTS_CA_BUNDLE=/path/to/your/ca_bundle.pem’

See Also

See also

vmware.vmware.tags

Manage one or more VMware tags.

Examples

- name: Create or update tag categories
  vmware.vmware.tag_categories:
    state: present
    tags:
      - name: my-test-category-1
      - id: urn:vmomi:InventoryServiceCategory:00000000-0000-0000-0000-21b1f07e73cf:GLOBAL
        name: my-test-category-2
        description: "This is a test category"
        cardinality: SINGLE
        associable_types: [VirtualMachine]
      - name: my-test-category-3
        description: "This is a test category"
        cardinality: MULTIPLE

- name: Delete tag categories
  vmware.vmware.tag_categories:
    state: absent
    tag_categories:
      - name: my-test-category-1
      - id: urn:vmomi:InventoryServiceCategory:00000000-0000-0000-0000-21b1f07e73cf:GLOBAL

# For better performance, manage many tag categories per module call
- name: Manage many categories
  vmware.vmware.tag_categories:
    state: present
    tag_categories:
      - name: my-test-category-1
      - name: my-test-category-2
      - name: my-test-category-3
      - name: my-test-category-4

# Do not use loops when possible
- name: This will be very slow
  vmware.vmware.tag_categories:
    state: present
    tag_categories: ["{{ item }}"]
  loop:
    - name: my-test-category-1
    - name: my-test-category-2
    - name: my-test-category-3
    - name: my-test-category-4

Return Values

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

Key

Description

created_categories

list / elements=string

List of tag category IDs that were created by this module.

The list is empty if no tag categories were created.

Returned: always

Sample: ["urn:vmomi:InventoryServiceCategory:00000000-0000-0000-0000-000000000000:GLOBAL"]

removed_categories

list / elements=string

List of tag category IDs that were removed by this module.

The list is empty if no tag categories were removed.

Returned: always

Sample: ["urn:vmomi:InventoryServiceCategory:00000000-0000-0000-0000-000000000000:GLOBAL"]

updated_categories

list / elements=string

List of tag category IDs that were updated by this module.

The list is empty if no tag categories were updated.

Returned: always

Sample: ["urn:vmomi:InventoryServiceCategory:00000000-0000-0000-0000-000000000000:GLOBAL"]

vsphere_tag_categories

dictionary

Dictionary of tag categories that were managed by this module. This includes any tag categories that the user specified, even if nothing was changed.

The key is the tag category ID, the value is a dictionary with tag category information.

Returned: always

Sample: {"urn:vmomi:InventoryServiceCategory:00000000-0000-0000-0000-000000000000:GLOBAL": {"associable_types": ["VirtualMachine", "Datastore"], "cardinality": "MULTIPLE", "description": "Description of cat1", "id": "urn:vmomi:InventoryServiceCategory:00000000-0000-0000-0000-000000000000:GLOBAL", "name": "cat1"}}

Authors

  • Ansible Cloud Team (@ansible-collections)