Configuration options

Using a configuration file

k0s can be installed without a config file. In that case the default configuration will be used. You can, though, create and run your own non-default configuration (used by the k0s controller nodes).

k0s supports providing only partial configurations. In case of partial configuration is provided, k0s will use the defaults for any missing values.

1. Generate a yaml config file that uses the default settings.

   mkdir -p /etc/k0s
   k0s config create > /etc/k0s/k0s.yaml

2. Modify the new yaml config file according to your needs, refer to Configuration file reference below. You can remove the default values if wanted as k0s supports partial configs too.

3. Install k0s with your new config file.

   sudo k0s install controller -c /etc/k0s/k0s.yaml

4. If you need to modify your existing configuration later on, you can change your config file also when k0s is running, but remember to restart k0s to apply your configuration changes.

   sudo k0s stop
   sudo k0s start

Configuration file reference

CAUTION: As many of the available options affect items deep in the stack, you should fully understand the correlation between the configuration file components and your specific environment before making any changes.

A YAML config file follows, with defaults as generated by the k0s config create command:

apiVersion: k0s.k0sproject.io/v1beta1
kind: ClusterConfig
metadata:
  name: k0s
spec:
  api:
    address: 192.168.68.104
    externalAddress: my-lb-address.example.com
    k0sApiPort: 9443
    port: 6443
    sans:
    - 192.168.68.104
    tunneledNetworkingMode: false
  controllerManager: {}
  extensions:
    helm:
      charts: null
      repositories: null
    storage:
      create_default_storage_class: false
      type: external_storage
  images:
    default_pull_policy: IfNotPresent
    calico:
      cni:
        image: docker.io/calico/cni
        version: v3.24.5
      kubecontrollers:
        image: docker.io/calico/kube-controllers
        version: v3.24.5
      node:
        image: docker.io/calico/node
        version: v3.24.5
    coredns:
      image: docker.io/coredns/coredns
      version: 1.10.0
    konnectivity:
      image: quay.io/k0sproject/apiserver-network-proxy-agent
      version: 0.0.33-k0s
    kubeproxy:
      image: registry.k8s.io/kube-proxy
      version: v1.26.8
    kuberouter:
      cni:
        image: docker.io/cloudnativelabs/kube-router
        version: v1.5.1
      cniInstaller:
        image: quay.io/k0sproject/cni-node
        version: 1.1.1-k0s.0
    metricsserver:
      image: registry.k8s.io/metrics-server/metrics-server
      version: v0.6.2
    pushgateway:
      image: quay.io/k0sproject/pushgateway-ttl
      version: edge@sha256:7031f6bf6c957e2fdb496161fe3bea0a5bde3de800deeba7b2155187196ecbd9
  installConfig:
    users:
      etcdUser: etcd
      kineUser: kube-apiserver
      konnectivityUser: konnectivity-server
      kubeAPIserverUser: kube-apiserver
      kubeSchedulerUser: kube-scheduler
  konnectivity:
    adminPort: 8133
    agentPort: 8132
  network:
    calico: null
    clusterDomain: cluster.local
    dualStack: {}
    kubeProxy:
      metricsBindAddress: 0.0.0.0:10249
      mode: iptables
    kuberouter:
      autoMTU: true
      hairpin: Enabled
      ipMasq: false
      metricsPort: 8080
      mtu: 0
      peerRouterASNs: ""
      peerRouterIPs: ""
    nodeLocalLoadBalancing:
      enabled: false
      envoyProxy:
        apiServerBindPort: 7443
        image:
          image: docker.io/envoyproxy/envoy-distroless
          version: v1.24.1
        konnectivityServerBindPort: 7132
      type: EnvoyProxy
    podCIDR: 10.244.0.0/16
    provider: kuberouter
    serviceCIDR: 10.96.0.0/12
  scheduler: {}
  storage:
    etcd:
      externalCluster: null
      peerAddress: 192.168.68.104
    type: etcd
  telemetry:
    enabled: true

spec Key Detail

spec.api

¹ If port and k0sApiPort are used with the externalAddress element, the loadbalancer serving at externalAddress must listen on the same ports.

spec.storage

spec.network

spec.network.calico

spec.network.calico.envVars

Environment variable’s value must be string, e.g.:

spec:
  network:
    provider: calico
    calico:
      envVars:
        TEST_BOOL_VAR: "true"
        TEST_INT_VAR: "42"
        TEST_STRING_VAR: test

K0s runs Calico with some predefined vars, which can be overwritten by setting new value in spec.network.calico.envVars:

CALICO_IPV4POOL_CIDR: "{{ spec.network.podCIDR }}"
CALICO_DISABLE_FILE_LOGGING: "true"
FELIX_DEFAULTENDPOINTTOHOSTACTION: "ACCEPT"
FELIX_LOGSEVERITYSCREEN: "info"
FELIX_HEALTHENABLED: "true"
FELIX_PROMETHEUSMETRICSENABLED: "true"

In SingleStack mode there are additional vars:

FELIX_IPV6SUPPORT: "false"

In DualStack mode there are additional vars:

CALICO_IPV6POOL_NAT_OUTGOING: "true"
FELIX_IPV6SUPPORT: "true"
IP6: "autodetect"
CALICO_IPV6POOL_CIDR: "{{ spec.network.dualStack.IPv6podCIDR }}"

spec.network.kuberouter

Note: Kube-router allows many networking aspects to be configured per node, service, and pod (for more information, refer to the Kube-router user guide).

spec.network.kubeProxy

Default kube-proxy iptables settings:

