feat: Migrate cloud deployment example from Kind to Minikube

  Replaces Kind with Minikube due to stability issues, especially with Podman.
  Adds support for both Docker and Podman container runtimes.

  Changes:
  - Migrate from Kind to Minikube with NodePort (port 30080)
  - Podman: Use tarball + minikube image load (no registry needed)
  - Docker: Use Minikube registry addon with port-forwarding
  - Linux + Podman: Rootless mode with containerd runtime
  - Linux + Podman: Check broker pod directly (entity operator compatibility issues)
  - Linux + Podman: Poll Kafka broker until topic exists before deploying agents
  - Mac/Linux + Podman: Background service tunnel for NodePort access
  - Dynamic image references and imagePullPolicy based on container tool

  Tested on:
  - macOS with Podman ✓
  - Linux (Fedora) with Podman ✓
  - Linux (GitHub Actions) with Docker ✓

Author: kabir

.github/workflows/cloud-deployment-example.yml

@@ -25,40 +25,44 @@ jobs:
           distribution: 'temurin'
           cache: maven
 
-      - name: Install Kind
+      - name: Install Minikube
         run: |
-          curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-linux-amd64
-          chmod +x ./kind
-          sudo mv ./kind /usr/local/bin/kind
-          kind version
+          curl -Lo minikube https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
+          chmod +x minikube
+          sudo mv minikube /usr/local/bin/
 
       - name: Build project
         run: mvn -B clean install -DskipTests -f pom.xml
 
-      - name: Deploy with Kind
+      - name: Deploy with Minikube
         working-directory: examples/cloud-deployment/scripts
         run: |
           chmod +x deploy.sh
-          ./deploy.sh --container-tool docker
+          ./deploy.sh
 
       - name: Verify deployment
         working-directory: examples/cloud-deployment/scripts
         run: |
           chmod +x verify.sh
           ./verify.sh
 
+      - name: Get service URL
+        id: service
+        run: |
+          echo "url=$(minikube service a2a-agent-service -n a2a-demo --url)" >> $GITHUB_OUTPUT
+
       - name: Verify agent card is accessible
         run: |
-          echo "Testing agent card endpoint at http://localhost:8080/.well-known/agent-card.json"
-          curl -f http://localhost:8080/.well-known/agent-card.json || (echo "Agent card not accessible" && exit 1)
+          echo "Testing agent card endpoint at ${{ steps.service.outputs.url }}/.well-known/agent-card.json"
+          curl -f ${{ steps.service.outputs.url }}/.well-known/agent-card.json || (echo "Agent card not accessible" && exit 1)
 
       - name: Run test client
         working-directory: examples/cloud-deployment/server
         run: |
           mvn test-compile exec:java \
             -Dexec.mainClass="io.a2a.examples.cloud.A2ACloudExampleClient" \
             -Dexec.classpathScope=test \
-            -Dagent.url=http://localhost:8080
+            -Dagent.url=${{ steps.service.outputs.url }}
 
       - name: Show diagnostics on failure
         if: failure()
@@ -96,6 +100,6 @@ jobs:
         if: always()
         run: |
           cd examples/cloud-deployment/scripts
-          echo "y" | ./cleanup.sh --container-tool docker || true
+          echo "y" | ./cleanup.sh || true
 
 

examples/cloud-deployment/README.md

