Requirements

SELinux

SELinux is fully supported provided it is enabled and set to “Enforcing” mode at the time of the initial cluster installation on all nodes. This is the default configuration for Red Hat Enterprise Linux and its derivatives, such as Oracle Linux and AlmaLinux. If the mode is set to “Enforcing” prior to install time, the necessary SELinux packages will be installed, and the cluster will be started with support for SELinux. For these reasons, enabling SELinux after the initial cluster installation is not supported.

Firewalld

Please see the Networking Guide for the current firewall recommendations.

Hardware

Refer to the System Requirements Guide for the current hardware, operating system, and network requirements.

Networking

A minimum of one network interface card must be present and configured as the default gateway on the node when the cluster is installed. If the node does not have an interface with the default route, a default route must be configured. Even a black-hole route via a dummy interface will suffice. The K3s software requires a default route in order to auto-detect the node’s primary IP, and for cluster routing to function properly. To add a dummy route do the following:

ip link add dummy0 type dummy
ip link set dummy0 up
ip addr add 203.0.113.254/31 dev dummy0
ip route add default via 203.0.113.255 dev dummy0 metric 1000

Special Considerations when using Multiple Network Interfaces

If there are special network considerations, such as using a non-default interface for cluster communication, that must be configured using the INSTALL_K3S_EXEC environment variable as below before installing the cluster or joining nodes.

As an example, consider the case where the node contains two interfaces, bond0 and bond1, where the default route exists through bond0, but where bond1 should be used for cluster communication. In that case, ensure that the INSTALL_K3S_EXEC environment variable is set as follows in the environment prior to installing or joining the cluster. Assuming that bond1 has the local IP address 10.0.0.10:

export INSTALL_K3S_EXEC="<MODE> --node-ip 10.0.0.10 --flannel-iface=bond1"

Where MODE should be one of server or agent depending on the role of the node. The initial node used to create the cluster MUST be server, and additional nodes vary depending on the role.

DNS and Hostname Resolution

Kubernetes clusters use internal DNS to allow services and pods to communicate using predictable hostnames. Each service is assigned a DNS name in the format:

<service>.<namespace>.svc.cluster.local

These names are automatically resolvable from within the cluster using the coredns service, which is deployed by default with K3s. This means that any pod or service can refer to another by its internal DNS name without needing to know its IP address.

For DNS queries outside the cluster.local domain (for example, public internet hostnames or your organization’s internal DNS), coredns forwards requests to an upstream nameserver. By default, this is set to Google’s public DNS servers (8.8.8.8 and 8.8.4.4).

However, if the primary installation node has custom nameservers configured in /etc/resolv.conf, K3s will automatically configure coredns to use those as the upstream resolvers instead. This allows the cluster to integrate with your local or corporate DNS infrastructure if needed.

Note for multi-datacenter deployments: If your cluster spans multiple datacenters and each datacenter uses different DNS servers, the cluster will be configured to forward DNS requests to the servers specified in /etc/resolv.conf on the node where the installation was performed. If nodes in other datacenters cannot reach those DNS servers (for example, if the servers are only routable within one datacenter), you must use the hostAliases mechanism (as described for air-gapped environments) to ensure proper DNS resolution for required services across all nodes.

Note for air-gapped environments: In air-gapped clusters, or any environment where no upstream DNS servers are available or configurable, external DNS queries will not resolve. In these cases, you can override DNS names for required services directly in the configuration using host overrides. This allows the cluster to function without external DNS resolution.

Example: To override hostnames in an air-gapped environment, add a hostAliases section to your values.yaml configuration.

manager:
  hostAliases:
    - ip: "192.0.2.10"
      hostnames:
        - acd-manager
        - acd-manager.example.local
    - ip: "192.0.2.11"
      hostnames:
        - acd-manager-alt
        - acd-manager-alt.example.local

Next Steps

Continue reading the Installation Guide.