Run a Local Cluster

Solution

1. Minikube Setup

# Install Minikube (macOS)
brew install minikube

# Install Minikube (Linux)
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

# Start cluster
minikube start \
  --cpus=4 \
  --memory=8192 \
  --disk-size=50g \
  --driver=docker

# Enable addons (the Gateway controller is installed in step 4)
minikube addons enable metrics-server
minikube addons enable dashboard

# Verify cluster
kubectl cluster-info
kubectl get nodes

# Open dashboard
minikube dashboard

2. Kind (Kubernetes in Docker) Setup

# Install Kind (macOS)
brew install kind

# Install Kind (Linux)
curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.33.0/kind-linux-amd64
chmod +x ./kind
sudo mv ./kind /usr/local/bin/kind

# Create cluster configuration
# Port 80 on your machine goes to NodePort 30080 on the control-plane node,
# where the Gateway's NGINX proxy listens (see step 4).
cat <<EOF > kind-config.yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  extraPortMappings:
  - containerPort: 30080
    hostPort: 80
    protocol: TCP
- role: worker
- role: worker
EOF

# Create cluster
kind create cluster --config kind-config.yaml --name dev-cluster

# Verify
kubectl cluster-info --context kind-dev-cluster

3. k3d Setup

# Install k3d (macOS/Linux)
curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash

# Create cluster
# k3s ships Traefik, which would also claim port 80. Turn it off so the
# Gateway's proxy gets port 80 behind k3d's load balancer.
k3d cluster create dev \
  --agents 2 \
  --port "8080:80@loadbalancer" \
  --port "8443:443@loadbalancer" \
  --api-port 6443 \
  --k3s-arg "--disable=traefik@server:*"

# Verify
kubectl cluster-info

# List clusters
k3d cluster list

4. Gateway API Controller

This lab uses NGINX Gateway Fabric 2.8.0. It supports Kubernetes 1.32 and later, including the v1.37 node image that kind v0.33 uses, and it implements Gateway API v1.6.3.

# 1. Install the Gateway API CRDs (standard channel, the version this release supports)
kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v2.8.0" \
  | kubectl apply -f -

The controller creates one NGINX proxy (a Deployment and a Service) for each Gateway. How that Service is exposed depends on your cluster.

# 2a. kind: expose the proxy on NodePort 30080, the port mapped to localhost:80.
# externalTrafficPolicy=Cluster lets the control-plane node forward to the
# proxy pod even when it runs on a worker.
helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric \
  --version 2.8.0 \
  --namespace nginx-gateway \
  --create-namespace \
  --set nginx.service.type=NodePort \
  --set nginx.service.externalTrafficPolicy=Cluster \
  --set-json 'nginx.service.nodePorts=[{"port":30080,"listenerPort":80}]'

# 2b. Minikube or k3d: keep the default LoadBalancer Service.
# Minikube gives it an IP through `minikube tunnel`; k3d through its built-in
# load balancer, which can send traffic to any node.
helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric \
  --version 2.8.0 \
  --namespace nginx-gateway \
  --create-namespace \
  --set nginx.service.externalTrafficPolicy=Cluster

# 3. Wait for the controller, then check the GatewayClass it created
kubectl wait --timeout=5m -n nginx-gateway \
  deployment/ngf-nginx-gateway-fabric --for=condition=Available
kubectl get gatewayclass nginx
# ACCEPTED should be True

After you apply test-app.yaml, the controller creates the proxy for hello-gateway as hello-gateway-nginx in the demo namespace:

kubectl get gateway,httproute -n demo
# The Gateway should show PROGRAMMED True

kubectl get svc hello-gateway-nginx -n demo

5. Local Development Workflow

Skaffold Configuration

# skaffold.yaml
apiVersion: skaffold/v4beta14
kind: Config
metadata:
  name: local-dev

build:
  artifacts:
  - image: myapp
    docker:
      dockerfile: Dockerfile
    sync:
      manual:
      - src: "src/**/*.js"
        dest: /app/src

