libvmi

package
v1.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 10, 2025 License: Apache-2.0 Imports: 10 Imported by: 0

README

libvmi

libvmi is a VMI manifest composer.

Overview

Motivation

While reading code, especially test code, a difficulty has been observed to understand in an easy and clear manner, what is the content of a VMI object. In a long chain of function call stack, different portions of the VMI got updated, sometime overriding previously set fields.

Goal
  • Simplify the creation of VMI objects.
  • Easily understand what VMI objects contain.

How

libvmi is aimed to build the vmi manifest.

It uses the builder pattern, allowing a modular construction of VMI different sections.

Rules

In order to keep the package useful and easy to maintain, a few rules are in order.

The main goal of these rules are to keep the package simple to use and easy to grow. While exceptions may apply, they will need a wide consensus and should not be overused. It would be better to just ask to change the rules.

  • Use only the existing builder pattern to support editing fields.
  • Place builders in a proper subject file, either one that exists or in a new one with a good name. A common developer should be able to find the relevant content based on the file name.
    • Do not fill up the vmi.go file, unless you have a very good reason.
  • Do not add logic in builders, unless they fell into these categories:
    • It is a factory that is widely used. (e.g. amount of memory depending on the architecture).
    • It is a widely used abstraction that combines several fields that have some dependency on each other.
  • Any builder can be added if it has no logic (except for lazy creation of the path to the relevant fields). In practice, this implies that even builders that are used by a small amount of callers can be added, as long as they do not possess logic.
  • Do not add commands on objects, e.g. calls through clients.
  • Building general annotations or labels which have special meaning are a fit if they related to VM or VMI objects. To clarify, annotation that relate to pods, are not a perfect fit here. Annotations that relate to a specific subject (e.g. network) may fit here or under a more dedicated library/package.

Note: A builder is considered widely used when it is needed from multiple packages. In case a single package or test file is using it, it may fit better under that package or test. The reason is simple, it has more context closer to the usage and known by the developers in a more accurate manner.

Structure
  • VMI: vmi.go contains the most basic tooling to start building VMI manifests. It contains the most basic factory (New), the definition of how the builders look like and any other helper that serves the whole libvmi package.
  • Subject builders: Various files in which builders and defined. These files should group builders with some commonality, such that they can be easily found. With time, the grouping and naming may change (e.g. subjects split when they grow too much).

Maintenance and Ownership

Maintainers are expected to follow the above rules or ask for exceptions. Possibly asking to change a rule with a good reasoning.

Make sure to always keep things in focus, simple and clean. When things get out of control, things get slower, not faster.

Documentation

Index

Constants

View Source 
const CloudInitDiskName = "cloudinitdisk"

Variables

This section is empty.

Functions

func GetCloudInitVolume added in v1.4.0 

func GetCloudInitVolume(vmi *v1.VirtualMachineInstance) *v1.Volume

func InterfaceDeviceWithBridgeBinding 

func InterfaceDeviceWithBridgeBinding(name string) kvirtv1.Interface

InterfaceDeviceWithBridgeBinding returns an Interface with bridge binding.

func InterfaceDeviceWithMasqueradeBinding 

func InterfaceDeviceWithMasqueradeBinding(ports ...kvirtv1.Port) kvirtv1.Interface

InterfaceDeviceWithMasqueradeBinding returns an Interface named "default" with masquerade binding.

func InterfaceDeviceWithSRIOVBinding 

func InterfaceDeviceWithSRIOVBinding(name string) kvirtv1.Interface

InterfaceDeviceWithSRIOVBinding returns an Interface with SRIOV binding.

func InterfaceWithBindingPlugin 

func InterfaceWithBindingPlugin(name string, binding kvirtv1.PluginBinding, ports ...kvirtv1.Port) kvirtv1.Interface

func InterfaceWithMac 

func InterfaceWithMac(iface *kvirtv1.Interface, macAddress string) *kvirtv1.Interface

InterfaceWithMac decorates an existing Interface with a MAC address.

func InterfaceWithMacvtapBindingPlugin 

func InterfaceWithMacvtapBindingPlugin(name string) *kvirtv1.Interface

InterfaceWithMacvtapBindingPlugin returns an Interface named "default" with "macvtap" binding plugin.

func InterfaceWithPasstBindingPlugin 

