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).
-
Generate a yaml config file that uses the default settings.
mkdir -p /etc/k0s k0s config create > /etc/k0s/k0s.yaml
-
Modify the new yaml config file according to your needs, refer to Configuration file reference below.
-
Install k0s with your new config file.
sudo k0s install controller -c /etc/k0s/k0s.yaml
-
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
port: 6443
k0sApiPort: 9443
externalAddress: my-lb-address.example.com
sans:
- 192.168.68.104
storage:
type: etcd
etcd:
peerAddress: 192.168.68.104
network:
podCIDR: 10.244.0.0/16
serviceCIDR: 10.96.0.0/12
provider: kuberouter
calico: null
kuberouter:
mtu: 0
peerRouterIPs: ""
peerRouterASNs: ""
autoMTU: true
podSecurityPolicy:
defaultPolicy: 00-k0s-privileged
telemetry:
enabled: true
installConfig:
users:
etcdUser: etcd
kineUser: kube-apiserver
konnectivityUser: konnectivity-server
kubeAPIserverUser: kube-apiserver
kubeSchedulerUser: kube-scheduler
images:
konnectivity:
image: k8s.gcr.io/kas-network-proxy/proxy-agent
version: v0.0.25
metricsserver:
image: k8s.gcr.io/metrics-server/metrics-server
version: v0.5.0
kubeproxy:
image: k8s.gcr.io/kube-proxy
version: v1.23.12
coredns:
image: k8s.gcr.io/coredns/coredns
version: v1.7.0
calico:
cni:
image: docker.io/calico/cni
version: v3.18.1
node:
image: docker.io/calico/node
version: v3.18.1
kubecontrollers:
image: docker.io/calico/kube-controllers
version: v3.18.1
kuberouter:
cni:
image: docker.io/cloudnativelabs/kube-router
version: v1.2.1
cniInstaller:
image: quay.io/k0sproject/cni-node
version: 0.1.0
default_pull_policy: IfNotPresent
konnectivity:
agentPort: 8132
adminPort: 8133
spec
Key Detail#
spec.api
#
Element | Description |
---|---|
externalAddress |
The loadbalancer address (for k0s controllers running behind a loadbalancer). Configures all cluster components to connect to this address and also configures this address for use when joining new nodes to the cluster. |
address |
Local address on wihich to bind an API. Also serves as one of the addresses pushed on the k0s create service certificate on the API. Defaults to first non-local address found on the node. |
sans |
List of additional addresses to push to API servers serving the certificate. |
extraArgs |
Map of key-values (strings) for any extra arguments to pass down to Kubernetes api-server process. |
port ¹ |
Custom port for kube-api server to listen on (default: 6443) |
k0sApiPort ¹ |
Custom port for k0s-api server to listen on (default: 9443) |
¹ If port
and k0sApiPort
are used with the externalAddress
element, the loadbalancer serving at externalAddress
must listen on the same ports.
spec.storage
#
Element | Description |
---|---|
type |
Type of the data store (valid values:etcd or kine ). Note: Type etcd will cause k0s to create and manage an elastic etcd cluster within the controller nodes. |
etcd.peerAddress |
Node address used for etcd cluster peering. |
kine.dataSource |
kine datasource URL. |
spec.network
#
Element | Description |
---|---|
provider |
Network provider (valid values: calico , kuberouter , or custom ). For custom , you can push any network provider (default: kuberouter ). Be aware that it is your responsibility to configure all of the CNI-related setups, including the CNI provider itself and all necessary host levels setups (for example, CNI binaries). Note: Once you initialize the cluster with a network provider the only way to change providers is through a full cluster redeployment. |
podCIDR |
Pod network CIDR to use in the cluster. |
serviceCIDR |
Network CIDR to use for cluster VIP services. |
spec.network.calico
#
Element | Description |
---|---|
mode |
vxlan (default) or ipip |
overlay |
Overlay mode: Always (default), CrossSubnet or Never (requires mode=vxlan to disable calico overlay-network). |
vxlanPort |
The UDP port for VXLAN (default: 4789 ). |
vxlanVNI |
The virtual network ID for VXLAN (default: 4096 ). |
mtu |
MTU for overlay network (default: 0 , which causes Calico to detect optimal MTU during bootstrap). |
wireguard |
Enable wireguard-based encryption (default: false ). Your host system must be wireguard ready (refer to the Calico documentation for details). |
flexVolumeDriverPath |
The host path for Calicos flex-volume-driver(default: /usr/libexec/k0s/kubelet-plugins/volume/exec/nodeagent~uds ). Change this path only if the default path is unwriteable (refer to Project Calico Issue #2712 for details). Ideally, you will pair this option with a custom volumePluginDir in the profile you use for your worker nodes. |
ipAutodetectionMethod |
Use to force Calico to pick up the interface for pod network inter-node routing (default: "" , meaning not set, so that Calico will instead use its defaults). For more information, refer to the Calico documentation. |
spec.network.kuberouter
#
Element | Description |
---|---|
autoMTU |
Autodetection of used MTU (default: true ). |
mtu |
Override MTU setting, if autoMTU must be set to false ). |
peerRouterIPs |
Comma-separated list of global peer addresses. |
peerRouterASNs |
Comma-separated list of global peer ASNs. |
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.podSecurityPolicy
#
Use the spec.podSecurityPolicy
key to configure the default PSP.
k0s creates two PSPs out-of-the-box:
PSP | Description |
---|---|
00-k0s-privileged |
Default; no restrictions; used also for Kubernetes/k0s level system pods. |
99-k0s-restricted |
Does not allow any host namespaces or root users, nor any bind mounts from the host |
Note: Users can create supplemental PSPs and bind them to users / access accounts as necessary.
spec.controllerManager
#
Element | Description |
---|---|
extraArgs |
Map of key-values (strings) for any extra arguments you want to pass down to the Kubernetes controller manager process. |
spec.scheduler
#
Element | Description |
---|---|
extraArgs |
Map of key-values (strings) for any extra arguments you want to pass down to Kubernetes scheduler process. |
spec.workerProfiles
#
Array of spec.workerProfiles.workerProfile
. Each element has following properties:
Property | Description |
---|---|
name |
String; name to use as profile selector for the worker process |
values |
Mapping object |
For each profile, the control plane creates a separate ConfigMap with kubelet-config yaml
. Based on the --profile
argument given to the k0s worker
, the corresponding ConfigMap is used to extract the kubelet-config.yaml
file. values
are recursively merged with default kubelet-config.yaml
Note that there are several fields that cannot be overridden:
clusterDNS
clusterDomain
apiVersion
kind
Examples#
mapping:
spec:
workerProfiles:
- name: custom-role
values:
key: value
mapping:
innerKey: innerValue
Custom volumePluginDir:
spec:
workerProfiles:
- name: custom-role
values:
volumePluginDir: /var/libexec/k0s/kubelet-plugins/volume/exec
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: k8s.gcr.io/metrics-server/metrics-server
version: v0.5.0
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.5.0
. 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 completely disabling some of the system components. This allows the user to build a minimal Kubernetes control plane and use what ever components they need to fullfill their need for the controlplane. Disabling the system components happens through a commandline flag for the controller process:
--disable-components strings disable components (valid items: konnectivity-server,kube-scheduler,kube-controller-manager,control-api,csr-approver,default-psp,kube-proxy,coredns,network-provider,helm,metrics-server,kubelet-config,system-rbac)
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.