API Reference

secretNamespace string

SecretNamespace is the namespace of the Secret.

secretRef string

SecretRef is the name of the Secret.

apiVersion string

k3k.io/v1beta1

kind string

Cluster

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

spec

Spec defines the desired state of the Cluster.

{ }

apiVersion string

k3k.io/v1beta1

kind string

ClusterList

metadata ListMeta

Refer to Kubernetes API documentation for fields of metadata.

items

version string

Version is the K3s version to use for the virtual nodes.
It should follow the K3s versioning convention (e.g., v1.28.2-k3s1).
If not specified, the Kubernetes version of the host node will be used.

mode

Mode specifies the cluster provisioning mode: "shared" or "virtual".
Defaults to "shared". This field is immutable.

shared

Enum: [shared virtual]

servers integer

Servers specifies the number of K3s pods to run in server (control plane) mode.
Must be at least 1. Defaults to 1.

1

agents integer

Agents specifies the number of K3s pods to run in agent (worker) mode.
Must be 0 or greater. Defaults to 0.
This field is ignored in "shared" mode.

0

clusterCIDR string

ClusterCIDR is the CIDR range for pod IPs.
Defaults to 10.42.0.0/16 in shared mode and 10.52.0.0/16 in virtual mode.
This field is immutable.

serviceCIDR string

ServiceCIDR is the CIDR range for service IPs.
Defaults to 10.43.0.0/16 in shared mode and 10.53.0.0/16 in virtual mode.
This field is immutable.

clusterDNS string

ClusterDNS is the IP address for the CoreDNS service.
Must be within the ServiceCIDR range. Defaults to 10.43.0.10.
This field is immutable.

persistence

Persistence specifies options for persisting etcd data.
Defaults to dynamic persistence, which uses a PersistentVolumeClaim to provide data persistence.
A default StorageClass is required for dynamic persistence.

expose

Expose specifies options for exposing the API server.
By default, it’s only exposed as a ClusterIP.

nodeSelector object (keys:string, values:string)

NodeSelector specifies node labels to constrain where server/agent pods are scheduled.
In "shared" mode, this also applies to workloads.

priorityClass string

PriorityClass specifies the priorityClassName for server/agent pods.
In "shared" mode, this also applies to workloads.

tokenSecretRef SecretReference

TokenSecretRef is a Secret reference containing the token used by worker nodes to join the cluster.
The Secret must have a "token" field in its data.

tlsSANs string array

TLSSANs specifies subject alternative names for the K3s server certificate.

serverArgs string array

ServerArgs specifies ordered key-value pairs for K3s server pods.
Example: ["--tls-san=example.com"]

agentArgs string array

AgentArgs specifies ordered key-value pairs for K3s agent pods.
Example: ["--node-name=my-agent-node"]

serverEnvs EnvVar array

ServerEnvs specifies list of environment variables to set in the server pod.

agentEnvs EnvVar array

AgentEnvs specifies list of environment variables to set in the agent pod.

addons

Addons specifies secrets containing raw YAML to deploy on cluster startup.

serverLimit ResourceList

ServerLimit specifies resource limits for server nodes.

workerLimit ResourceList

WorkerLimit specifies resource limits for agent nodes.

mirrorHostNodes boolean

MirrorHostNodes controls whether node objects from the host cluster
are mirrored into the virtual cluster.

customCAs

CustomCAs specifies the cert/key pairs for custom CA certificates.

sync

Sync specifies the resources types that will be synced from virtual cluster to host cluster.

{}

enabled boolean

Enabled is an on/off switch for syncing resources.

selector object (keys:string, values:string)

Selector specifies set of labels of the resources that will be synced. If empty, then all resources of the given type will be synced.

secretName string

SecretName specifies the name of an existing secret to use.
The controller expects specific keys inside based on the credential type:
- For TLS pairs (e.g., ServerCA): 'tls.crt' and 'tls.key'.
- For ServiceAccountTokenKey: 'tls.key'.

serverCA

ServerCA specifies the server-ca cert/key pair.

clientCA

ClientCA specifies the client-ca cert/key pair.

requestHeaderCA

RequestHeaderCA specifies the request-header-ca cert/key pair.

etcdServerCA

ETCDServerCA specifies the etcd-server-ca cert/key pair.

etcdPeerCA

ETCDPeerCA specifies the etcd-peer-ca cert/key pair.

serviceAccountToken

ServiceAccountToken specifies the service-account-token key.

enabled boolean

Enabled toggles this feature on or off.

sources

Sources defines the sources for all required custom CA certificates.

ingress

