openapi: 3.1.0
info:
  title: KubeVirt Containerized Data Importer DataSources VirtualMachineInstances API
  description: The KubeVirt Containerized Data Importer (CDI) API provides Kubernetes CRD endpoints for managing virtual machine disk image import and cloning pipelines. CDI introduces DataVolume, DataSource, and StorageProfile resources that automate importing VM disk images from HTTP, S3, OCI registries, and other sources into PersistentVolumeClaims ready for use as KubeVirt VM disks.
  version: 1.59.0
  contact:
    name: KubeVirt Community
    url: https://kubevirt.io/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://{kubernetes-api-server}
  description: Kubernetes API server
  variables:
    kubernetes-api-server:
      default: localhost:6443
      description: Address of the Kubernetes API server
tags:
- name: VirtualMachineInstances
  description: Operations for managing VirtualMachineInstance (VMI) resources. A VirtualMachineInstance represents a running virtual machine and tracks its actual state.
paths:
  /apis/kubevirt.io/v1/namespaces/{namespace}/virtualmachineinstances:
    get:
      operationId: listNamespacedVirtualMachineInstance
      summary: KubeVirt List VirtualMachineInstances
      description: Returns all running VirtualMachineInstance resources in the specified namespace. Each VMI represents an active virtual machine process.
      tags:
      - VirtualMachineInstances
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/labelSelector'
      - $ref: '#/components/parameters/fieldSelector'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: List of VirtualMachineInstances
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualMachineInstanceList'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /apis/kubevirt.io/v1/namespaces/{namespace}/virtualmachineinstances/{name}:
    get:
      operationId: readNamespacedVirtualMachineInstance
      summary: KubeVirt Get a VirtualMachineInstance
      description: Returns the specified VirtualMachineInstance including its phase, network interfaces, volumes, node assignment, and guest OS information.
      tags:
      - VirtualMachineInstances
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/name'
      responses:
        '200':
          description: VirtualMachineInstance details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualMachineInstance'
        '401':
          description: Unauthorized
        '404':
          description: VirtualMachineInstance not found
