Go Development Guide

Set up your Go development environment for the control plane, management API, and edge device agent.

Prerequisites

  • Go 1.21+ installed
  • golangci-lint for comprehensive linting
  • protoc for gRPC protobuf compilation (optional)

Project Structure

go/
  controlplane/                 # Service orchestration
    cmd/controlplane/main.go    # Entrypoint
    internal/
      policy/                   # OPA policy engine
        bundles.go              # Policy bundle management
        engine_test.go          # Policy engine tests
      vault/                    # HashiCorp Vault client
        client.go               # Vault API integration
    go.mod                      # Module definition

  mgmtapi/                      # Management REST API
    cmd/mgmtapi/main.go         # Entrypoint
    internal/
      devices/                  # Device lifecycle
        certificates.go         # Certificate management
        lifecycle.go            # Device lifecycle
    go.mod

  agents/device-agent/          # Edge device agent
    main.go                     # Entrypoint
    internal/
      tpm/sealing.go            # TPM secret sealing
    go.mod

Building

# Build control plane
cd go/controlplane
go build -trimpath -o ../../dist/controlplane ./cmd/controlplane

# Build management API
cd go/mgmtapi
go build -trimpath -o ../../dist/mgmtapi ./cmd/mgmtapi

# Build device agent
cd go/agents/device-agent
go build -trimpath -o ../../../dist/device-agent .

# Run the control plane
./dist/controlplane

Testing

# Run all tests for control plane
cd go/controlplane && go test ./...

# Run all tests for management API
cd go/mgmtapi && go test ./...

# Run with verbose output
go test -v ./...

# Run with coverage
go test -cover ./...

# Generate coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

# Run a specific test
go test -run TestPolicyEngine ./internal/policy/

Linting

# Install golangci-lint
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# Run linter
golangci-lint run ./...

# Run with all enabled linters
golangci-lint run --enable-all ./...

# Format code
gofmt -w .

Working with OPA Policies

The control plane loads OPA policy bundles from ops/opa-policies/. When adding new policies:

  1. Write the Rego policy in ops/opa-policies/
  2. Add test cases alongside the policy file
  3. Register the policy in the bundle loader (internal/policy/bundles.go)
  4. Run policy tests: go test ./internal/policy/ -v

Vault Integration

The vault package provides a client for HashiCorp Vault operations. For local development, start a Vault dev server:

# Start Vault in dev mode
vault server -dev

# Set environment variables
export VAULT_ADDR=http://127.0.0.1:8200
export VAULT_TOKEN=dev-root-token

Code Conventions

  • Follow the standard Effective Go guidelines
  • Use internal/ packages for non-exported code
  • Error handling: always wrap errors with context using fmt.Errorf
  • Use structured logging with slog
  • Table-driven tests for comprehensive coverage

Next Steps