Project Setup with kubebuilder

Table of Contents

1. Introduction

2. Installing the Toolchain

3. Initializing the Project

4. Understanding the Generated Structure

5. Scaffolding the API and Controller

6. Understanding main.go

7. Running the Operator Locally

8. The Development Loop

---

Introduction

kubebuilder is the scaffolding CLI maintained by the Kubernetes SIGs team. It generates a working Go project — go.mod, main.go, Makefile, RBAC manifests, and CRD generation tooling — from a few commands. The goal isn't to hide complexity; it's to give you a consistent, idiomatic project structure so you can focus on reconcile logic rather than boilerplate.

This article walks through initializing appstack-operator, understanding every file that gets generated, and running the controller locally against a kind cluster.

---

Installing the Toolchain

Go

# macOS via Homebrew
brew install go

# Verify
go version  # should be 1.22+

kubebuilder

# Download the kubebuilder binary
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/

# Verify
kubebuilder version

kubebuilder doesn't have a brew formula. Download it directly from the releases page or use the command above.

kind (local Kubernetes)

brew install kind
kind version

# Create a development cluster
kind create cluster --name operator-dev
kubectl cluster-info --context kind-operator-dev

controller-gen

controller-gen is the code generation tool that reads Go struct markers and outputs CRD YAML and DeepCopy methods. kubebuilder installs it automatically via the Makefile, but you can install it manually:

go install sigs.k8s.io/controller-tools/cmd/controller-gen@latest

---

Initializing the Project

mkdir appstack-operator && cd appstack-operator

# Initialize a kubebuilder project
kubebuilder init \
  --domain htunn.io \
  --repo github.com/htunn/appstack-operator

The --domain flag sets the API group domain. Your CRDs will live under apps.htunn.io/v1alpha1. The --repo flag sets the Go module name in go.mod.

Expected output:

Writing kustomize manifests for you to edit...
Writing scaffold for you to edit...
Get controller runtime:
$ go get sigs.k8s.io/[email protected]
Update dependencies:
$ go mod tidy
Next: define a resource with:
$ kubebuilder create api

---

Understanding the Generated Structure

appstack-operator/
├── cmd/
│   └── main.go                    # Entry point — creates and starts the Manager
├── api/                           # (empty until you scaffold an API)
├── internal/
│   └── controller/                # (empty until you scaffold a controller)
├── config/
│   ├── default/                   # Kustomize overlay for full deployment
│   ├── manager/                   # Manager Deployment manifest
│   ├── rbac/                      # ClusterRole, ClusterRoleBinding
│   └── prometheus/                # ServiceMonitor for metrics (if enabled)
├── Dockerfile
├── Makefile
├── go.mod
├── go.sum
└── PROJECT                        # kubebuilder metadata file

Makefile Targets

The generated Makefile is the interface you'll use every day:

make manifests    # Run controller-gen to generate CRD YAML from Go markers
make generate     # Run controller-gen to generate DeepCopy methods
make fmt          # gofmt
make vet          # go vet
make test         # Run tests with envtest
make build        # Build the binary
make run          # Run the controller locally against current kubeconfig
make docker-build # Build the container image
make deploy       # Apply manifests to the cluster (kustomize)
make install      # Apply CRD manifests to cluster
make uninstall    # Remove CRD manifests from cluster

The PROJECT File

kubebuilder writes a PROJECT file that tracks what APIs and controllers you've scaffolded:

domain: htunn.io
layout:
- go.kubebuilder.io/v4
projectName: appstack-operator
repo: github.com/htunn/appstack-operator
version: "3"

When you run kubebuilder create api, it appends to this file. It's also used by kubebuilder to validate compatibility when you add new resources.

---

Scaffolding the API and Controller

kubebuilder create api \
  --group apps \
  --version v1alpha1 \
  --kind AppStack

kubebuilder will prompt:

Create Resource [y/n]  y
Create Controller [y/n]  y

Answer y to both. This generates:

api/
└── v1alpha1/
    ├── appstack_types.go        # CRD struct definitions (edit this)
    ├── appstack_webhook.go      # Webhook (if you scaffold one later)
    ├── groupversion_info.go     # API group registration
    └── zz_generated.deepcopy.go # Auto-generated DeepCopy methods (do not edit)

internal/
└── controller/
    ├── appstack_controller.go   # Reconciler (edit this)
    └── suite_test.go            # envtest setup for controller tests

The PROJECT file is updated:

resources:
- api:
    crdVersion: v1
    namespaced: true
  controller: true
  domain: htunn.io
  group: apps
  kind: AppStack
  path: github.com/htunn/appstack-operator/api/v1alpha1
  version: v1alpha1

---

Understanding main.go

The generated cmd/main.go is the entry point. It's worth reading in full before touching any controller logic:

package main

import (
    "flag"
    "os"

    _ "k8s.io/client-go/plugin/pkg/client/auth"

    "k8s.io/apimachinery/pkg/runtime"
    utilruntime "k8s.io/apimachinery/pkg/util/runtime"
    clientgoscheme "k8s.io/client-go/kubernetes/scheme"
    ctrl "sigs.k8s.io/controller-runtime"
    "sigs.k8s.io/controller-runtime/pkg/healthz"
    "sigs.k8s.io/controller-runtime/pkg/log/zap"
    metricsserver "sigs.k8s.io/controller-runtime/pkg/metrics/server"

    appsv1alpha1 "github.com/htunn/appstack-operator/api/v1alpha1"
    "github.com/htunn/appstack-operator/internal/controller"
)

var (
    scheme   = runtime.NewScheme()
    setupLog = ctrl.Log.WithName("setup")
)

