# Understanding Kaabah


Kaabah relies on various technologies such as Terraform, Docker Swarm, Traefik... and we assume that you are enough familiar with them. If not, please take a while to discover them.

# Key concepts

Kaabah let you manipulate 4 kind of entities:

  • Workspace: a collection of everything Kaabah needs to create and manage an infrastructure.
  • Configuration: a set of Terraform variables used to define your infrastructure.
  • Cluster: a Docker Swarm.
  • Service: an application deployed on your Swarm.

The following image illustrates how these entities interact:

Kaabah principle

In addition Kaabah provides a set of commands that help you to operate the cluster. For instance, you can easily prune all the images on the different nodes, execute a command on a given node... See the reference page to have the complete list.

# Workspace

Kaabah is designed to take advantage of Terraform Workspaces. Indeed, Kaabah relies on the Terraform recommend practices and assume a Workspace is used to store the required data needed to build and manage an infrastructure for a specific environment (staging, production...):

  • the configuration of the infrastructure.
  • the SSH private key to get connected to the infrastructure
  • the user scripts you want to be executed when creating the infrastructure
  • the Terraform states of the infrastructure.

Starting from this premise, Kaabah lets you to manage as many clusters as your projects require. If we decide to name our workspaces with both the project name and its environment (i.e. dev, test...), we can sketch the following diagram to illustrate the overall functioning of Kaabah:

Kaabah terraform

In this diagram, the states of the different workspaces are stored within a dedicated bucket on amazon S3, but you are free to use any other Terraform backends.

# Configuration

The Kaabah configuration file is a Terraform variable file describing the characteristics of the desired infrastructure.

Here is an example of a configuration file:

provider = "AWS"

manager_ip = ""

manager_instance_type = "t2.small"

worker_instance_type = "t3.large"

worker_instance_count = 3

worker_additional_volume_count = 2

worker_additional_volume_size = 500

worker_additional_volume_type = "st1"

worker_additional_volume_mount_point = "DATA"

Assuming the current workspace is app-dev, then when applying such a configuration, Kaabah will generate a Docker Swarm infrastructure on AWS (provider variable) composed of:

  • one manager node, app-dev-manager, of type t2.small with the public IP address
  • 3 worker nodes, app-dev-worker-0, app-dev-worker-1 and app-dev-worker-2, of type of t3.large. To each worker is attached 2 optimized hard-disk (sc1) of 500GB and these volumes are accessible through the mount points: /mnt/DATA0 and /mnt/DATA1.

Kaabah exposes many more variables allowing you to customize in detail your infrastructure such as adding labels, running user scripts... Have a look at the complete list of variables and the tests as an example.

# Cluster

The cluster consists in of multiple Docker hosts which run in swarm mode and act as manager (to manage membership and delegation) and workers (which run services).

swarm concept

# Instances

When generated from a given <WORKSPACE>, the instances are named according the following convention:

  • <WORKSPACE>-manager
  • <WORKSPACE>-woker-<INDEX>

You can add some labels to the nodes using the manager_labels and worker_labels variables.


Kaabah supports only x86 architecture.

# Volumes

When needed extra disk spaces, you can attach additional volumes to the workers. These volumes are automatically attached, formatted (ext4 file system) and mounted on the workers. By default the volumes attached on a worker are accessible with the paths /mnt/data0, mnt/data1 and so on. You can override the default data mount point by overriding the worker_additional_volume_mount_point variable.

# Network

# Security Groups

By default, Kaabah creates 2 security groups:

  • the manager security group allowing:
    • external HTTP traffic (port 80)
    • external HTTPS traffic (port 443)
    • internal SSH traffic (port 22)
    • internal Docker swarm traffic.
  • the workers security group with the following rules:
    • internal SSH traffic (port 22)
    • internal Docker swarm traffic

# Docker Network

The traffic between the nodes relies on a Docker network of type of Overlay.

The name of the Docker network is automatically computed from the workspace name but you can override it using the docker_network variable.

# Security


Kaabah requires the use of a Bastion to get connected to your instances. The implemented solution relies on the following architecture:

bastion architecture

Your bastion instance must be instantiated in the same network of your cluster. The Security Groups rules allows the SSH traffic from the bastion.


It is a best practice to harden your bastion host because it is a critical point of network security. Hardening might include disabling unnecessary applications or services, restrict the inbound traffic to well-known hosts.

# Docker Engine

The Docker daemon only allows connections from clients authenticated by a certificate signed by a Certificate Authority (CA).

When creating the cluster, Kaabah handles the creation of the server and client keys but it requires you to provide this CA. Check out the Getting started section to learn how to generate this CA.


Kaabah relies on OpenSSL to generate the server and client keys.