# kubevirt – Inventory source for KubeVirt VirtualMachines

Note

This inventory plugin is part of the kubevirt.core collection.

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 kubevirt.core`. You need further requirements to be able to use this inventory plugin, see Requirements for details.

To use it in a playbook, specify: `kubevirt.core.kubevirt`.

## Synopsis

- Fetch running `VirtualMachineInstances` for one or more namespaces with an optional label selector.

- Groups by cluster name, namespace and labels.

- Uses the kubernetes.core.kubectl connection plugin to access the Kubernetes cluster.

- Uses `*.kubevirt.[yml|yaml]` YAML configuration file to set parameter values.

## Requirements

The below requirements are needed on the local controller node that executes this inventory.

- python >= 3.9

- kubernetes >= 28.1.0

- PyYAML >= 3.11

## Parameters

Parameter | Comments
--- | ---
- cache boolean | Toggle to enable/disable the caching of the inventory's source data, requires a cache plugin setup to work. Choices: `false` ← (default) `true` Configuration: INI entry
      [inventory]
      cache = false
Environment variable: `ANSIBLE_INVENTORY_CACHE`
- cache_connection string | Cache connection data or path, read cache plugin documentation for specifics. Configuration: INI entries
      [defaults]
      fact_caching_connection = VALUE
      [inventory]
      cache_connection = VALUE
Environment variable: `ANSIBLE_CACHE_PLUGIN_CONNECTION` Environment variable: `ANSIBLE_INVENTORY_CACHE_CONNECTION`
- cache_plugin string | Cache plugin to use for the inventory's source data. Default: `"memory"` Configuration: INI entries
      [defaults]
      fact_caching = memory
      [inventory]
      cache_plugin = memory
Environment variable: `ANSIBLE_CACHE_PLUGIN` Environment variable: `ANSIBLE_INVENTORY_CACHE_PLUGIN`
- cache_prefix string | Prefix to use for cache plugin files/tables Default: `"ansible_inventory_"` Configuration: INI entries
      [defaults]
      fact_caching_prefix = ansible_inventory_
      [inventory]
      cache_prefix = ansible_inventory_
Environment variable: `ANSIBLE_CACHE_PLUGIN_PREFIX` Environment variable: `ANSIBLE_INVENTORY_CACHE_PLUGIN_PREFIX`
- cache_timeout integer | Cache duration in seconds Default: `3600` Configuration: INI entries
      [defaults]
      fact_caching_timeout = 3600
      [inventory]
      cache_timeout = 3600
Environment variable: `ANSIBLE_CACHE_PLUGIN_TIMEOUT` Environment variable: `ANSIBLE_INVENTORY_CACHE_TIMEOUT`
compose dictionary | Create vars from jinja2 expressions. Default: `{}`
connections list / elements=dictionary | Optional list of cluster connection settings. If no connections are provided, the default ~/.kube/config and active context will be used, and objects will be returned for all namespaces the active user is authorized to access.
api_key string | Token used to authenticate with the API. Can also be specified via `K8S_AUTH_API_KEY` environment variable.
api_version string | Specify the used KubeVirt API version. Default: `"kubevirt.io/v1"`
append_base_domain boolean | Append the base domain of the cluster to host names constructed from SSH `Services` of type `NodePort`. Choices: `false` ← (default) `true`
base_domain string | Override the base domain used to construct host names of `VirtualMachines`. Used in case of `kubesecondarydns` or `Services` of type `NodePort` if `connections.append_base_domain` is set.
ca_cert aliases: ssl_ca_cert string | Path to a CA certificate used to authenticate with the API. Can also be specified via `K8S_AUTH_SSL_CA_CERT` environment variable.
client_cert aliases: cert_file string | Path to a certificate used to authenticate with the API. Can also be specified via `K8S_AUTH_CERT_FILE` environment variable.
client_key aliases: key_file string | Path to a key file used to authenticate with the API. Can also be specified via `K8S_AUTH_KEY_FILE` environment variable.
context string | The name of a context found in the config file. Can also be specified via `K8S_AUTH_CONTEXT` environment variable.
create_groups boolean | Enable the creation of groups from labels on `VirtualMachines`. Choices: `false` ← (default) `true`
host string | Provide a URL for accessing the API. Can also be specified via `K8S_AUTH_HOST` environment variable.
kube_secondary_dns boolean | Enable `kubesecondarydns` derived host names when using a secondary network interface. Choices: `false` ← (default) `true`
kubeconfig string | Path to an existing Kubernetes config file. If not provided, and no other connection options are provided, the Kubernetes client will attempt to load the default configuration file from ~/.kube/config. Can also be specified via `K8S_AUTH_KUBECONFIG` environment variable.
label_selector string | Define a label selector to select a subset of the fetched `VirtualMachineInstances`.
name string | Optional name to assign to the cluster. If not provided, a name is constructed from the server and port.
namespaces string | List of namespaces. If not specified, will fetch all `VirtualMachineInstances` for all namespaces the user is authorized to access.
network_name aliases: interface_name string | In case multiple networks are attached to a `VirtualMachineInstance`, define which interface should be returned as primary IP address.
password string | Provide a password for authenticating with the API. Can also be specified via `K8S_AUTH_PASSWORD` environment variable.
use_service boolean | Enable the use of `Services` to establish an SSH connection to the `VirtualMachine`. Services are only used if no `connections.network_name` was provided. Choices: `false` `true` ← (default)
username string | Provide a username for authenticating with the API. Can also be specified via `K8S_AUTH_USERNAME` environment variable.
validate_certs aliases: verify_ssl boolean | Whether or not to verify the API server's SSL certificates. Can also be specified via `K8S_AUTH_VERIFY_SSL` environment variable. Choices: `false` `true`
groups dictionary | Add hosts to group based on Jinja2 conditionals. Default: `{}`
host_format string | Specify the format of the host in the inventory group. Available specifiers: `name`, `namespace` and `uid`. Default: `"{namespace}-{name}"`
keyed_groups list / elements=dictionary | Add hosts to group based on the values of a variable. Default: `[]`
default_value string added in ansible-core 2.12 | The default value when the host variable's value is an empty string. This option is mutually exclusive with `keyed_groups[].trailing_separator`.
key string | The key from input dictionary used to generate groups
parent_group string | parent group for keyed group
prefix string | A keyed group name will start with this prefix Default: `""`
separator string | separator used to build the keyed group name Default: `"_"`
trailing_separator boolean added in ansible-core 2.12 | Set this option to `False` to omit the `keyed_groups[].separator` after the host variable when the value is an empty string. This option is mutually exclusive with `keyed_groups[].default_value`. Choices: `false` `true` ← (default)
leading_separator boolean added in ansible-core 2.11 | Use in conjunction with keyed_groups. By default, a keyed group that does not have a prefix or a separator provided will have a name that starts with an underscore. This is because the default prefix is "" and the default separator is "_". Set this option to False to omit the leading underscore (or other separator) if no prefix is given. If the group name is derived from a mapping the separator is still used to concatenate the items. To not use a separator in the group name at all, set the separator for the keyed group to an empty string instead. Choices: `false` `true` ← (default)
plugin string / required | Token that ensures this is a source file for the kubevirt.core.kubevirt plugin. Choices: `"kubevirt"` `"kubevirt.core.kubevirt"`
strict boolean | If `yes` make invalid entries a fatal error, otherwise skip and continue. Since it is possible to use facts in the expressions they might not always be available and we ignore those errors by default. Choices: `false` ← (default) `true`
- use_extra_vars boolean added in ansible-core 2.11 | Merge extra vars into the available variables for composition (highest precedence). Choices: `false` ← (default) `true` Configuration: INI entry
      [inventory_plugins]
      use_extra_vars = false
Environment variable: `ANSIBLE_INVENTORY_USE_EXTRA_VARS`

## Examples

    # Filename must end with kubevirt.[yml|yaml]

    - name: Authenticate with token and return all VirtualMachineInstances for all accessible namespaces
      plugin: kubevirt.core.kubevirt
      connections:
        - host: https://192.168.64.4:8443
          api_key: xxxxxxxxxxxxxxxx
          validate_certs: false

    - name: Use default ~/.kube/config and return VirtualMachineInstances from namespace testing connected to network bridge-network
      plugin: kubevirt.core.kubevirt
      connections:
        - namespaces:
            - testing
          network_name: bridge-network

    - name: Use default ~/.kube/config and return VirtualMachineInstances from namespace testing with label app=test
      plugin: kubevirt.core.kubevirt
      connections:
        - namespaces:
            - testing
          label_selector: app=test

    - name: Use a custom config file and a specific context
      plugin: kubevirt.core.kubevirt
      connections:
        - kubeconfig: /path/to/config
          context: 'awx/192-168-64-4:8443/developer'

### Authors

- KubeVirt.io Project

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.