Kubernetes su WSL2 con Minikube, Nginx Ingress e OpenTofu: Control Plane e Cifratura In-Transit

Nello sviluppo di architetture distribuite cloud-native, l'allineamento topologico tra gli ambienti di staging locale e i cluster di produzione rappresenta un vincolo ingegneristico primario. La virtualizzazione basata su WSL2 (Windows Subsystem for Linux) accoppiata a Minikube costituisce la soluzione standard per l'emulazione del control plane di Kubernetes (K8s) in ambienti guest. Tuttavia, l'integrazione di costrutti IaC (Infrastructure as Code) tramite OpenTofu (fork open-source di Terraform) introduce complessità strutturali relative alla mappatura dei descrittori POSIX, all'isolamento dei bridge di rete del container runtime e alla convergenza dello stato del cluster.

Questo articolo analizza l'ingegnerizzazione e il deployment end-to-end di un microservizio Java Spring Boot, orchestrato via OpenTofu e instradato mediante un API Gateway implementato tramite Nginx Ingress Controller, con terminazione TLS gestita nativamente mediante injection crittografica di secret X.509.

1. Dimensionamento dell'Hypervisor e Bootstrap dei Binari

L'istanza di virtualizzazione di WSL2 (distribuzione Ubuntu) richiede una profilazione minima definita nel file .wslconfig host di almeno 2 vCPU e 2 GB di RAM, allocando un backend di memoria dinamico. Il container runtime di riferimento è Docker Engine installato nativamente nel kernel guest Linux, eludendo i layer di astrazione e le tabelle di routing proprietarie di Docker Desktop per Windows, al fine di garantire l'integrità dei namespace di rete.

Per prevenire disallineamenti di runtime generati dall'interoperabilità dei file system (es. i mount point sotto /mnt/c/), il provisioning dei binari deve avvenire esclusivamente nella directory HOME nativa (~), eseguendo un hashing di validazione SHA-256 sulla firma di kubectl:

cd ~

# Download and install the native Debian package for Minikube
wget https://storage.googleapis.com/minikube/releases/latest/minikube_latest_amd64.deb
sudo dpkg -i minikube_latest_amd64.deb
rm minikube_latest_amd64.deb

# Fetch the static binary of kubectl and validate its SHA-256 checksum
curl -LO "https://dl.k8s.io/release/stable/bin/linux/amd64/kubectl"
curl -LO "https://dl.k8s.io/release/stable/bin/linux/amd64/kubectl.sha256"
echo "$(cat kubectl.sha256)  kubectl" | sha256sum --check
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
rm kubectl kubectl.sha256

2. Sanitizzazione del Database Utente ed Esecuzione in User-Space

Durante il bootstrap di Minikube in modalità unprivileged (necessaria per non corrompere i socket proprietari del demone Docker), il control plane può lanciare un'eccezione di tipo GUEST_START causata dalla configurazione errata delle variabili d'ambiente globali ereditate dall'host Windows:

× Exiting due to GUEST_START: ... Error creating directory: /marco/.kube: permission denied

