KaaS Portal — Learn-by-Building Guide

1Verify Go is installed

Run go version. You should see Go 1.26.x (already installed via brew).

2Understand what changed since 2016-2018

You used Go before modules existed. Here's what's different now:

3Warm up: Write a small program

Before touching the KaaS project, write a standalone Go program that:

• Creates a module (go mod init warmup)
• Defines a struct with JSON tags
• Starts an HTTP server using the new ServeMux routing ("GET /hello/{name}")
• Returns JSON responses
• Uses slog for logging
• Handles graceful shutdown with signal.NotifyContext

Why: This covers the exact patterns you'll use in the KaaS portal, in a throwaway sandbox.

1Initialize the project

You can either start from the existing scaffold at ~/PyCharmProjects/kaas-portal or wipe it and start fresh. If starting fresh:

• mkdir -p ~/PyCharmProjects/kaas-portal and cd into it
• go mod init github.com/<your-username>/kaas-portal
• git init

2Choose your project layout

Go doesn't enforce a project structure, but the community convention for non-trivial projects is:

Why internal/? The Go compiler enforces that packages under internal/ can only be imported by code in the parent directory tree. This is a hard compiler guarantee, not just convention. It keeps your API surface intentional.

3Build these pieces yourself

• Config package: Load port and environment from env vars. Keep it simple — just a struct and a Load() function.
• Server struct: Holds your dependencies (config, logger). Has a Router() method that returns http.Handler.
• Health endpoint: GET /healthz returns {"status": "ok"}
• Logging middleware: Wraps every request with timing and status code logging using slog.
• main.go: Wires everything together. Starts server. Handles graceful shutdown.

4Test it

Run go run ./cmd/kaas-portal and curl http://localhost:8080/healthz.

Then write an actual Go test. Create internal/api/server_test.go:

• Use httptest.NewRequest and httptest.NewRecorder
• Call your handler directly
• Assert the response status and body

Why: Go's testing story is built into the language (go test ./...). No test framework needed. Table-driven tests are the Go idiom — learn this pattern early.

1Design the Cluster model

Think about what a cluster is, provider-agnostically. At minimum:

• ID, Name, Provider ("kind", "aws", "gcp"), Region, Status, K8sVersion, NodeCount
• Timestamps (created, updated)
• Kubeconfig (sensitive — should not appear in list responses)

Write this as a struct in pkg/models/cluster.go with JSON tags.

Why pkg/? This is your public API. If someone imported your module, they could use these types. The provider implementations in internal/ will create and return these models.

2Design the Provider interface

This is where Go's interface model shines. Define an interface with methods like:

• Name() string
• CreateCluster(ctx context.Context, req CreateClusterRequest) (*Cluster, error)
• GetCluster(ctx context.Context, id string) (*ClusterDetail, error)
• ListClusters(ctx context.Context) ([]Cluster, error)
• DeleteCluster(ctx context.Context, id string) error

3Think about error handling

Every method returns error. Think about what errors mean for each operation:

• Cluster not found vs. provider failure — are these different error types?
• Should you define custom error types? (e.g., type NotFoundError struct{...})
• How will API handlers distinguish "not found" (404) from "provider broken" (500)?

For now, keep it simple — you can use errors.Is() and sentinel errors. Refine later.

4Wire the provider map into your server

Your server should accept a map[string]Provider. Add a GET /api/v1/providers endpoint that returns the list of registered provider names.

1Understand what Kind does under the hood

Before writing code, understand what happens when Kind creates a cluster:

1. Kind pulls a Docker image (kindest/node:v1.x.x) that contains kubelet, kubeadm, and containerd
2. It runs that image as Docker containers — each container = one K8s node
3. Inside each container, containerd runs as the container runtime and kubelet manages it via CRI
4. kubeadm bootstraps the control plane
5. Kind generates a kubeconfig pointing to the API server

This is containers running inside containers — the node is a Docker container, and the pods inside it use containerd. Understanding this nesting is key.

2Add the Kind library dependency

go get sigs.k8s.io/kind

Look at the sigs.k8s.io/kind/pkg/cluster package. The key type is cluster.Provider which has methods like Create(), Delete(), List(), and KubeConfig().

