3.4. Installing K3s

This section describes how to install K3s.

K3s is a lightweight Kubernetes distribution by Kubernetes vendor Rancher. K3s is compatible with most Linux flavors and comes with a convenient multi-OS installer.

The LOCKSS Installer provides install-k3s, a script that streamlines the installation and configuration of K3s for the purposes of running the LOCKSS system. To install, configure and check K3s:

  1. In the lockss user's lockss-installer directory, run the following command 1 as root 2:

    scripts/install-k3s
    

    (Typically, this is /home/lockss/lockss-installer/scripts/install-k3s.)

  2. The install-k3s script is capable of detecting a variety of problematic situations with iptables, firewalld, and ufw (firewall). If applicable, install-k3s will display warning messages and prompt you to confirm before taking corrective action. Enter Y for "yes" and N for "no", or simply hit Enter to accept the proposed answer (displayed in square brackets).

    Caution

    If you opt out of the proposed remediations, install-k3s will proceed, but K3s is likely to malfunction without external intervention.

  3. The install-k3s script is also capable of detecting a problematic situation with DNS resolution. If applicable, install-k3s will display a warning message and the following prompt:

    IP address(es) of DNS resolvers, separated by ';'

    Enter a semicolon-separated list of DNS server IP addresses that are not loopback addresses. A suggested default will be offered to you in square brackets, consisting of non-loopback addresses collected from your machine's resolv.conf files; you can simply hit Enter to accept the suggested default.

    Troubleshooting

    For details, see Troubleshooting CoreDNS.

  4. You will be prompted for a K3s state data directory:

    K3s state data directory: [/var/lib/rancher/k3s]

    K3s stores state data in /var/lib/rancher/k3s by default, but if /var is space-limited, you should specify a different directory as the K3s state data directory will grow to at least 5-10GB. Enter a directory path of your choice followed by Enter, or simply hit Enter to accept the default.

  5. If Rancher's K3s install script (which is invoked by install-k3s) cannot recover from an error condition, it may display an error message with a suggested remediation before exiting. If applicable, perform the recommended action and re-run install-k3s.

    Troubleshooting

    For details, see Troubleshooting the K3s Installer.

  1. The LOCKSS Installer provides check-k3s, a tool to check that K3s is running and resolving DNS names properly. In the lockss user's lockss-installer directory, run this command as the lockss user 3:

    scripts/check-k3s
    

    If all tests succeed, the last line of output will be STATUS: pass.

    Troubleshooting

    If check-k3s fails (for example STATUS: fail or STATUS: fail (3 errors)) or keeps retrying the same step many times without succeeding, see Troubleshooting K3s.

  1. K3s comes with k3s check-config, a configuration and system checker. Run the following command as root 2:

    k3s check-config
    

    If all tests succeed, the last line of output will be STATUS: pass.

    Important

    On some operating systems, this checker may report an iptables error message similar to iptables v1.8.4 (nf_tables): should be older than v1.8.0 or in legacy mode (fail), even though nothing is wrong. This is a known bug in the version of K3s used by LOCKSS 2.0-alpha4. If check-k3s ran successfully previously, you may ignore this spurious error message. For details, see iptables should be older than v1.8.0 or in legacy mode.

    Troubleshooting

    If this checker fails (for example STATUS: 1 (fail)), see Troubleshooting the K3s Configuration Checker.


Footnotes

1

If you invoke install-k3s with the option --k3s-data-dir=DATADIRPATH, the directory path DATADIRPATH will be used as your answer to the K3s state data directory question without an interactive prompt.

If you invoke install-k3s with the option --assume-yes, install-k3s will assume that the answer to every interactive yes/no question is Y for "yes", and that the answer to the K3s state data directory question is the default /var/lib/rancher/k3s (unless you also used the --k3s-data-dir, which takes precedence).

2

See Running Commands as root.

3

See Running Commands as the lockss User.