v1alpha1 API Reference

v1alpha1

APIEndpoint
ClusterNetworkConfiguration
CommonInstancetypesDeploymentConfiguration
ControlPlaneConfig
DashboardAuthConfig
DashboardBasicConfig
DashboardConfiguration
DashboardOIDCConfig
DeveloperConfiguration
DexConfiguration
DexConnector
DexStaticClient
HostConfig
IDPConfiguration
KubeVCluster
KubeletConfig
KubevirtConfiguration
LoadBalancerSpec
Longhorn
MetalLBSpec
MigrationsConfiguration
NetworkConfiguration
NoneSpec
OCIConfiguration
OfflineSettings
PciHostDevice
PermittedHostDevices
StaticWorkersConfig
StorageConfiguration

APIEndpoint

APIEndpoint is the endpoint used to communicate with the Kubernetes API.

Field	Description	Scheme	Required
host	Host is the hostname or IP on which API is running.	string	true
alternativeNames	AlternativeNames is a list of Subject Alternative Names for the API Server signing cert.	[]string	false

Back to Group

ClusterNetworkConfiguration

NetworkConfiguration holds network settings for the Kubernetes cluster.

Field	Description	Scheme	Required
networkCIDR	NetworkCIDR is the pod network CIDR. Defaults to "10.18.0.0/16".	string	false
serviceCIDR	ServiceCIDR is the service network CIDR. Defaults to "10.112.0.0/12".	string	false

Back to Group

CommonInstancetypesDeploymentConfiguration

CommonInstancetypesDeploymentConfiguration controls deployment of common-instancetypes resources.

Field	Description	Scheme	Required
enabled	Enabled controls whether the common-instancetypes bundle is deployed. Defaults to true.	*bool	false

Back to Group

ControlPlaneConfig

ControlPlaneConfig defines control plane nodes.

Field	Description	Scheme	Required
hosts	Hosts array of all control plane hosts.	[]HostConfig	true

Back to Group

DashboardAuthConfig

DashboardAuthConfig selects the authentication mode for the dashboard. Exactly one of None, Basic, or OIDC must be set. Default is None when unset.

Field	Description	Scheme	Required
none	None disables authentication. The dashboard is accessible without login.	*NoneSpec	false
basic	Basic enables username/password authentication backed by a Kubernetes Secret.	*DashboardBasicConfig	false
oidc	OIDC enables OpenID Connect authentication via an external provider (e.g. Dex).	*DashboardOIDCConfig	false

Back to Group

DashboardBasicConfig

DashboardBasicConfig holds basic-auth settings for the dashboard.

Field	Scheme	Required
secretName	string	false
secretNamespace	string	false
sessionDuration	string	false

Back to Group

DashboardConfiguration

DashboardConfiguration configures the KubeV API server and web dashboard components.

Field	Description	Scheme	Required
enabled	Enabled controls whether the API server and dashboard are deployed. Defaults to false.	bool	false
auth	Auth configures how users authenticate to the dashboard. Required when Enabled is true.	DashboardAuthConfig	false
dashboardURL	DashboardURL is the public URL where the dashboard is reachable (e.g. "https://kubev.example.com"). Used as the redirect target after a successful OIDC login.	string	false
imagePullSecret	ImagePullSecret overrides the cluster-level ImagePullSecret for the api-server and dashboard components only. When empty, the cluster-level value is used.	string	false

Back to Group

DashboardOIDCConfig

DashboardOIDCConfig holds the OIDC provider settings for the dashboard.

Field	Scheme	Required
issuerURL	string	true
clientID	string	true
clientSecret	string	true
redirectURL	string	true
scopes	[]string	false

Back to Group

DeveloperConfiguration

DeveloperConfiguration holds settings for developers working on KubeV and KubeVirt.

Field	Description	Scheme	Required
featureGates	FeatureGates specifies a list of experimental feature gates to enable. Defaults to none. A feature gate must not appear in both FeatureGates and DisabledFeatureGates.	[]string	false
useEmulation	UseEmulation can be set to true to allow fallback to software emulation in case hardware-assisted emulation is not available. Defaults to false	bool	false

Back to Group

DexConfiguration

DexConfiguration configures the Dex OIDC identity provider deployed alongside the cluster.