Per aggirare tale blocco ed evitare la derivazione dei permessi (evitando l'uso di sudo minikube), è obbligatorio ridefinire i descrittori di percorso del profilo utente prima di inizializzare l'hypervisor del cluster locale:

# Initialize configuration directories in the correct Linux path
mkdir -p /home/marco/.minikube
mkdir -p /home/marco/.kube

# Bootstrap the cluster enforcing runtime environment variables at process level
MINIKUBE_HOME=/home/marco KUBECONFIG=/home/marco/.kube/config minikube start --driver=docker

# Persist KUBECONFIG for the kubectl client within the current shell session
export KUBECONFIG=/home/marco/.kube/config

Una volta stabilito lo stato operativo del nodo master, viene eseguito il deploy dei controller di ingresso attivando l'add-on Nginx integrato, che esporrà i socket di ascolto per i proxy di routing:

MINIKUBE_HOME=/home/marco KUBECONFIG=/home/marco/.kube/config minikube addons enable ingress

3. Modello Dichiarativo IaC via OpenTofu con Terminazione TLS Nativa

Nelle architetture distribuite moderne, la sicurezza del canale di comunicazione (cifratura in-transit) viene gestita centralmente dall'Ingress Controller. Delegando al provider tls di OpenTofu la generazione delle chiavi asimmetriche e del certificato X.509 autofirmato, si implementa una pipeline immutabile che inietta i blocchi crittografici in un oggetto Secret di Kubernetes, associandolo poi alle regole del proxy Ingress.

Nota sintattica ingegneristica: Nelle specifiche correnti del provider Kubernetes per OpenTofu, il blocco di instradamento HTTP richiede l'utilizzo del costrutto singolare path posizionato direttamente sotto la direttiva http. Inoltre, l'attributo metadata delle risorse esportate è strutturato come una lista di oggetti, imponendo l'indicizzazione esplicita ([0]) per la risoluzione corretta dei puntatori dinamici inter-risorsa.

Di seguito si riporta il manifest di configurazione completo main.tf:

terraform {
  required_providers {
    kubernetes = {
      source  = "hashicorp/kubernetes"
      version = "~> 2.0"
    }
    tls = {
      source  = "hashicorp/tls"
      version = "~> 4.0"
    }
  }
}

provider "kubernetes" {
  config_path = "/home/marco/.kube/config"
}

# 1. Provision asymmetric RSA private key
resource "tls_private_key" "ingress_key" {
  algorithm = "RSA"
  rsa_bits  = 2048
}

# 2. Generate self-signed X.509 certificate valid for 1 year
resource "tls_self_signed_cert" "ingress_cert" {
  private_key_pem = tls_private_key.ingress_key.private_key_pem

  subject {
    common_name  = "mio-gateway.local"
    organization = "Dev Local Lab"
  }

  validity_period_hours = 8760

  allowed_uses = [
    "key_encipherment",
    "digital_signature",
    "server_auth",
  ]

  dns_names = ["mio-gateway.local"]
}

# 3. Create Kubernetes TLS Secret object within the cluster
resource "kubernetes_secret" "java_app_tls_secret" {
  metadata {
    name      = "java-app-tls-secret"
    namespace = "default"
  }

  type = "kubernetes.io/tls"

  data = {
    "tls.crt" = tls_self_signed_cert.ingress_cert.cert_pem
    "tls.key" = tls_private_key.ingress_key.private_key_pem
  }
}

# 4. Define the Java Spring Boot microservice Deployment
resource "kubernetes_deployment" "java_app" {
  metadata {
    name = "java-app-deployment"
    labels = { app = "java-app" }
  }

  spec {
    replicas = 1
    selector { match_labels = { app = "java-app" } }

    template {
      metadata { labels = { app = "java-app" } }
      spec {
        container {
          image = "springio/gs-spring-boot-docker" 
          name  = "java-app-container"
          port { container_port = 8080 }
        }
      }
    }
  }
}

# 5. Abstract the internal logical Service resource
resource "kubernetes_service" "java_app_service" {
  metadata { name = "java-app-service" }
  spec {
    selector = { app = "java-app" }
    port {
      port        = 80
      target_port = 8080
    }
    type = "NodePort"
  }
}

# 6. Configure Nginx Ingress with TLS termination and forced SSL redirect
resource "kubernetes_ingress_v1" "java_app_ingress" {
  metadata {
    name = "java-app-ingress"
    annotations = {
      "nginx.ingress.kubernetes.io/rewrite-target" = "/"
      "nginx.ingress.kubernetes.io/ssl-redirect"   = "true"
    }
  }

  spec {
    ingress_class_name = "nginx"

    tls {
      hosts       = ["mio-gateway.local"]
      secret_name = kubernetes_secret.java_app_tls_secret.metadata[0].name
    }

    rule {
      host = "mio-gateway.local"
      http {
        path {
          path      = "/"
          path_type = "Prefix"
          backend {
            service {
              name = kubernetes_service.java_app_service.metadata[0].name
              port { number = 80 }
            }
          }
        }
      }
    }
  }
}

L'applicazione dello stato desiderato avviene tramite l'inizializzazione del modulo e il tracking dei nuovi provider crittografici:

# Initialize configuration and apply state downstream
export KUBECONFIG=/home/marco/.kube/config
tofu init
tofu apply -auto-approve

4. Inoltro dei Flussi di Rete ed Interoperabilità Host-Guest

A causa della topologia isolata dei bridge di rete del driver Docker all'interno del sottosistema WSL2, le interfacce virtuali del cluster non sono instradabili dall'ambiente host Windows. Per stabilire una comunicazione prima sulla porta 80 e poi sulla porta protetta 443 (HTTPS), occorre inizializzare un demone di tunneling che esegua il binding dei descrittori di socket sulla scheda di loopback locale dell'host:

# Establish a network bridge to expose internal services to localhost
MINIKUBE_HOME=/home/marco KUBECONFIG=/home/marco/.kube/config minikube tunnel

Successivamente, si istruisce il gestore DNS dell'host Windows aggiornando staticamente il file hosts di sistema (C:\Windows\System32\drivers\etc\hosts, eseguito con privilegi amministrativi elevati), mappando il dominio di test definito nel blocco Ingress:

# Target mapping for local ingress routing
127.0.0.1   mio-gateway.local

5. Validazione del Flusso di Rete ed Offloading SSL

L'interrogazione del dominio tramite un client web host permette di tracciare analiticamente il ciclo di vita della richiesta:

La scomposizione del flusso evidenzia la convergenza delle configurazioni IaC applicate:

• Risoluzione del Record Host: La stringa URL https://mio-gateway.local dimostra il corretto aggancio delle interfacce di loopback virtualizzate tra Windows e la rete interna di WSL2.
• Terminazione ed Offloading TLS: L'esposizione del protocollo https:// accoppiata all'avviso di sicurezza "Non sicuro" (originato dalla mancanza di una firma di una CA pubblica attendibile) certifica che l'Nginx Ingress Controller sta intercettando i flussi sul socket 443, eseguendo correttamente la decifratura tramite le chiavi X.509 iniettate da OpenTofu.
• Esecuzione del Payload Java: La visualizzazione a schermo del corpo del messaggio Hello Docker World conferma che l'offloading TLS è andato a buon fine e che il traffico HTTP in chiaro è stato veicolato dal Service Kubernetes all'endpoint del pod Spring Boot sulla porta 8080.

Questo pattern architetturale definisce un ambiente di staging locale a complessità ridotta ma strutturalmente allineato ai criteri di deployment dei cluster cloud di produzione.