@@ -11,12 +11,12 @@ Note that the aim of this example is just to demonstrate how to set up a2a-java
 ## Architecture
 
 ```
-                              localhost:8080
-                            (extraPortMappings)
+                         minikube service --url
+                         (tunnel to NodePort)
                                     ▲
                                     │
 ┌───────────────────────────────────┼───────────────────────┐
-│  Kubernetes Cluster (Kind)        │                       │
+│  Kubernetes Cluster (Minikube)    │                       │
 │                                    │                      │
 │                        ┌───────────▼──────────┐           │
 │                        │ Service (NodePort)   │           │
@@ -60,7 +60,7 @@ Note that the aim of this example is just to demonstrate how to set up a2a-java
 
 ## Prerequisites
 
-- **Kind** (Kubernetes IN Docker) v0.20+
+- **Minikube** v1.30+
 - **kubectl** (v1.27+)
 - **Maven** (3.8+)
 - **Java** 17+
@@ -70,15 +70,15 @@ Note that the aim of this example is just to demonstrate how to set up a2a-java
 
 ### 1. Install Prerequisites
 
-**Install Kind:**
-See https://kind.sigs.k8s.io/docs/user/quick-start/ for installation instructions.
+**Install Minikube:**
+See https://minikube.sigs.k8s.io/docs/start/ for installation instructions.
 
 **Install kubectl:**
 See https://kubernetes.io/docs/tasks/tools/ for installation instructions.
 
 ### 2. Deploy the Stack
 
-The deployment script will automatically create the Kind cluster and deploy all components:
+The deployment script will automatically create the Minikube cluster and deploy all components:
 
 ```bash
 cd scripts
@@ -88,20 +88,21 @@ cd scripts
 **If using Podman instead of Docker:**
 ```bash
 ./deploy.sh --container-tool podman
+# OR set environment variable:
+export CONTAINER_TOOL=podman
+./deploy.sh
 ```
 
-Note that using Kind with Podman on Linux may have some occasional issues due to Kind's experimental support for Podman. In our testing, a reboot normally solves this. 
+**Note**: Minikube with Podman requires the Podman driver. The script will configure this automatically.
 
 The script will:
-- Create Kind cluster with local registry support (if not already exists)
-- Set up local container registry (localhost:5001)
+- Start Minikube cluster (if not already running)
+- Enable the registry addon
 - Install Strimzi Kafka operator
 - Deploy PostgreSQL
 - Deploy Kafka cluster (using KRaft mode)
 - Build and deploy the A2A agent (2 pods)
 
-**Note:** You don't need to manually create the Kind cluster - the script handles everything.
-
 ### 3. Verify Deployment
 
 ```bash
@@ -121,13 +122,20 @@ Expected output:
 
 #### Understanding the NodePort Setup
 
-The agent service uses **NodePort** with Kind **extraPortMappings** to expose the service:
+The agent service uses **NodePort** for external access with reliable load balancing:
+
+- Kubernetes Service exposes **NodePort 30080** → **pod port 8080** (configured in `k8s/05-agent-deployment.yaml`)
+- Minikube makes NodePort accessible via `minikube service` command
+- Result: Access the agent at the URL provided by `minikube service a2a-agent-service -n a2a-demo --url`
 
-- Kind maps **host port 8080** → **node port 30080** (configured in `kind-config.yaml`)
-- Kubernetes Service maps **NodePort 30080** → **pod port 8080** (configured in `k8s/05-agent-deployment.yaml`)
-- Result: Access the agent at **http://localhost:8080** from your host machine
+**Why NodePort instead of LoadBalancer?**
+- ✅ Works without `minikube tunnel` (which can have networking issues, especially in CI)
+- ✅ Provides reliable round-robin load balancing across multiple pods
+- ✅ Simpler setup for local development
+- ✅ Consistent behavior across different host operating systems (macOS, Linux, Windows)
+- ✅ Works reliably in CI environments like GitHub Actions
 
-This approach provides the same round-robin load balancing as a real LoadBalancer but works consistently across all platforms (macOS, Linux, Windows, and CI environments like GitHub Actions).
+**Note**: The test client creates fresh HTTP connections for each request to ensure proper load distribution across both pods.
 
 #### Run the Test Client
 
@@ -339,23 +347,17 @@ kubectl logs <pod-name> -n a2a-demo
 **Registry not accessible:**
 
 ```bash
-# Verify registry is running
-docker ps | grep kind-registry
-# or for Podman:
-podman ps | grep kind-registry
+# Verify Minikube registry addon is enabled
+minikube addons list | grep registry
 
