k3k/docs/crds/crd-docs.md

API Reference

Packages

• k3k.io/v1alpha1

k3k.io/v1alpha1

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/v1alpha1
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/v1alpha1
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.

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	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'.

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.
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.

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 string	StorageRequestSize is the requested size for the PVC. This field is only relevant in "dynamic" mode.	1G

PersistenceMode

Underlying type: string

PersistenceMode is the storage mode of a Cluster.

Appears in:

• PersistenceConfig

PodSecurityAdmissionLevel

Underlying type: string

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

Validation:

• Enum: [privileged baseline restricted]

Appears in:

• VirtualClusterPolicySpec

VirtualClusterPolicy

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

Appears in:

• VirtualClusterPolicyList

Field	Description	Default	Validation
apiVersion string	k3k.io/v1alpha1
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/v1alpha1
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]