Build a Local Kubernetes Lab with kind and Terraform

Running Kubernetes locally is easy when all you need is a temporary cluster. The challenge begins when you want the environment to be reproducible, accessible from another computer, and simple enough to rebuild without repeating a long list of manual commands.

In this first part of the series, we will prepare an Ubuntu host with Ansible and provision a three-node Kubernetes cluster with Terraform and kind. The result will be a small lab that we can destroy and recreate consistently as we add a private registry, an original API and UI, GitOps, and observability in later articles.

The goal is not to pretend that kind is a production platform. It is to create an inexpensive and practical environment for learning, testing automation, and reproducing Kubernetes workflows.

By the end, we will have:

• An Ubuntu host prepared automatically with Ansible.

• Docker, Terraform, kubectl, Helm and kind installed.

• One kind control-plane node and two workers.

• A kubeconfig written to ~/.kube/config.

• Stable host-to-NodePort mappings for future services.

• Repeatable apply, validation and destroy workflows.

• An optional Portainer installation for visual cluster inspection.

Architecture

 1                     Ubuntu host
 2                          |
 3                          v
 4                 Ansible host setup
 5                          |
 6                          v
 7                      Terraform
 8                          |
 9                          v
10                    +-------------+
11                    | kind cluster |
12                    +-------------+
13                          |
14       +------------------+------------------+------------------+
15       |                  |                  |                  |
16       v                  v                  v                  v
17 Control plane         Worker 1           Worker 2      Portainer (optional)

Ansible prepares the operating system. Terraform owns the cluster lifecycle. kind runs the Kubernetes nodes as Docker containers. This separation gives each tool a clear responsibility and makes troubleshooting much easier.

Why kind?

kind, short for Kubernetes IN Docker, runs Kubernetes nodes as containers. It was created primarily for testing Kubernetes, but it is also a good fit for local labs because it is fast, supports multi-node topologies, and can be recreated easily.

For this project, kind gives us three useful characteristics:

1. Portability: the lab does not require a cloud account.

2. Reproducibility: the complete cluster definition lives in code.

3. Low operational cost: destroying the lab removes the Kubernetes nodes without leaving cloud resources running.

This environment is for development and learning. A production design would normally use a managed service such as Amazon EKS, Azure Kubernetes Service or Google Kubernetes Engine, or a purpose-built on-premises distribution.

Why combine Ansible and Terraform?

There is some overlap between both tools, but they solve different parts of this lab well:

The workflow is intentionally layered:

1Ubuntu → Ansible → Terraform → kind → Kubernetes workloads

Requirements

Use a fresh Ubuntu 22.04 or 24.04 host when possible.

Recommended resources:

Eight gigabytes is enough for the base cluster and a few small workloads. Harbor, observability components and application workloads will need more headroom. During my own tests, insufficient memory caused worker nodes to become NotReady, so I recommend 16 GB for the complete series.

You also need:

• Internet access to download packages and container images.

• A user with sudo privileges.

• Git to clone the project.

Repository structure

Create the following structure:

 1didgii-local-k8s-platform/
 2├── ansible/
 3│   ├── inventory.ini
 4│   ├── setup-host.yml
 5│   └── manage-kind-cluster.yml
 6├── terraform/
 7│   └── kind-cluster/
 8│       ├── versions.tf
 9│       ├── main.tf
10│       ├── variables.tf
11│       └── outputs.tf
12└── .gitignore

The application, Harbor and GitOps directories will be added in later articles.

Step 1: Create the Ansible inventory

Create ansible/inventory.ini:

1[local]
2localhost ansible_connection=local

The playbooks run directly on the Ubuntu host, so no SSH connection is needed.

Step 2: Prepare Ubuntu with Ansible

