libvmi

package
v1.2.0 Latest Latest
Warning

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

 Go to latest Published: Feb 26, 2024 License: Apache-2.0 Imports: 16 Imported by: 0

README

libvmi

libvmi is a VMI manifest composer.

Overview

Motivation

While reading code, especially e2e 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.
  • Factory: factory.go file contains commonly used base VMI specs. Users will usually pick one factory to use and then add different builders to continue building the spec.
  • 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 (
	WindowsFirmware = "5d307ca9-b3ef-428c-8861-06e72d69f223"
	WindowsPVCName  = "disk-windows"
)

Variables

This section is empty.

Functions

func GetPodByVirtualMachineInstance added in v0.36.0 

func GetPodByVirtualMachineInstance(vmi *v1.VirtualMachineInstance, namespace string) (*k8sv1.Pod, error)

func IndexInterfaceStatusByName added in v0.36.0 

func IndexInterfaceStatusByName(vmi *v1.VirtualMachineInstance) map[string]v1.VirtualMachineInstanceNetworkInterface

func InterfaceDeviceWithBridgeBinding added in v0.34.0 

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 added in v0.36.0 

func InterfaceDeviceWithSRIOVBinding(name string) kvirtv1.Interface

InterfaceDeviceWithSRIOVBinding returns an Interface with SRIOV binding.

func InterfaceDeviceWithSlirpBinding added in v0.50.0 

func InterfaceDeviceWithSlirpBinding(name string, ports ...kvirtv1.Port) kvirtv1.Interface

InterfaceDeviceWithSlirpBinding returns an Interface with SLIRP binding.

func InterfaceWithBindingPlugin added in v1.2.0 

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

func InterfaceWithMac added in v0.36.0 

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

InterfaceWithMac decorates an existing Interface with a MAC address.

func InterfaceWithMacvtapBindingPlugin added in v1.2.0 

func InterfaceWithMacvtapBindingPlugin(name string) *kvirtv1.Interface

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

func InterfaceWithPasstBindingPlugin added in v1.2.0 

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

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

func MultusNetwork added in v0.35.0 

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 NewAlpine added in v0.50.0 

func NewAlpine(opts ...Option) *kvirtv1.VirtualMachineInstance

NewAlpine instantiates a new Alpine based VMI configuration

func NewAlpineWithTestTooling added in v0.53.0 

func NewAlpineWithTestTooling(opts ...Option) *kvirtv1.VirtualMachineInstance

func NewCirros added in v0.34.0 

func NewCirros(opts ...Option) *kvirtv1.VirtualMachineInstance

NewCirros instantiates a new CirrOS based VMI configuration

func NewFedora 

func NewFedora(opts ...Option) *kvirtv1.VirtualMachineInstance

NewFedora instantiates a new Fedora based VMI configuration, building its extra properties based on the specified With* options. This image has tooling for the guest agent, stress, SR-IOV and more.

func NewVirtualMachine added in v1.2.0 

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

func NewWindows added in v1.1.0 

func NewWindows(opts ...Option) *kvirtv1.VirtualMachineInstance

Types

type Option 

type Option func(vmi *v1.VirtualMachineInstance)

Option represents an action that enables an option.

func WithAnnotation added in v0.42.0 

func WithAnnotation(key, value string) Option

WithAnnotation adds an annotation with specified value

func WithCDRom added in v0.58.0 

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

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

func WithCPUCount added in v1.0.0 

func WithCPUCount(cores, threads, sockets uint32) Option

func WithCPUFeature added in v0.56.0 

func WithCPUFeature(featureName, policy string) Option

func WithCPUModel added in v0.56.0 

func WithCPUModel(model string) Option

func WithCloudInitConfigDriveUserData added in v1.2.0 

func WithCloudInitConfigDriveUserData(data string) Option

WithCloudInitConfigDriveUserData adds cloud-init config-drive user data.

func WithCloudInitNoCloudEncodedUserData added in v1.2.0 

func WithCloudInitNoCloudEncodedUserData(data string) Option

WithCloudInitNoCloudEncodedUserData adds cloud-init no-cloud base64-encoded user data

func WithCloudInitNoCloudNetworkData added in v0.35.0 

func WithCloudInitNoCloudNetworkData(data string) Option

WithCloudInitNoCloudNetworkData adds cloud-init no-cloud network data.

func WithCloudInitNoCloudUserData 

func WithCloudInitNoCloudUserData(data string) Option

WithCloudInitNoCloudUserData adds cloud-init no-cloud user data.

func WithConfigMapDisk added in v1.0.0 

func WithConfigMapDisk(configMapName, volumeName string) Option

func WithConfigMapFs added in v1.0.0 

func WithConfigMapFs(configMapName, volumeName string) Option

func WithContainerDisk added in v1.2.0 

func WithContainerDisk(diskName, imageName string) Option

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

func WithDataVolume added in v0.56.0 

func WithDataVolume(diskName, pvcName string) Option

WithDataVolume specifies the name of the DataVolume to be used.

func WithDedicatedCPUPlacement added in v0.56.0 

func WithDedicatedCPUPlacement() Option

func WithDownwardAPIDisk added in v1.0.0 

func WithDownwardAPIDisk(name string) Option

func WithDownwardAPIFs added in v1.0.0 

