Provider Config File

mtv-api-tests keeps source provider definitions in .providers.json. Two shipped files describe it: providers_schema.json is a JSON Schema (draft 2020-12) that your editor can validate against, and .providers.json.example is an annotated template with one entry per provider type.

At runtime the suite only parses JSON. It reads specific fields per provider type and ignores the rest, so the schema is the reference for what each provider entry may contain.

Warning: .providers.json.example is an annotated template, not a ready-to-use .providers.json. The loader parses the file with json.loads(...), so your real file must be strict JSON: remove comments, keep valid quoting, and avoid trailing commas.

Warning: .providers.json usually contains provider passwords and guest OS passwords. Treat it as a secret file.

Note: The top-level key is the provider name you select with source_provider. It does not have to match type. For example, the example file has a key named vsphere-copy-offload, but its "type" is still "vsphere".

How the file is located

load_source_providers() resolves the path in this order:

Fail-fast behavior:

• A path that does not exist raises FileNotFoundError.
• An empty or whitespace-only file raises ProviderEmptyContentError.
• A file whose top level is not a JSON object raises ValueError.
• source_provider must match one of the top-level keys, or provider lookups fail later.

Top-Level Shape

{
  "$schema": "https://raw.githubusercontent.com/RedHatQE/mtv-api-tests/main/providers_schema.json",
  "vsphere": { "type": "vsphere", "...": "..." }
}

• The root is an object. Every key except $schema is a provider definition.
• $schema is optional and is used only for editor validation.
• Each provider definition is validated against a oneOf block, one per provider type. Exactly one type block must match.

Warning: The OpenShift provider block sets additionalProperties: false. Unknown keys in an openshift entry fail schema validation, even though the runtime loader ignores extra keys on other provider types.

Fields By Provider Type

type selects the block. These tables match providers_schema.json exactly.

type: "vsphere"

type: "ovirt"

type: "openstack"

type: "openshift"

This block is the strict one: additionalProperties is false, so no other keys are allowed.

Note: The runtime path for an openshift entry does not authenticate with these values. The loader rewrites api_url to the current cluster host and reuses the session's own token secret, which is always created with insecureSkipVerify: "true". See OpenShift.

type: "ova"

type: "hyperv"

Note: Hyper-V is the only provider that fetches its CA certificate from port 5986 instead of 443.

Fields The Runtime Always Reads

Before dispatching on type, the loader builds the provider secret and connection arguments from three fields. They must be present for every provider entry, including openshift and ova:

Guest Credentials

Guest credentials are separate from provider credentials.

The provider username and password fields log in to the source platform itself. The guest_vm_* fields are read later by post-migration SSH or WinRM checks when the destination VM is powered on. If those checks run and the matching guest credentials are missing, validation fails.

This matters even if the shipped example for a provider does not show guest credentials. The loader keeps extra keys, so you can add guest_vm_linux_* and guest_vm_win_* to a vsphere, ovirt, openstack, ova, or hyperv provider entry when your selected tests need them. The openshift entry is the exception: its schema block sets additionalProperties: false, so guest credential keys there fail schema validation in your editor and must be left out.

Tip: Think of guest_vm_linux_* and guest_vm_win_* as per-guest test credentials, not part of the provider login.

SSL Behavior

Source-provider SSL behavior is controlled in tests/tests_config/config.py, not inside .providers.json:

insecure_verify_skip: str = "true"  # SSL verification for OCP API connections
source_provider_insecure_skip_verify: str = "false"  # SSL verification for source provider (VMware, RHV, etc.)

Key points:

• source_provider_insecure_skip_verify controls the source provider Secret created for vSphere, RHV, OpenStack, and Hyper-V.
• insecure_verify_skip is for OpenShift API connections and does not control source provider validation.

• These settings are stored as strings, so use "true" or "false". When source_provider_insecure_skip_verify is "false", the harness fetches a CA certificate from fqdn and stores it in the provider Secret for vSphere, OpenStack, and Hyper-V.

• RHV is special: the code always fetches the CA certificate, even when verification is skipped, because the ImageIO path still needs it. It is stored under cacert by default.

• OpenShift is also special: the source provider reuses the current cluster token Secret, which is created with insecureSkipVerify: "true".
• OVA has no CA download step.

Note: Secure mode only works if fqdn points to a host that serves the provider certificate on the expected port. If the certificate fetch fails, provider creation fails.

vSphere

Example from .providers.json.example:

