Setting Up Your Environment

Get a workstation to the point where you can build, run, test, and debug the operator without fighting the toolchain.

Start by bootstrapping the repository-managed tools, then choose the smallest development loop that matches your task. Most contributor work does not need a full cluster deployment on the first edit, but webhooks, RBAC, networking, and lifecycle behavior eventually do.

Prerequisites

Required tools:

• Go 1.26.1+
• Docker 28.3.3+
• kubectl 1.33+
• Helm 3+
• Trivy
• Python 3
• Node.js 20+ with npm
• a Kubernetes cluster such as Kind, Minikube, or a cloud cluster

Optional but recommended:

• Kind for local E2E work
• k9s for cluster inspection
• Tilt for the fast in-cluster inner loop

Verify

Bootstrap the repository-managed toolchain

bash

make bootstrap
make doctor

Run this first on a new machine, inside a fresh devcontainer, or after toolchain changes. make doctor is the quickest way to see what is still missing locally.

Decision matrix

Choose a development loop

Choose a development loop.

Use this loop	Best for	Main command path
Local controller on your host	Fast logic changes, renderer work, and controller behavior that does not depend on webhook reachability or cluster-local network policy.	make install then make run-controller.
In-cluster integration loop	RBAC, webhook, lifecycle, and deployment behavior where the controller must run as a Pod inside the cluster.	Build image, load it into Kind, then make deploy IMG=....
Tilt fast cluster loop	Repeated controller changes against a local cluster when you want rebuilds, deploys, logs, and helper actions in one UI.	make tilt-up and make tilt-down.

Apply

Fast local controller loop

bash

git clone https://github.com/dc-tec/openbao-operator.git
cd openbao-operator

make bootstrap
make doctor
make install
make run-controller

This is the default contributor loop. It is fast, but it does not fully represent webhook reachability or cluster-local network behavior.

Local loop limitations

When the controller runs on your host, validating webhooks usually need additional tunneling or a different deployment path. NetworkPolicies are also not realistically tested from this loop.

Apply

In-cluster integration loop

bash

kind create cluster --name openbao-dev

make bootstrap
make doctor
make docker-build IMG=openbao-operator:dev
kind load docker-image openbao-operator:dev --name openbao-dev
make deploy IMG=openbao-operator:dev

kubectl get pods -n openbao-operator-system

Use this when the feature depends on cluster-local execution, admission behavior, or realistic operator RBAC.

Apply

Tilt fast cluster loop

bash

make bootstrap
make doctor
make tilt-up

# optional helper image override
tilt up -- --operator-version=edge

make tilt-down

Tilt is the best inner loop when you expect several controller edits against the same local cluster and want logs, deploy state, and helper actions in one place.

Reference table

High-value local commands

High-value local commands.

Area	Command	What it gives you
Core verification	make ci-core	The default local PR-equivalent gate except E2E.
Unit and integration	make test, make test-integration, make test-sum, make test-integration-sum	Targeted test coverage with optional JUnit output under dist/test/.
Controller debugging	make air-controller, make debug-controller, make debug-test PKG=... TEST=...	Live reload or Delve-based debugging for controller and test work.
Architecture policy	make generate-ast-rules, make verify-arch-policy, make report-internal-deps	Boundary verification plus a local dependency report for internal package drift.

Inspect

Architecture report and policy verification

bash

make report-internal-deps
make report-internal-deps-snapshot
make report-internal-deps-diff

make generate-ast-rules
make verify-arch-policy
make test-ast
make lint-ast

Use this when you change controller wiring, add new internal/* package boundaries, or want to compare package drift across a refactor.

RBAC errors during `make deploy`?

Make sure the current kubeconfig identity has enough privileges to install CRDs, RBAC, and admission resources.

Webhooks failing locally?

Switch from the host-based loop to the in-cluster loop. Webhook traffic needs the API server to reach the operator inside the cluster network.

How do I confirm my workstation is still healthy?

Run make doctor. It reports missing external tools and which contributor workflows they block.

After your environment works

Testing strategyChoose the smallest test layer that proves the change you are about to make.Project conventionsReview the repository-specific rules that shape how code, generated files, and reviews should look.Continuous integrationOpen the CI map when you need to understand how local checks expand into branch and release workflows.