Airgap install

You can install k0s in an environment with restricted Internet access. Airgap installation requires an image bundle, which contains all the needed container images. There are two options to get the image bundle:

  • Use a ready-made image bundle, which is created for each k0s release. It can be downloaded from the releases page.
  • Create your own image bundle. In this case, you can easily customize the bundle to also include container images, which are not used by default in k0s.

Prerequisites

In order to create your own image bundle, you need

  • A working cluster with at least one controller, to be used to build the image bundle. For more information, refer to the Quick Start Guide.
  • The containerd CLI management tool ctr, installed on the worker machine (refer to the ContainerD getting-started guide).

1. Create your own image bundle (optional)

k0s/containerd uses OCI (Open Container Initiative) bundles for airgap installation. OCI bundles must be uncompressed. As OCI bundles are built specifically for each architecture, create an OCI bundle that uses the same processor architecture (x86-64, ARM64, ARMv7) as on the target system.

k0s offers two methods for creating OCI bundles, one using Docker and the other using a previously set up k0s worker. Be aware, though, that you cannot use the Docker method for the ARM architectures due to kube-proxy image multiarch manifest problem.

Note: k0s strictly matches image architecture, e.g. arm/v7 images won’t work for arm64.

Docker

  1. Pull the images.

    1. k0s airgap list-images | xargs -I{} docker pull {}
  2. Create a bundle.

    1. docker image save $(k0s airgap list-images | xargs) -o bundle_file

Previously set up k0s worker

As containerd pulls all the images during the k0s worker normal bootstrap, you can use it to build the OCI bundle with images.

Use the following commands on a machine with an installed k0s worker:

  1. ctr --namespace k8s.io \
  2. --address /run/k0s/containerd.sock \
  3. images export bundle_file $(k0s airgap list-images | xargs)

2a. Sync the bundle file with the airgapped machine (locally)

Copy the bundle_file you created in the previous step or downloaded from the releases page to the target machine into the images directory in the k0s data directory. Copy the bundle only to the worker nodes. Controller nodes don’t use it.

  1. # mkdir -p /var/lib/k0s/images
  2. # cp bundle_file /var/lib/k0s/images/bundle_file

2b. Sync the bundle file with the airgapped machines (remotely with k0sctl)

As an alternative to the previous step, you can use k0sctl to upload the bundle file to the worker nodes. k0sctl can also be used to upload k0s binary file to all nodes. Take a look at this example (k0sctl.yaml) with one controller and one worker node to upload the bundle file and k0s binary:

  1. apiVersion: k0sctl.k0sproject.io/v1beta1
  2. kind: ClusterConfig
  3. metadata:
  4. name: k0s-cluster
  5. spec:
  6. k0s:
  7. version: 1.26.8+k0s.0
  8. hosts:
  9. - role: controller
  10. ssh:
  11. address: <controller-ip-address>
  12. user: ubuntu
  13. keyPath: /path/.ssh/id_rsa
  14. # uploadBinary: <boolean>
  15. # When true the k0s binaries are cached and uploaded
  16. # from the host running k0sctl instead of downloading
  17. # directly to the target host.
  18. uploadBinary: true
  19. # k0sBinaryPath: <local filepath>
  20. # Upload a custom or manually downloaded k0s binary
  21. # from a local path on the host running k0sctl to the
  22. # target host.
  23. # k0sBinaryPath: path/to/k0s_binary/k0s
  24. - role: worker
  25. ssh:
  26. address: <worker-ip-address>
  27. user: ubuntu
  28. keyPath: /path/.ssh/id_rsa
  29. uploadBinary: true
  30. files:
  31. # This airgap bundle file will be uploaded from the k0sctl
  32. # host to the specified directory on the target host
  33. - src: /local/path/to/bundle-file/airgap-bundle-amd64.tar
  34. dstDir: /var/lib/k0s/images/
  35. perm: 0755

3. Ensure pull policy in the k0s.yaml (optional)

Use the following k0s.yaml to ensure that containerd does not pull images for k0s components from the Internet at any time.

  1. apiVersion: k0s.k0sproject.io/v1beta1
  2. kind: ClusterConfig
  3. metadata:
  4. name: k0s
  5. spec:
  6. images:
  7. default_pull_policy: Never

4. Set up the controller and worker nodes

Refer to the Manual Install for information on setting up the controller and worker nodes locally. Alternatively, you can use k0sctl.

Note: During the worker start up k0s imports all bundles from the $K0S_DATA_DIR/images before starting kubelet.