"vsphere": {
  "type": "vsphere",
  "version": "<SERVER VERSION>",
  "fqdn": "SERVER FQDN/IP",
  "api_url": "<SERVER FQDN/IP>/sdk",
  "username": "USERNAME",
  "password": "PASSWORD",  # pragma: allowlist secret
  "guest_vm_linux_user": "LINUX VMS USERNAME",
  "guest_vm_linux_password": "LINUX VMS PASSWORD",  # pragma: allowlist secret
  "guest_vm_win_user": "WINDOWS VMS USERNAME",
  "guest_vm_win_password": "WINDOWS VMS PASSWORD",  # pragma: allowlist secret
  "luks_passphrase": "LUKS DISK ENCRYPTION PASSPHRASE",  # pragma: allowlist secret
  "vddk_init_image": "<PATH TO VDDK INIT IMAGE>",
  "endpoint_type": "vcenter",
}

What matters for vSphere:

• fqdn is used for the direct vSphere connection.
• In secure mode the API URL is normalized for TLS before the certificate is downloaded.
• vddk_init_image is passed to the MTV Provider resource when present.
• endpoint_type maps to sdkEndpoint in the MTV Provider resource settings. Use "esxi" for direct ESXi host connections.
• luks_passphrase here is the provider-level fallback. A per-VM luks_passphrase in the test plan config takes precedence.

ESXi cloning via clone_provider

ESXi hosts do not support the CloneVM_Task API. That is a vCenter-only operation. To enable VM cloning for test isolation when the source provider is an ESXi host, configure clone_provider so the harness can reach a vCenter entry that performs the clone.

How it works:

• The clone_provider value must match a top-level key in .providers.json.
• A missing key fails with a ValueError that lists the available provider names.
• The referenced entry must be a vSphere provider.
• When clone_provider is set, the harness creates a separate VMWareProvider connection to that vCenter and uses it for cloning operations.
• If clone_provider is not set, the harness uses the source provider for cloning. That works for vCenter entries but will fail for ESXi.

ESXi provider example:

"vsphere-esxi": {
  "type": "vsphere",
  "version": "<SERVER VERSION>",
  "fqdn": "ESXI HOST FQDN/IP",
  "api_url": "<ESXI HOST FQDN/IP>/sdk",
  "username": "USERNAME",
  "password": "PASSWORD",
  "endpoint_type": "esxi",
  "vddk_init_image": "<PATH TO VDDK INIT IMAGE>",
  "clone_provider": "vsphere"
}

Here "clone_provider": "vsphere" references the "vsphere" entry shown earlier, which must be a vCenter that manages ESXI HOST FQDN/IP.

Tip: Keep a separate vSphere entry for copy-offload, like the example's vsphere-copy-offload. That makes it easy to switch between regular and copy-offload runs by changing only source_provider.

vSphere copy-offload

The copyoffload block is only meaningful for vSphere entries. The code validates it before copy-offload tests run, uses it to build the storage Secret, and passes that Secret into the vsphereXcopyConfig storage-map plugin configuration.

Required fields

The schema requires exactly two fields, and the copy-offload fixture re-validates both at runtime:

Supported storage_vendor_product values:

Warning: These values are fixed in code. Use the exact spellings above.

Vendor-specific required fields

The schema requires extra fields for some vendors, and the copy-offload fixture raises when a required vendor field is missing:

Optional fields

resource_pool selection priority order:

1. The configured resource_pool value.
2. The target ESXi host's pool, when target_esxi_host is set on the clone options.
3. The source VM's or template's pool.
4. A cluster-wide search with a datastore compatibility check.

dedicated_migration_hosts must be a non-empty list of non-empty strings. When more than one host is listed, Forklift selects one at random per disk. Dedicated-host tests raise a ValueError when this field is missing.

Tip: Every copy-offload credential can come from an environment variable instead of the file, and environment variables win. Names are built as COPYOFFLOAD_<FIELD_IN_UPPERCASE>, so examples include COPYOFFLOAD_STORAGE_HOSTNAME, COPYOFFLOAD_STORAGE_USERNAME, COPYOFFLOAD_STORAGE_PASSWORD, COPYOFFLOAD_ONTAP_SVM, COPYOFFLOAD_ESXI_HOST, COPYOFFLOAD_ESXI_USER, and COPYOFFLOAD_ESXI_PASSWORD. storage_secret_extra has its own JSON-object override, COPYOFFLOAD_STORAGE_SECRET_EXTRA.

RHV / oVirt

The RHV source path uses type: "ovirt".

Example from .providers.json.example:

"ovirt": {
  "type": "ovirt",
  "version": "<SERVER VERSION>",
  "fqdn": "SERVER FQDN/IP",
  "api_url": "<SERVER FQDN/IP>/ovirt-engine/api",
  "username": "USERNAME",
  "password": "PASSWORD"  # pragma: allowlist secret
}

What matters for RHV:

• Use type: "ovirt" even if you think of the source as RHV.
• fqdn should point to the engine host, because the CA certificate is fetched from it.
• The RHV provider also expects a data center named MTV-CNV to exist with status up. That is not configurable in .providers.json, but it is enforced during connection.

