Local Development

This guide explains how to set up and run the CloudAPI Operator locally for development and debugging.

Prerequisites

• Go (version 1.24+)
• kubectl to access a Kubernetes cluster
• A running Kubernetes cluster (e.g., kind or a remote cluster)
• Make to utilize provided makefile

Development Environment Setup

We recommend using Nix for a reproducible development environment:

nix develop

This ensures all tools and dependencies are available in consistent versions.

Setting Up a Local Kubernetes Cluster

If you don't have a Kubernetes cluster available, you can spawn a local Kind cluster for development:

make setup-test-e2e

This creates a Kind cluster that can be used for local development and testing. The cluster will persist until you explicitly delete it.

To tear down the cluster when you're done:

make cleanup-test-e2e

Install CRDs

Before running the operator, install the Custom Resource Definitions in your cluster:

make install

Verify the CRDs are installed like so:

kubectl get crds | grep cloudapi

Running the Operator Locally

Run the operator from the commandline like so:

go run ./cmd/main.go

or add a run configuration to your favorite IDE/Editor.

Testing Your Changes

Once the operator is running, create a sample WorkspaceClaim to trigger reconciliation:

kubectl apply -f config/samples/cloudapi.team-orca.dev_v1alpha1_workspaceclaim.yaml

Watch the operator logs to see the reconciliation loop in action.

Verify the resource status

kubectl get workspaceclaims
kubectl describe workspaceclaim workspaceclaim-sample

Running Tests

Unit Tests

make test

End-to-End Tests

make test-e2e

Useful Commands

Run make help to see all available commands. Here's a summary:

General

Command	Description
make help	Display help with all available targets

Development

Command	Description
make manifests	Generate WebhookConfiguration, ClusterRole and CustomResourceDefinition objects
make generate	Generate code containing DeepCopy, DeepCopyInto, and DeepCopyObject method implementations
make fmt	Run go fmt against code
make vet	Run go vet against code
make test	Run tests
make setup-test-e2e	Set up a Kind cluster for e2e tests if it does not exist
make test-e2e	Run the e2e tests (expects an isolated environment using Kind)
make cleanup-test-e2e	Tear down the Kind cluster used for e2e tests
make lint	Run golangci-lint linter
make lint-fix	Run golangci-lint linter and perform fixes
make lint-config	Verify golangci-lint linter configuration

Build

Command	Description
make build	Build manager binary
make run	Run a controller from your host
make docker-build	Build docker image with the manager
make docker-push	Push docker image with the manager
make docker-buildx	Build and push docker image for cross-platform support
make build-installer	Generate a consolidated YAML with CRDs and deployment

Deployment

Command	Description
make install	Install CRDs into the K8s cluster specified in ~/.kube/config
make uninstall	Uninstall CRDs from the K8s cluster specified in ~/.kube/config
make deploy	Deploy controller to the K8s cluster specified in ~/.kube/config
make undeploy	Undeploy controller from the K8s cluster specified in ~/.kube/config

Dependencies

Command	Description
make kustomize	Download kustomize locally if necessary
make controller-gen	Download controller-gen locally if necessary
make setup-envtest	Download the binaries required for ENVTEST in the local bin directory
make envtest	Download setup-envtest locally if necessary
make golangci-lint	Download golangci-lint locally if necessary

Troubleshooting

CRDs not found

If you see errors about unknown resource types, ensure CRDs are installed:

make install

Permission errors

Ensure your kubeconfig has sufficient permissions. For local clusters like kind or minikube, this is usually not an issue.

Operator not reconciling

The reconcile loop only triggers when:

1. A WorkspaceClaim resource exists in the cluster
2. The resource is created, updated, or deleted

If you don't see logs, create or modify a WorkspaceClaim resource.