Local Kubermatic Kubernetes Platform (KKP) Installation

Local KKP installation is not intended for production setups.

This page will guide you through using the KKP installer local command kubermatic-installer local. This command simplifies and automates the installation of KKP using kind and a preconfigured KubeVirt seed. The command is intended only for evaluation and local development purposes. For production KKP installation use the CE installation guide or EE installation guide.

Pre-Installation Requirements

  • Operating System: Currently, only Linux is supported.
  • Disk Space: A minimum of 10Gi is recommended.
  • RAM: At least 8Gi of RAM is needed; 16Gi is recommended for more than a single KubeVirt user cluster.
  • kind (version 0.17 or higher): Please refer to the kind documentation for installation instructions.

The kubermatic-installer local kind is currently considered experimental. It will install KubeVirt and CDI inside of the kind cluster and for every user cluster download VM image from Kubermatic hosted registry. KubeVirt nodes may require significant portion of your available CPU and RAM, in addition to 600Mi of disk space per VM image.

Installation Procedure

Follow these steps to use the KKP installer local command:

1. Download the installer. This is the only manual step; there’s no need to prepare any configuration since the installer should automatically configure KKP.

If you already have an active KKP license, you can use the enterprise edition installer. Otherwise, use the community edition installer.

KUBERMATIC_EDITION=ce
KUBERMATIC_EDITION=ee

Download the installer:

VERSION=$(curl -w '%{url_effective}' -I -L -s -S https://github.com/kubermatic/kubermatic/releases/latest -o /dev/null | sed -e 's|.*/v||')
wget https://github.com/kubermatic/kubermatic/releases/download/v${VERSION}/kubermatic-${KUBERMATIC_EDITION}-v${VERSION}-linux-amd64.tar.gz
tar -xzvf kubermatic-${KUBERMATIC_EDITION}-v${VERSION}-linux-amd64.tar.gz
# Determine your macOS processor architecture type
# Replace 'amd64' with 'arm64' if using an Apple Silicon (M1) Mac.
export ARCH=amd64
# For latest version:
VERSION=$(curl -w '%{url_effective}' -I -L -s -S https://github.com/kubermatic/kubermatic/releases/latest -o /dev/null | sed -e 's|.*/v||')
# For specific version set it explicitly:
# VERSION=2.21.x
wget "https://github.com/kubermatic/kubermatic/releases/download/v${VERSION}/kubermatic-${KUBERMATIC_EDITION}-v${VERSION}-darwin-${ARCH}.tar.gz"
tar -xzvf "kubermatic-${KUBERMATIC_EDITION}-v${VERSION}-darwin-${ARCH}.tar.gz"

You can find more information regarding the download instructions in the CE installation guide or EE installation guide.

2. Provide the image pull secret (EE)

This step is only required if you are using the enterprise edition installer. Replace ${AUTH_TOKEN} with the Docker authentication JSON provided by Kubermatic and run the following command:

sed -i 's/<your-auth-token>/${AUTH_TOKEN}/g' examples/kubermatic.example.yaml

3. Run the local command.

./kubermatic-installer local kind

The KKP installation should take no longer than a couple of minutes. First, it creates a kind cluster named kind-kkp-cluster, exposes ports 443, 80 for the KKP API, KKP dashboard, dex, and ports 6443, 8088 for user cluster kube-apiserver via the tunneling expose strategy. You can examine the generated kind config, as well as the generated Kubermatic and Helm values configuration, under your working directory:

./examples/kind-config.yaml
./examples/kubermatic.yaml
./examples/values.yaml

The installer also configures a single Seed and Presets for KubeVirt user clusters deployed in the same kind cluster. You can inspect the resources using kubectl:

kubectl get seed -nkubermatic kubermatic -o yaml
kubectl get preset -nkubermatic local -o yaml

Post-Installation

After completing the installation, you should have a local, trimmed-down KKP setup suitable for development purposes. The installer will provide login instructions:

INFO[0408] KKP installed successfully, login at http://10.0.0.12.nip.io
INFO[0408]   Default login:    kubermatic@example.com
INFO[0408]   Default password: password

Teardown Procedure

When you’re finished experimenting with your local KKP setup, you can easily terminate it with a single command:

kind delete cluster --name kkp-cluster

Configuration and Customization

The KKP dashboard is exposed using nip.io, and certain browser plugins, such as various ad blockers, may prevent access to nip.io. If this is the case, consider disabling these plugins.

By default, KubeVirt is configured to use hardware virtualization. If this is not possible for your setup, consider setting KubeVirt to use software emulation mode.

On Linux, KubeVirt uses the inode notify kernel subsystem inotify to watch for changes in certain files. Usually you shouldn’t need to configure this but in case you can observe the virt-handler failing with

kubectl log -nkubevirt ds/virt-handler
...
{"component":"virt-handler","level":"fatal","msg":"Failed to create an inotify watcher","pos":"cert-manager.go:105","reason":"too many open files","timestamp":"2023-06-22T09:58:24.284130Z"}

You may need to set the default values higher to ensure KubeVirt operates correctly. How to change this, along with reasonably elevated values, is described below but it’s recommended to inspect your system to figure out the correct inotify values depending on your needs and current setup.

sudo sysctl -w fs.inotify.max_user_watches=524288
sudo sysctl -w fs.inotify.max_user_instances=256