community.libvirt.virt_secret module – Manage libvirt secrets and their values

Note

This module is part of the community.libvirt collection (version 2.2.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 community.libvirt. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.libvirt.virt_secret.

New in community.libvirt 2.1.0

Synopsis 

Manage libvirt secrets. Can add, remove or update secrets in libvirt.
Can be used to set secrets value.

Requirements 

The below requirements are needed on the host that executes this module.

libvirt
lxml
PyYAML

Parameters 

Parameter	Comments
command string	Executes commands to manage secret. If defined `create`, creates secret described by either `xml` or(secret). It is analagous to `state=present`. If defined `delete`, removes secret defined by either `uuid`, `state`, `xml`. It is analagous to `state=absent`. If defined `list_secrets` it will return `list_secrets` with all existing secrets in XML format. If defined `get_xml` module will try to get secret definition from libvirt. If existing secret found, returns `secret_xml`. Otherwise it will return None. If defined `set_value` module will define a secret value. This command is not idempotent and will always show changed. Requires `password` to be defined. Choices: `"create"` `"delete"` `"list_secrets"` `"get_xml"` `"set_value"`
password string	A value of the secret which will be stored in the libvirt secret. As in majority cases secrets are private, password is defined only during secret creation or when `command=set_value` is executed. If the secret already exist and the `password` is defined, it will not try to set it once again. Even if different password is provided.
secret dictionary	Defines a secret as a set of fields instead of raw XML. This property is mutually exclusive with `xml`. If `uuid` is not defined, `secret.usage` and `secret.usage_id` must be defined.
description string	Defines secret description.
ephemeral boolean	If `True`, secret will only be kept in memory. Default value is `False`. Choices: `false` ← (default) `true`
private boolean	If `True`, value will not be retrivable from libvirt. Default value is `False`. Choices: `false` `true` ← (default)
usage string	Specifies what this secret is used for. Possible values are `none`, `volume`, `ceph`, `iscsi`, `tls`, `vtpm`. Choices: `"none"` `"volume"` `"ceph"` `"iscsi"` `"tls"` `"vtpm"`
usage_id string	Defines unique secret_ID. Unique for each `secret.usage`.
state string	Alternative for the `command` option. If `present`, creates a volume described by either `xml` or `secret`. Can be used to update existing secrets properties. If `absent`, removes secret defined by either `uuid`, `state` or `xml`. If `present` and UUID is not specified in either `uuid` or `xml`, it will try to find existing secret using `secret.usage` and `secret.usage_id` Mutually exclusive with `command`. Choices: `"present"` `"absent"`
uri string	Libvirt connection uri. Default: `"qemu:///system"`
uuid string	Secret UUID. The value is unique across all secret types. If UUID value is also defined in the `xml` this option is ignored.
xml string	XML document used with the define command. Must be raw XML content using `lookup`. XML cannot be reference to a file.

Attributes 

Attribute	Support	Description
check_mode	Support: full In check mode, secrets are not actually created, updated or deleted. Module compares existing state of the secret in libvirt and check if change is required. Will always produce changed with `command=set_value`.	Check mode is fully supported.
diff_mode	Support: full For all made changes except `command=set_value` module will return diff in a dict form to illustrate was was changed. In check_mode diff will contain the same output as if it was executed normally.	Module provides state change as a dict.
idempotent	Support: partial If `command=set_value` the module is not idempotent as it don’t try to get secrets from libvirt and always return changed. In most of the cases secrets are private and their value is not obtainable from the libvirt.	In most cases, this module is idempotent.

Examples 

---
- name: Create new secret using xml option and command
  community.libvirt.virt_secret:
    command: create
    xml: |
      <secret ephemeral='no' private='yes'>
        <uuid>e4b5978c-ba37-5605-97c1-4a20413d0fc9</uuid>
        <description>test ceph pool secret</description>
        <usage type='ceph'>
        <name>test_secret</name>
        </usage>
      </secret>

- name: Get secret XML by uuid
  community.libvirt.virt_secret:
    uuid: e4b5978c-ba37-5605-97c1-4a20413d0fc9
    command: get_xml
  register: result

- name: Get XML by secret usage and usage_id
  community.libvirt.virt_secret:
    secret:
      usage: ceph
      usage_id: test_secret
    command: get_xml
  register: result

- name: Print found XML
  ansible.builtin.debug:
    var: result.secret_xml

- name: Define secret using options secret and uuid
  community.libvirt.virt_secret:
    uuid: e4b5978c-ba37-5605-97c1-4a20413d0fc9
    secret:
      usage: tls
      usage_id: test_secret
      description: Test TLS secret
    state: present

- name: List all currently defined secrets
  community.libvirt.virt_secret:
    command: list_secrets
  register: result

- name: Print found secrets list
  ansible.builtin.debug:
    var: result.secrets_list

- name: Set value of the secret
  community.libvirt.virt_secret:
    uuid: e4b5978c-ba37-5605-97c1-4a20413d0fc9
    command: set_value
    password: somesecureandrandomsecret1234

- name: Remove secret
  community.libvirt.virt_secret:
    uuid: 57ea8fd0-9b82-4e54-9d16-df7d2765844d
    state: absent

Return Values 

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

Key

Description

list_secrets

list / elements=string

When (command=list_secrets) returns a list of secrets in XML format.

Returned: success

Sample: ["<secret ephemeral='no' private='yes'>\n <uuid>fce0c61a-f0fc-5727-90b2-56c92534070f</uuid>\n <description>sample vTPM secret</description>\n <usage type='vtpm'><name>VTPM_example</name></usage></secret>\n", "<secret ephemeral='no' private='yes'>\n <uuid>e4b5978c-ba37-5605-97c1-4a20413d0fc9</uuid>\n <description>changed_test pool secret</description>\n <usage type='ceph'><name>test_secret</name></usage>\n</secret>\n", "<secret ephemeral='no' private='yes'>\n <uuid>edfa6124-eb0e-4449-a680-66f5fa7aedeb</uuid>\n <description>Secret puppy name</description>\n <usage type='volume'><volume>/var/lib/libvirt/images/puppyname.img</volume></usage>\n</secret>\n"]

secret_xml

string

When command=get_xml returns XML definition of the secret.

Returned: success

Sample: "<secret ephemeral=\"no\" private=\"yes\">\n <uuid>e4b5978c-ba37-5605-97c1-4a20413d0fc9</uuid>\n <description>test_secret pool secret</description>\n <usage type=\"ceph\">\n <name>test_secret</name>\n </usage>\n</secret>\"\n"

Authors

Denys Mishchenko (@arddennis)

community.libvirt.virt_secret module – Manage libvirt secrets and their values

Synopsis

Requirements

Parameters

Attributes

Examples

Return Values