func WithDownwardAPIFs(name string) Option

func WithDownwardMetricsChannel added in v1.1.0 

func WithDownwardMetricsChannel() Option

func WithDownwardMetricsVolume added in v1.1.0 

func WithDownwardMetricsVolume(volumeName string) Option

func WithEmptyDisk added in v0.57.0 

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

WithEmptyDisk specifies the name of the EmptyDisk to be used.

func WithEphemeralCDRom added in v1.2.0 

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

WithEphemeralCDRom specifies a CDRom drive to be used.

func WithEphemeralPersistentVolumeClaim added in v1.1.0 

func WithEphemeralPersistentVolumeClaim(diskName, pvcName string) Option

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

func WithEvictionStrategy added in v1.1.0 

func WithEvictionStrategy(evictionStrategy v1.EvictionStrategy) Option

func WithFilesystemDV added in v0.58.0 

func WithFilesystemDV(dataVolumeName string) Option

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

func WithFilesystemPVC added in v0.58.0 

func WithFilesystemPVC(claimName string) Option

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

func WithGuestMemory added in v0.56.0 

func WithGuestMemory(memory string) Option

func WithHostDisk added in v1.2.0 

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

func WithHugepages added in v0.56.0 

func WithHugepages(pageSize string) Option

func WithInterface 

func WithInterface(iface kvirtv1.Interface) Option

WithInterface adds a Domain Device Interface.

func WithLabel added in v0.42.0 

func WithLabel(key, value string) Option

WithLabel sets a label with specified value

func WithLabelledConfigMapDisk added in v1.0.0 

func WithLabelledConfigMapDisk(configMapName, volumeName, label string) Option

func WithLabelledSecretDisk added in v1.0.0 

func WithLabelledSecretDisk(secretName, volumeName, label string) Option

func WithLimitCPU added in v0.56.0 

func WithLimitCPU(value string) Option

WithLimitCPU specifies the VMI CPU limit.

func WithLimitMemory added in v0.56.0 

func WithLimitMemory(value string) Option

WithLimitMemory specifies the VMI memory limit.

func WithMasqueradeNetworking added in v0.53.0 

func WithMasqueradeNetworking(ports ...kvirtv1.Port) []Option

func WithNUMAGuestMappingPassthrough added in v0.56.0 

func WithNUMAGuestMappingPassthrough() Option

func WithNamespace added in v0.59.0 

func WithNamespace(namespace string) Option

func WithNetwork 

func WithNetwork(network *kvirtv1.Network) Option

WithNetwork adds a network object.

func WithNodeAffinityFor added in v0.58.1 

func WithNodeAffinityFor(nodeName string) Option

func WithNodeAffinityForLabel added in v1.2.0 

func WithNodeAffinityForLabel(nodeLabelKey, nodeLabelValue string) Option

func WithNodeSelectorFor added in v0.44.2 

func WithNodeSelectorFor(node *k8sv1.Node) Option

WithNodeSelectorFor ensures that the VMI gets scheduled on the specified node

func WithPasstInterfaceWithPort added in v0.58.1 

func WithPasstInterfaceWithPort() Option

func WithPersistentVolumeClaim added in v0.56.0 

func WithPersistentVolumeClaim(diskName, pvcName string) Option

WithPersistentVolumeClaim specifies the name of the PersistentVolumeClaim to be used.

func WithPersistentVolumeClaimLun added in v1.0.0 

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

func WithRealtimeMask added in v0.56.0 

func WithRealtimeMask(realtimeMask string) Option

func WithResourceCPU added in v0.56.0 

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 added in v0.49.0 

func WithSEV(isESEnabled bool) Option

WithSEV adds `launchSecurity` with `sev`.

func WithSEVAttestation added in v1.1.0 

func WithSEVAttestation() Option

func WithSecretDisk added in v1.0.0 

func WithSecretDisk(secretName, volumeName string) Option

func WithSecretFs added in v1.0.0 

func WithSecretFs(secretName, volumeName string) Option

func WithServiceAccountDisk added in v1.0.0 

func WithServiceAccountDisk(name string) Option

func WithServiceAccountFs added in v1.0.0 

func WithServiceAccountFs(serviceAccountName, volumeName string) Option

func WithStartStrategy added in v1.2.0 

func WithStartStrategy(startStrategy v1.StartStrategy) Option

func WithTerminationGracePeriod 

func WithTerminationGracePeriod(seconds int64) Option

WithTerminationGracePeriod specifies the termination grace period in seconds.

func WithUefi added in v0.49.0 

func WithUefi(secureBoot bool) Option

WithUefi configures EFI bootloader and SecureBoot.

func WithWatchdog added in v1.1.0 

func WithWatchdog(action v1.WatchdogAction) Option

WithWatchdog adds a watchdog to the vmi devices.

func WithoutSerialConsole added in v1.2.0 

func WithoutSerialConsole() Option

type VMOption added in v1.2.0 

type VMOption func(vm *v1.VirtualMachine)

func WithDataVolumeTemplate added in v1.2.0 

func WithDataVolumeTemplate(datavolume *v1beta1.DataVolume) VMOption

func WithRunning added in v1.2.0 

func WithRunning() VMOption

Source Files

View all Source files

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.