Presets¶

FEATURE STATE:

VirtualMachineInstancePresets are deprecated as of the v0.57.0 release and will be removed in a future release.
Users should instead look to use Instancetypes and preferences as a replacement.

VirtualMachineInstancePresets are an extension to general VirtualMachineInstance configuration behaving much like PodPresets from Kubernetes. When a VirtualMachineInstance is created, any applicable VirtualMachineInstancePresets will be applied to the existing spec for the VirtualMachineInstance. This allows for re-use of common settings that should apply to multiple VirtualMachineInstances.

Create a VirtualMachineInstancePreset¶

You can describe a VirtualMachineInstancePreset in a YAML file. For example, the vmi-preset.yaml file below describes a VirtualMachineInstancePreset that requests a VirtualMachineInstance be created with a resource request for 64M of RAM.

apiVersion: kubevirt.io/v1
kind: VirtualMachineInstancePreset
metadata:
  name: small-qemu
spec:
  selector:
    matchLabels:
      kubevirt.io/size: small
  domain:
    resources:
      requests:
        memory: 64M

Create a VirtualMachineInstancePreset based on that YAML file:

    kubectl create -f vmipreset.yaml

Required Fields¶

As with most Kubernetes resources, a VirtualMachineInstancePreset requires apiVersion, kind and metadata fields.

Additionally VirtualMachineInstancePresets also need a spec section. While not technically required to satisfy syntax, it is strongly recommended to include a Selector in the spec section, otherwise a VirtualMachineInstancePreset will match all VirtualMachineInstances in a namespace.

VirtualMachine Selector¶

KubeVirt uses Kubernetes Labels and Selectors to determine which VirtualMachineInstancePresets apply to a given VirtualMachineInstance, similarly to how PodPresets work in Kubernetes. If a setting from a VirtualMachineInstancePreset is applied to a VirtualMachineInstance, the VirtualMachineInstance will be marked with an Annotation upon completion.

Any domain structure can be listed in the spec of a VirtualMachineInstancePreset, e.g. Clock, Features, Memory, CPU, or Devices such as network interfaces. All elements of the spec section of a VirtualMachineInstancePreset will be applied to the VirtualMachineInstance.

Once a VirtualMachineInstancePreset is successfully applied to a VirtualMachineInstance, the VirtualMachineInstance will be marked with an annotation to indicate that it was applied. If a conflict occurs while a VirtualMachineInstancePreset is being applied, that portion of the VirtualMachineInstancePreset will be skipped.

Any valid Label can be matched against, but it is suggested that a general rule of thumb is to use os/shortname, e.g. kubevirt.io/os: rhel7.

Updating a VirtualMachineInstancePreset¶

If a VirtualMachineInstancePreset is modified, changes will not be applied to existing VirtualMachineInstances. This applies to both the Selector indicating which VirtualMachineInstances should be matched, and also the Domain section which lists the settings that should be applied to a VirtualMachine.

Overrides¶

VirtualMachineInstancePresets use a similar conflict resolution strategy to Kubernetes PodPresets. If a portion of the domain spec is present in both a VirtualMachineInstance and a VirtualMachineInstancePreset and both resources have the identical information, then creation of the VirtualMachineInstance will continue normally. If however there is a difference between the resources, an Event will be created indicating which DomainSpec element of which VirtualMachineInstancePreset was overridden. For example: If both the VirtualMachineInstance and VirtualMachineInstancePreset define a CPU, but use a different number of Cores, KubeVirt will note the difference.

If any settings from the VirtualMachineInstancePreset were successfully applied, the VirtualMachineInstance will be annotated.

In the event that there is a difference between the Domains of a VirtualMachineInstance and VirtualMachineInstancePreset, KubeVirt will create an Event. kubectl get events can be used to show all Events. For example:

    $ kubectl get events
    ....
    Events:
      FirstSeen                         LastSeen                        Count From                              SubobjectPath                Reason    Message
      2m          2m           1         myvmi.1515bbb8d397f258                       VirtualMachineInstance                                     Warning   Conflict                  virtualmachineinstance-preset-controller   Unable to apply VirtualMachineInstancePreset 'example-preset': spec.cpu: &{6} != &{4}

Usage¶

VirtualMachineInstancePresets are namespaced resources, so should be created in the same namespace as the VirtualMachineInstances that will use them:

kubectl create -f <preset>.yaml [--namespace <namespace>]

KubeVirt will determine which VirtualMachineInstancePresets apply to a Particular VirtualMachineInstance by matching Labels. For example:

apiVersion: kubevirt.io/v1
kind: VirtualMachineInstancePreset
metadata:
  name: example-preset
  selector:
    matchLabels:
      kubevirt.io/os: win10
  ...

would match any VirtualMachineInstance in the same namespace with a Label of flavor: foo. For example:

