Install on a developer machine

Install Konvoy on a developer machine

You can also use Konvoy to deploy Kubernetes on a single laptop using Docker to simulate cluster nodes and networking topology. This is very useful for development and end-to-end testing with Konvoy.


Before starting the development machine installation, you should verify the following:

  • Docker version 18.09.2 or later
  • kubectl v1.20.6 or later (for interacting with the running cluster)
  • Docker is configured with the following minimum requirements for CPU, memory, and disk:
    • 4 CPUs
    • 8 GB memory
    • 40 GB of free disk space
    • The disk used by Docker should be less than 85% full.


After verifying your prerequisites, you can create a Kubernetes cluster on your development machine using the following command:

konvoy up --provisioner=docker [--cluster-name <YOUR_SPECIFIED_NAME>]

This command creates Docker containers, each of which simulates a cluster host. And then it installs the Kubernetes cluster in those Docker containers, and installs default addons to support the Kubernetes cluster.

Specifically, the konvoy up --provisioner=docker command does the following:

  • Provisions one Docker container as the Kubernetes control plane node
  • Provisions one Docker container as the Kubernetes worker node
  • Deploy Kubernetes in the above Docker containers
  • Deploys all of the following default addons:
    • Calico
    • CoreDNS
    • Helm
    • MetalLB
    • Static local volume provisioner
    • Traefik
    • Kubernetes dashboard
    • Operations portal
    • Velero
    • Dex identity service
    • Dex Kubernetes client authenticator
    • Traefik forward authorization proxy
    • Kommander

The following addons are not installed by default. However, you could enable those addons by editing cluster.yaml and run konvoy up again.

  • Elasticsearch (including Elasticsearch Exporter)
  • Kibana
  • Fluent Bit
  • Prometheus operator (including Grafana, AlertManager and Prometheus Adapter)

Viewing installation operations

As noted above, you start the cluster installation by running the konvoy up --provisioner=docker command. As the konvoy up --provisioner=docker command runs, you will see output about the operations performed. The first set of messages you see is the output generated by Terraform as it provisions your nodes using Terraform Docker provider.

After the nodes are provisioned, Ansible connects to the hosts (Docker containers) and installs Kubernetes in steps called tasks and playbooks. Near the end of the output, addons are installed.

Viewing cluster operations

You can access user interfaces to monitor your cluster through the Operations Portal. After you run the konvoy up --provisioner=docker command, if the installation is successful, the command output displays the information you need to access the Operations Portal.

You should see information similar to this:

Kubernetes cluster and addons deployed successfully!

Run `konvoy apply kubeconfig` to update kubectl credentials.

Navigate to the URL below to access various services running in the cluster.
And login using the credentials below.

The dashboard and services may take a few minutes to be accessible.

Using a virtual private network for Docker on MacOS

If you use Docker on a MacOS computer, the host does not have direct access to the Docker network. Because of this limitation, you cannot directly access the services running in Docker containers using their IP addresses (including the operations portal).

To access the services in Docker containers when using a MacOS computer, you can create a virtual private network (VPN) between the host and the Docker network.

Create a VPN for Docker on MacOS

Create the virtual private network (VPN) by running the following command:

curl -sL | bash -s create

Destroy the VPN on MacOS

Destroy the virtual private network (VPN) when it is no longer needed by running the following command:

curl -sL | bash -s destroy

Differences from deploying on AWS

By deploying Konvoy using Docker, you should note the following differences from deploying on a public cloud infrastructure. The Docker based install essentially simulates an on-premises environment.

Accessing cluster nodes

As mentioned above, cluster nodes are simulated using Docker containers. Use the command docker exec to access the nodes in the corresponding container.

First, list the containers running:

$ docker ps
CONTAINER ID        IMAGE             COMMAND                  CREATED             STATUS              PORTS                                            NAMES
45fecdd2008b        7845b297b4ed      "/usr/local/bin/entr…"   37 minutes ago      Up 37 minutes>22/tcp,>6443/tcp   konvoy-control-plane-0
a95ede5b272a        7845b297b4ed      "/usr/local/bin/entr…"   37 minutes ago      Up 37 minutes>22/tcp                            konvoy-worker-pool0-0

The containers for the cluster nodes are named using the following convention:

  • Control plane nodes: <CLUSTER_NAME>-control-plane-<INDEX>
  • Worker nodes: <CLUSTER_NAME>-worker-pool<POOL_INDEX>-<INDEX>

Once you identify the node you want to access, docker exec into the container:

docker exec -ti konvoy-control-plane-0 /bin/bash