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

- :ansible-option-choices-entry-default:`false` ← (default)

- :ansible-option-choices-entry:`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: :ansible-option-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-option-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: :ansible-option-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: :ansible-option-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: :ansible-option-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.
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:

- :ansible-option-choices-entry-default:`false` ← (default)

- :ansible-option-choices-entry:`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:

- :ansible-option-choices-entry:`false`

- :ansible-option-choices-entry-default:`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:

- :ansible-option-choices-entry:`false`

- :ansible-option-choices-entry:`true`

groups dictionary | Add hosts to group based on Jinja2 conditionals. Default: :ansible-option-default:`{}`
host_format string | Specify the format of the host in the inventory group. Available specifiers: name, namespace, uid. Default: :ansible-option-default:`"{namespace}-{name}"`
keyed_groups list / elements=dictionary | Add hosts to group based on the values of a variable. Default: :ansible-option-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: :ansible-option-default:`""`
separator string | separator used to build the keyed group name Default: :ansible-option-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:

- :ansible-option-choices-entry:`false`

- :ansible-option-choices-entry-default:`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:

- :ansible-option-choices-entry:`false`

- :ansible-option-choices-entry-default:`true` ← (default)

plugin

string / required

Token that ensures this is a source file for the “kubevirt” plugin.

Choices:

- :ansible-option-choices-entry:`"kubevirt"`

- :ansible-option-choices-entry:`"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:

- :ansible-option-choices-entry-default:`false` ← (default)

- :ansible-option-choices-entry:`true`

use_extra_vars

boolean

added in ansible-core 2.11

Merge extra vars into the available variables for composition (highest precedence).

Choices:

- :ansible-option-choices-entry-default:`false` ← (default)

- :ansible-option-choices-entry:`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.