-# Verify registry is accessible
-curl http://localhost:5001/v2/
-# Should return: {}
-
-# List images in registry
-curl http://localhost:5001/v2/_catalog
+# Verify images are cached in Minikube
+minikube ssh "crictl images" | grep a2a-cloud-deployment
 ```
 
 **Image push failures:**
-- Check registry container is running
-- For Podman: Ensure you use `--tls-verify=false` flag when pushing
-- Restart registry if needed: `docker/podman stop kind-registry && docker/podman start kind-registry`
+- Verify Minikube is running: `minikube status`
+- Check registry addon is enabled: `minikube addons enable registry`
+- For Podman: Ensure Minikube is started with `--driver=podman`
 
 ### Database Connection Failures
 
@@ -407,10 +409,8 @@ kubectl get svc a2a-agent-service -n a2a-demo
 # NAME                 TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
 # a2a-agent-service    NodePort    10.96.123.45    <none>        8080:30080/TCP   5m
 
-# 3. Verify Kind extraPortMappings are configured
-docker ps | grep kind-control-plane
-# or for Podman:
-podman ps | grep kind-control-plane
+# 3. Get service URL via minikube
+minikube service a2a-agent-service -n a2a-demo --url
 ```
 
 **Only seeing 1 pod:**
@@ -436,20 +436,22 @@ kubectl get crd kafkas.kafka.strimzi.io
 kubectl create -f 'https://strimzi.io/install/latest?namespace=kafka' -n kafka
 ```
 
-### Kind Resource Issues
+### Minikube Resource Issues
 
 **Insufficient resources:**
-Kind uses your Docker/Podman resources. Increase Docker Desktop memory/CPU limits if needed.
+Minikube uses your Docker/Podman resources. Increase Docker Desktop or Podman Machine memory/CPU limits if needed.
 
 **Disk space:**
 ```bash
-# Check disk usage inside Kind node
-docker exec -it kind-control-plane df -h
-# or for Podman:
-podman exec -it kind-control-plane df -h
+# Check disk usage inside Minikube
+minikube ssh df -h
 
 # Clean up old images
 docker system prune -a   # or: podman system prune -a
+
+# Delete and recreate Minikube with more resources
+minikube delete
+minikube start --cpus=4 --memory=8192
 ```
 
 ## Cleanup
@@ -461,6 +463,16 @@ cd scripts
 ./cleanup.sh
 ```
 
+**If you used Podman:**
+```bash
+./cleanup.sh --container-tool podman
+```
+
+**Skip confirmation prompt:**
+```bash
+./cleanup.sh --yes
+```
+
 This will delete:
 - A2A agent deployment and service
 - Kafka cluster
@@ -472,23 +484,18 @@ To also remove Strimzi operator:
 kubectl delete namespace kafka
 ```
 
-To delete the Kind cluster:
+To stop the Minikube cluster:
 ```bash
-kind delete cluster
+minikube stop
 ```
 
 ### Complete Clean Slate
 
 For a completely fresh start (useful for testing from scratch):
 
 ```bash
-# Delete Kind cluster
-kind delete cluster
-
-# Remove local registry container
-docker stop kind-registry && docker rm kind-registry
-# or for Podman:
-podman stop kind-registry && podman rm kind-registry
+# Delete Minikube cluster
+minikube delete
 
 # Optional: Clean up container images
 docker system prune -a   # or: podman system prune -a
