API Reference

secretNamespace string

SecretNamespace is the namespace of the Secret.

secretRef string

SecretRef is the name of the Secret.

name string

name is the name of the VirtualClusterPolicy currently applied to this cluster.

MinLength: 1

priorityClass string

priorityClass is the priority class enforced by the active VirtualClusterPolicy.

nodeSelector object (keys:string, values:string)

nodeSelector is a node selector enforced by the active VirtualClusterPolicy.

serverAffinity Affinity

serverAffinity is the affinity rules for server pods enforced by the active VirtualClusterPolicy.
This includes both node affinity and pod affinity/anti-affinity rules.

agentAffinity Affinity

agentAffinity is the affinity rules for agent pods enforced by the active VirtualClusterPolicy.
This includes both node affinity and pod affinity/anti-affinity rules.

sync SyncConfig

sync is the SyncConfig enforced by the active VirtualClusterPolicy.

runtimeClassName string

SecurityContext specifies custom SecurityContext to be added
to the agent and server pods of the cluster in virtual or shared mode.

securityContext SecurityContext

RuntimeClassName specifies alternative runtime class for the
agent and server pods of the cluster in virtual or shared mode.

hostUsers boolean

HostUsers sets the user namespace for server and agent pods.
If set to true or not present, the pod will be run in the host user namespace.
When set to false, a new userns is created for the pod.
This field is alpha-level and is only honored by servers that enable the UserNamespacesSupport feature.

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.

{ }

status ClusterStatus

Status reflects the observed state of the Cluster.

{ }

apiVersion string

k3k.io/v1beta1

kind string

ClusterList

metadata ListMeta

Refer to Kubernetes API documentation for fields of metadata.

items Cluster array

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.

serverResources ResourceRequirements

ServerResources specifies resources limits and requests for server nodes.

workerResources ResourceRequirements

WorkerResources specifies resources limits and requests for worker nodes.

serverAffinity Affinity

ServerAffinity specifies the affinity rules for server pods.
This includes both node affinity and pod affinity/anti-affinity rules.

agentAffinity Affinity

AgentAffinity specifies the affinity rules for agent pods.
This includes both node affinity and pod affinity/anti-affinity rules.

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.

securityContext SecurityContext

SecurityContext specifies custom SecurityContext to be added
to the agent and server pods of the cluster in virtual or shared mode.
This option will override the SecurityContext set by default for virtual mode.

runtimeClassName string

RuntimeClassName specifies alternative runtime class for the
agent and server pods of the cluster in virtual or shared mode.

hostUsers boolean

HostUsers sets the user namespace for server and agent pods.
If set to true or not present, the pod will be run in the host user namespace.
When set to false, a new userns is created for the pod.
This field is alpha-level and is only honored by servers that enable the UserNamespacesSupport feature.

hostVersion string

HostVersion is the Kubernetes version of the host node.

clusterCIDR string

ClusterCIDR is the CIDR range for pod IPs.

serviceCIDR string

ServiceCIDR is the CIDR range for service IPs.

clusterDNS string

ClusterDNS is the IP address for the CoreDNS service.

tlsSANs string array

TLSSANs specifies subject alternative names for the K3s server certificate.

policyName string

PolicyName specifies the virtual cluster policy name bound to the virtual cluster.

policy AppliedPolicy

policy represents the status of the policy applied to this cluster.
This field is set by the VirtualClusterPolicy controller.

kubeletPort integer

KubeletPort specefies the port used by k3k-kubelet in shared mode.

conditions Condition array

Conditions are the individual conditions for the cluster set.

phase ClusterPhase

Phase is a high-level summary of the cluster’s current lifecycle state.

Unknown

Enum: [Pending Provisioning Ready Failed Terminating Unknown]

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.

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.

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.

enabled boolean

Enabled toggles this feature on or off.

true

sources CredentialSources

Sources defines the sources for all required custom CA certificates.

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.

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.

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.

disableTLSSecretTranslation boolean

DisableTLSSecretTranslation is an on/off switch for translating TLS secrets
from virtual cluster to host cluster

false

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

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.

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.

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]

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.

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.

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.

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 }

storageClasses StorageClassSyncConfig

StorageClasses 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 VirtualClusterPolicySpec

Spec defines the desired state of the VirtualClusterPolicy.

{ }

status VirtualClusterPolicyStatus

Status reflects the observed state of the VirtualClusterPolicy.

apiVersion string

k3k.io/v1beta1

kind string

VirtualClusterPolicyList

metadata ListMeta

Refer to Kubernetes API documentation for fields of metadata.

items VirtualClusterPolicy array

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.

defaultServerAffinity Affinity

DefaultServerAffinity specifies the affinity rules applied to server pods of all clusters in the target Namespace.
This includes both node affinity and pod affinity/anti-affinity rules.

defaultAgentAffinity Affinity

DefaultAgentAffinity specifies the affinity rules applied to agent pods of all clusters in the target Namespace.
This includes both node affinity and pod affinity/anti-affinity rules.

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.

{ }

runtimeClassName string

SecurityContext specifies custom SecurityContext to be added
to the agent and server pods of the cluster in virtual or shared mode.

securityContext SecurityContext

RuntimeClassName specifies alternative runtime class for the
agent and server pods of the cluster in virtual or shared mode.

hostUsers boolean

HostUsers sets the user namespace for server and agent pods.
If set to true or not present, the pod will be run in the host user namespace.
When set to false, a new userns is created for the pod.
This field is alpha-level and is only honored by servers that enable the UserNamespacesSupport feature.

observedGeneration integer

ObservedGeneration was the generation at the time the status was updated.

lastUpdateTime string

LastUpdate is the timestamp when the status was last updated.

summary string

Summary is a summary of the status.

conditions Condition array

Conditions are the individual conditions for the cluster set.