Overview

Development Overview

This guide covers the development workflow for contributing to the Forkspacer operator, including setting up your development environment, building, testing, and running the operator locally.

Prerequisites

Before you begin development, ensure you have the following tools installed:

Go (v1.24 or later) - The operator is written in Go
Docker or Podman - For building container images
kubectl (v1.20 or later) - Kubernetes command-line tool
Kind (Kubernetes in Docker) - Recommended for local development
Git - Version control

Project Structure

The Forkspacer operator follows the standard Kubebuilder project layout:

forkspacer/
├── api/v1/              # CRD definitions (Workspace, Module)
├── cmd/                 # Application entrypoint
├── config/              # Kubernetes manifests and kustomize configs
│   ├── crd/            # Generated CRD manifests
│   ├── manager/        # Operator deployment manifests
│   ├── rbac/           # RBAC configurations
│   └── webhook/        # Webhook configurations
├── internal/
│   ├── controller/     # Reconciliation logic for CRDs
│   └── webhook/        # Webhook validation and defaulting
├── pkg/                # Reusable packages
│   ├── manager/        # Manager initialization
│   ├── resources/      # Resource management utilities
│   ├── services/       # Business logic services
│   ├── types/          # Common types
│   └── utils/          # Utility functions
├── plugins/            # Plugin system for extensibility
├── test/
│   ├── e2e/           # End-to-end tests
│   └── utils/         # Test utilities
└── Makefile           # Development commands

Getting Started

1. Clone the Repository

git clone https://github.com/forkspacer/forkspacer.git
cd forkspacer/forkspacer

2. Install Dependencies

The project uses Go modules. Dependencies will be downloaded automatically, but you can explicitly install them:

go mod download

3. Install Development Tools

The Makefile will automatically install required tools (controller-gen, kustomize, etc.) when needed. These tools are installed in the local bin/ directory:

make help  # View available commands

Common Development Workflows

Running the Operator

Option 1: Run on Host (Quick Testing)

For rapid iteration, run the operator directly on your host machine:

# First, install CRDs if not already installed
make install

# Run the operator on your host
make dev-host

This runs the operator against your current kubeconfig context. It’s useful for:

Quick testing of controller logic
Debugging with your IDE
Fast iteration without image builds

Important Notes:

Webhooks are disabled - The operator runs with ENABLE_WEBHOOKS=false, so validation and defaulting webhooks won’t be active
Use local connection type - When creating Workspaces in dev-host mode, use type: local instead of type: in-cluster for the connection configuration
Your kubeconfig must point to a running cluster (Kind, minikube, etc.)

Example Workspace for dev-host mode:

apiVersion: batch.forkspacer.com/v1
kind: Workspace
metadata:
  name: dev-workspace
  namespace: default
spec:
  type: kubernetes
  connection:
    type: local  # Use 'local' when running with dev-host
    secretReference:
      name: local

Option 2: Run in Kind Cluster (Recommended)

For a complete, isolated development environment, use Kind:

make dev-kind

This will:

Delete any existing operator-dev Kind cluster
Create a fresh Kind cluster
Install cert-manager
Install CRDs
Build the operator image
Load the image into Kind
Deploy the operator

Benefits of Kind Development:

Isolated environment that won’t affect other clusters
Tests the full deployment process
Validates webhook configurations
Mimics production deployment

Cleanup:

make cleanup-dev-kind

Code Generation

When you modify API types (api/v1/*.go), you need to regenerate manifests and code:

# Generate CRDs, RBAC, and webhook configurations
make manifests

# Generate DeepCopy, DeepCopyInto, and DeepCopyObject methods
make generate

These commands use controller-gen and are automatically run as part of make build.

Code Quality

Format Code

make fmt

Run Static Analysis

make vet

Run Linter

# Run golangci-lint
make lint

# Run linter with auto-fix
make lint-fix

# Verify linter configuration
make lint-config

Testing

Unit Tests

Run unit tests with coverage:

make test

This runs all tests except e2e tests and generates a coverage report in cover.out.

End-to-End Tests

E2E tests run against a real Kubernetes cluster (Kind):

make test-e2e

This will:

Create a Kind cluster named operator-test-e2e (if it doesn’t exist)
Run e2e tests using Ginkgo
Clean up the Kind cluster after tests complete

Manual cleanup (if needed):

make cleanup-test-e2e

Deploying to a Cluster

Install CRDs Only

make install

Deploy the Operator

# Build image
make docker-build IMG=myregistry/forkspacer:dev

# Load into Kind (if using Kind)
kind load docker-image myregistry/forkspacer:dev -n operator-dev

# Deploy to cluster
make deploy IMG=myregistry/forkspacer:dev

Undeploy the Operator

make undeploy

Uninstall CRDs

make uninstall

Building Release Artifacts

Generate Installation Manifest

Create a consolidated YAML for installation:

make build-installer

This generates dist/install.yaml containing all CRDs and deployment manifests.

Multi-Platform Build

Build and push images for multiple architectures:

make docker-buildx IMG=myregistry/forkspacer:v1.0.0

Platforms: linux/arm64, linux/amd64, linux/s390x, linux/ppc64le

Development Tips

Debugging

Enable verbose logging: Set environment variable before running:
Terminal window
```
export LOG_LEVEL=debug
make dev-host
```
Use delve for debugging:
Terminal window
```
dlv debug ./cmd/main.go
```

Check operator logs in cluster:

kubectl logs -n forkspacer-system deployment/forkspacer-controller-manager -f

Rapid Iteration

For the fastest development cycle:

Run operator on host: make dev-host
Make code changes
Stop the operator (Ctrl+C)
Run make manifests generate if you changed API types
Restart with make dev-host

Working with Webhooks

Webhooks require TLS certificates, which makes local development challenging. When running on host:

Webhooks are disabled by default in dev-host mode
Use dev-kind to test webhook functionality
Webhook code is in internal/webhook/

Version Management

The version is controlled by variables in the Makefile:

VERSION ?= v0.1.3

To build with a custom version:

make build VERSION=v0.2.0-dev

Contributing Workflow

Fork the repository on GitHub
Create a feature branch:
Terminal window
```
git checkout -b feature/my-new-feature
```
Make your changes following the project structure
Run tests and linting:
Terminal window
```
make test lint
```
Commit your changes with clear commit messages
Push to your fork:
Terminal window
```
git push origin feature/my-new-feature
```
Open a Pull Request on GitHub

Next Steps

Plugin Development - Learn how to create custom plugins
API Reference - Understand the CRD specifications