k3k/docs/crds/crds.md

API Reference

Packages

• k3k.io/v1beta1

k3k.io/v1beta1

Resource Types

• Cluster
• ClusterList
• VirtualClusterPolicy
• VirtualClusterPolicyList

Addon

Addon specifies a Secret containing YAML to be deployed on cluster startup.

Appears in:

• ClusterSpec

Field	Description	Default	Validation
secretNamespace string	SecretNamespace is the namespace of the Secret.
secretRef string	SecretRef is the name of the Secret.

Cluster

Cluster defines a virtual Kubernetes cluster managed by k3k. It specifies the desired state of a virtual cluster, including version, node configuration, and networking. k3k uses this to provision and manage these virtual clusters.

Appears in:

• ClusterList

Field	Description	Default	Validation
apiVersion string	k3k.io/v1beta1
kind string	Cluster
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec ClusterSpec	Spec defines the desired state of the Cluster.	{ }

ClusterList

ClusterList is a list of Cluster resources.

Field	Description	Default	Validation
apiVersion string	k3k.io/v1beta1
kind string	ClusterList
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items Cluster array

ClusterMode

Underlying type: string

ClusterMode is the possible provisioning mode of a Cluster.

Validation:

• Enum: [shared virtual]

Appears in:

• ClusterSpec
• VirtualClusterPolicySpec

ClusterPhase

Underlying type: string

ClusterPhase is a high-level summary of the cluster's current lifecycle state.

Appears in:

• ClusterStatus

ClusterSpec

ClusterSpec defines the desired state of a virtual Kubernetes cluster.

Appears in:

• Cluster

Field	Description	Default	Validation
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 ClusterMode	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 PersistenceConfig	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 ExposeConfig	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 Addon array	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	CustomCAs specifies the cert/key pairs for custom CA certificates.
sync SyncConfig	Sync specifies the resources types that will be synced from virtual cluster to host cluster.	{ }
secretMounts SecretMount array	SecretMounts specifies a list of secrets to mount into server and agent pods. Each entry defines a secret and its mount path within the pods.

ConfigMapSyncConfig

ConfigMapSyncConfig specifies the sync options for services.

Appears in:

• SyncConfig

Field	Description	Default	Validation
enabled boolean	Enabled is an on/off switch for syncing resources.	true
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.

CredentialSource

CredentialSource defines where to get a credential from. It can represent either a TLS key pair or a single private key.

Appears in:

• CredentialSources

Field	Description	Default	Validation
secretName string	The secret must contain specific keys based on the credential type: - For TLS certificate pairs (e.g., ServerCA): tls.crt and tls.key. - For the ServiceAccountToken signing key: tls.key.

CredentialSources

CredentialSources lists all the required credentials, including both TLS key pairs and single signing keys.

Appears in:

• CustomCAs

Field	Description	Default	Validation
serverCA CredentialSource	ServerCA specifies the server-ca cert/key pair.
clientCA CredentialSource	ClientCA specifies the client-ca cert/key pair.
requestHeaderCA CredentialSource	RequestHeaderCA specifies the request-header-ca cert/key pair.
etcdServerCA CredentialSource	ETCDServerCA specifies the etcd-server-ca cert/key pair.
etcdPeerCA CredentialSource	ETCDPeerCA specifies the etcd-peer-ca cert/key pair.
serviceAccountToken CredentialSource	ServiceAccountToken specifies the service-account-token key.

CustomCAs

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

Appears in:

• ClusterSpec

Field	Description	Default	Validation
enabled boolean	Enabled toggles this feature on or off.	true
sources CredentialSources	Sources defines the sources for all required custom CA certificates.

ExposeConfig

ExposeConfig specifies options for exposing the API server.

Appears in:

• ClusterSpec

Field	Description	Default	Validation
ingress IngressConfig	Ingress specifies options for exposing the API server through an Ingress.
loadBalancer LoadBalancerConfig	LoadBalancer specifies options for exposing the API server through a LoadBalancer service.
nodePort NodePortConfig	NodePort specifies options for exposing the API server through NodePort.

IngressConfig

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

Appears in:

• ExposeConfig

Field	Description	Default	Validation
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.

IngressSyncConfig

IngressSyncConfig specifies the sync options for services.

Appears in:

• SyncConfig