Create ansible/setup-host.yml:

  1---
  2- name: Prepare the Didgii Kubernetes lab host
  3  hosts: local
  4  become: true
  5  gather_facts: true
  6
  7  vars:
  8    target_user: "{{ ansible_env.SUDO_USER | default(ansible_user_id, true) }}"
  9    system_arch: "{{ 'amd64' if ansible_architecture == 'x86_64' else 'arm64' }}"
 10    kind_version: "v0.33.0"
 11
 12  tasks:
 13    - name: Validate the host architecture
 14      ansible.builtin.assert:
 15        that:
 16          - ansible_architecture in ['x86_64', 'aarch64', 'arm64']
 17        fail_msg: "This playbook currently supports AMD64 and ARM64 hosts."
 18
 19    - name: Install prerequisite packages
 20      ansible.builtin.apt:
 21        name:
 22          - ca-certificates
 23          - curl
 24          - git
 25          - gnupg
 26          - unzip
 27        state: present
 28        update_cache: true
 29
 30    - name: Create the APT keyring directory
 31      ansible.builtin.file:
 32        path: /etc/apt/keyrings
 33        state: directory
 34        mode: "0755"
 35
 36    - name: Download the Docker signing key
 37      ansible.builtin.get_url:
 38        url: https://download.docker.com/linux/ubuntu/gpg
 39        dest: /etc/apt/keyrings/docker.asc
 40        mode: "0644"
 41
 42    - name: Configure the Docker repository
 43      ansible.builtin.apt_repository:
 44        repo: >-
 45          deb [arch={{ system_arch }} signed-by=/etc/apt/keyrings/docker.asc]
 46          https://download.docker.com/linux/ubuntu
 47          {{ ansible_distribution_release }} stable
 48        filename: docker
 49        state: present
 50        update_cache: true
 51
 52    - name: Install Docker
 53      ansible.builtin.apt:
 54        name:
 55          - docker-ce
 56          - docker-ce-cli
 57          - containerd.io
 58          - docker-buildx-plugin
 59          - docker-compose-plugin
 60        state: present
 61
 62    - name: Start and enable Docker
 63      ansible.builtin.systemd_service:
 64        name: docker
 65        state: started
 66        enabled: true
 67
 68    - name: Add the local user to the Docker group
 69      ansible.builtin.user:
 70        name: "{{ target_user }}"
 71        groups: docker
 72        append: true
 73      register: docker_group
 74
 75    - name: Download the HashiCorp signing key
 76      ansible.builtin.get_url:
 77        url: https://apt.releases.hashicorp.com/gpg
 78        dest: /etc/apt/keyrings/hashicorp.asc
 79        mode: "0644"
 80
 81    - name: Configure the HashiCorp repository
 82      ansible.builtin.apt_repository:
 83        repo: >-
 84          deb [signed-by=/etc/apt/keyrings/hashicorp.asc]
 85          https://apt.releases.hashicorp.com
 86          {{ ansible_distribution_release }} main
 87        filename: hashicorp
 88        state: present
 89        update_cache: true
 90
 91    - name: Install Terraform
 92      ansible.builtin.apt:
 93        name: terraform
 94        state: present
 95
 96    - name: Download kubectl
 97      ansible.builtin.get_url:
 98        url: >-
 99          https://dl.k8s.io/release/{{ lookup('ansible.builtin.url',
100          'https://dl.k8s.io/release/stable.txt') | trim }}/bin/linux/{{ system_arch }}/kubectl
101        dest: /usr/local/bin/kubectl
102        mode: "0755"
103
104    - name: Download kind
105      ansible.builtin.get_url:
106        url: "https://kind.sigs.k8s.io/dl/{{ kind_version }}/kind-linux-{{ system_arch }}"
107        dest: /usr/local/bin/kind
108        mode: "0755"
109
110    - name: Download the Helm installer
111      ansible.builtin.get_url:
112        url: https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
113        dest: /tmp/get_helm.sh
114        mode: "0700"
115
116    - name: Install Helm
117      ansible.builtin.command:
118        cmd: /tmp/get_helm.sh
119        creates: /usr/local/bin/helm
120
121    - name: Remove the Helm installer
122      ansible.builtin.file:
123        path: /tmp/get_helm.sh
124        state: absent
125
126    - name: Explain the Docker group change
127      ansible.builtin.debug:
128        msg: >-
129          Docker group membership changed. Log out and back in before continuing.
130      when: docker_group.changed

First install Ansible using the Ubuntu package manager:

1sudo apt update
2sudo apt install -y ansible

Then run the playbook:

1cd didgii-local-k8s-platform/ansible
2ansible-playbook -i inventory.ini setup-host.yml

If your user was just added to the Docker group, log out and back in. For a temporary shell refresh, you can also run:

1newgrp docker

Validate the tools:

1docker info
2terraform version
3kind version
4kubectl version --client
5helm version

Do not continue until docker info works without sudo.

Step 3: Configure the Terraform provider

Create terraform/kind-cluster/versions.tf:

 1terraform {
 2  required_version = ">= 1.5.0"
 3
 4  required_providers {
 5    kind = {
 6      source  = "tehcyx/kind"
 7      version = "~> 0.11.0"
 8    }
 9  }
10}
11
12provider "kind" {}

The provider source is important. Terraform does not publish an official hashicorp/kind provider. If the source is omitted or declared incorrectly, terraform init may try to download a provider that does not exist.