func init() {
    // Register built-in Kubernetes types
    utilruntime.Must(clientgoscheme.AddToScheme(scheme))

    // Register your custom types
    utilruntime.Must(appsv1alpha1.AddToScheme(scheme))
}

func main() {
    var metricsAddr string
    var enableLeaderElection bool
    var probeAddr string

    flag.StringVar(&metricsAddr, "metrics-bind-address", ":8080", "The address the metrics endpoint binds to.")
    flag.StringVar(&probeAddr, "health-probe-bind-address", ":8081", "The address the probe endpoint binds to.")
    flag.BoolVar(&enableLeaderElection, "leader-elect", false,
        "Enable leader election for controller manager. "+
            "Enabling this will ensure there is only one active controller manager.")

    opts := zap.Options{Development: true}
    opts.BindFlags(flag.CommandLine)
    flag.Parse()

    ctrl.SetLogger(zap.New(zap.UseFlagOptions(&opts)))

    mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
        Scheme: scheme,
        Metrics: metricsserver.Options{
            BindAddress: metricsAddr,
        },
        HealthProbeBindAddress: probeAddr,
        LeaderElection:         enableLeaderElection,
        LeaderElectionID:       "appstack-operator-leader",
    })
    if err != nil {
        setupLog.Error(err, "unable to start manager")
        os.Exit(1)
    }

    // Register the controller with the manager
    if err = (&controller.AppStackReconciler{
        Client: mgr.GetClient(),
        Scheme: mgr.GetScheme(),
    }).SetupWithManager(mgr); err != nil {
        setupLog.Error(err, "unable to create controller", "controller", "AppStack")
        os.Exit(1)
    }

    if err := mgr.AddHealthzCheck("healthz", healthz.Ping); err != nil {
        setupLog.Error(err, "unable to set up health check")
        os.Exit(1)
    }
    if err := mgr.AddReadyzCheck("readyz", healthz.Ping); err != nil {
        setupLog.Error(err, "unable to set up ready check")
        os.Exit(1)
    }

    setupLog.Info("starting manager")
    if err := mgr.Start(ctrl.SetupSignalHandler()); err != nil {
        setupLog.Error(err, "problem running manager")
        os.Exit(1)
    }
}

Key things to understand in this file:

The scheme: A scheme maps Go types (AppStack) to Kubernetes API group/version/kind strings. You register both built-in types and your custom types in init(). Every API call goes through the scheme.

The Manager: The ctrl.Manager starts all your registered controllers, manages the client cache, serves the metrics endpoint, and handles leader election. You start it with mgr.Start(), which blocks until a signal is received.

SetupWithManager: Each controller calls this to register itself with the manager. This is where you configure watches (covered in the controller article).

---

Running the Operator Locally

Before writing any reconcile logic, verify the scaffolded project builds and runs:

Install the CRD

# Generate CRD YAML from Go type markers (creates config/crd/bases/)
make manifests

# Install the CRD into the kind cluster
make install

# Verify the CRD is registered
kubectl get crd appstacks.apps.htunn.io

Expected:

NAME                       CREATED AT
appstacks.apps.htunn.io   2026-04-01T10:00:00Z

Run the Controller

# Run the controller locally, connecting to the kind cluster via kubeconfig
make run

This runs go run ./cmd/main.go with the current kubeconfig. The controller connects to your kind cluster, registers event watches, and begins its goroutines. You should see output like:

{"level":"info","ts":"2026-04-01T10:00:01Z","msg":"starting manager"}
{"level":"info","ts":"2026-04-01T10:00:01Z","msg":"Starting EventSource","controller":"appstack","source":"kind source: *v1alpha1.AppStack"}
{"level":"info","ts":"2026-04-01T10:00:01Z","msg":"Starting Controller","controller":"appstack"}
{"level":"info","ts":"2026-04-01T10:00:01Z","msg":"Starting workers","controller":"appstack","worker count":1}

Apply a Test Resource

While make run is running, open a second terminal:

kubectl apply -f - <<EOF
apiVersion: apps.htunn.io/v1alpha1
kind: AppStack
metadata:
  name: test-stack
  namespace: default
spec: {}
EOF

The controller will call Reconcile(). In the logs you'll see:

{"level":"info","ts":"...","msg":"Reconciling AppStack","controller":"appstack","name":"test-stack","namespace":"default"}

Nothing happens yet because the reconcile body is empty in the scaffold. That logic is what the next articles build.

---

The Development Loop

The day-to-day loop when developing an operator:

# 1. Edit Go types in api/v1alpha1/appstack_types.go
# 2. Regenerate CRD YAML and DeepCopy methods
make generate manifests

# 3. Re-install the CRD (if you changed the spec schema)
make install

# 4. Edit reconcile logic in internal/controller/appstack_controller.go

# 5. Run the controller locally
make run

# 6. Apply test CRs with kubectl in another terminal
kubectl apply -f config/samples/apps_v1alpha1_appstack.yaml

# 7. Check status
kubectl describe appstack test-stack
kubectl get events --field-selector involvedObject.name=test-stack

# 8. Run tests
make test

Keeping make run running while you modify resources in another terminal is the most efficient development flow. You don't need to rebuild or redeploy between changes — just restart make run when you change Go code.

Useful Debug Commands

# Describe the CRD schema (validates your type markers were applied)
kubectl get crd appstacks.apps.htunn.io -o yaml | grep -A 50 "spec:"

# Watch all AppStack resources
kubectl get appstack -A -w

# Watch events for a specific AppStack
kubectl get events -n default --field-selector involvedObject.name=test-stack --watch

# Check controller logs when running in-cluster
kubectl logs -n appstack-system deployment/appstack-controller-manager -f

---

Next: CRD Design and Go API Types →