Field	Description	Scheme	Required
issuer	Issuer is the base URL at which Dex will be reachable (e.g., "https://dex.example.com").	string	true
connectors	Connectors is the list of identity provider connectors (OIDC, LDAP, GitHub, etc.).	[]DexConnector	false
staticClients	StaticClients is the list of pre-registered OAuth2 clients.	[]DexStaticClient	false
enablePasswordDB	EnablePasswordDB enables the built-in local password database connector.	bool	false

Back to Group

DexConnector

DexConnector defines a single Dex identity provider connector.

Field	Description	Scheme	Required
type	Type is the connector type (e.g., "oidc", "ldap", "github").	string	true
id	ID is a unique identifier for this connector.	string	true
name	Name is the human-readable display name shown on the login page.	string	true
config	Config holds connector-specific configuration. The structure depends on Type.	apiextensionsv1.JSON	false

Back to Group

DexStaticClient

DexStaticClient defines a statically configured OAuth2 client in Dex.

Field	Description	Scheme	Required
id	ID is the OAuth2 client identifier.	string	true
secret	Secret is the plaintext OAuth2 client secret.	string	false
name	Name is the human-readable display name for this client.	string	true
redirectURIs	RedirectURIs is the list of allowed redirect URIs for this client.	[]string	false
public	Public marks this as a public client (no secret required, e.g. for CLI flows).	bool	false

Back to Group

HostConfig

HostConfig describes a single control plane or worker node.

Field	Description	Scheme	Required
address	Address is internal RFC-1918 IP address.	string	true
sshUsername	SSHUsername is system login name. Default value is "root".	string	false
sshPrivateKeyFile	SSHPrivateKeyFile is path to the file with PRIVATE AND CLEANTEXT ssh key. Default value is "".	string	false
labels	Labels to be used to apply (or remove, with minus symbol suffix, see more kubectl help label) labels to/from node	map[string]string	false
annotations	Annotations to be used to apply (or remove, with minus symbol suffix, see more kubectl help annotate) annotations to/from node	map[string]string	false
tunnelInterface	TunnelInterface specifies the physical NIC used for Kube-OVN overlay tunnel traffic on this node. Must be a valid Linux network interface name (max 15 characters, alphanumeric with _, ., -).	string	false
kubelet	Kubelet holds per-node kubelet configuration options that override the cluster-level defaults.	KubeletConfig	false

Back to Group

IDPConfiguration

IDPConfiguration selects which identity provider to deploy alongside the cluster. Exactly one of Dex or None must be set. Default is None when unset.

Field	Description	Scheme	Required
dex	Dex deploys a Dex OIDC identity provider alongside the cluster.	*DexConfiguration	false
none	None explicitly disables any managed identity provider deployment.	*NoneSpec	false

Back to Group

KubeVCluster

KubeVCluster is Kubermatic Virtualization Cluster API Schema.

Field	Description	Scheme	Required
controlPlane	ControlPlane describes the control plane nodes and how to access them.	ControlPlaneConfig	true
staticWorkers	StaticWorkers describes the worker nodes that are managed by KubeV/kubeadm.	StaticWorkersConfig	false
networkConfiguration	NetworkConfiguration holds the network settings for the Kubermatic Virtualization Platform.	NetworkConfiguration	false
apiEndpoint	APIEndpoint are pairs of address and port used to communicate with the Kubernetes API.	APIEndpoint	true
loadBalancer	LoadBalancer configures the platform’s external load balancing. Exactly one implementation (e.g., MetalLB, None) must be specified.	LoadBalancerSpec	false
storage	Storage configures the persistent storage solution for the cluster. Exactly one option (e.g., Longhorn, None) must be specified.	StorageConfiguration	false
offlineSettings	OfflineSettings configures the platform for air-gapped (offline) operation. When used, all external dependencies must be served from internal mirrors.	OfflineSettings	false
kubevirt	KubevirtConfiguration holds settings specific to the KubeVirt integration.	KubevirtConfiguration	false
idp	IDP configures an optional identity provider to deploy alongside the cluster. Exactly one option (e.g., Dex, None) must be specified. Default is None when unset.	IDPConfiguration	false
dashboard	Dashboard configures the KubeV API server and web dashboard.	DashboardConfiguration	false
imagePullSecret	ImagePullSecret is the raw Docker config JSON for authenticating to the image registry. Applied to all platform components (controller-manager, api-server, dashboard). If empty, the installer checks KUBEV_USERNAME and KUBEV_PASSWORD environment variables.	string	false
kubeletConfig	KubeletConfig defines cluster-wide kubelet configuration applied to all nodes. Per-node overrides can be set via HostConfig.Kubelet.	KubeletConfig	false

