Building a Kubernetes controller using Go is the standard way to scale cluster behavior, because Go has a high performance, powerful ecosystem and mature toolchain. 1. Install Kubebuilder and initialize the project; 2. Create custom resource (CRD) definitions such as MyApp; 3. Implement Reconcile logic to ensure the expected state (such as creating or updating a Deployment); 4. Use the make command to run or deploy the controller; 5. Follow best practices, including idempotence, error retry, RBAC permission configuration, and extend the use of Finalizers, Status subresources, and Webhooks. Through controller-runtime and Kubebuilder, Go makes building reliable, maintainable controllers efficient and easy to manage, ultimately achieving automated operation and maintenance goals.

Building custom Kubernetes controllers with Go is a powerful way to extend the behavior of your cluster and automatic complex operational logic. Since Kubernetes itself is written in Go, the ecosystem around Go is mature, with robust libraries like client-go , controller-runtime , and tools like Kubebuilder and kustomize that make building controllers efficient and maintainable.

Here's how you can get started and what you need to know.

Why Use Go for Kubernetes Controllers?

Go is the de facto language for Kubernetes development. The main reasons include:

• Performance : Go compiles to a single binary, has low memory overhead, and excellent concurrency support via goroutines.
• Strong Ecosystem : client-go provides deep integration with the Kubernetes API; controller-runtime (part of Kubernetes SIGs) simplifies common controller patterns.
• Tooling : Tools like Kubebuilder , Operator SDK , and kubebuilder init streamline scaffolding, testing, and deployment.

If you're extending Kubernetes in production, Go is the most practical choice.

Key Components of a Custom Controller

A Kubernetes controller watches resources and take actions to move the system from its current state to the desired state. At a high level, it includes:

• Informers/Watchers : Listen to changes on specific resources (eg, Pods, Custom Resources).
• Client : Interact with the Kubernetes API to read, create, update, or delete objects.
• Reconciliation Loop : The core logic that runs whenever a change is detected.
• Custom Resource Definition (CRD) : If you're building an operator, you'll likely define a CRD to represent your custom object.

Step-by-Step: Building a Controller with controller-runtime

The easiest way to build a controller today is using Kubebuilder and controller-runtime .

1. Install Kubebuilder

 # On Linux/macOS
curl -L -o kubebuilder https://go.kubebuilder.io/dl/latest/$(go env GOOS)/$(go env GOARCH)
chmod x kubebuilder && sudo mv kubebuilder /usr/local/bin/

2. Initialize a Project

 mkdir my-controller && cd my-controller
kubebuilder init --domain example.com --repo example.com/mymodule

This sets up a Go module with basic scaffolding and Docker support.

3. Create a Custom Resource (API)

 kubebuilder create api --group apps --version v1 --kind MyApp

This generates:

• A Go struct for MyApp
• A CRD manifest ( config/crd/bases/ )
• A controller scaffold

You can now customize the MyAppSpec and MyAppStatus structs in api/v1/myapp_types.go .

4. Implement the Reconcile Logic

Edit controllers/myapp_controller.go :

 func (r *MyAppReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    log := r.Log.WithValues("myapp", req.NamespacedName)

    // Fetch the MyApp instance
    var myapp MyApp
    if err := r.Get(ctx, req.NamespacedName, &myapp); err != nil {
        return ctrl.Result{}, client.IgnoreNotFound(err)
    }

    // Your logic here: eg, ensure a Deployment exists
    desiredDeployment := newDeploymentForMyApp(&myapp)

    var found appsv1.Deployment
    err := r.Get(ctx, types.NamespacedName{Name: desiredDeployment.Name, Namespace: desiredDeployment.Namespace}, &found)
    if err != nil && errors.IsNotFound(err) {
        log.Info("Creating Deployment", "name", desiredDeployment.Name)
        return ctrl.Result{}, r.Create(ctx, desiredDeployment)
    } else if err != nil {
        return ctrl.Result{}, err
    }

    // If found, maybe update or do nothing
    if !reflect.DeepEqual(found.Spec, desiredDeployment.Spec) {
        found.Spec = desiredDeployment.Spec
        log.Info("Updating Deployment")
        return ctrl.Result{}, r.Update(ctx, &found)
    }

    return ctrl.Result{}, nil
}

5. Run the Controller

During development:

 Make run

Or deploy to cluster:

 make docker-build docker-push IMG=myregistry/my-controller:v1
make deploy IMG=myregistry/my-controller:v1

Your CRD and controller will be installed in the cluster.

Best Practices

• Use controller-runtime : It handles informer setup, retry logic, leader election, and more.
• Idempotency : Reconcile functions must be idealpotent — safe to run multiple times.
• Error Handling : Return errors to retry, use ctrl.Result{RequeueAfter: ...} for delayed requests.
• Logging & Metrics : Use structured logging ( logr ) and expose Prometheus metrics (built-in support).
• RBAC : Define proper permissions in config/rbac/role.yaml .

Advanced Patterns

• Finalizers : For cleanup before object deletion (eg, deleting cloud resources).
• Status Subresource : Update only .status without affecting .spec .
• Webhooks : Add validation or defaulting using admission.Webhook .
• Multi-Version CRDs : Support version upgrades with conversion webhooks.

Alternatives and Tools

• Operator SDK : Built on Kubebuilder, adds higher-level abstractions and Ansible/Helm support.
• KubeBuilder Docs : Excellent guides at book.kubebuilder.io
• Sample Controllers : Check the kubebuilder example for a full walkthrough.

Building controllers in Go gives you full control and performance, and with modern tools, it's more approachable than ever. Whether you're automated deployments, managing databases, or integrating external systems, a custom controller lets Kubernetes work for you.

Basically, define your CRD, write a reconcile loop, and let the control plane do the rest.

The above is the detailed content of Using Go to build custom Kubernetes controllers. For more information, please follow other related articles on the PHP Chinese website!