apiVersion: kubevirt.io/v1
kind: VirtualMachineInstance
version: v1
metadata:
  name: myvmi
  labels:
    kubevirt.io/os: win10
  ...

Conflicts¶

When multiple VirtualMachineInstancePresets match a particular VirtualMachineInstance, if they specify the same settings within a Domain, those settings must match. If two VirtualMachineInstancePresets have conflicting settings (e.g. for the number of CPU cores requested), an error will occur, and the VirtualMachineInstance will enter the Failed state, and a Warning event will be emitted explaining which settings of which VirtualMachineInstancePresets were problematic.

Matching Multiple `VirtualMachineInstances`¶

The main use case for VirtualMachineInstancePresets is to create re-usable settings that can be applied across various machines. Multiple methods are available to match the labels of a VirtualMachineInstance using selectors.

matchLabels: Each VirtualMachineInstance can use a specific label shared by all

instances. * matchExpressions: Logical operators for sets can be used to match multiple

labels.

Using matchLabels, the label used in the VirtualMachineInstancePreset must match one of the labels of the VirtualMachineInstance:

selector:
  matchLabels:
    kubevirt.io/memory: large

would match

metadata:
  labels:
    kubevirt.io/memory: large
    kubevirt.io/os: win10

or

metadata:
  labels:
    kubevirt.io/memory: large
    kubevirt.io/os: fedora27

Using matchExpressions allows for matching multiple labels of VirtualMachineInstances without needing to explicity list a label.

selector:
  matchExpressions:
    - {key: kubevirt.io/os, operator: In, values: [fedora27, fedora26]}

would match both:

metadata:
  labels:
    kubevirt.io/os: fedora26

metadata:
  labels:
    kubevirt.io/os: fedora27

The Kubernetes documentation has a detailed explanation. Examples are provided below.

Exclusions¶

Since VirtualMachineInstancePresets use Selectors that indicate which VirtualMachineInstances their settings should apply to, there needs to exist a mechanism by which VirtualMachineInstances can opt out of VirtualMachineInstancePresets altogether. This is done using an annotation:

kind: VirtualMachineInstance
version: v1
metadata:
  name: myvmi
  annotations:
    virtualmachineinstancepresets.admission.kubevirt.io/exclude: "true"
  ...

Examples¶

Simple `VirtualMachineInstancePreset` Example¶

apiVersion: kubevirt.io/v1
kind: VirtualMachineInstancePreset
version: v1
metadata:
  name: example-preset
spec:
  selector:
    matchLabels:
      kubevirt.io/os: win10
  domain:
    features:
      acpi: {}
      apic: {}
      hyperv:
        relaxed: {}
        vapic: {}
        spinlocks:
          spinlocks: 8191
---
apiVersion: kubevirt.io/v1
kind: VirtualMachineInstance
version: v1
metadata:
  name: myvmi
  labels:
    kubevirt.io/os: win10
spec:
  domain:
    firmware:
      uuid: c8f99fc8-20f5-46c4-85e5-2b841c547cef

Once the VirtualMachineInstancePreset is applied to the VirtualMachineInstance, the resulting resource would look like this:

apiVersion: kubevirt.io/v1
kind: VirtualMachineInstance
metadata:
  annotations:
    presets.virtualmachineinstances.kubevirt.io/presets-applied: kubevirt.io/v1
    virtualmachineinstancepreset.kubevirt.io/example-preset: kubevirt.io/v1
  labels:
    kubevirt.io/os: win10
    kubevirt.io/nodeName: master
  name: myvmi
  namespace: default
spec:
  domain:
    devices: {}
    features:
      acpi:
        enabled: true
      apic:
        enabled: true
      hyperv:
        relaxed:
          enabled: true
        spinlocks:
          enabled: true
          spinlocks: 8191
        vapic:
          enabled: true
    firmware:
      uuid: c8f99fc8-20f5-46c4-85e5-2b841c547cef
    machine:
      type: q35
    resources:
      requests:
        memory: 8Mi

Conflict Example¶

This is an example of a merge conflict. In this case both the VirtualMachineInstance and VirtualMachineInstancePreset request different number of CPU's.

apiVersion: kubevirt.io/v1
kind: VirtualMachineInstancePreset
version: v1
metadata:
  name: example-preset
spec:
  selector:
    matchLabels:
      kubevirt.io/flavor: default-features
  domain:
    cpu:
      cores: 4
---
apiVersion: kubevirt.io/v1
kind: VirtualMachineInstance
version: v1
metadata:
  name: myvmi
  labels:
    kubevirt.io/flavor: default-features
spec:
  domain:
    cpu:
      cores: 6

In this case the VirtualMachineInstance Spec will remain unmodified. Use kubectl get events to show events.