Back to Group

KubeletConfig

KubeletConfig provides kubelet configuration options propagated via kubeadm’s KubeletConfiguration. See https://kubernetes.io/docs/tasks/administer-cluster/reserve-compute-resources/ for resource reservation details.

Field	Description	Scheme	Required
systemReserved	SystemReserved configures –system-reserved command-line flag of the kubelet.	map[string]string	false
kubeReserved	KubeReserved configures –kube-reserved command-line flag of the kubelet.	map[string]string	false
evictionHard	EvictionHard configures –eviction-hard command-line flag of the kubelet.	map[string]string	false
maxPods	MaxPods configures the maximum number of pods per node. Defaults to 110.	*int32	false
imageGCHighThresholdPercent	ImageGCHighThresholdPercent is the percent of disk usage after which image garbage collection is always run. Must be between 0 and 100, inclusive, and greater than ImageGCLowThresholdPercent. Default: 85.	*int32	false
imageGCLowThresholdPercent	ImageGCLowThresholdPercent is the percent of disk usage before which image garbage collection is never run. Must be between 0 and 100, inclusive, and less than ImageGCHighThresholdPercent. Default: 80.	*int32	false
imageMinimumGCAge	ImageMinimumGCAge is the minimum age for an unused image before it is garbage collected. Default: "2m".	metav1.Duration	false
imageMaximumGCAge	ImageMaximumGCAge is the maximum age an image can be unused before it is garbage collected. Default "0s" disables this field.	metav1.Duration	false

Back to Group

KubevirtConfiguration

KubevirtConfiguration holds settings specific to the KubeVirt integration.

Field	Description	Scheme	Required
developerConfiguration	DeveloperConfiguration holds settings for developers working on KubeV and KubeVirt.	*DeveloperConfiguration	false
migrations	Migrations holds live-migration tuning parameters applied cluster-wide.	*MigrationsConfiguration	false
commonInstancetypesDeployment	CommonInstancetypesDeployment controls whether the common-instancetypes bundle is deployed.	*CommonInstancetypesDeploymentConfiguration	false
permittedHostDevices	PermittedHostDevices declares PCI devices that may be passed through to VMs.	*PermittedHostDevices	false

Back to Group

LoadBalancerSpec

LoadBalancerSpec configures the platform’s load balancing. Exactly one of the following fields must be set: None, MetalLB. (KubeLB will be supported in the future.) If no load balancer is desired, set None: {}.

Field	Description	Scheme	Required
none	None explicitly disables external L4 load balancing. Use this when LoadBalancer-type services should not be exposed externally.	*NoneSpec	false
metallb	MetalLB configures MetalLB to allocate external IPs for LoadBalancer services.	*MetalLBSpec	false

Back to Group

Longhorn

Longhorn defines Longhorn-specific settings.

Field	Description	Scheme	Required

Back to Group

MetalLBSpec

MetalLBSpec defines MetalLB-specific settings.

Field	Description	Scheme	Required
ipRange	IPRange is the IP address range used to allocate external IPs for LoadBalancer services. Acceptable formats: CIDR (e.g., "192.168.10.0/24") or inclusive range (e.g., "192.168.10.50-192.168.10.100").	string	true

Back to Group

MigrationsConfiguration

MigrationsConfiguration holds cluster-wide live-migration tuning parameters.

Field	Description	Scheme	Required
parallelMigrationsPerCluster	ParallelMigrationsPerCluster is the total number of concurrent live migrations allowed cluster-wide. Defaults to 5.	*uint32	false
parallelOutboundMigrationsPerNode	ParallelOutboundMigrationsPerNode is the maximum number of concurrent outgoing live migrations allowed per node. Defaults to 2.	*uint32	false
completionTimeoutPerGiB	CompletionTimeoutPerGiB is the maximum number of seconds per GiB a migration is allowed to take. Defaults to 150.	*int64	false
progressTimeout	ProgressTimeout is the maximum number of seconds a live migration is allowed to make no progress before it is cancelled. Defaults to 150.	*int64	false

Back to Group

NetworkConfiguration

