Presets¶
FEATURE STATE:
VirtualMachineInstancePresets
are deprecated as of thev0.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:
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 allinstances. * 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
:
would match
or
Using matchExpressions allows for matching multiple labels of
VirtualMachineInstances
without needing to explicity list a label.
would match both:
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