DEV Community

Cover image for Kubernetes at Home: Set Up Your Own Cluster Using Vagrant & Ansible
Houssam Bourkane
Houssam Bourkane

Posted on

Kubernetes at Home: Set Up Your Own Cluster Using Vagrant & Ansible

#devops #kubernetes #vagrant #ansible

TL;DR: Learn how to build a lightweight Kubernetes cluster on your local machine using Vagrant, Ansible, and VMware Fusion. Perfect for ARM-based Mac users looking to experiment with Kubernetes in a reproducible environment.

Why This Guide?

Setting up a Kubernetes cluster manually can be complex and time-consuming. But with the power of Vagrant for managing virtual machines and Ansible for automating setup tasks, you can spin up a local cluster with minimal effort and maximum reproducibility. This tutorial walks you through building a two-node cluster on macOS with ARM chips (e.g., M1/M2), but it's adaptable to other setups.

Table of Contents

Prerequisites

Before we start, ensure you have the following installed:

For macOS ARM users, refer to this special setup guide: Run Vagrant VMs in a M1/M2/M3 Apple Sillicon Chip

Project Structure

Create a project directory and replicate the following structure:

.
├── ansible
│   ├── ansible.cfg
│   ├── inventory.ini
│   └── k8s-cluster-setup.yml
└── Vagrantfile
Enter fullscreen mode Exit fullscreen mode

Step 1: Configure Vagrant

Install the VMware Desktop plugin:

vagrant plugin install vagrant-vmware-desktop
Enter fullscreen mode Exit fullscreen mode

Next, reserve two static private IPs from your LAN. Scan your local network using:

nmap -sn 192.168.1.0/24
Enter fullscreen mode Exit fullscreen mode

Replace 192.168.1.0 with you LAN network IP

Update your Vagrantfile with something like this:

Vagrant.configure("2") do |config|
  config.vm.define "kubmaster" do |kub|
    kub.vm.box = "spox/ubuntu-arm"
    kub.vm.box_version = "1.0.0"
    kub.vm.hostname = 'kubmaster'
    kub.vm.provision "docker"
    kub.vm.network "public_network", ip: "192.168.1.101", bridge: "en0: Wifi"
    kub.vm.provider "vmware_desktop" do |v|
      v.allowlist_verified = true
      v.gui = false
      v.vmx["memsize"] = "4096"
      v.vmx["numvcpus"] = "2"
    end
  end

  config.vm.define "kubnode1" do |kubnode|
    kubnode.vm.box = "spox/ubuntu-arm"
    kubnode.vm.box_version = "1.0.0"
    kubnode.vm.hostname = 'kubnode1'
    kubnode.vm.provision "docker"
    kubnode.vm.network "public_network", ip: "192.168.1.102", bridge: "en0: Wifi"
    kubnode.vm.provider "vmware_desktop" do |v|
      v.allowlist_verified = true
      v.gui = false
      v.vmx["memsize"] = "4096"
      v.vmx["numvcpus"] = "2"
    end
  end
end
Enter fullscreen mode Exit fullscreen mode

Replace the IPs with ones that match your LAN.

Now bring up the VMs:

vagrant up
Enter fullscreen mode Exit fullscreen mode

Step 2: Configure Ansible

ansible/inventory.ini 

[master]
kubmaster ansible_host=192.168.1.101 ansible_ssh_private_key_file=.vagrant/machines/kubmaster/vmware_desktop/private_key

[workers]
kubnode1 ansible_host=192.168.1.102 ansible_ssh_private_key_file=.vagrant/machines/kubnode1/vmware_desktop/private_key

[all:vars]
ansible_user=vagrant
Enter fullscreen mode Exit fullscreen mode

Make sure to replace the IP addresses

ansible/ansible.cfg 

[defaults]
inventory = inventory.ini
host_key_checking = False
Enter fullscreen mode Exit fullscreen mode

Step 3: Ansible Playbook for Kubernetes Setup

ansible/k8s-cluster-setup.yml

This playbook performs the following:

  • Prepares all nodes: disables swap, installs required packages, configures kernel modules, adds K8s repositories, installs kubeadm, kubelet, and kubectl.
  • Initializes the master node and stores the cluster join command.
  • Sets up Flannel CNI for networking.
  • Joins worker nodes using the generated join command. 
---
- name: Prepare Kubernetes Nodes
  hosts: all
  become: yes

  tasks:  

    - name: Disable swap (runtime)
      command: swapoff -a
      when: ansible_swaptotal_mb > 0

    - name: Comment out swap line in /etc/fstab
      lineinfile:
        path: /etc/fstab
        regexp: '^\s*([^#]\S*\s+\S+\s+swap\s+\S+)\s*$'
        line: '# \1'
        backrefs: yes

    - name: Apply mount changes
      command: mount -a

    - name: Stop AppArmor
      systemd:
        name: apparmor
        state: stopped
        enabled: no

    - name: Restart containerd
      systemd:
        name: containerd
        state: restarted

    - name: Configure sysctl for Kubernetes
      copy:
        dest: /etc/sysctl.d/kubernetes.conf
        content: |
          net.bridge.bridge-nf-call-ip6tables = 1
          net.bridge.bridge-nf-call-iptables = 1

    - name: Apply sysctl settings
      command: sysctl --system

    - name: Install transport and curl
      apt:
        name:
          - apt-transport-https
          - curl
        update_cache: yes
        state: present

    - name: Add Kubernetes APT key
      shell: |
        curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.33/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
      args:
        creates: /etc/apt/keyrings/kubernetes-apt-keyring.gpg

    - name: Add Kubernetes APT repository
      apt_repository:
        repo: "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.33/deb/ /"
        filename: "kubernetes"
        state: present

    - name: Install Kubernetes components
      apt:
        name:
          - kubelet
          - kubeadm
          - kubectl
          - kubernetes-cni
        update_cache: yes
        state: present

    - name: Enable kubelet service
      systemd:
        name: kubelet
        enabled: yes