func InterfaceWithPasstBindingPlugin(ports ...kvirtv1.Port) kvirtv1.Interface

InterfaceWithPasstBinding returns an Interface named "default" with passt binding plugin.

func MultusNetwork 

func MultusNetwork(name, nadName string) *kvirtv1.Network

MultusNetwork returns a Network with the given name, associated to the given nad

func New 

func New(opts ...Option) *v1.VirtualMachineInstance

New instantiates a new VMI configuration, building its properties based on the specified With* options.

func NewVirtualMachine 

func NewVirtualMachine(vmi *v1.VirtualMachineInstance, opts ...VMOption) *v1.VirtualMachine

func RegisterDefaultOption 

func RegisterDefaultOption(opt Option)

Types

type DiskOption added in v1.5.0 

type DiskOption func(vm *v1.Disk)

func WithDedicatedIOThreads added in v1.5.0 

func WithDedicatedIOThreads(enabled bool) DiskOption

type Option 

type Option func(vmi *v1.VirtualMachineInstance)

Option represents an action that enables an option.

func WithAccessCredentialSSHPublicKey added in v1.4.0 

func WithAccessCredentialSSHPublicKey(secretName, userName string) Option

WithAccessCredentialSSHPublicKey adds an AccessCredential that propagates the public keys found in secretName to the authorized_keys file of the user with name userName via the qemu-guest-agent.

func WithAccessCredentialUserPassword added in v1.4.0 

func WithAccessCredentialUserPassword(secretName string) Option

WithAccessCredentialUserPassword adds an AccessCredential that propagates the user passwords found in secretName via the qemu-guest-agent.

func WithAnnotation 

func WithAnnotation(key, value string) Option

WithAnnotation adds an annotation with specified value

func WithArchitecture 

func WithArchitecture(arch string) Option

func WithAutoAttachPodInterface added in v1.4.0 

func WithAutoAttachPodInterface(enabled bool) Option

WithAutoAttachPodInterface sets the autoattachPodInterface parameter.

func WithCDRom 

func WithCDRom(cdRomName string, bus v1.DiskBus, claimName string) Option

WithCDRom specifies a CDRom drive backed by a PVC to be used.

func WithCDRomAndVolume added in v1.5.0 

func WithCDRomAndVolume(bus v1.DiskBus, volume v1.Volume) Option

WithCDRomAndVolume specifies a CDRom drive backed by given volume and given bus.

func WithCPUCount 

func WithCPUCount(cores, threads, sockets uint32) Option

func WithCPUFeature 

func WithCPUFeature(featureName, policy string) Option

func WithCPUModel 

func WithCPUModel(model string) Option

func WithCloudInitConfigDrive added in v1.4.0 

func WithCloudInitConfigDrive(opts ...cloudinit.ConfigDriveOption) Option

WithCloudInitConfigDrive adds cloud-init config-drive sources.

func WithCloudInitNoCloud added in v1.4.0 

func WithCloudInitNoCloud(opts ...cloudinit.NoCloudOption) Option

WithCloudInitNoCloud adds cloud-init no-cloud sources.

func WithConfigMapDisk 

func WithConfigMapDisk(configMapName, volumeName string) Option

func WithConfigMapFs 

func WithConfigMapFs(configMapName, volumeName string) Option

func WithContainerDisk 

func WithContainerDisk(diskName, imageName string, options ...DiskOption) Option

WithContainerDisk specifies the disk name and the name of the container image to be used.

func WithContainerDiskAndPullPolicy added in v1.5.0 

func WithContainerDiskAndPullPolicy(diskName, imageName string, imagePullPolicy k8sv1.PullPolicy, diskOpts ...DiskOption) Option

WithContainerDiskAndPullPolicy specifies the disk name, the name of the container image and Pull Policy to be used.

func WithContainerSATADisk added in v1.4.0 

func WithContainerSATADisk(diskName, imageName string, diskOpts ...DiskOption) Option

WithContainerSATADisk specifies the disk name and the name of the container image to be used.

func WithDataVolume 

func WithDataVolume(diskName, pvcName string, diskOpts ...DiskOption) Option

WithDataVolume specifies the name of the DataVolume to be used.

func WithDedicatedCPUPlacement 

func WithDedicatedCPUPlacement() Option

func WithDownwardAPIDisk 