components:
  schemas:
    ObjectMeta:
      type: object
      description: Standard Kubernetes object metadata.
      required:
      - name
      properties:
        name:
          type: string
          description: Name of the resource.
        namespace:
          type: string
          description: Namespace the resource belongs to.
        labels:
          type: object
          additionalProperties:
            type: string
          description: Labels for organizing and selecting resources.
        annotations:
          type: object
          additionalProperties:
            type: string
          description: Non-identifying metadata.
        resourceVersion:
          type: string
        uid:
          type: string
        creationTimestamp:
          type: string
          format: date-time
    VirtualMachineInstanceSpec:
      type: object
      description: Specification of the virtual machine hardware and guest configuration.
      properties:
        domain:
          $ref: '#/components/schemas/DomainSpec'
        networks:
          type: array
          description: Network interfaces to attach to the VM.
          items:
            $ref: '#/components/schemas/Network'
        volumes:
          type: array
          description: Volumes to attach to the VM.
          items:
            $ref: '#/components/schemas/Volume'
        affinity:
          type: object
          description: Kubernetes affinity rules for pod scheduling.
        tolerations:
          type: array
          description: Kubernetes tolerations for node scheduling.
          items:
            type: object
        nodeSelector:
          type: object
          additionalProperties:
            type: string
          description: Node selector constraints for VM placement.
        hostname:
          type: string
          description: Hostname to set in the guest OS.
        subdomain:
          type: string
          description: Subdomain for the VM's DNS entry.
        terminationGracePeriodSeconds:
          type: integer
          description: Grace period in seconds before forceful VM termination.
          minimum: 0
        evictionStrategy:
          type: string
          description: Controls how the VM behaves during node eviction. 'LiveMigrate' migrates instead of stopping.
          enum:
          - LiveMigrate
          - None
    Interface:
      type: object
      description: A virtual network interface device.
      required:
      - name
      properties:
        name:
          type: string
          description: Name of the interface, must match a network name.
        model:
          type: string
          description: Network interface model type. 'virtio' is recommended for best performance.
          enum:
          - virtio
          - e1000
          - e1000e
          - rtl8139
        masquerade:
          type: object
          description: NAT masquerade networking mode.
        bridge:
          type: object
          description: Bridge networking mode, connected to a host bridge.
        sriov:
          type: object
          description: SR-IOV passthrough networking mode.
        macAddress:
          type: string
          description: Fixed MAC address for the interface.
          pattern: ^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$
        ports:
          type: array
          description: Port forwarding rules for masquerade interfaces.
          items:
            type: object
            properties:
              name:
                type: string
              port:
                type: integer
                minimum: 1
                maximum: 65535
              protocol:
                type: string
                enum:
                - TCP
                - UDP
    VirtualMachineInstance:
      type: object
      description: A running VirtualMachineInstance representing the actual state of an active virtual machine process in KubeVirt.
      properties:
        apiVersion:
          type: string
          enum:
          - kubevirt.io/v1
        kind:
          type: string
          enum:
          - VirtualMachineInstance
        metadata:
          $ref: '#/components/schemas/ObjectMeta'
        spec:
          $ref: '#/components/schemas/VirtualMachineInstanceSpec'
        status:
          $ref: '#/components/schemas/VirtualMachineInstanceStatus'
    VirtualMachineInstanceList:
      type: object
      description: List of VirtualMachineInstance resources.
      properties:
        apiVersion:
          type: string
        kind:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/VirtualMachineInstance'
    Volume:
      type: object
      description: A storage volume to attach to a disk device.
      required:
      - name
      properties:
        name:
          type: string
          description: Name of the volume, referenced by disk name.
        containerDisk:
          type: object
          description: OCI container image used as a disk.
          properties:
            image:
              type: string
              description: OCI image reference containing the disk image.
            imagePullPolicy:
              type: string
              enum:
              - Always
              - Never
              - IfNotPresent
        dataVolume:
          type: object
          description: DataVolume (CDI) as a disk source.
          properties:
            name:
              type: string
              description: Name of the DataVolume resource.
        persistentVolumeClaim:
          type: object
          description: Kubernetes PersistentVolumeClaim as a disk source.
          properties:
            claimName:
              type: string
              description: Name of the PVC.
            readOnly:
              type: boolean
        cloudInitNoCloud:
          type: object
          description: Cloud-init NoCloud data source for guest initialization.
          properties:
            userData:
              type: string
              description: Cloud-init user-data as a string.
            networkData:
              type: string
              description: Cloud-init network-config as a string.
        cloudInitConfigDrive:
          type: object
          description: Cloud-init Config Drive data source.
          properties:
            userData:
              type: string
            networkData:
              type: string
        sysprep:
          type: object
          description: Windows Sysprep answer file source.
          properties:
            configMap:
              type: object
              properties:
                name:
                  type: string
        emptyDisk:
          type: object
          description: Ephemeral empty disk created for the VM.
          properties:
            capacity:
              type: string
              description: Disk capacity in Kubernetes resource quantity format.
        hostDisk:
          type: object
          description: Host filesystem path as a disk.
          properties:
            path:
              type: string
              description: Absolute path on the host.
            type:
              type: string
              enum:
              - DiskOrCreate
              - Disk
    Network:
      type: object
      description: A network to attach a VM interface to.
      required:
      - name
      properties:
        name:
          type: string
          description: Name of the network, referenced by interface name.
        pod:
          type: object
          description: Default pod network configuration.
          properties:
            vmNetworkCIDR:
              type: string
              description: CIDR for the VM network in masquerade mode.
        multus:
          type: object
          description: Multus CNI network attachment.
          properties:
            networkName:
              type: string
              description: Name of the NetworkAttachmentDefinition.
            default:
              type: boolean
              description: If true, this is the default network.
    VirtualMachineInstanceStatus:
      type: object
      description: Observed runtime status of a VirtualMachineInstance.
      properties:
        nodeName:
          type: string
          description: Node where the VMI is running.
        guestOSInfo:
          type: object
          description: Information about the guest operating system.
          properties:
            name:
              type: string
              description: OS name reported by the guest agent.
            version:
              type: string
              description: OS version.
            id:
              type: string
              description: OS ID (e.g. 'rhel', 'ubuntu').
            prettyName:
              type: string
              description: Human-readable OS name.
        interfaces:
          type: array
          description: Network interfaces as reported by the guest agent.
          items:
            type: object
            properties:
              name:
                type: string
              mac:
                type: string
              ipAddress:
                type: string
              ipAddresses:
                type: array
                items:
                  type: string
        phase:
          type: string
          description: Current lifecycle phase of the VMI.
          enum:
          - Pending
          - Scheduling
          - Scheduled
          - Running
          - Succeeded
          - Failed
          - Unknown
        phaseTransitionTimestamps:
          type: array
          description: History of phase transitions with timestamps.
          items:
            type: object
            properties:
              phase:
                type: string
              phaseTransitionTimestamp:
                type: string
                format: date-time
        migrationState:
          type: object
          description: Current migration state if the VMI is being migrated.
          properties:
            startTimestamp:
              type: string
              format: date-time
            endTimestamp:
              type: string
              format: date-time
            targetNode:
              type: string
            sourceNode:
              type: string
            completed:
              type: boolean
            failed:
              type: boolean
        conditions:
          type: array
          items:
            type: object
    DomainSpec:
      type: object
      description: Virtual hardware configuration for the VM guest.
      properties:
        cpu:
          type: object
          description: CPU configuration for the VM.
          properties:
            cores:
              type: integer
              description: Number of CPU cores.
              minimum: 1
            sockets:
              type: integer
              description: Number of CPU sockets.
              minimum: 1
            threads:
              type: integer
              description: Number of CPU threads per core.
              minimum: 1
            model:
              type: string
              description: CPU model to emulate, e.g. 'host-model' or 'Westmere'.
            dedicatedCpuPlacement:
              type: boolean
              description: If true, requests dedicated CPU pinning via CPU Manager.
            features:
              type: array
              description: CPU feature flags to enable or disable.
              items:
                type: object
                properties:
                  name:
                    type: string
                  policy:
                    type: string
                    enum:
                    - force
                    - require
                    - optional
                    - disable
                    - forbid
        memory:
          type: object
          description: Memory configuration for the VM.
          properties:
            guest:
              type: string
              description: Amount of memory for the guest OS in Kubernetes resource quantity format, e.g. '2Gi', '512Mi'.
            hugepages:
              type: object
              description: Huge pages configuration.
              properties:
                pageSize:
                  type: string
                  description: Size of huge pages, e.g. '2Mi' or '1Gi'.
        devices:
          type: object
          description: Virtual device configuration.
          properties:
            disks:
              type: array
              description: Disk devices attached to the VM.
              items:
                $ref: '#/components/schemas/Disk'
            interfaces:
              type: array
              description: Network interface devices.
              items:
                $ref: '#/components/schemas/Interface'
            rng:
              type: object
              description: Random number generator device configuration.
            watchdog:
              type: object
              description: Hardware watchdog device configuration.
        features:
          type: object
          description: Hardware feature flags for the VM.
          properties:
            acpi:
              type: object
              description: ACPI configuration.
            smm:
              type: object
              description: System Management Mode configuration.
            hyperv:
              type: object
              description: Hyper-V enlightenments for Windows VMs.
        firmware:
          type: object
          description: Firmware configuration for the VM.
          properties:
            bootloader:
              type: object
              description: Bootloader configuration (BIOS or UEFI).
              properties:
                bios:
                  type: object
                  description: BIOS bootloader.
                efi:
                  type: object
                  description: EFI/UEFI bootloader.
                  properties:
                    secureBoot:
                      type: boolean
                      description: If true, enables Secure Boot.
            serial:
              type: string
              description: Serial number to expose to the guest.
            uuid:
              type: string
              format: uuid
              description: SMBIOS UUID for the VM.
        machine:
          type: object
          description: Machine type configuration.
          properties:
            type:
              type: string
              description: Machine type, e.g. 'q35' or 'pc-q35-rhel8.4.0'.
    Disk:
      type: object
      description: A virtual disk device attached to the VM.
      required:
      - name
      properties:
        name:
          type: string
          description: Name of the disk, must match a volume name.
        bootOrder:
          type: integer
          description: Boot order for this disk (lower numbers boot first).
          minimum: 1
        disk:
          type: object
          description: Virtio disk configuration.
          properties:
            bus:
              type: string
              enum:
              - virtio
              - sata
              - scsi
              - ide
        cdrom:
          type: object
          description: CD-ROM device configuration.
          properties:
            bus:
              type: string
              enum:
              - virtio
              - sata
              - scsi
            readonly:
              type: boolean
        lun:
          type: object
          description: LUN device configuration.
          properties:
            bus:
              type: string
  parameters:
    labelSelector:
      name: labelSelector
      in: query
      required: false
      description: Label selector to filter resources.
      schema:
        type: string
    limit:
      name: limit
      in: query
      required: false
      description: Maximum number of results per page.
      schema:
        type: integer
        minimum: 1
    namespace:
      name: namespace
      in: path
      required: true
      description: The Kubernetes namespace of the resource.
      schema:
        type: string
    fieldSelector:
      name: fieldSelector
      in: query
      required: false
      description: Field selector to filter resources.
      schema:
        type: string
    name:
      name: name
      in: path
      required: true
      description: The name of the resource.
      schema:
        type: string
externalDocs:
  description: CDI Documentation
  url: https://kubevirt.io/user-guide/storage/containerized_data_importer/