k8s-controller

Kubernetes Controller

My implementation of the Golang Kubernetes Controller course from FWDays.

About

This project follows the step-by-step tutorial for building production-grade Kubernetes controllers in Go. Each step is implemented as a separate commit/branch with detailed explanations.

Course: Crash Course: Kubernetes controllers Instructors: @den-vasyliev (Principal SRE), @Alex0M (Senior Platform Engineer)

Quick Start

Prerequisites

• Go 1.23.1+ - Installation guide
• Taskfile - Installation guide
• Podman - Installation guide
• Docker (optional) - Alternative to Podman

One-Command Setup

Get a complete Kubernetes development environment running in seconds:

# Clone the repository
git clone https://github.com/Searge/k8s-controller.git
cd k8s-controller

# Initialize Podman machine and provision Kubernetes cluster
task init && task ssh -- 'cd /srv/app && go-task provision'

# Access your cluster
task ssh
kubectl get nodes
kubectl get all -A

This automated setup creates:

• Podman machine with Fedora CoreOS
• Complete single-node Kubernetes cluster (v1.30.0)
• All control plane components (etcd, API server, scheduler, controller-manager)
• Kubelet with containerd runtime
• CNI networking with bridge plugin
• PKI infrastructure with auto-generated certificates

Development Environment

The project includes a fully automated Kubernetes cluster setup for realistic controller development and testing. See ansible/README.md for detailed information about:

• Automated cluster provisioning
• Component configuration
• Available Ansible tags for selective deployment
• Troubleshooting and logging

Available Tasks

The project uses Taskfile for task automation:

# View all available tasks
task

# Development workflow
task dev          # Format, lint, test, build
task test-watch   # Run tests in watch mode
task docker-build # Build Docker image

# Environment management
task init         # Create and setup Podman machine
task ssh          # SSH into the machine
task provision    # Run Ansible provisioning
task reboot       # Restart the machine
task rm           # Remove the machine

Progress

• Foundation

  • Golang CLI Application using Cobra
  • Structured logging with zerolog
  • HTTP server with FastHTTP
  • Comprehensive testing suite
  • Quality assurance with linters
  • Development environment automation
  • Documentation and examples

• Kubernetes Integration (Next Steps)

  • List Kubernetes Deployments with client-go
  • Deployment Informer with client-go
  • JSON API Endpoint for deployments
  • controller-runtime Deployment Controller
  • Leader Election and Metrics

• Advanced Features (Future)

  • Custom Resource (FrontendPage CRD)
  • Platform API (CRUD + Swagger)
  • JWT Authentication
  • OpenTelemetry Instrumentation
  • Helm Charts and GitOps

Architecture

C4Container
    title Kubernetes Controller Architecture

    Person(user, "DevOps Engineer", "Uses CLI")

    System_Boundary(app, "Controller Application") {
        Container(cli, "CLI Client", "Go, Cobra", "Command line interface")
        Container(server, "HTTP Server", "Go, FastHTTP", "REST API and UI")
        Container(controller, "Controller", "Go, controller-runtime", "Reconciliation logic")
        Container(informers, "Informers", "Go, client-go", "Watch and cache")
    }

    System_Ext(k8s, "Kubernetes API", "Manages cluster resources")

    Rel(user, cli, "Uses")
    Rel(cli, server, "Commands")
    Rel(server, k8s, "API calls")
    Rel(k8s, informers, "Events")
    Rel(informers, controller, "Cached data")
    Rel(controller, k8s, "Reconcile")

Project Structure

├── ansible/              # Kubernetes cluster automation
│   ├── README.md         # Detailed Ansible documentation
│   ├── init.yml          # Initial system setup
│   ├── provision.yml     # Main K8s provisioning
│   └── templates/        # Service and config templates
├── cmd/                  # CLI application code
├── notebooks/            # Go learning notebooks
├── scripts/              # Setup and utility scripts
├── Taskfile.yaml        # Task automation
├── Dockerfile           # Container image definition
└── README.md            # This file

📚 Documentation

• API Documentation - HTTP endpoints and CLI commands

🔗 Resources

• Course: Kubernetes Controllers Crash Course
• Reference: Tutorial Reference Implementation
• Go Style: Google Go Style Guide
• Kubernetes: client-go Documentation

📄 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Built with ❤️ by @Searge