iptables:
  masqueradeAll: false
  masqueradeBit: null
  minSyncPeriod: 0s
  syncPeriod: 0s

Default kube-proxy ipvs settings:

ipvs:
  excludeCIDRs: null
  minSyncPeriod: 0s
  scheduler: ""
  strictARP: false
  syncPeriod: 0s
  tcpFinTimeout: 0s
  tcpTimeout: 0s
  udpTimeout: 0s

spec.network.nodeLocalLoadBalancing

Configuration options related to k0s’s node-local load balancing feature.

Note: This feature is experimental! Expect instabilities and/or breaking changes.

spec.network.nodeLocalLoadBalancing.envoyProxy

Configuration options required for using Envoy as the backing implementation for node-local load balancing.

Note: This type of load balancing is not supported on ARMv7 workers.

spec.controllerManager

spec.scheduler

spec.workerProfiles

Worker profiles are used to manage worker-specific configuration in a centralized manner. A ConfigMap is generated for each worker profile. Based on the --profile argument given to the k0s worker, the configuration in the corresponding ConfigMap is is picked up during startup.

The worker profiles are defined as an array. Each element has following properties:

spec.workerProfiles[].values (Kubelet configuration overrides)

The Kubelet configuration overrides of a profile override the defaults defined by k0s.

Note that there are several fields that cannot be overridden:

• clusterDNS
• clusterDomain
• apiVersion
• kind
• staticPodURL

Examples

Feature Gates

The below is an example of a worker profile with feature gates enabled:

spec:
  workerProfiles:
    - name: custom-feature-gate      # name of the worker profile
      values:
         featureGates:        # feature gates mapping
            DevicePlugins: true
            Accelerators: true
            AllowExtTrafficLocalEndpoints: false

Custom volumePluginDir

spec:
  workerProfiles:
    - name: custom-pluginDir
      values:
         volumePluginDir: /var/libexec/k0s/kubelet-plugins/volume/exec

Eviction Policy

spec:
  workerProfiles:
    - name: custom-eviction
      values:
        evictionHard:
          memory.available: "500Mi"
          nodefs.available: "1Gi"
          imagefs.available: "100Gi"
        evictionMinimumReclaim:
          memory.available: "0Mi"
          nodefs.available: "500Mi"
          imagefs.available: "2Gi"

Unsafe Sysctls

spec:
  workerProfiles:
    - name: custom-eviction
      values:
        allowedUnsafeSysctls:
          - fs.inotify.max_user_instances

spec.images

Nodes under the images key all have the same basic structure:

spec:
  images:
    coredns:
      image: quay.io/coredns/coredns
      version: v1.7.0

Available keys

• spec.images.konnectivity
• spec.images.metricsserver
• spec.images.kubeproxy
• spec.images.coredns
• spec.images.calico.cni
• spec.images.calico.flexvolume
• spec.images.calico.node
• spec.images.calico.kubecontrollers
• spec.images.kuberouter.cni
• spec.images.kuberouter.cniInstaller
• spec.images.repository¹

¹ If spec.images.repository is set and not empty, every image will be pulled from images.repository

If spec.images.default_pull_policy is set and not empty, it will be used as a pull policy for each bundled image.

Example

images:
  repository: "my.own.repo"
  konnectivity:
    image: calico/kube-controllers
    version: v3.16.2
  metricsserver:
    image: registry.k8s.io/metrics-server/metrics-server
    version: v0.6.2

In the runtime the image names are calculated as my.own.repo/calico/kube-controllers:v3.16.2 and my.own.repo/metrics-server/metrics-server:v0.6.2. This only affects the the imgages pull location, and thus omitting an image specification here will not disable component deployment.

spec.extensions.helm

spec.extensions.helm is the config file key in which you configure the list of Helm repositories and charts to deploy during cluster bootstrap (for more information, refer to Helm Charts).

spec.extensions.storage

spec.extensions.storage controls bundled storage provider. The default value external makes no storage deployed.

To enable embedded host-local storage provider use the following configuration:

spec:
  extensions:
    storage:
      type: openebs_local_storage

spec.konnectivity

The spec.konnectivity key is the config file key in which you configure Konnectivity-related settings.

• agentPort agent port to listen on (default 8132)
• adminPort admin port to listen on (default 8133)

spec.telemetry

To improve the end-user experience k0s is configured by defaul to collect telemetry data from clusters and send it to the k0s development team. To disable the telemetry function, change the enabled setting to false.

The telemetry interval is ten minutes.

spec:
  telemetry:
    enabled: true

Disabling controller components

k0s allows to completely disable some of the system components. This allows users to build a minimal Kubernetes control plane and use what ever components they need to fulfill their need for the control plane. Disabling the system components happens through a command line flag for the controller process:

--disable-components strings                     disable components (valid items: api-config,autopilot,control-api,coredns,csr-approver,endpoint-reconciler,helm,konnectivity-server,kube-controller-manager,kube-proxy,kube-scheduler,metrics-server,network-provider,node-role,system-rbac,worker-config)

Note: As of k0s 1.26, the kubelet-config component has been replaced by the worker-config component. k0s will issue a warning when the old component name is being used. It is scheduled for removal in k0s 1.27. Please update to the new component name.

If you use k0sctl, just add the flag when installing the cluster for the first controller at spec.hosts.installFlags in the config file like e.g.:

spec:
  hosts:
  - role: controller
    installFlags:
    - --disable-components=metrics-server

As seen from the component list, the only always-on component is the Kubernetes api-server, without that k0s serves no purpose.