Step 4: Define the cluster variables

Create terraform/kind-cluster/variables.tf:

 1variable "cluster_name" {
 2  description = "Name of the local kind cluster"
 3  type        = string
 4  default     = "didgii-lab"
 5}
 6
 7variable "kubeconfig_path" {
 8  description = "Path where kind writes the kubeconfig"
 9  type        = string
10  default     = "~/.kube/config"
11}
12
13variable "extra_port_mappings" {
14  description = "Ports published from the kind control-plane container"
15
16  type = list(object({
17    container_port = number
18    host_port      = number
19    listen_address = string
20    protocol       = string
21  }))
22
23  default = [
24    {
25      container_port = 30779
26      host_port      = 9443
27      listen_address = "127.0.0.1"
28      protocol       = "TCP"
29    },
30    {
31      container_port = 30443
32      host_port      = 8443
33      listen_address = "127.0.0.1"
34      protocol       = "TCP"
35    },
36    {
37      container_port = 30080
38      host_port      = 8080
39      listen_address = "127.0.0.1"
40      protocol       = "TCP"
41    }
42  ]
43}

These mappings reserve ports for Portainer, Argo CD and the example application used later in the series. Binding them to 127.0.0.1 keeps them accessible only from the Ubuntu host.

If this lab runs inside a remote VM and you need to access it from your laptop, change listen_address to 0.0.0.0. That exposes the ports on every host interface, so protect the VM with a firewall and never expose these management interfaces directly to the internet.

Port mappings are applied when kind creates the node container. Changing them later requires recreating the cluster.

Step 5: Create the multi-node cluster

Create terraform/kind-cluster/main.tf:

 1resource "kind_cluster" "lab" {
 2  name            = var.cluster_name
 3  wait_for_ready  = true
 4  kubeconfig_path = pathexpand(var.kubeconfig_path)
 5
 6  kind_config {
 7    kind        = "Cluster"
 8    api_version = "kind.x-k8s.io/v1alpha4"
 9
10    node {
11      role = "control-plane"
12
13      dynamic "extra_port_mappings" {
14        for_each = var.extra_port_mappings
15
16        content {
17          container_port = extra_port_mappings.value.container_port
18          host_port      = extra_port_mappings.value.host_port
19          listen_address = extra_port_mappings.value.listen_address
20          protocol       = extra_port_mappings.value.protocol
21        }
22      }
23    }
24
25    node {
26      role = "worker"
27    }
28
29    node {
30      role = "worker"
31    }
32  }
33}

This creates three Docker containers: one Kubernetes control plane and two workers. A multi-node lab is useful for testing scheduling, node failures and workload distribution, but it does not make a single-host environment highly available. If the Ubuntu host or Docker daemon fails, the complete cluster becomes unavailable.

Create terraform/kind-cluster/outputs.tf:

1output "cluster_name" {
2  description = "Name of the kind cluster"
3  value       = kind_cluster.lab.name
4}
5
6output "kubeconfig_path" {
7  description = "Kubeconfig generated for the cluster"
8  value       = kind_cluster.lab.kubeconfig_path
9}

Step 6: Orchestrate Terraform with Ansible

Create ansible/manage-kind-cluster.yml:

 1---
 2- name: Manage the Didgii kind cluster
 3  hosts: local
 4  connection: local
 5  gather_facts: false
 6
 7  vars:
 8    action: apply
 9    terraform_directory: "{{ playbook_dir }}/../terraform/kind-cluster"
10
11  tasks:
12    - name: Validate the requested action
13      ansible.builtin.assert:
14        that:
15          - action in ['apply', 'destroy']
16        fail_msg: "Use -e action=apply or -e action=destroy."
17
18    - name: Initialize Terraform
19      ansible.builtin.command:
20        cmd: terraform init -input=false
21        chdir: "{{ terraform_directory }}"
22      when: action == 'apply'
23
24    - name: Check Terraform formatting
25      ansible.builtin.command:
26        cmd: terraform fmt -check -recursive
27        chdir: "{{ terraform_directory }}"
28      when: action == 'apply'
29
30    - name: Validate Terraform
31      ansible.builtin.command:
32        cmd: terraform validate
33        chdir: "{{ terraform_directory }}"
34      when: action == 'apply'
35
36    - name: Create the cluster
37      ansible.builtin.command:
38        cmd: terraform apply -auto-approve -input=false
39        chdir: "{{ terraform_directory }}"
40      when: action == 'apply'
41
42    - name: Destroy the cluster
43      ansible.builtin.command:
44        cmd: terraform destroy -auto-approve -input=false
45        chdir: "{{ terraform_directory }}"
46      when: action == 'destroy'

