Crea un laboratorio Kubernetes local con kind y Terraform

Crear un clúster Kubernetes local es sencillo cuando solo necesitas un entorno temporal. El reto empieza cuando quieres que sea reproducible, accesible desde otra computadora y fácil de reconstruir sin repetir una larga lista de comandos manuales.

En esta primera parte prepararemos un host Ubuntu con Ansible y crearemos un clúster Kubernetes de tres nodos con Terraform y kind. El resultado será un laboratorio pequeño que podremos destruir y reconstruir de forma consistente mientras agregamos un registro privado, una API y una interfaz propias, GitOps y observabilidad en los próximos artículos.

El objetivo no es presentar kind como una plataforma de producción. Buscamos un entorno práctico y económico para aprender, probar automatización y reproducir flujos de trabajo de Kubernetes.

Al terminar tendremos:

• Un host Ubuntu preparado automáticamente con Ansible.

• Docker, Terraform, kubectl, Helm y kind instalados.

• Un nodo de control y dos workers.

• El kubeconfig disponible en ~/.kube/config.

• Puertos estables reservados para los próximos servicios.

• Flujos repetibles para crear, validar y destruir el laboratorio.

• Una instalación opcional de Portainer para inspeccionar el clúster visualmente.

Arquitectura

 1                      Host Ubuntu
 2                           |
 3                           v
 4                Preparación con Ansible
 5                           |
 6                           v
 7                       Terraform
 8                           |
 9                           v
10                    +--------------+
11                    | Clúster kind |
12                    +--------------+
13                           |
14       +-------------------+-------------------+-------------------+
15       |                   |                   |                   |
16       v                   v                   v                   v
17 Control plane          Worker 1            Worker 2      Portainer (opcional)

Ansible prepara el sistema operativo. Terraform controla el ciclo de vida del clúster. kind ejecuta los nodos Kubernetes como contenedores Docker. Esta separación le da una responsabilidad clara a cada herramienta y facilita mucho el diagnóstico de problemas.

¿Por qué kind?

kind significa Kubernetes IN Docker y ejecuta los nodos de Kubernetes como contenedores. Fue creado principalmente para probar Kubernetes, pero también funciona muy bien en laboratorios locales porque es rápido, permite topologías multinodo y se puede reconstruir fácilmente.

Para este proyecto nos ofrece tres ventajas:

1. Portabilidad: no necesitamos una cuenta de nube.

2. Reproducibilidad: la definición completa del clúster vive en código.

3. Bajo costo operativo: podemos destruir el laboratorio sin dejar recursos de nube ejecutándose.

Este entorno es para desarrollo y aprendizaje. Para producción normalmente usaríamos un servicio administrado como Amazon EKS, Azure Kubernetes Service o Google Kubernetes Engine, o una distribución diseñada para instalaciones on-premises.

¿Por qué combinar Ansible y Terraform?

Las dos herramientas tienen algunas funciones similares, pero en este laboratorio cada una tiene una responsabilidad concreta:

Nuestro flujo queda así:

1Ubuntu → Ansible → Terraform → kind → cargas de Kubernetes

Requisitos

Siempre que sea posible, utiliza un host limpio con Ubuntu 22.04 o 24.04.

Recursos recomendados:

Ocho gigabytes son suficientes para el clúster base y algunas cargas pequeñas. Harbor, las herramientas de observabilidad y nuestras aplicaciones necesitarán más espacio. Durante mis pruebas, la falta de memoria hizo que los workers cambiaran a NotReady, así que recomiendo 16 GB para completar toda la serie.

También necesitas:

• Acceso a Internet para descargar paquetes e imágenes.

• Un usuario con permisos de sudo.

• Git para clonar el proyecto.

Estructura del repositorio

Crea la siguiente estructura:

 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

En los próximos artículos agregaremos los directorios de la aplicación, Harbor y GitOps.

Paso 1: crea el inventario de Ansible

Crea ansible/inventory.ini:

1[local]
2localhost ansible_connection=local

Los playbooks se ejecutan directamente en el host Ubuntu, así que no necesitamos una conexión SSH.

Paso 2: prepara Ubuntu con Ansible

Crea 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

Primero instala Ansible:

1sudo apt update
2sudo apt install -y ansible

Después ejecuta el playbook:

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

Si el usuario acaba de agregarse al grupo de Docker, cierra la sesión y vuelve a entrar. Para actualizar temporalmente la sesión actual también puedes ejecutar:

1newgrp docker

Valida las herramientas:

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

No continúes hasta que docker info funcione sin sudo.

Paso 3: configura el provider de Terraform

Crea 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" {}

El origen del provider es importante: Terraform no publica un provider oficial llamado hashicorp/kind. Si se omite o se declara incorrectamente, terraform init puede intentar descargar un provider que no existe.