Field	Description	Scheme	Required
networkCIDR	NetworkCIDR specifies the IP address range used to assign network addresses to all managed workloads, including containers and virtual machines. This CIDR block serves as the default pool for internal IP allocation across the platform.	string	false
dnsServerIP	DNSServerIP is the IP address of the DNS server used by the entire platform. This field is required. In offline deployments, this address will be configured as the DNS resolver for all nodes and services within the Kubermatic Virtualization Platform.	string	true
gatewayIP	GatewayIP specifies the IP address of the network gateway for the default NetworkCIDR. This gateway facilitates external network access for workloads within the Kubermatic Virtualization Platform.	string	false
serviceCIDR	ServiceCIDR specifies the IP address range reserved for internal platform services. This CIDR block is used to allocate virtual IPs for services, ensuring they are reachable within the platform.	string	false
tunnelInterface	TunnelInterface specifies the physical NIC used for Kube-OVN overlay tunnel traffic. Accepts a single interface name (e.g., "eth0"), a comma-separated list (e.g., "eth0,eth1"), or a regular expression (e.g., "^eth[0-9]+$").	string	false

Back to Group

NoneSpec

NoneSpec is a marker type used to explicitly disable LB/CSI integration. It carries no configuration.

Field	Description	Scheme	Required

Back to Group

OCIConfiguration

OCIConfiguration defines how to connect to an OCI-compatible container registry. This is used for pulling container images and Helm charts in offline environments.

Field	Description	Scheme	Required
address	Address is the registry hostname and optional port (e.g., "http://registry.example.com:5000").	string	true
username	Username is the basic-auth username for registry authentication. Required if the registry requires authentication.	string	false
password	Password is the basic-auth password for registry authentication.	string	false
insecure	Insecure, when true, disables TLS verification and may allow HTTP connections. Use only for internal, trusted registries. Not recommended for production.	bool	false

Back to Group

OfflineSettings

OfflineSettings configures the platform for air-gapped (offline) operation. When used, all external dependencies must be served from internal mirrors.

Field	Description	Scheme	Required
enabled	Enabled indicates whether the platform is operating in offline (air-gapped) mode. When true, all container images, Helm charts, and software packages must be sourced from the internal endpoints specified below.	bool	true
containerRegistry	ContainerRegistry specifies the internal OCI registry that hosts all container images required by the platform and workloads. This registry must be pre-populated before deployment.	OCIConfiguration	true
helmRegistry	HelmRegistry specifies the internal OCI registry or HTTP server that hosts Helm charts used by the platform. Charts must be available at this location in offline mode.	OCIConfiguration	true
packageRepository	PackageRepository is the URL or local path to the internal repository serving platform-related OS or software packages (e.g., RPMs, DEBs, or binaries). This is used during node provisioning and upgrades in offline environments.	string	true

Back to Group

PciHostDevice

PciHostDevice represents a host PCI device allowed for passthrough.

Field	Description	Scheme	Required
pciVendorSelector	PCIVendorSelector is the vendor_id:product_id tuple of the PCI device (e.g. "10DE:233B").	string	true
resourceName	ResourceName is the device-plugin resource name exposed by the host (e.g. "nvidia.com/gpu").	string	true
externalResourceProvider	ExternalResourceProvider indicates that an external device plugin manages allocation and monitoring for this device. Defaults to false.	bool	false

Back to Group

PermittedHostDevices

PermittedHostDevices declares devices that may be passed through to virtual machines.

Field	Description	Scheme	Required
pciHostDevices	PciHostDevices is the list of PCI devices allowed for passthrough.	[]PciHostDevice	false

Back to Group

StaticWorkersConfig

StaticWorkersConfig defines static worker nodes provisioned by KubeOne and kubeadm.

Field	Description	Scheme	Required
hosts	Hosts	[]HostConfig	false

Back to Group

StorageConfiguration

StorageConfiguration configures the platform’s persistent storage solution. Exactly one of the following fields must be set: None, Longhorn. (Additional storage providers may be supported in the future.) If no managed storage is desired, set None: {}.

Field	Description	Scheme	Required
none	None explicitly disables managed storage integration. Users must provide their own StorageClass or provision volumes manually.	*NoneSpec	false
longhorn	Longhorn configures Longhorn as the default distributed block storage system.	*Longhorn	false

Back to Group