Terraform remains the owner of the cluster. Ansible only provides a consistent entry point and will later orchestrate the other platform layers in the correct order.

Step 7: Create and validate the cluster

Run:

1cd didgii-local-k8s-platform/ansible
2ansible-playbook -i inventory.ini manage-kind-cluster.yml -e action=apply

Validate the result:

1kubectl cluster-info --context kind-didgii-lab
2kubectl get nodes -o wide
3kubectl get pods --all-namespaces
4docker ps --filter label=io.x-k8s.kind.cluster=didgii-lab

Expected node state:

1didgii-lab-control-plane   Ready   control-plane
2didgii-lab-worker          Ready   <none>
3didgii-lab-worker2         Ready   <none>

Confirm that all nodes become ready:

1kubectl wait \
2  --for=condition=Ready \
3  nodes \
4  --all \
5  --timeout=180s

Optional: Install Portainer

Portainer is not required to operate Kubernetes, but it provides a useful visual check while learning how resources relate to each other.

Add the repository and install it as a NodePort service:

 1helm repo add portainer https://portainer.github.io/k8s/
 2helm repo update
 3
 4helm upgrade --install portainer \
 5  portainer/portainer \
 6  --namespace portainer \
 7  --create-namespace \
 8  --set service.type=NodePort \
 9  --set service.httpsNodePort=30779 \
10  --wait \
11  --timeout 5m

Open:

1https://localhost:9443

If the cluster runs inside a VM and the port is bound to 0.0.0.0, use:

1https://HOST_IP:9443

Retrieve the initial setup token without publishing its value:

1kubectl logs deployment/portainer \
2  --namespace portainer \
3  --since=10m | grep setup_token

Portainer limits the initial configuration window for security. If the page reports that the installation timed out, restart the Deployment and try again:

1kubectl rollout restart deployment/portainer -n portainer
2kubectl rollout status deployment/portainer -n portainer --timeout=120s

Troubleshooting

Docker works only with sudo

Confirm your effective groups:

1id
2getent group docker

If the account appears in the Docker group but the current shell does not, log out and back in or run:

1newgrp docker

Worker nodes remain NotReady

Start with host capacity:

1free -h
2docker stats --no-stream
3kubectl describe node didgii-lab-worker
4kubectl get pods -A -o wide

Memory pressure is common when several Kubernetes nodes and platform applications share one small VM. Increase the VM memory before trying random Kubernetes changes.

A host port is already in use

Check the listener before recreating the cluster:

1sudo ss -lntp
2docker ps --format 'table {{.Names}}\t{{.Ports}}'

Choose a different host_port or stop the process that legitimately owns it. Avoid killing processes until you identify what started them.

Port mapping changes do not appear

extraPortMappings are Docker container settings. Terraform must recreate the kind cluster for changes to take effect:

1cd ../terraform/kind-cluster
2terraform apply -replace=kind_cluster.lab

This deletes the existing cluster data. Use it only when rebuilding the lab is acceptable.

Destroy the lab

Run:

1cd ../../ansible
2ansible-playbook -i inventory.ini manage-kind-cluster.yml -e action=destroy

Destroying the cluster removes its workloads and locally stored Kubernetes data. Terraform configuration remains in Git, so the environment can be recreated later.

What comes next?

We now have a repeatable Kubernetes foundation, but the cluster does not yet contain our application platform.

In Part 2, we will deploy Harbor as a private container registry, generate a local certificate authority, configure HTTPS, and make Docker and every kind node trust the registry. We will also reproduce and solve one of the most common local-registry errors:

1x509: certificate signed by unknown authority

Frequently asked questions

Is kind suitable for production?

No. kind is primarily designed for testing Kubernetes and is excellent for local development, CI and labs. Use a production-oriented Kubernetes platform for real workloads.

Why use three nodes on one host?

It allows us to test scheduling and multi-node Kubernetes behavior. It does not provide host-level high availability because every node still runs on the same Ubuntu machine.

Why use Terraform instead of only kind commands?

Terraform gives the cluster a declarative lifecycle and makes its topology, kubeconfig path and port mappings reviewable in code.

Why do port changes require cluster recreation?

kind implements these mappings as published Docker container ports. Docker assigns them when the node container is created.

References

• kind documentation

• kind configuration

• Terraform kind provider

• Ansible documentation

• Portainer Kubernetes installation