Ingress specifies options for exposing the API server through an Ingress.

loadbalancer

LoadBalancer specifies options for exposing the API server through a LoadBalancer service.

nodePort

NodePort specifies options for exposing the API server through NodePort.

annotations object (keys:string, values:string)

Annotations specifies annotations to add to the Ingress.

ingressClassName string

IngressClassName specifies the IngressClass to use for the Ingress.

enabled boolean

Enabled is an on/off switch for syncing resources.

selector object (keys:string, values:string)

Selector specifies set of labels of the resources that will be synced. If empty, then all resources of the given type will be synced.

serverPort integer

ServerPort is the port on which the K3s server is exposed when type is LoadBalancer.
If not specified, the default https 443 port will be allocated.
If 0 or negative, the port will not be exposed.

etcdPort integer

ETCDPort is the port on which the ETCD service is exposed when type is LoadBalancer.
If not specified, the default etcd 2379 port will be allocated.
If 0 or negative, the port will not be exposed.

serverPort integer

ServerPort is the port on each node on which the K3s server is exposed when type is NodePort.
If not specified, a random port between 30000-32767 will be allocated.
If out of range, the port will not be exposed.

etcdPort integer

ETCDPort is the port on each node on which the ETCD service is exposed when type is NodePort.
If not specified, a random port between 30000-32767 will be allocated.
If out of range, the port will not be exposed.

type

Type specifies the persistence mode.

dynamic

storageClassName string

StorageClassName is the name of the StorageClass to use for the PVC.
This field is only relevant in "dynamic" mode.

storageRequestSize string

StorageRequestSize is the requested size for the PVC.
This field is only relevant in "dynamic" mode.

1G

enabled boolean

ServerPort is the port on each node on which the K3s server is exposed when type is NodePort.
If not specified, a random port between 30000-32767 will be allocated.
If out of range, the port will not be exposed.

etcdPort integer

ETCDPort is the port on each node on which the ETCD service is exposed when type is NodePort.
If not specified, a random port between 30000-32767 will be allocated.
If out of range, the port will not be exposed.

enabled boolean

Enabled is an on/off switch for syncing resources.

selector object (keys:string, values:string)

Selector specifies set of labels of the resources that will be synced. If empty then all resources of the given type will be synced.

enabled boolean

Enabled is an on/off switch for syncing resources.

selector object (keys:string, values:string)

Selector specifies set of labels of the resources that will be synced. If empty then all resources of the given type will be synced.

enabled boolean

Enabled is an on/off switch for syncing resources.

selector object (keys:string, values:string)

Selector specifies set of labels of the resources that will be synced. If empty then all resources of the given type will be synced.

services ServiceSyncConfig

Services resources sync configuration.

{ enabled:true }

configmaps ConfigMapSyncConfig

ConfigMaps resources sync configuration.

{ enabled:true }

secrets SecretSyncConfig

Secrets resources sync configuration.

{ enabled:true }

ingresses IngressSyncConfig

Ingresses resources sync configuration.

{ enabled:false }

persistentVolumeClaims PersistentVolumeClaimSyncConfig

PersistentVolumeClaims resources sync configuration.

{ enabled:false }

priorityClasses PriorityClassSyncConfig

PriorityClasses resources sync configuration.

{ enabled:false }

apiVersion string

k3k.io/v1beta1

kind string

VirtualClusterPolicy

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

spec

Spec defines the desired state of the VirtualClusterPolicy.

{ }

apiVersion string

k3k.io/v1beta1

kind string

VirtualClusterPolicyList

metadata ListMeta

Refer to Kubernetes API documentation for fields of metadata.

items

quota ResourceQuotaSpec

Quota specifies the resource limits for clusters within a clusterpolicy.

limit LimitRangeSpec

Limit specifies the LimitRange that will be applied to all pods within the VirtualClusterPolicy
to set defaults and constraints (min/max)

defaultNodeSelector object (keys:string, values:string)

DefaultNodeSelector specifies the node selector that applies to all clusters (server + agent) in the target Namespace.

defaultPriorityClass string

DefaultPriorityClass specifies the priorityClassName applied to all pods of all clusters in the target Namespace.

allowedMode

AllowedMode specifies the allowed cluster provisioning mode. Defaults to "shared".

shared

Enum: [shared virtual]

disableNetworkPolicy boolean

DisableNetworkPolicy indicates whether to disable the creation of a default network policy for cluster isolation.

podSecurityAdmissionLevel

PodSecurityAdmissionLevel specifies the pod security admission level applied to the pods in the namespace.

Enum: [privileged baseline restricted]