vmware.vmware.key_provider_native module – Manage a native key provider in a vCenter instance.
Note
This module is part of the vmware.vmware collection (version 2.12.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.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: vmware.vmware.key_provider_native.
Synopsis
This module allows you to create, update, and delete a native key provider in a vCenter instance.
Native key providers leverage the built-in cryptography libraries of the ESXi and vCenter appliance to encrypt and decrypt data.
You can optionally require TPM protection on the ESXi hosts that use the key provider.
Requirements
The below requirements are needed on the host that executes this module.
vSphere Automation SDK
Parameters
Parameter |
Comments |
|---|---|
Whether to set the key provider as the default provider for the vCenter instance. Choices:
|
|
If true, the module will not return the export URL and token. This is useful if you want to perform the backup via the web UI or other means and do not want to expose backup options in the logs or memory. Choices:
|
|
The password to use when exporting or backing up the key provider. This is used to encrypt the exported key provider data (as a P12 file). Since this module does not actually perform the backup for you, this password is only applied to the backup if you use the export URL and token from the module’s return values to perform the backup. If no password is provided, the key provider data will be exported without encryption. If you choose to backup the key provider via the web UI, you can provide a password there instead. |
|
The hostname or IP address of the vSphere vCenter server. If the value is not specified in the task, the value of environment variable |
|
The password of the vSphere vCenter server. If the value is not specified in the task, the value of environment variable |
|
The port number of the vSphere vCenter server. If the value is not specified in the task, the value of environment variable Default: |
|
The name or ID of the key provider to manage. The name and ID are interchangeable. This is used as a unique identifier for the key provider in vSphere. |
|
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 |
|
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 |
|
The proxy connection protocol to use. This option is used if the correct proxy protocol cannot be automatically determined. Choices:
|
|
Whether to ensure the key provider is present or absent. Choices:
|
|
Whether to require ESXi hosts to have TPM protection before they can use the key provider. This setting cannot be changed once the provider is created. It is only used when creating new providers. Choices:
|
|
The username of the vSphere vCenter server. If the value is not specified in the task, the value of environment variable |
|
Allows connection when SSL certificates are not valid. Set to If the value is not specified in the task, the value of environment variable Choices:
|
Notes
Note
Key providers must be backed up and ‘activated’ before they can be used. You can do this at any time in vCenter, or use the module’s return values to perform the backup. See the examples below for more details.
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’
Examples
- name: Ensure a native key provider is absent
vmware.vmware.key_provider_native:
provider_name: my-native-key-provider
state: absent
- name: Create a native key provider
vmware.vmware.key_provider_native:
provider_name: my-native-key-provider
state: present
tpm_required: true
default_provider: false
- name: Create a key provider and back it up to activate it
block:
- name: Create a native key provider and return export details for backup
vmware.vmware.key_provider_native:
provider_name: my-native-key-provider
state: present
tpm_required: true
export_password: backup-password
register: native_key_provider
- name: Backup and activate the native key provider
ansible.builtin.get_url:
url: "{{ native_key_provider.export_info.url }}"
dest: "/tmp/native_key_provider.p12"
headers:
Authorization: "Bearer {{ native_key_provider.export_info.token }}"
when: native_key_provider is ansible.builtin.changed
- name: Set a native key provider as the default and do not log export information
vmware.vmware.key_provider_native:
provider_name: my-native-key-provider
state: present
default_provider: true
disable_export_outputs: true
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
Information needed to export and back up a newly created native key provider. Use the URL and token to download the key provider backup before the export token expires. This information is only available once, immediately after creation. You can perform the backup without this information via the vCenter web UI. Note that the token value may be considered sensitive. You can reduce the risk of its exposure by setting the Returned: when a new key provider was created and Sample: |