Kubernetes Deployment using Kubespray

In this article, we will provide a step-by-step guide to deploy a Kubernetes cluster using Kubespray. For easiness and simplicity, we will use a container image from a public repo.

First, we will configure our cluster by writing an inventory yaml file. Then, we will initiate a Kubernetes deployment using a kubespray container available on quay.io/kubspray.

Writing Inventory Files

We download the kubespray release from its official website. We will use v2.22.2 for this deployment.

wget https://github.com/kubernetes-sigs/kubespray/archive/refs/tags/v2.22.2.tar.gz
tar -xf v2.22.2.tar.gz --strip-components=1 kubespray-2.22.2/inventory/
cp -rfp inventory/sample inventory/mycluster

We will write an ansible inventory file in inventory/mycluster directory that we created in the previous step. Its format is shown below.

---
all:
  vars:
    ansible_ssh_common_args: '-o User=<username> -o StrictHostKeyChecking=no'
    ansible_ssh_pass: <user password>
    ansible_become_pass: <user password>
  hosts:
    # list of all nodes
    # in a form of 
#   <node-name>:
#    ip: <ip address>
#    node_labels:                              # for worker node only
#      node-role.kubernetes.io/worker: ""      # for worker node only
  children:
    kube_control_plane:
      hosts:
        # list of master nodes
        # in a form of <node-name>:
    kube_node:
      hosts:
        # list of worker nodes
        # in a form of <node-name>:
    etcd:
      hosts:
        # list of etcd nodes
        # in a form of <node-name>:
    k8s_cluster:
      children:
        kube_control_plane:
        kube_node:
    calico_rr:
      hosts: {}

Please note that node names must consist of lower case alphanumeric characters, ‘.’ or ‘-’, and must start and end with an alphanumeric character. Otherwise, an error occurs during deployment.

Initiating a Kubernetes Deployment

To initiate the deployment, we need two files.

• inventory file for Kubernetes cluster
• ssh config file

These two files will be copied into the container.

Once we have these two file, we will run the kubespray container.

docker pull quay.io/kubespray/kubespray:v2.22.2
docker run -it --name=kubespray --network=host quay.io/kubespray/kubespray:v2.22.2 bash

Then, we create two directories inside the container.

mkdir -p /inventory /root/.ssh

Now, we will copy the cluster directory and the ssh config file into the container.

docker cp inventory/mycluster kubespray:/inventory/cluster
docker cp ssh-config kubespray:/root/.ssh/config

If the owner of the copied directory and file are not root, it is better to change ownership of them to root.

chown -R root:root /inventory/cluster /root/.ssh/config

Now, we are ready to run the ansible playbook for Kubernetes deployment. Before we launch it, we can test the inventory files.

# Check inventory file
ansible all -i /inventory/cluster/inventory.yaml -a "hostname"
# Launch kubernetes deployment
ansible-playbook -i /inventory/cluster/inventory.yaml cluster.yml -b

For the nodes, a simple OS installation is sufficient. All the component will be installed by kubespray. The deployment will take time. Once it is finished, we can exit from the container.

Kubernetes Setup

Let us to make kubectl work. The version of the installed Kubernetes cluster is 1.26.11. So, we will download the corresponding kubectl executables.

curl -LO https://dl.k8s.io/release/v1.26.11/bin/linux/amd64/kubectl
chmod +x kubectl

Then, we can get Kubernetes admin configuration file from a master node. The location of the admin config file is this.

/etc/kubernetes/admin.conf

If the client node is not a master node, the server information in the config file need to be updated. Now, we can update environment variables and bash configuration.

export KUBECONFIG="<path to admin config file>"
export PATH="<path to kubectl directory>:$PATH"
source <(kubectl completion bash)                  # Auto-completion

Now, the cluster is ready to be used.

Deployed Kubernetes Cluster

Additional Resources

A complete example is available at the cluster-wizard gitlab page. For VMs, they can be requested by creating an issue of free-vm-request template at cluster-wizard/release project.