# kubevirt – KubeVirt inventory source

Note

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

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 namespace, namespace_vmis and labels.

- Uses the 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.6

- kubernetes >= 12.0.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:
      [default]
      fact_caching_prefix = ansible_inventory_
  Removed in: version 2.16 of ansible.builtin Why: Fixes typing error in INI section name Alternative: Use the ‘defaults’ section instead
      [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 string | 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"`
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. 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, 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 `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 `separator` after the host variable when the value is an empty string. This option is mutually exclusive with `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” 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]

    # 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

    # Use default config (~/.kube/config) file and active context, and return VirtualMachineInstances
    # from namespace testing with interfaces connected to network bridge-network
    plugin: kubevirt.core.kubevirt
    connections:
    - namespaces:
      - testing
      network_name: bridge-network

    # Use default config (~/.kube/config) file and active context, and return VirtualMachineInstances
    # from namespace testing with label app=test
    plugin: kubevirt.core.kubevirt
    connections:
    - namespaces:
      - testing
      label_selector: app=test

    # 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.