func WithDownwardAPIDisk(name string) Option

func WithDownwardAPIFs 

func WithDownwardAPIFs(name string) Option

func WithDownwardMetricsChannel 

func WithDownwardMetricsChannel() Option

func WithDownwardMetricsVolume 

func WithDownwardMetricsVolume(volumeName string) Option

func WithEmptyDisk 

func WithEmptyDisk(diskName string, bus v1.DiskBus, capacity resource.Quantity, diskOpts ...DiskOption) Option

WithEmptyDisk specifies the name of the EmptyDisk to be used.

func WithEphemeralCDRom 

func WithEphemeralCDRom(cdRomName string, bus v1.DiskBus, claimName string) Option

WithEphemeralCDRom specifies a CDRom drive to be used.

func WithEphemeralPersistentVolumeClaim 

func WithEphemeralPersistentVolumeClaim(diskName, pvcName string, diskOpts ...DiskOption) Option

WithEphemeralPersistentVolumeClaim specifies the name of the Ephemeral.PersistentVolumeClaim to be used.

func WithEvictionStrategy 

func WithEvictionStrategy(evictionStrategy v1.EvictionStrategy) Option

func WithFilesystemDV 

func WithFilesystemDV(dataVolumeName string) Option

WithFilesystemDV specifies a filesystem backed by a DV to be used.

func WithFilesystemPVC 

func WithFilesystemPVC(claimName string) Option

WithFilesystemPVC specifies a filesystem backed by a PVC to be used.

func WithGuestMemory 

func WithGuestMemory(memory string) Option

func WithHostDisk 

func WithHostDisk(diskName, path string, diskType v1.HostDiskType) Option

func WithHostDiskAndCapacity added in v1.5.0 

func WithHostDiskAndCapacity(diskName, path string, diskType v1.HostDiskType, capacity string) Option

func WithHostname 

func WithHostname(hostname string) Option

WithHostname sets the hostname parameter.

func WithHugepages 

func WithHugepages(pageSize string) Option

func WithIOThreads added in v1.5.0 

func WithIOThreads(iothreads v1.DiskIOThreads) Option

func WithIOThreadsPolicy added in v1.4.0 

func WithIOThreadsPolicy(policy v1.IOThreadsPolicy) Option

WithIOThreadsPolicy sets the WithIOThreadPolicy parameter

func WithInterface 

func WithInterface(iface kvirtv1.Interface) Option

WithInterface adds a Domain Device Interface.

func WithKernelBootContainer added in v1.5.0 

func WithKernelBootContainer(imageName string) Option

func WithLabel 

func WithLabel(key, value string) Option

WithLabel sets a label with specified value

func WithLabelledConfigMapDisk 

func WithLabelledConfigMapDisk(configMapName, volumeName, label string) Option

func WithLabelledSecretDisk 

func WithLabelledSecretDisk(secretName, volumeName, label string) Option

func WithLimitCPU 

func WithLimitCPU(value string) Option

WithLimitCPU specifies the VMI CPU limit.

func WithLimitMemory 

func WithLimitMemory(value string) Option

WithLimitMemory specifies the VMI memory limit.

func WithLogSerialConsole added in v1.4.0 

func WithLogSerialConsole(enable bool) Option

func WithMaxGuest 

func WithMaxGuest(memory string) Option

func WithNUMAGuestMappingPassthrough 

func WithNUMAGuestMappingPassthrough() Option

func WithName added in v1.4.0 

func WithName(name string) Option

func WithNamespace 

func WithNamespace(namespace string) Option

func WithNetwork 

func WithNetwork(network *kvirtv1.Network) Option

WithNetwork adds a network object.

func WithNodeAffinityFor 

func WithNodeAffinityFor(nodeName string) Option

func WithNodeAffinityForLabel 

func WithNodeAffinityForLabel(nodeLabelKey, nodeLabelValue string) Option

func WithNodeSelector added in v1.4.0 

func WithNodeSelector(key, value string) Option

WithNodeSelector ensures that the VMI gets scheduled on a node with specified key/value label

func WithNodeSelectorFor 

func WithNodeSelectorFor(nodeName string) Option

WithNodeSelectorFor ensures that the VMI gets scheduled on the specified node

func WithPasstInterfaceWithPort 

func WithPasstInterfaceWithPort() Option

