This version is under construction, please use an official release version

Kubermatic Virtualization CRDs Reference

v1alpha1

KubeVRole

KubeVRole defines what operations a subject may perform.

Field Description Scheme Required
metadata metav1.ObjectMeta false
spec KubeVRoleSpec true

Back to Group

KubeVRoleBinding

KubeVRoleBinding grants a KubeVRole to a user.

Field Description Scheme Required
metadata metav1.ObjectMeta false
spec KubeVRoleBindingSpec true

Back to Group

KubeVRoleBindingList

KubeVRoleBindingList is the list type for KubeVRoleBinding.

Field Description Scheme Required
metadata metav1.ListMeta false
items []KubeVRoleBinding true

Back to Group

KubeVRoleBindingSpec

KubeVRoleBindingSpec defines who gets what role.

Field Description Scheme Required
subject Subject is the name of the User being bound. string true
roleRef RoleRef is the name of the KubeVRole to grant. string true

Back to Group

KubeVRoleList

KubeVRoleList is the list type for KubeVRole.

Field Description Scheme Required
metadata metav1.ListMeta false
items []KubeVRole true

Back to Group

KubeVRoleSpec

KubeVRoleSpec defines the rules of a KubeVRole.

Field Description Scheme Required
displayName DisplayName is a human-readable label shown in the UI. string false
description Description explains what this role is intended for. string false
system System marks the role as built-in. System roles cannot be deleted via the API. bool false
rules Rules is the list of policy rules that define the permissions of this role. []PolicyRule true

Back to Group

PolicyRule

PolicyRule grants a set of verbs on a set of resources, optionally scoped to one or more resource groups. Any field left empty (or set to ["*"]) is a wildcard that matches everything.

Example — full compute access:

{ resourceGroups: [\"compute\"], verbs: [\"*\"] }

Example — read-only access to a single resource type:

{ resourceGroups: [\"networking\"], resources: [\"subnets\"], verbs: [\"view\"] }
Field Description Scheme Required
resourceGroups ResourceGroups scopes the rule to one or more IAM resource categories (e.g. "compute", "networking", "storage", "iam"). An empty list or ["*"] matches all groups. []string false
resources Resources further narrows the rule to specific resource types within the group (e.g. "virtualmachines", "subnets"). An empty list or ["*"] matches all resources in the matched groups. []string false
verbs Verbs is the list of operations this rule permits. Standard verbs are: create, delete, update, view, manage, start, stop, restart, console. The wildcard "*" permits all verbs. []string true

Back to Group

User

User represents a synced OIDC identity. The controller creates and updates these from OIDC subject claims so that bindings can reference stable K8s resource names instead of raw OIDC subjects.

Field Description Scheme Required
metadata metav1.ObjectMeta false
spec UserSpec false
status UserStatus false

Back to Group

UserList

UserList is the list type for User.

Field Description Scheme Required
metadata metav1.ListMeta false
items []User true

Back to Group

UserSpec

UserSpec is the desired state of a User.

Field Description Scheme Required
sub Sub is the stable OIDC subject identifier (never changes for a given user). string true
email Email is the user’s email address from the OIDC claims. string false
name Name is the user’s display name from the OIDC claims. string false
disabled Disabled prevents the user from authenticating when true. bool false

Back to Group

UserStatus

UserStatus is the observed state of a User.

Field Description Scheme Required
lastSeen LastSeen is the timestamp of the user’s most recent authentication. *metav1.Time false

Back to Group

Image

Image is a catalog entry describing an OS image available for use as a DataVolume source when creating VirtualMachines or VMPools.

Field Description Scheme Required
metadata metav1.ObjectMeta false
spec ImageSpec false

Back to Group

ImageList

ImageList is the list type for Image.

Field Description Scheme Required
metadata metav1.ListMeta false
items []Image true

Back to Group

ImageSourceGCS

ImageSourceGCS references an image stored in Google Cloud Storage.

Field Description Scheme Required
url URL is the GCS URL of the image. string true

Back to Group

ImageSourceHTTP

ImageSourceHTTP references an image hosted at an HTTP/HTTPS URL.

Field Description Scheme Required
url URL is the full HTTP/HTTPS URL of the image. string true

Back to Group

ImageSourcePVC

ImageSourcePVC references an image backed by an existing PersistentVolumeClaim.

Field Description Scheme Required
name Name is the PVC name. string true
namespace Namespace is the PVC namespace. Defaults to the Image’s namespace when omitted. string false

Back to Group

ImageSourceRegistry

ImageSourceRegistry references an image stored in a container registry.

Field Description Scheme Required
url URL is the full registry URL including tag or digest (e.g. docker.io/library/ubuntu:22.04). string true

Back to Group

ImageSourceS3

ImageSourceS3 references an image stored in an S3-compatible bucket.

Field Description Scheme Required
url URL is the S3 URL of the image. string true

Back to Group

ImageSpec

ImageSpec defines the desired state of an Image.

Field Description Scheme Required
type Type identifies the kind of source backing this image. ImageSourceType true
readableName ReadableName is a human-friendly display name shown in the UI. string true
readableDescription ReadableDescription is an optional human-friendly description. string false
credentials Credentials is an optional reference to a Secret holding credentials required to access the image source. string false
http HTTP describes an image hosted at an HTTP/HTTPS URL. *ImageSourceHTTP false
registry Registry describes an image stored in a container registry. *ImageSourceRegistry false
s3 S3 describes an image stored in an S3-compatible object store. *ImageSourceS3 false
gcs GCS describes an image stored in Google Cloud Storage. *ImageSourceGCS false
pvc PVC describes an image backed by an existing PersistentVolumeClaim. *ImageSourcePVC false

Back to Group

SSHKey

SSHKey stores an SSH public key in the workspace namespace. The controller reconciles each SSHKey into an owned K8s Secret so that cloud-init can inject the key into virtual machines at creation time.

Field Description Scheme Required
metadata metav1.ObjectMeta false
spec SSHKeySpec false
status SSHKeyStatus false

Back to Group

SSHKeyList

SSHKeyList is the list type for SSHKey.

Field Description Scheme Required
metadata metav1.ListMeta false
items []SSHKey true

Back to Group

SSHKeySpec

SSHKeySpec defines the desired state of an SSHKey.

Field Description Scheme Required
publicKey PublicKey is the SSH public key content (e.g. "ssh-rsa AAAA… user@host"). string true

Back to Group

SSHKeyStatus

SSHKeyStatus is the observed state of an SSHKey.

Field Description Scheme Required
phase Phase is the current lifecycle phase. SSHKeyPhase false
secretRef SecretRef is the name of the managed Secret in the same namespace. string false
message Message contains a human-readable description of the current phase. string false

Back to Group

DNATRule

DNATRule maps an external port on an EIP to an internal address and port.

Field Description Scheme Required
externalPort ExternalPort is the port on the EIP to forward. string true
internalIP InternalIP is the internal VM IP to forward traffic to. string true
internalPort InternalPort is the destination port on the internal VM. string true
protocol Protocol is the transport protocol: tcp or udp. string false
eipRef EIPRef is the name of the ElasticIP wrapper in the same namespace. string true

Back to Group

ElasticIP

ElasticIP is the namespace-scoped wrapper for a Kube-OVN IptablesEIP resource. It represents a public IP address that can be associated with a NAT gateway.

Field Description Scheme Required
metadata metav1.ObjectMeta false
spec ElasticIPSpec false
status ElasticIPStatus false

Back to Group

ElasticIPList

ElasticIPList is the list type for ElasticIP.

Field Description Scheme Required
metadata metav1.ListMeta false
items []ElasticIP true

Back to Group

ElasticIPSpec

ElasticIPSpec defines the desired state of an ElasticIP.

Field Description Scheme Required
natGatewayRef NATGatewayRef is the name of the NATGateway wrapper this EIP belongs to. string false

Back to Group

ElasticIPStatus

ElasticIPStatus is the observed state of the ElasticIP wrapper.

Field Description Scheme Required
phase Phase is the current lifecycle phase. Phase false
realName RealName is the actual Kube-OVN IptablesEIP object name. string false
ipAddress IPAddress is the public IP address allocated to this EIP. string false
isUsed IsUsed indicates whether this EIP is currently in use by a NAT rule. bool true
associatedNat AssociatedNAT is the real Kube-OVN NAT gateway name this EIP is bound to. string false

Back to Group

NATGateway

NATGateway is the namespace-scoped wrapper for a Kube-OVN VpcNatGateway resource. It bundles SNAT and DNAT rules that are individually provisioned as separate Kube-OVN objects (IptablesSnatRule / IptablesDnatRule).

Field Description Scheme Required
metadata metav1.ObjectMeta false
spec NATGatewaySpec false
status NATGatewayStatus false

Back to Group

NATGatewayList

NATGatewayList is the list type for NATGateway.

Field Description Scheme Required
metadata metav1.ListMeta false
items []NATGateway true

Back to Group

NATGatewaySpec

NATGatewaySpec defines the desired state of a NAT gateway.

Field Description Scheme Required
vpcRef VPCRef is the name of the VPC wrapper in the same namespace. string true
subnetRef SubnetRef is the name of the Subnet wrapper in the same namespace. string true
lanIP LanIP is the LAN-side IP address of the NAT gateway. string false
snatRules SNATRules define source NAT rules for outbound connectivity. []SNATRule false
dnatRules DNATRules define destination NAT rules for inbound port-forwarding. []DNATRule false

Back to Group

NATGatewayStatus

NATGatewayStatus is the observed state of the NATGateway wrapper.

Field Description Scheme Required
phase Phase is the current lifecycle phase. Phase false
realName RealName is the actual Kube-OVN VpcNatGateway object name. string false

Back to Group

SNATRule

SNATRule maps an internal CIDR to an EIP for outbound NAT.

Field Description Scheme Required
cidr CIDR is the internal IP range to SNAT. string true
eipRef EIPRef is the name of the ElasticIP wrapper in the same namespace. string true

Back to Group

SecurityGroup

SecurityGroup is the namespace-scoped wrapper for a Kube-OVN SecurityGroup resource. It defines ACL-based firewall rules that can be applied to VMs.

Field Description Scheme Required
metadata metav1.ObjectMeta false
spec SecurityGroupSpec false
status SecurityGroupStatus false

Back to Group

SecurityGroupList

SecurityGroupList is the list type for SecurityGroup.

Field Description Scheme Required
metadata metav1.ListMeta false
items []SecurityGroup true

Back to Group

SecurityGroupRule

SecurityGroupRule is a single ACL rule within a SecurityGroup.

Field Description Scheme Required
ipVersion IPVersion specifies whether the rule applies to IPv4 or IPv6 traffic. string false
protocol Protocol is the network protocol: tcp, udp, icmp, or all. string false
priority Priority determines the rule evaluation order (lower values = higher priority). int false
remoteType RemoteType is the type of the remote endpoint: address or securityGroup. string true
remoteAddress RemoteAddress is the IP address or CIDR of the remote endpoint when RemoteType is address. string false
remoteSecurityGroup RemoteSecurityGroup is the name of the remote security group when RemoteType is securityGroup. string false
portRangeMin PortRangeMin is the inclusive minimum port number for this rule. int false
portRangeMax PortRangeMax is the inclusive maximum port number for this rule. int false
policy Policy is the rule action: allow or drop. string true

Back to Group

SecurityGroupSpec

SecurityGroupSpec defines the desired firewall rules.

Field Description Scheme Required
allowSameGroupTraffic AllowSameGroupTraffic permits traffic between members of the same security group. bool false
ingressRules IngressRules defines the inbound firewall rules. []SecurityGroupRule false
egressRules EgressRules defines the outbound firewall rules. []SecurityGroupRule false

Back to Group

SecurityGroupStatus

SecurityGroupStatus is the observed state of the SecurityGroup wrapper.

Field Description Scheme Required
phase Phase is the current lifecycle phase. Phase false
realName RealName is the actual Kube-OVN SecurityGroup object name. string false

Back to Group

Subnet

Subnet is the namespace-scoped wrapper for a Kube-OVN Subnet resource. It is always associated with a VPC wrapper in the same namespace.

Field Description Scheme Required
metadata metav1.ObjectMeta false
spec SubnetSpec false
status SubnetStatus false

Back to Group

SubnetList

SubnetList is the list type for Subnet.

Field Description Scheme Required
metadata metav1.ListMeta false
items []Subnet true

Back to Group

SubnetSpec

SubnetSpec defines the desired state of a Subnet wrapper.

Field Description Scheme Required
vpcRef VPCRef is the name of the VPC wrapper in the same namespace. string true
cidrBlock CIDRBlock is the IP address range for this subnet. string true
gateway Gateway is the gateway IP address for this subnet. string false
protocol Protocol is the IP protocol family: IPv4, IPv6, or Dual. string false
excludeIPs ExcludeIPs is a list of IP ranges to exclude from allocation. []string false
enableDHCP EnableDHCP enables DHCP on this subnet. bool false
gatewayType GatewayType controls the gateway mode: distributed or centralized. string false
natOutgoing NatOutgoing enables NAT for traffic leaving this subnet. bool false
private Private denies traffic from outside this subnet when true. bool false
provider Provider is the kube-ovn provider name for this subnet, used to associate it with a NetworkAttachmentDefinition (NAD) via kube-ovn’s provider matching. Required for multi-homed pods (e.g. AZ transit NICs). string false

Back to Group

SubnetStatus

SubnetStatus is the observed state of the Subnet wrapper.

Field Description Scheme Required
phase Phase is the current lifecycle phase of this Subnet. Phase false
realName RealName is the actual Kube-OVN Subnet object name. string false
vpcRealName VPCRealName is the real Kube-OVN Vpc name this subnet belongs to. string false
availableIPs AvailableIPs is the number of IP addresses currently available in this subnet. int64 true
usedIPs UsedIPs is the number of IP addresses currently in use. int64 true

Back to Group

UnderlayCustomInterface

UnderlayCustomInterface overrides DefaultInterface on a specific set of nodes.

Field Description Scheme Required
interface Interface is the physical NIC name to use on the listed nodes. It must be a valid Linux network interface name, which the kernel caps at 15 bytes. string true
nodes Nodes is the list of node names that use Interface instead of the spec-level DefaultInterface. []string true

Back to Group

UnderlaySubnet

UnderlaySubnet is the namespace-scoped wrapper that bundles the three Kube-OVN objects required to expose an underlay (L2) network: a cluster- scoped ProviderNetwork (which physical NIC per node), a Vlan (the 802.1Q tag), and a Subnet bound to that Vlan. The reconciler ensures the children are created and torn down in dependency order.

Field Description Scheme Required
metadata metav1.ObjectMeta false
spec UnderlaySubnetSpec false
status UnderlaySubnetStatus false

Back to Group

UnderlaySubnetList

UnderlaySubnetList is the list type for UnderlaySubnet.

Field Description Scheme Required
metadata metav1.ListMeta false
items []UnderlaySubnet true

Back to Group

UnderlaySubnetSpec

UnderlaySubnetSpec defines the desired state of an UnderlaySubnet wrapper.

Field Description Scheme Required
defaultInterface DefaultInterface is the physical NIC name (e.g. "eth1") that the ProviderNetwork attaches to on every selected node. It must be a valid Linux network interface name, which the kernel caps at 15 bytes. string true
nodeSelector NodeSelector restricts the ProviderNetwork to a subset of nodes via label selection. When empty, the ProviderNetwork applies to all nodes. *metav1.LabelSelector false
customInterfaces CustomInterfaces overrides DefaultInterface on specific nodes. []UnderlayCustomInterface false
vlanID VlanID is the 802.1Q tag applied to traffic on this underlay. int true
cidrBlock CIDRBlock is the IP address range allocated from this underlay subnet. string true
gateway Gateway is the gateway IP address for this subnet. string false
gatewayNode GatewayNode is the comma-separated list of node names that host the centralized gateway for this subnet. string false
protocol Protocol is the IP protocol family: IPv4, IPv6, or Dual. string false
excludeIPs ExcludeIPs is a list of IP addresses or ranges to exclude from allocation. []string false

Back to Group

UnderlaySubnetStatus

UnderlaySubnetStatus is the observed state of the UnderlaySubnet wrapper.

Field Description Scheme Required
phase Phase is the current lifecycle phase of this UnderlaySubnet. Phase false
providerNetworkName ProviderNetworkName is the name of the cluster-scoped Kube-OVN ProviderNetwork backing this underlay. string false
vlanName VlanName is the name of the cluster-scoped Kube-OVN Vlan backing this underlay. string false
subnetName SubnetName is the name of the cluster-scoped Kube-OVN Subnet backing this underlay. string false
availableIPs AvailableIPs is the number of IP addresses currently available in this subnet. int64 true
usedIPs UsedIPs is the number of IP addresses currently in use. int64 true

Back to Group

VPC

VPC is the namespace-scoped wrapper for a Kube-OVN Vpc resource. Users create VPCs inside workspace namespaces; the operator reconciles them into cluster-scoped Kube-OVN Vpc objects, prefixing their names with the workspace namespace to prevent cross-tenant collisions.

Field Description Scheme Required
metadata metav1.ObjectMeta false
spec VPCSpec false
status VPCStatus false

Back to Group

VPCBFDPort

VPCBFDPort holds optional BFD logical router port configuration.

Field Description Scheme Required
enabled Enabled activates the BFD port. bool true
ip IP is the IP address assigned to the BFD port. string false
nodeSelector NodeSelector restricts which nodes the BFD LRP is hosted on. If not set, Kube-OVN selects up to 3 nodes automatically. *metav1.LabelSelector false

Back to Group

VPCBFDPortStatus

VPCBFDPortStatus is the observed state of the BFD logical router port.

Field Description Scheme Required
name string false
ip string false
nodes []string false

Back to Group

VPCList

VPCList is the list type for VPC.

Field Description Scheme Required
metadata metav1.ListMeta false
items []VPC true

Back to Group

VPCPeering

VPCPeering configures a peering connection between two VPCs. The RemoteVPCRef references the name of another VPC wrapper in the same namespace.

Field Description Scheme Required
remoteVpcRef RemoteVPCRef is the name of the remote VPC wrapper in the same namespace. string true
localConnectIP LocalConnectIP is the local IP used to establish the peering connection. string false

Back to Group

VPCPolicyRoute

VPCPolicyRoute is a policy-based routing rule for the VPC router.

Field Description Scheme Required
priority Priority determines evaluation order; lower numbers are evaluated first. int false
match Match is the OVN match expression that selects traffic for this rule. string true
action Action is the rule action: allow, drop, or reroute. string true
nextHopIP NextHopIP is required when Action is reroute. string false

Back to Group

VPCSpec

VPCSpec defines the desired state of a VPC wrapper.

Field Description Scheme Required
defaultSubnet DefaultSubnet is the name of the default subnet wrapper in this namespace. string false
staticRoutes StaticRoutes configures static routes for the VPC router. []VPCStaticRoute false
policyRoutes PolicyRoutes configures policy-based routing rules for the VPC router. []VPCPolicyRoute false
vpcPeerings VPCPeerings configures peering connections to other VPCs in the same namespace. []VPCPeering false
enableExternal EnableExternal controls whether the VPC has access to the external network. bool false
enableBfd EnableBfd enables Bidirectional Forwarding Detection on the VPC router. bool false
bfdPort BFDPort holds configuration for the BFD logical router port. Only effective when EnableBfd is true. *VPCBFDPort false

Back to Group

VPCStaticRoute

VPCStaticRoute is a single static route entry for the VPC router.

Field Description Scheme Required
cidr CIDR is the destination IP prefix for this route. string true
nextHopIP NextHopIP is the IP address of the next-hop router. string true
policy Policy is the routing policy direction: dst or src. string false
bfdID BFDID is the UUID of the BFD session to associate with this route. When set, the underlying KubeOVN VPC will use BFD-monitored ECMP for this route. string false
ecmpMode ECMPMode sets the ECMP mode for this route (e.g. "ecmp" or "ecmp-symmetric"). string false

Back to Group

VPCStatus

VPCStatus mirrors the Kube-OVN VpcStatus, surfacing the full operational state of the underlying cluster-scoped Vpc object.

Field Description Scheme Required
phase Phase is the lifecycle phase of this VPC wrapper. Phase false
realName RealName is the cluster-scoped Kube-OVN Vpc object name (namespace-prefixed). Used internally by dependent controllers. string false
standby bool true
default bool true
defaultLogicalSwitch string true
router string true
tcpLoadBalancer string true
udpLoadBalancer string true
sctpLoadBalancer string true
tcpSessionLoadBalancer string true
udpSessionLoadBalancer string true
sctpSessionLoadBalancer string true
subnets Subnets lists the user-facing names of subnets belonging to this VPC (namespace prefix stripped). []string true
vpcPeerings VPCPeerings lists the real names of peered Kube-OVN Vpcs. []string true
enableExternal bool true
extraExternalSubnets ExtraExternalSubnets lists additional external subnets attached to this VPC. []string true
enableBfd bool true
bfdPort VPCBFDPortStatus true

Back to Group