manifests:
  rawYaml:
  - k8s/*.yaml

deploy:
  kubectl: {}

portForward:
- resourceType: service
  resourceName: myapp
  namespace: demo
  port: 80
  localPort: 3000

profiles:
- name: debug
  activation:
  - command: debug
  patches:
  - op: add
    path: /build/artifacts/0/docker/buildArgs
    value:
      NODE_ENV: development

# Start development with Skaffold
skaffold dev

# Or with debugging
skaffold debug

Tilt Configuration

# Tiltfile
# Build Docker image
docker_build('myapp', '.')

# Deploy to Kubernetes
k8s_yaml('k8s/deployment.yaml')

# Port forward
k8s_resource('myapp', port_forwards=3000)

# Live update
docker_build('myapp', '.',
  live_update=[
    sync('./src', '/app/src'),
    run('npm install', trigger=['package.json']),
  ]
)

# Start Tilt
tilt up

6. Local Registry

For Kind

# Create registry
docker run -d -p 5000:5000 --restart=always --name registry registry:2

# Connect registry to Kind network
docker network connect kind registry

# Build and push
docker build -t localhost:5000/myapp:latest .
docker push localhost:5000/myapp:latest

# Use in Kubernetes
kubectl set image deployment/myapp myapp=localhost:5000/myapp:latest

For Minikube

# Use Minikube's Docker daemon
eval $(minikube docker-env)

# Build directly in Minikube
docker build -t myapp:latest .

# Use in deployment (no push needed)
kubectl set image deployment/myapp myapp=myapp:latest

7. Helper Scripts

start-cluster.sh

#!/bin/bash

set -euo pipefail

CLUSTER_NAME="${1:-dev}"
TOOL="${2:-kind}"

NGF_VERSION="2.8.0"

echo "Starting local Kubernetes cluster..."
echo "Tool: $TOOL"
echo "Name: $CLUSTER_NAME"

case $TOOL in
  minikube)
    minikube start \
      --profile=$CLUSTER_NAME \
      --cpus=4 \
      --memory=8192 \
      --kubernetes-version=v1.37.0

    minikube addons enable metrics-server -p $CLUSTER_NAME
    GATEWAY_SERVICE_ARGS=()
    ;;

  kind)
    kind create cluster \
      --name=$CLUSTER_NAME \
      --config=kind-config.yaml

    # NodePort 30080 is mapped to localhost:80 in kind-config.yaml
    GATEWAY_SERVICE_ARGS=(
      --set nginx.service.type=NodePort
      --set-json 'nginx.service.nodePorts=[{"port":30080,"listenerPort":80}]'
    )
    ;;

  k3d)
    k3d cluster create $CLUSTER_NAME \
      --agents 2 \
      --port "8080:80@loadbalancer" \
      --k3s-arg "--disable=traefik@server:*"
    GATEWAY_SERVICE_ARGS=()
    ;;

  *)
    echo "Unknown tool: $TOOL"
    echo "Usage: $0 <cluster-name> <minikube|kind|k3d>"
    exit 1
    ;;
esac

echo "Installing the Gateway API CRDs and NGINX Gateway Fabric $NGF_VERSION..."
kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v$NGF_VERSION" \
  | kubectl apply -f -
helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric \
  --version "$NGF_VERSION" \
  --namespace nginx-gateway \
  --create-namespace \
  --set nginx.service.externalTrafficPolicy=Cluster \
  ${GATEWAY_SERVICE_ARGS[@]+"${GATEWAY_SERVICE_ARGS[@]}"}  # empty-array safe on macOS bash 3.2
kubectl wait --timeout=5m -n nginx-gateway \
  deployment/ngf-nginx-gateway-fabric --for=condition=Available

echo "✅ Cluster created successfully"
kubectl cluster-info
kubectl get nodes

stop-cluster.sh

#!/bin/bash

set -euo pipefail

CLUSTER_NAME="${1:-dev}"
TOOL="${2:-kind}"

echo "Stopping local Kubernetes cluster..."

case $TOOL in
  minikube)
    minikube stop -p $CLUSTER_NAME
    ;;
  kind)
    kind delete cluster --name=$CLUSTER_NAME
    ;;
  k3d)
    k3d cluster delete $CLUSTER_NAME
    ;;
  *)
    echo "Unknown tool: $TOOL"
    exit 1
    ;;
esac

echo "✅ Cluster stopped"

Explanation

Comparison of Local Kubernetes Tools

Feature	Minikube	Kind	k3d
Speed	Slow	Fast	Fastest
Multi-node	Yes	Yes	Yes
Resource usage	High	Medium	Low
VM required	Optional	No	No
Addons	Many	None	Some
Best for	Learning	CI/CD	Development

How They Work

Minikube:

Minikube → VM (or Docker) → Single-node Kubernetes

Kind:

Kind → Docker containers as nodes → Multi-node Kubernetes

k3d:

k3d → k3s in Docker → Lightweight Kubernetes

Local Development Pattern

1. Code change → 2. Build image → 3. Push to cluster → 4. Restart pods → 5. Test

With live reload:

1. Code change → 2. Sync to pod → 3. Auto-restart → 4. Test (faster!)