- name: Initialize Kubernetes Master
  hosts: master
  become: yes
  vars:
    pod_cidr: "10.244.0.0/16"

  tasks:

    - name: Remove default containerd config
      file:
        path: /etc/containerd/config.toml
        state: absent

    - name: Restart containerd
      systemd:
        name: containerd
        state: restarted
        enabled: yes

    - name: Wait for containerd socket to be available
      wait_for:
        path: /run/containerd/containerd.sock
        state: present
        timeout: 20

    - name: Initialize Kubernetes control plane
      command: kubeadm init --apiserver-advertise-address={{ ansible_host }} --node-name {{ inventory_hostname }} --pod-network-cidr={{ pod_cidr }}
      register: kubeadm_output
      args:
        creates: /etc/kubernetes/admin.conf

    - name: Extract join command
      shell: |
        kubeadm token create --print-join-command
      register: join_command
      changed_when: false

    - name: Set join command fact
      set_fact:
        kube_join_command: "{{ join_command.stdout }}"

    - name: Create .kube directory for vagrant user
      become_user: vagrant
      file:
        path: /home/vagrant/.kube
        state: directory
        mode: 0755

    - name: Copy Kubernetes admin config to vagrant user
      copy:
        src: /etc/kubernetes/admin.conf
        dest: /home/vagrant/.kube/config
        remote_src: yes
        owner: vagrant
        group: vagrant
        mode: 0644

- name: Configure networking
  hosts: all
  become: yes

  tasks:

    - name: Ensure br_netfilter loads at boot
      copy:
        dest: /etc/modules-load.d/k8s.conf
        content: |
          br_netfilter

    - name: Load br_netfilter kernel module now
      command: modprobe br_netfilter

    - name: Configure sysctl for Kubernetes networking
      copy:
        dest: /etc/sysctl.d/k8s.conf
        content: |
          net.bridge.bridge-nf-call-iptables = 1
          net.bridge.bridge-nf-call-ip6tables = 1

    - name: Apply sysctl settings
      command: sysctl --system

- name: Configure flannel
  hosts: master
  become: yes

  tasks:

    - name: Apply Flannel CNI plugin
      become_user: vagrant
      command: kubectl apply -f https://raw.githubusercontent.com/flannel-io/flannel/master/Documentation/kube-flannel.yml
      environment:
        KUBECONFIG: /home/vagrant/.kube/config


- name: Join worker nodes to cluster
  hosts: workers
  become: yes
  vars:
    kube_join_command: "{{ hostvars['kubmaster']['kube_join_command'] }}"

  tasks:
    - name: Remove default containerd config
      file:
        path: /etc/containerd/config.toml
        state: absent

    - name: Restart containerd
      systemd:
        name: containerd
        state: restarted
        enabled: yes
    - name: Wait until the Kubernetes API server is reachable
      wait_for:
        host: "{{ hostvars['kubmaster']['ansible_host'] }}"
        port: 6443
        delay: 10
        timeout: 120
        state: started

    - name: Join the node to Kubernetes cluster
      command: "{{ kube_join_command }}"
      args:
        creates: /etc/kubernetes/kubelet.conf
Enter fullscreen mode Exit fullscreen mode

Step 4: Test and Deploy the Cluster

Test Ansible SSH connectivity: 

ansible all -m ping -i ansible/inventory.ini
Enter fullscreen mode Exit fullscreen mode

Run the full cluster setup: 

ansible-playbook -i ansible/inventory.ini ansible/k8s-cluster-setup.yml
Enter fullscreen mode Exit fullscreen mode

Retrieve the kubeconfig file locally: 

vagrant ssh kubmaster -c "sudo cat /etc/kubernetes/admin.conf" > ~/kubeconfig-vagrant.yaml
Enter fullscreen mode Exit fullscreen mode

Test your cluster: 

KUBECONFIG=~/kubeconfig-vagrant.yaml kubectl get nodes
Enter fullscreen mode Exit fullscreen mode

You should see both the master and worker nodes in Ready status.

What's Next?

You now have a fully functioning local Kubernetes cluster on ARM-based hardware, with everything automated and reproducible. You can now:

  • Experiment with Helm charts
  • Try GitOps with ArgoCD
  • Deploy sample apps

Stay tuned for the next part of this series!

Useful Links

Top comments (2)

Collapse
 
kozmer_vip profile image
Kozmer Vip •

Thanks for this tutorial!! I have been struggling doing it manually for so long, can't wait for upcoming sections

Collapse
 
thegeekfellow profile image
GeekGuy •

I mean, I've always wanted to automate my K8s cluster deployment, and I looked it up on Google I found this. How lucky am i ???