Paso 4: define las variables del clúster

Crea 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}

Los puertos reservados son:

Al usar 127.0.0.1, los puertos solo están disponibles desde el host Ubuntu.

Si el laboratorio se ejecuta dentro de una VM remota y necesitas entrar desde tu laptop, cambia listen_address a 0.0.0.0. Esto expone los puertos en todas las interfaces del host, así que debes proteger la VM con un firewall y nunca publicar las interfaces administrativas directamente en Internet.

Los port mappings se aplican cuando kind crea el contenedor del nodo. Si los cambias después, tendrás que recrear el clúster.

Paso 5: crea el clúster multinodo

Crea 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}

Terraform creará tres contenedores Docker: un control plane y dos workers. Esta topología permite practicar scheduling, fallas de nodos y distribución de cargas, pero no convierte un laboratorio de un solo host en una plataforma de alta disponibilidad. Si falla Ubuntu o Docker, todo el clúster deja de estar disponible.

Crea 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}

Paso 6: orquesta Terraform con Ansible

Crea 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 continúa siendo el propietario del ciclo de vida del clúster. Ansible nos ofrece un punto de entrada consistente y después coordinará las demás capas de la plataforma en el orden correcto.

Paso 7: crea y valida el clúster

Ejecuta:

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

Valida el resultado:

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

El estado esperado es:

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

Espera hasta que todos los nodos estén listos:

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

Opcional: instala Portainer

Portainer no es necesario para operar Kubernetes, pero ofrece una referencia visual útil mientras aprendemos cómo se relacionan los recursos.

 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

Abre:

1https://localhost:9443

Si el laboratorio se encuentra en una VM y configuraste 0.0.0.0, utiliza:

1https://IP_DEL_HOST:9443

Obtén el setup token inicial sin publicarlo:

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

Portainer limita el tiempo disponible para completar la configuración inicial. Si la instalación expira, reinicia el Deployment:

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

Solución de problemas

Docker solo funciona con sudo

Comprueba los grupos efectivos de tu usuario:

1id
2getent group docker

Si tu cuenta pertenece al grupo docker, pero la sesión actual todavía no lo reconoce, vuelve a iniciar sesión o ejecuta:

1newgrp docker

Los workers permanecen en NotReady

Empieza revisando los recursos del host:

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

La presión de memoria es común cuando varios nodos y aplicaciones comparten una VM pequeña. Aumenta la memoria disponible antes de realizar cambios aleatorios en Kubernetes.

Un puerto ya está ocupado

Identifica el proceso antes de recrear el clúster:

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

Selecciona otro host_port o detén correctamente el servicio que lo utiliza. No mates procesos hasta entender quién los inició.

Los cambios en los puertos no aparecen

extraPortMappings forma parte de la configuración de los contenedores Docker. Terraform debe recrear el clúster para aplicar los cambios:

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

Este proceso elimina la información guardada dentro del clúster. Úsalo únicamente cuando puedas reconstruir el laboratorio.

Destruye el laboratorio

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

Al destruir el clúster también se eliminan sus workloads y los datos almacenados localmente por Kubernetes. La configuración de Terraform permanece en Git, así que podremos crear el entorno nuevamente.

¿Qué sigue?

Ya tenemos una base Kubernetes reproducible, pero todavía no contamos con nuestra plataforma de aplicaciones.

En la segunda parte instalaremos Harbor como registro privado de contenedores, crearemos nuestra propia autoridad certificadora, configuraremos HTTPS y haremos que Docker y cada nodo de kind confíen en el registro. También reproduciremos y solucionaremos uno de los errores más comunes en registros locales:

1x509: certificate signed by unknown authority

Preguntas frecuentes

¿kind es adecuado para producción?

No. kind está diseñado principalmente para probar Kubernetes y funciona muy bien en desarrollo local, CI y laboratorios. Para cargas reales debes utilizar una plataforma orientada a producción.

¿Por qué crear tres nodos en un solo host?

Nos permite practicar scheduling y comportamiento multinodo. No proporciona alta disponibilidad a nivel de host porque todos los nodos siguen ejecutándose en la misma máquina Ubuntu.

¿Por qué usar Terraform en lugar de ejecutar únicamente comandos de kind?

Terraform proporciona un ciclo de vida declarativo y permite revisar en código la topología, la ubicación del kubeconfig y los puertos publicados.

¿Por qué debo recrear el clúster al cambiar los puertos?

kind implementa esos mappings como puertos publicados de los contenedores Docker. Docker los asigna cuando se crea el contenedor de cada nodo.

Referencias

• Documentación de kind

• Configuración de kind

• Provider de kind para Terraform

• Documentación de Ansible

• Instalación de Portainer en Kubernetes