@@ -571,9 +578,10 @@ From `pom.xml`:
 ## References
 
 - [A2A Protocol Specification](https://github.com/a2aproject/a2a)
-- [Kind Quick Start](https://kind.sigs.k8s.io/docs/user/quick-start/)
-- [Kind Local Registry](https://kind.sigs.k8s.io/docs/user/local-registry/)
-- [Kind extraPortMappings](https://kind.sigs.k8s.io/docs/user/configuration/#extra-port-mappings)
+- [Minikube Quick Start](https://minikube.sigs.k8s.io/docs/start/)
+- [Minikube Services](https://minikube.sigs.k8s.io/docs/handbook/accessing/)
+- [Minikube with Podman](https://minikube.sigs.k8s.io/docs/drivers/podman/)
 - [Strimzi Kafka Operator](https://strimzi.io/)
 - [Quarkus Reactive Messaging](https://quarkus.io/guides/kafka)
 - [Kubernetes Downward API](https://kubernetes.io/docs/concepts/workloads/pods/downward-api/)
+- [Kubernetes NodePort Service](https://kubernetes.io/docs/concepts/services-networking/service/#type-nodeport)

examples/cloud-deployment/k8s/05-agent-deployment.yaml

@@ -17,7 +17,7 @@ spec:
     spec:
       containers:
         - name: a2a-agent
-          image: localhost:5001/a2a-cloud-deployment:latest
+          image: localhost:5000/a2a-cloud-deployment:latest
           # Always pull to ensure latest image is used when rebuilding with :latest tag
           # For production, use digest-based image references (e.g., @sha256:...)
           imagePullPolicy: Always
@@ -91,6 +91,6 @@ spec:
     - protocol: TCP
       port: 8080        # Service port inside cluster
       targetPort: 8080  # Pod port
-      nodePort: 30080   # Fixed NodePort (mapped to host port 8080 via Kind config)
+      nodePort: 30080   # Fixed NodePort for consistent access
   type: NodePort
   sessionAffinity: None  # Ensures round-robin load balancing

examples/cloud-deployment/scripts/cleanup.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 echo "============================================"
-echo "A2A Cloud Deployment - Cleanup Script"
+echo "A2A Cloud Deployment - Cleanup Script for Minikube"
 echo "============================================"
 echo ""
 
@@ -12,33 +12,40 @@ YELLOW='\033[1;33m'
 NC='\033[0m' # No Color
 
 # Parse command line arguments
-CONTAINER_TOOL="docker"
+CONTAINER_TOOL="${CONTAINER_TOOL:-docker}"  # Use env var or default to docker
+SKIP_CONFIRMATION=false
 while [[ $# -gt 0 ]]; do
     case $1 in
         --container-tool)
             CONTAINER_TOOL="$2"
             shift 2
             ;;
+        -y|--yes)
+            SKIP_CONFIRMATION=true
+            shift
+            ;;
         *)
             echo -e "${RED}Unknown option: $1${NC}"
-            echo "Usage: $0 [--container-tool docker|podman]"
+            echo "Usage: $0 [--container-tool docker|podman] [--yes]"
             exit 1
             ;;
     esac
 done
 
-# Configure Kind to use podman if specified
+# Configure Minikube driver based on container tool
 if [ "$CONTAINER_TOOL" = "podman" ]; then
-    export KIND_EXPERIMENTAL_PROVIDER=podman
+    export MINIKUBE_DRIVER=podman
 fi
 
-echo -e "${YELLOW}This will delete all resources in the a2a-demo namespace and the Kind cluster${NC}"
-read -p "Are you sure you want to continue? (y/N) " -n 1 -r
-echo ""
+if [ "$SKIP_CONFIRMATION" != "true" ]; then
+    echo -e "${YELLOW}This will delete all resources in the a2a-demo namespace and stop the Minikube cluster${NC}"
+    read -p "Are you sure you want to continue? (y/N) " -n 1 -r
+    echo ""
 
-if [[ ! $REPLY =~ ^[Yy]$ ]]; then
-    echo "Cleanup cancelled"
-    exit 0
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        echo "Cleanup cancelled"
+        exit 0
+    fi
 fi
 
 echo ""
@@ -66,13 +73,16 @@ echo "Deleting namespace..."
 kubectl delete -f ../k8s/00-namespace.yaml --ignore-not-found=true
 
 echo ""
-echo "Deleting Kind cluster..."
-kind delete cluster
+echo "Stopping registry port-forward..."
+# Stop socat container (macOS)
+$CONTAINER_TOOL stop socat-registry 2>/dev/null || true
+$CONTAINER_TOOL rm socat-registry 2>/dev/null || true
+# Kill kubectl port-forward (Linux)
+pkill -f "kubectl.*port-forward.*registry" 2>/dev/null || true
 
 echo ""
-echo "Stopping and removing registry container..."
-$CONTAINER_TOOL stop kind-registry > /dev/null 2>&1 || true
-$CONTAINER_TOOL rm kind-registry > /dev/null 2>&1 || true
+echo "Stopping Minikube..."
+minikube stop
 
 echo ""
 echo -e "${GREEN}Cleanup completed${NC}"