func WithPersistentVolumeClaim 

func WithPersistentVolumeClaim(diskName, pvcName string, diskOpts ...DiskOption) Option

WithPersistentVolumeClaim specifies the name of the PersistentVolumeClaim to be used.

func WithPersistentVolumeClaimLun 

func WithPersistentVolumeClaimLun(diskName, pvcName string, reservation bool) Option

func WithPreferredNodeAffinity 

func WithPreferredNodeAffinity(term k8sv1.PreferredSchedulingTerm) Option

func WithPreferredPodAffinity 

func WithPreferredPodAffinity(term k8sv1.WeightedPodAffinityTerm) Option

func WithRealtimeMask 

func WithRealtimeMask(realtimeMask string) Option

func WithResourceCPU 

func WithResourceCPU(value string) Option

WithResourceCPU specifies the vmi CPU resource.

func WithResourceMemory 

func WithResourceMemory(value string) Option

WithResourceMemory specifies the vmi memory resource.

func WithRng 

func WithRng() Option

WithRng adds `rng` to the vmi devices.

func WithSEV 

func WithSEV(isESEnabled bool) Option

WithSEV adds `launchSecurity` with `sev`.

func WithSEVAttestation 

func WithSEVAttestation() Option

func WithSecretDisk 

func WithSecretDisk(secretName, volumeName string) Option

func WithSecretFs 

func WithSecretFs(secretName, volumeName string) Option

func WithServiceAccountDisk 

func WithServiceAccountDisk(name string) Option

func WithServiceAccountFs 

func WithServiceAccountFs(serviceAccountName, volumeName string) Option

func WithStartStrategy 

func WithStartStrategy(startStrategy v1.StartStrategy) Option

func WithSubdomain 

func WithSubdomain(subdomain string) Option

WithSubdomain sets the subdomain parameter.

func WithSysprepConfigMap added in v1.5.0 

func WithSysprepConfigMap(volumeName, configMapName string) Option

func WithSysprepSecret added in v1.5.0 

func WithSysprepSecret(volumeName, secretName string) Option

func WithTPM added in v1.5.0 

func WithTPM(persistent bool) Option

func WithTablet added in v1.5.0 

func WithTablet(name string, bus v1.InputBus) Option

WithTablet adds tablet device with given name and bus

func WithTerminationGracePeriod 

func WithTerminationGracePeriod(seconds int64) Option

WithTerminationGracePeriod specifies the termination grace period in seconds.

func WithToleration added in v1.4.0 

func WithToleration(toleration k8sv1.Toleration) Option

func WithUefi 

func WithUefi(secureBoot bool) Option

WithUefi configures EFI bootloader and SecureBoot.

func WithWatchdog 

func WithWatchdog(action v1.WatchdogAction) Option

WithWatchdog adds a watchdog to the vmi devices.

func WithoutSerialConsole 

func WithoutSerialConsole() Option

type VMOption 

type VMOption func(vm *v1.VirtualMachine)

func WithAnnotations added in v1.5.0 

func WithAnnotations(annotations map[string]string) VMOption

func WithClusterInstancetype 

func WithClusterInstancetype(name string) VMOption

func WithClusterPreference 

func WithClusterPreference(name string) VMOption

func WithDataVolumeTemplate 

func WithDataVolumeTemplate(datavolume *cdiv1.DataVolume) VMOption

func WithInstancetype 

func WithInstancetype(name string) VMOption

func WithInstancetypeInferredFromVolume 

func WithInstancetypeInferredFromVolume(name string) VMOption

func WithInstancetypeRevision 

func WithInstancetypeRevision(revisionName string) VMOption

func WithLabels added in v1.5.0 

func WithLabels(labels map[string]string) VMOption

func WithPreference 

func WithPreference(name string) VMOption

func WithPreferenceInferredFromVolume 

func WithPreferenceInferredFromVolume(name string) VMOption

func WithPreferenceRevision 

func WithPreferenceRevision(revisionName string) VMOption

func WithRunStrategy added in v1.4.0 

func WithRunStrategy(strategy v1.VirtualMachineRunStrategy) VMOption

Source Files

View all Source files

Directories

Path Synopsis
Package status provides utility options to manage the vmi status.
 Package status provides utility options to manage the vmi status.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.
JackTT - Gopher 🇻🇳