Note: RHV is the one provider where the harness always downloads the CA certificate. In secure mode it is used for SDK validation; in insecure mode it is still carried because the ImageIO flow needs it.

OpenStack

Example from .providers.json.example:

"openstack": {
  "type": "openstack",
  "version": "SERVER VERSION",
  "fqdn": "SERVER FQDN/IP",
  "api_url": "<SERVER FQDN/IP>:<PORT>/v3",
  "username": "USERNAME",
  "password": "PASSWORD",  # pragma: allowlist secret
  "user_domain_name": "<DOMAIN>",
  "region_name": "<REGION>",
  "project_name": "<PROJECT>",
  "user_domain_id": "<USER DOMAIN ID>",
  "project_domain_id": "PROJECT DOMAIN ID",
  "guest_vm_linux_user": "LINUX VMS USERNAME",
  "guest_vm_linux_password": "LINUX VMS PASSWORD"  # pragma: allowlist secret
}

What matters for OpenStack:

• project_name, user_domain_name, region_name, user_domain_id, and project_domain_id are all passed to the provider. All five are required by the schema.
• fqdn still matters in secure mode because the harness fetches a CA certificate from it.

OpenShift

Example from .providers.json.example:

"openshift": {
  "type": "openshift",
  "version": "<SERVER VERSION>",
  "host": "<CLUSTER API URL>",
  "api_url": "<CLUSTER API URL>",
  "username": "<USERNAME>",
  "password": "<PASSWORD>",  # pragma: allowlist secret
  "storage_class": "<STORAGE CLASS NAME>"
}

What matters for OpenShift:

• Keep the placeholder shape from the example; openshift entries allow no extra keys.
• The OpenShift source provider does not use these values to log in. The code rewrites api_url to the current cluster host and reuses the current cluster token Secret.
• Because this provider block sets additionalProperties: false, do not add guest credential keys here. Use a separate source provider entry if your tests need them.
• The schema requires host and storage_class, but the loader never reads them. Target storage comes from the runtime storage_class value passed with --tc.

Note: The reused OpenShift Secret is created with insecureSkipVerify: "true", so source_provider_insecure_skip_verify does not affect OpenShift the same way it affects vSphere, RHV, OpenStack, or Hyper-V.

OVA

Example from .providers.json.example:

"ova": {
  "type": "ova",
  "version": "<SERVER VERSION>", # Can be anything, just placeholder
  "fqdn": "",
  "api_url": "<NFS SHARE URL>",
  "username": "<USERNAME>",
  "password": ""  # pragma: allowlist secret
}

What matters for OVA:

• api_url is the NFS share URL and the only field the OVA provider consumes for its connection.
• version is used for naming, not protocol negotiation.
• fqdn, username, and password must still be present because the loader reads them for every provider type.
• OVA source VMs are never cloned. The test flow requires each plan VM name to match an existing OVA file.
• There is no CA download step for OVA.

Hyper-V

Example from .providers.json.example:

"hyperv": {
  "type": "hyperv",
  "version": "2025",
  "fqdn": "hyperv-host.example.com",
  "api_url": "hyperv-host.example.com",
  "username": "Administrator",
  "password": "PASSWORD",  # pragma: allowlist secret
  "smb_url": "//hyperv-host.example.com/VMShare",
  "smb_user": "",  # Optional: SMB username if different from provider credentials
  "smb_password": "",  # pragma: allowlist secret  # Optional: SMB password if different from provider credentials
  "guest_vm_linux_user": "root",
  "guest_vm_linux_password": "PASSWORD",  # pragma: allowlist secret
  "guest_vm_win_user": "Administrator",
  "guest_vm_win_password": "PASSWORD"  # pragma: allowlist secret
}

What matters for Hyper-V:

• smb_url is required by the schema and is what the provider uses to transfer VM disks.
• smb_user and smb_password are optional. When present and non-empty they become the smbUser and smbPassword Secret keys.
• In secure mode the CA certificate is fetched from fqdn on port 5986.
• Hyper-V guest OS detection can be overridden per VM with the win_os key in the test plan config.

Practical Checklist

• Start from .providers.json.example, then remove all comments before saving the real .providers.json.
• Validate your editor against the providers_schema.json URL in the $schema key.
• Make sure your source_provider setting matches a top-level key in the file.
• Keep fqdn accurate for vSphere, RHV, OpenStack, and Hyper-V, especially if SSL verification is enabled.
• Add guest credentials for any provider entry whose powered-on guests will be validated over SSH or WinRM.
• For vSphere copy-offload, populate both the common storage credentials and the vendor-specific fields required by your chosen storage_vendor_product.
• Remember that OpenShift is the only provider type that rejects unknown keys.