Skip to content

Development Setup

Set up a local development environment for AIM Engine.

Prerequisites

  • Docker or Podman — For building images and running Kind clusters
  • kubectl — Kubernetes CLI
  • Go 1.24+, controller-gen, golangci-lint, chainsaw — See Tool Management below

Tool Management

This project uses mise to pin exact tool versions (Go, controller-gen, chainsaw, golangci-lint, etc.). This is the recommended approach to ensure you have compatible versions:

# Install mise
curl https://mise.run | sh

# Activate mise in your shell (adds tools to PATH)
echo 'eval "$(mise activate bash)"' >> ~/.bashrc
source ~/.bashrc

# Install all project tools
mise install

After activation, all tools are available directly on your PATH — no mise exec -- prefix needed.

If you prefer to manage tools yourself, check mise.toml for the required versions.

Getting Started

git clone https://github.com/amd-enterprise-ai/aim-engine.git
cd aim-engine

Building

make build        # Build binary to bin/manager
make generate     # Generate DeepCopy methods
make manifests    # Generate CRDs and RBAC
make fmt          # Format code
make vet          # Vet code
make lint         # Run golangci-lint

Local Cluster

Create a local Kind cluster with dependencies:

make kind-create  # Create Kind cluster
make install      # Install CRDs

Running the Operator

Standard Mode

make run          # Run controller against kubeconfig
make run-debug    # Run with debug logging

make watch        # Rebuild and restart on file changes

This uses air for live reload. Operator logs are written to timestamped files in .tmp/logs/:

# Tail the latest log
tail -f "$(ls -t .tmp/logs/air-*.log | head -1)"

# Search for errors
grep -E '"level":"error"' "$(ls -t .tmp/logs/air-*.log | head -1)"

Readiness Check

Wait for the operator to be ready before running tests:

make wait-ready   # Polls localhost:8081/readyz

Environment Switching

Switch between local (Kind) and remote (GPU vcluster) environments:

# Kind environment (default)
make watch

# GPU environment
export KUBE_CONTEXT_GPU=my-vcluster-context
export ENV=gpu
make watch

# Check current environment
make env-info

The current environment is persisted to .tmp/current-env and shared across terminals.

Code Generation

Pre-commit hooks auto-run make generate and make manifests when api/ files change.

Generated files (don't edit manually):

  • api/v1alpha1/zz_generated.deepcopy.go
  • config/crd/bases/*.yaml
  • config/rbac/role.yaml

Documentation

make generate-docs    # Generate CRD and Helm values reference
make docs-serve       # Start local docs server

Next Steps