Field	Description	Default	Validation
enabled boolean	Enabled is an on/off switch for syncing resources.	false
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.

LoadBalancerConfig

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

Appears in:

• ExposeConfig

Field	Description	Default	Validation
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.

NodePortConfig

NodePortConfig specifies options for exposing the API server through NodePort.

Appears in:

• ExposeConfig

Field	Description	Default	Validation
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.

PersistenceConfig

PersistenceConfig specifies options for persisting etcd data.

Appears in:

• ClusterSpec

Field	Description	Default	Validation
type PersistenceMode	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 Quantity	StorageRequestSize is the requested size for the PVC. This field is only relevant in "dynamic" mode.	2G

PersistenceMode

Underlying type: string

PersistenceMode is the storage mode of a Cluster.

Appears in:

• PersistenceConfig

PersistentVolumeClaimSyncConfig

PersistentVolumeClaimSyncConfig specifies the sync options for services.

Appears in:

• SyncConfig

Field	Description	Default	Validation
enabled boolean	Enabled is an on/off switch for syncing resources.	true
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.

PodSecurityAdmissionLevel

Underlying type: string

PodSecurityAdmissionLevel is the policy level applied to the pods in the namespace.

Validation:

• Enum: [privileged baseline restricted]

Appears in:

• VirtualClusterPolicySpec

PriorityClassSyncConfig

PriorityClassSyncConfig specifies the sync options for services.

Appears in:

• SyncConfig

Field	Description	Default	Validation
enabled boolean	Enabled is an on/off switch for syncing resources.	false
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.

SecretMount

SecretMount defines a secret to be mounted into server or agent pods, allowing for custom configurations, certificates, or other sensitive data.

Appears in:

• ClusterSpec

Field	Description	Default	Validation
secretName string	secretName is the name of the secret in the pod's namespace to use. More info: https://kubernetes.io/docs/concepts/storage/volumes#secret
items KeyToPath array	items If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'.
defaultMode integer	defaultMode is Optional: mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.
optional boolean	optional field specify whether the Secret or its keys must be defined
mountPath string	MountPath is the path within server and agent pods where the secret contents will be mounted.
subPath string	SubPath is an optional path within the secret to mount instead of the root. When specified, only the specified key from the secret will be mounted as a file at MountPath, keeping the parent directory writable.
role string	Role is the type of the k3k pod that will be used to mount the secret. This can be 'server', 'agent', or 'all' (for both).		Enum: [server agent all]

SecretSyncConfig

SecretSyncConfig specifies the sync options for services.

Appears in:

• SyncConfig

Field	Description	Default	Validation
enabled boolean	Enabled is an on/off switch for syncing resources.	true
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.

ServiceSyncConfig

ServiceSyncConfig specifies the sync options for services.

Appears in:

• SyncConfig

Field	Description	Default	Validation
enabled boolean	Enabled is an on/off switch for syncing resources.	true
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.

SyncConfig

SyncConfig will contain the resources that should be synced from virtual cluster to host cluster.

Appears in:

• ClusterSpec
• VirtualClusterPolicySpec

Field	Description	Default	Validation
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:true }
priorityClasses PriorityClassSyncConfig	PriorityClasses resources sync configuration.	{ enabled:false }

VirtualClusterPolicy

VirtualClusterPolicy allows defining common configurations and constraints for clusters within a clusterpolicy.

Appears in:

• VirtualClusterPolicyList

Field	Description	Default	Validation
apiVersion string	k3k.io/v1beta1
kind string	VirtualClusterPolicy
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec VirtualClusterPolicySpec	Spec defines the desired state of the VirtualClusterPolicy.	{ }

VirtualClusterPolicyList

VirtualClusterPolicyList is a list of VirtualClusterPolicy resources.

Field	Description	Default	Validation
apiVersion string	k3k.io/v1beta1
kind string	VirtualClusterPolicyList
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items VirtualClusterPolicy array

VirtualClusterPolicySpec

VirtualClusterPolicySpec defines the desired state of a VirtualClusterPolicy.

Appears in:

• VirtualClusterPolicy

Field	Description	Default	Validation
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 ClusterMode	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	PodSecurityAdmissionLevel specifies the pod security admission level applied to the pods in the namespace.		Enum: [privileged baseline restricted]
sync SyncConfig	Sync specifies the resources types that will be synced from virtual cluster to host cluster.	{ }