apiVersion: kubevirt.io/v1
kind: VirtualMachineInstance
metadata:
  annotations:
    presets.virtualmachineinstances.kubevirt.io/presets-applied: kubevirt.io/v1
  generation: 0
  labels:
    kubevirt.io/flavor: default-features
  name: myvmi
  namespace: default
spec:
  domain:
    cpu:
      cores: 6
    devices: {}
    machine:
      type: ""
    resources: {}
status: {}

Calling kubectl get events would have a line like:

2m 2m 1 myvmi.1515bbb8d397f258 VirtualMachineInstance Warning Conflict virtualmachineinstance-preset-controller Unable to apply VirtualMachineInstancePreset example-preset: spec.cpu: &{6} != &{4}

Matching Multiple VirtualMachineInstances Using MatchLabels¶

These VirtualMachineInstances have multiple labels, one that is unique and one that is shared.

Note: This example breaks from the convention of using os-shortname as a Label for demonstration purposes.

apiVersion: kubevirt.io/v1
kind: VirtualMachineInstancePreset
metadata:
  name: twelve-cores
spec:
  selector:
    matchLabels:
      kubevirt.io/cpu: dodecacore
  domain:
    cpu:
      cores: 12
---
apiVersion: kubevirt.io/v1
kind: VirtualMachineInstance
metadata:
  name: windows-10
  labels:
    kubevirt.io/os: win10
    kubevirt.io/cpu: dodecacore
spec:
---
apiVersion: kubevirt.io/v1
kind: VirtualMachineInstance
metadata:
  name: windows-7
  labels:
    kubevirt.io/os: win7
    kubevirt.io/cpu: dodecacore
spec:
  terminationGracePeriodSeconds: 0

Adding this VirtualMachineInstancePreset and these VirtualMachineInstances will result in:

apiVersion: kubevirt.io/v1
kind: VirtualMachineInstance
metadata:
  annotations:
    presets.virtualmachineinstances.kubevirt.io/presets-applied: kubevirt.io/v1
    virtualmachineinstancepreset.kubevirt.io/twelve-cores: kubevirt.io/v1
  labels:
    kubevirt.io/cpu: dodecacore
    kubevirt.io/os: win10
  name: windows-10
spec:
  domain:
    cpu:
      cores: 12
    devices: {}
    resources:
      requests:
        memory: 4Gi
---
apiVersion: kubevirt.io/v1
kind: VirtualMachineInstance
metadata:
  annotations:
    presets.virtualmachineinstances.kubevirt.io/presets-applied: kubevirt.io/v1
    virtualmachineinstancepreset.kubevirt.io/twelve-cores: kubevirt.io/v1
  labels:
    kubevirt.io/cpu: dodecacore
    kubevirt.io/os: win7
  name: windows-7
spec:
  domain:
    cpu:
      cores: 12
    devices: {}
    resources:
      requests:
        memory: 4Gi
  terminationGracePeriodSeconds: 0

Matching Multiple VirtualMachineInstances Using MatchExpressions¶

This VirtualMachineInstancePreset has a matchExpression that will match two labels: kubevirt.io/os: win10 and kubevirt.io/os: win7.

apiVersion: kubevirt.io/v1
kind: VirtualMachineInstancePreset
metadata:
  name: windows-vmis
spec:
  selector:
    matchExpressions:
      - {key: kubevirt.io/os, operator: In, values: [win10, win7]}
  domain:
    resources:
      requests:
        memory: 128M
---
apiVersion: kubevirt.io/v1
kind: VirtualMachineInstance
metadata:
  name: smallvmi
  labels:
    kubevirt.io/os: win10
spec:
  terminationGracePeriodSeconds: 60
---
apiVersion: kubevirt.io/v1
kind: VirtualMachineInstance
metadata:
  name: largevmi
  labels:
    kubevirt.io/os: win7
spec:
  terminationGracePeriodSeconds: 120

Applying the preset to both VM's will result in:

apiVersion: v1
items:
- apiVersion: kubevirt.io/v1
  kind: VirtualMachineInstance
  metadata:
    annotations:
      presets.virtualmachineinstances.kubevirt.io/presets-applied: kubevirt.io/v1
      virtualmachineinstancepreset.kubevirt.io/windows-vmis: kubevirt.io/v1
    labels:
      kubevirt.io/os: win7
    name: largevmi
  spec:
    domain:
      resources:
        requests:
          memory: 128M
    terminationGracePeriodSeconds: 120
- apiVersion: kubevirt.io/v1
  kind: VirtualMachineInstance
  metadata:
    annotations:
      presets.virtualmachineinstances.kubevirt.io/presets-applied: kubevirt.io/v1
      virtualmachineinstancepreset.kubevirt.io/windows-vmis: kubevirt.io/v1
    labels:
      kubevirt.io/os: win10
    name: smallvmi
  spec:
    domain:
      resources:
        requests:
          memory: 128M
    terminationGracePeriodSeconds: 60