3Implement the Kind provider

Create internal/provider/kind/kind.go. You need:

• A struct that holds a Kind cluster.Provider instance and an in-memory map of clusters
• A sync.RWMutex to protect the map (multiple goroutines may read/write concurrently)
• CreateCluster: call Kind's Create(), track state, get kubeconfig
• ListClusters: return from your in-memory map
• DeleteCluster: call Kind's Delete(), update state

4Add CRUD handlers

Wire up these endpoints:

5Test it end-to-end

Start the server and create an actual cluster:

# Create a Kind cluster
curl -X POST http://localhost:8080/api/v1/clusters \
  -H "Content-Type: application/json" \
  -d '{"name": "test-1", "provider": "kind", "node_count": 1}'

# This will take 1-2 minutes. When it returns, you have a real K8s cluster.

# List clusters
curl http://localhost:8080/api/v1/clusters | jq

# Get kubeconfig and use it
curl http://localhost:8080/api/v1/clusters/kind-test-1/kubeconfig > /tmp/test-1.kubeconfig
kubectl --kubeconfig /tmp/test-1.kubeconfig get nodes

# Clean up
curl -X DELETE http://localhost:8080/api/v1/clusters/kind-test-1

6Explore what Kind created

While the cluster is running, investigate what's happening at the container runtime level:

# See the Docker containers Kind created (each is a K8s "node")
docker ps

# Exec into the node container and look at containerd
docker exec -it test-1-control-plane bash
  # Inside the node:
  crictl ps          # List containers via CRI (like kubectl for the runtime)
  crictl images      # List images in containerd
  cat /etc/containerd/config.toml   # containerd configuration
  ps aux | grep kubelet              # The kubelet process
  mount | head -30                   # See the mount table (remember the Mount Mayhem blog!)
  cat /proc/1/cgroup                 # cgroup of the init process

1Add the client-go dependency

go get k8s.io/client-go@latest

This is a large dependency. It pulls in the same code that powers kubectl and every K8s controller.

2Build a cluster info endpoint

Add GET /api/v1/clusters/{id}/info that:

• Gets the kubeconfig for the cluster
• Creates a Kubernetes clientset from the kubeconfig (look at clientcmd and kubernetes.NewForConfig)
• Queries the K8s API for: node count, node status, K8s server version, namespace list
• Returns it all as JSON

3Add a pod listing endpoint

Add GET /api/v1/clusters/{id}/pods that lists pods across all namespaces (or filtered by ?namespace=).

Use clientset.CoreV1().Pods(namespace).List(ctx, metav1.ListOptions{})

4Deploy a workload through the API

Add POST /api/v1/clusters/{id}/deployments that creates a Deployment in the cluster. Accept a simple payload (image, replicas, name) and use client-go to create it.

1Make creation async

Change CreateCluster to:

1. Immediately return the cluster in "provisioning" status with a 202 Accepted
2. Kick off the actual Kind creation in a goroutine
3. The goroutine updates the cluster status to "running" or "failed" when done

Clients poll GET /api/v1/clusters/{id} to check status.

2Handle cancellation

What if someone deletes a cluster while it's still provisioning? Think about:

• Using context.WithCancel for each provisioning goroutine
• Storing the cancel function alongside the cluster state
• Calling cancel on delete

3Add a status event stream (stretch goal)

Add GET /api/v1/clusters/{id}/events using Server-Sent Events (SSE) to stream status updates in real-time.

1Add the AWS SDK

go get github.com/aws/aws-sdk-go-v2 and the EKS, EC2, IAM, and STS service packages.

You used the AWS SDK in Go at Symantec — this will feel familiar, but the SDK has been rewritten (v2). The API design is different: it uses functional options and context everywhere.

2Implement the EKS provider

This is more complex than Kind. You'll need to:

• Create an EKS cluster (API call)
• Create a managed node group
• Handle IAM roles (cluster role + node role)
• Wait for the cluster to become ACTIVE
• Generate a kubeconfig using STS token

3Handle the cost angle

EKS clusters cost money. Consider:

• Auto-delete after a TTL (e.g., 2 hours)
• Use the smallest instance types for learning (t3.small)
• Add a max_clusters config to prevent runaway costs