Debug a Kubernetes Operator written in GO

In this blog post I want to share how to debug a GO Operator on your local machine on macOS. Adam de Leeuw and I verified it in different GO operator projects. Sometimes you find on Google information which uses the older Operator SDK. The following instructions worked for us in March 2022. 😉

The blog post is structured in four sections:

  1. Prerequisites
  2. Basics
  3. Configure Visual Studio Code to debug the operator
  4. Debug your GO operator

The 45 min live stream about “Debugging a GO Operator and extend spec section of a custom resource definition” also cover the topic in that blog post.

1. Prerequisites

You need to …

2. Basics

Please keep in mind some essentially basics when you run your operator locally with the make command:

make install run

That make install run command does …

  1. deploy the needed manifests (yaml's) to the Kubernetes cluster you use and create the connection.
  2. … it starts the local GO application with the file called main.go 
    (in the last step inside make file with the command go run ./main.go )

3. Configure Visual Studio Code to debug the operator

With that in mind we know how to debug.

  1. First, you to run the make install run command to ensure you operator will find all need manifests configurations on your cluster.
  2. Now you need to configure the DELVE GO debug in Visual Studio Code .vscode/launch.json configurations file in your workspace.

Step 1: Create a .vscode/launch.json file in Visual Studio Code with a GO configuration

The following short gif shows the creation of a .vscode/launch.json file. In that case it uses the folder where my workspace file is located and you see that go package was used as debug a configuration.

That’s the example result you saw in the gif.

    "configurations": [
            "name": "Launch Package",
            "type": "go",
            "request": "launch",
            "mode": "auto",
            "program": "${fileDirname}"

Step 2: Now you can optional configure the location where you want to start the main.go file.

Just to ensure the right operator will be started. The gif below show how to customize the .vscode/launch.json file.

That’s the example result you saw in the gif.

    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit:
    "version": "0.2.0",
    "configurations": [
            "name": "Launch Frontend Operator",
            "type": "go",
            "request": "launch",
            "mode": "auto",
            "program": "/Users/thomassuedbroecker/Downloads/dev/multi-tenancy-frontend-operator/frontendOperator"

4. Debug your GO operator

Step 1: Execute the make install run for your operator

You see the my example operator I used for my blog post and live stream Develop a simple operator to deploy a web application using the GO Operator SDK¶.

make install run

  • Example output
/Users/thomassuedbroecker/Downloads/dev/multi-tenancy-frontend-operator/frontendOperator/bin/controller-gen rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
/Users/thomassuedbroecker/Downloads/dev/multi-tenancy-frontend-operator/frontendOperator/bin/kustomize build config/crd | kubectl apply -f - configured
/Users/thomassuedbroecker/Downloads/dev/multi-tenancy-frontend-operator/frontendOperator/bin/controller-gen object:headerFile="hack/boilerplate.go.txt" paths="./..."
go fmt ./...
go vet ./...
go run ./main.go
1.6461312240985138e+09  INFO    controller-runtime.metrics      Metrics server is starting to listen      {"addr": ":8080"}
1.646131224098974e+09   INFO    setup   starting manager
1.646131224099315e+09   INFO    Starting server {"path": "/metrics", "kind": "metrics", "addr": "[::]:8080"}
1.646131224099315e+09   INFO    Starting server {"kind": "health probe", "addr": "[::]:8081"}
1.6461312240993888e+09  INFO    controller.tenancyfrontend      Starting EventSource      {"reconciler group": "", "reconciler kind": "TenancyFrontend", "source": "kind source: *v1alpha1.TenancyFrontend"}
1.6461312240994549e+09  INFO    controller.tenancyfrontend      Starting Controller       {"reconciler group": "", "reconciler kind": "TenancyFrontend"}
1.646131224200895e+09   INFO    controller.tenancyfrontend      Starting workers {"reconciler group": "", "reconciler kind": "TenancyFrontend", "worker count": 1}

Step 2: Stop the operator execution

Step 3: Add a break point to the controller and start the debugging for the GO operator

The gif below shows how create a break point and start the debugging. You need to take a look in the debug console.

In the following image you see a screen shot of the running debugging.

Take a short look at

  • Run and debug
    • Start the debug session with the just defined GO configuration for the Operator
  • Observe
    • Variables
    • Watch
    • Stack
  • Debug console
    • Show the output we would see, when we would have started operator with a make command


It’s awesome to use the powerful DELVE debugger for GO inside Visual Studio Code when you build a GO Operator. 🙂

I hope this was useful for you and let’s see what’s next?



#operator, #go, #operatorsdk, #kubernetes, #delve, #buildlabs4saas, #operatorlearningjourney

One thought on “Debug a Kubernetes Operator written in GO

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.