Makefile Reference

The Nebari Operator uses a Makefile generated by Kubebuilder that provides convenient commands for development, testing, and deployment. This document describes the available targets and how they're used in CI/CD.

Overview

The Makefile is located at the root of the repository and provides a consistent interface for common operations. It's used both locally during development and in GitHub Actions workflows to ensure consistency.

🔧 Development Targets

Code Generation

`make manifests`

Generates WebhookConfiguration, ClusterRole, and CustomResourceDefinition objects.

make manifests

Used in CI:

✅ PR builds (.github/workflows/build-pr.yml)
✅ Release workflow (.github/workflows/release.yml)

When to use: After modifying CRD types, RBAC markers, or webhook configurations.

`make generate`

Generates code containing DeepCopy, DeepCopyInto, and DeepCopyObject method implementations.

make generate

Used in CI:

✅ PR builds
✅ Release workflow

When to use: After modifying API types in api/v1/.

Code Quality

`make fmt`

Runs go fmt against code to ensure consistent formatting.

make fmt

Used in CI:

✅ PR builds (with validation)
✅ Release workflow (with validation)

When to use: Before committing code.

`make vet`

Runs go vet against code to find suspicious constructs.

make vet

Used in CI:

✅ PR builds
✅ Release workflow

When to use: Before committing code, as part of pre-commit checks.

`make lint`

Runs golangci-lint linter with full rule set.

make lint

Used in CI:

✅ PR builds
✅ Release workflow

Alternatives:

make lint-fix - Runs linter with auto-fix
make lint-config - Verifies linter configuration

Testing

`make test`

Runs unit tests with coverage report.

make test

Used in CI:

✅ PR builds
✅ Release workflow

Output: Generates cover.out coverage profile.

When to use: After making any code changes, before committing.

🏗️ Build Targets

Local Binary

`make build`

Builds the manager binary for local testing.

make build
# Output: bin/manager

Used in CI: ❌ Not used (we use docker-build instead)

When to use: Testing locally without Docker.

`make run`

Runs the controller from your host (outside cluster).

make run

Used in CI: ❌ Not used

When to use: Local development and debugging.

Docker Images

`make docker-build`

Builds the Docker image with the manager.

make docker-build IMG=quay.io/nebari/nebari-operator:dev

Used in CI: ❌ Not directly (we use docker-build-push-action for multi-arch)

When to use: Building single-arch images locally.

`make docker-push`

Pushes the Docker image to a registry.

make docker-push IMG=quay.io/nebari/nebari-operator:dev

Used in CI: ❌ Not directly (handled by docker-build-push-action)

When to use: After building an image locally.

`make docker-buildx`

Builds and pushes multi-architecture Docker images.

make docker-buildx IMG=quay.io/nebari/nebari-operator:v1.0.0

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

Used in CI: ❌ Not directly (we use docker-build-push-action)

When to use: Building multi-arch images locally (requires Docker Buildx).

Installer Manifests

`make build-installer`

Generates a consolidated YAML with CRDs and deployment.

Important: Always specify the IMG parameter to ensure correct image references in the generated manifests.

make build-installer IMG=quay.io/nebari/nebari-operator:v1.0.0

Output: dist/install.yaml

Used in CI:

✅ Release workflow
✅ Generates installer with version-specific image tag

When to use: Creating installation artifacts for releases.

Note: The IMG parameter updates all image references in the generated YAML to use the specified image.

🚀 Deployment Targets

CRD Management

`make install`

Installs CRDs into the Kubernetes cluster specified in ~/.kube/config.

make install

Used in CI: ❌ Not used

When to use: Installing CRDs during development.

`make uninstall`

Uninstalls CRDs from the Kubernetes cluster.

make uninstall
# Or ignore errors if CRDs don't exist:
make uninstall ignore-not-found=true

Used in CI: ❌ Not used

When to use: Cleaning up after development.

Operator Deployment

`make deploy`

Deploys the controller to the Kubernetes cluster.

make deploy IMG=quay.io/nebari/nebari-operator:latest

Used in CI: ❌ Not used (deployment is manual)

When to use: Testing the operator in a development cluster.

`make undeploy`

Removes the controller from the Kubernetes cluster.

make undeploy
# Or ignore errors:
make undeploy ignore-not-found=true

Used in CI: ❌ Not used

When to use: Cleaning up after testing.

🛠️ Tool Management

The Makefile automatically downloads and manages required tools in the bin/ directory.

Available Tools

kustomize - For customizing Kubernetes manifests
controller-gen - For generating CRDs and RBAC
setup-envtest - For setting up test environment
golangci-lint - For linting

Tool Targets

`make kustomize`

Downloads kustomize locally if not present.

`make controller-gen`

Downloads controller-gen locally if not present.

`make setup-envtest`

Downloads setup-envtest and configures test binaries.

`make golangci-lint`

Downloads golangci-lint locally if not present.

Note: These are automatically invoked by other targets when needed.

📊 CI/CD Integration

PR Build Workflow

The PR build workflow (.github/workflows/build-pr.yml) uses:

make fmt - Validate formatting
make vet - Run static analysis
make test - Run unit tests
make lint - Run linter
make manifests - Validate manifests are up to date
make generate - Validate generated code is up to date

Release Workflow

The release workflow (.github/workflows/release.yml) uses:

make fmt - Validate formatting
make vet - Run static analysis
make test - Run unit tests
make lint - Run linter
make manifests - Generate CRDs and RBAC
make generate - Generate DeepCopy methods
make build-installer - Create installation YAML

🎯 Common Workflows

Pre-Commit Workflow

Before committing code:

make fmt          # Format code
make vet          # Run static analysis
make test         # Run tests
make lint         # Run linter
make manifests    # Update manifests if needed
make generate     # Update generated code if needed

Tip: Create a git pre-commit hook:

#!/bin/bash
# .git/hooks/pre-commit
make fmt && make vet && make test && make lint

Development Workflow

For active development:

# 1. Make changes to code
vim api/v1/nebariapp_types.go

# 2. Update generated code
make manifests generate

# 3. Test locally
make test

# 4. Run the operator locally
make run

# 5. Or deploy to cluster
make deploy IMG=quay.io/nebari/nebari-operator:dev

Release Preparation

Before creating a release:

# 1. Ensure everything is up to date
make manifests generate

# 2. Run full test suite
make test

# 3. Run linter
make lint

# 4. Build and test installer
make build-installer IMG=quay.io/nebari/nebari-operator:v1.0.0

# 5. Test the installer
kubectl apply -f dist/install.yaml

🔍 Makefile Variables

You can override these variables when invoking make:

Variable	Default	Description
`IMG`	`nebari-operator:latest`	Docker image name and tag
`PLATFORMS`	`linux/arm64,linux/amd64,...`	Platforms for docker-buildx
`CONTAINER_TOOL`	`docker`	Container tool (docker or podman)
`ENVTEST_K8S_VERSION`	(auto-detected)	Kubernetes version for envtest

Example:

make docker-build IMG=quay.io/nebari/nebari-operator:dev CONTAINER_TOOL=podman

📝 Adding Custom Targets

To add custom targets to the Makefile:

.PHONY: my-custom-target
my-custom-target: ## Description of what this does
	@echo "Running custom target"
	# Your commands here

The ## comment makes it appear in make help output.

🆘 Troubleshooting

"make: command not found"

Make sure you have make installed:

# macOS
brew install make

# Ubuntu/Debian
sudo apt-get install build-essential

# Fedora/RHEL
sudo dnf install make

Tools Fail to Download

If tools fail to download, clear the bin directory:

rm -rf bin/
make test  # This will re-download tools

Test Environment Issues

If tests fail with envtest errors:

make setup-envtest

This ensures the test environment binaries are properly configured.

Docker Build Failures

For Docker-related issues:

Check Docker is running: docker ps
Check credentials: docker login quay.io
Use verbose output: make docker-build V=1

🔗 Related Documentation

Release Process - How releases use the Makefile
Quick Reference - Quick command reference
Kubebuilder Book - Official Kubebuilder documentation

💡 Tips and Best Practices

Always run make test before committing - Catch issues early
Use make fmt to format code - Ensures consistency
Run make manifests generate after API changes - Keeps generated code in sync
Use make lint frequently - Catch potential issues before CI
Leverage make help - See all available targets
Keep tools updated - Delete bin/ occasionally to get latest versions

Uh oh!

FilesExpand file tree

makefile-reference.md

Latest commit

History

makefile-reference.md

File metadata and controls

Makefile Reference

Overview

🔧 Development Targets

Code Generation

make manifests

make generate

Code Quality

make fmt

make vet

make lint

Testing

make test

🏗️ Build Targets

Local Binary

make build

make run

Docker Images

make docker-build

make docker-push

make docker-buildx

Installer Manifests

make build-installer

🚀 Deployment Targets

CRD Management

make install

make uninstall

Operator Deployment

make deploy

make undeploy

🛠️ Tool Management

Available Tools

Tool Targets

make kustomize

make controller-gen

make setup-envtest

make golangci-lint

📊 CI/CD Integration

PR Build Workflow

Release Workflow

🎯 Common Workflows

Pre-Commit Workflow

Development Workflow

Release Preparation

🔍 Makefile Variables

📝 Adding Custom Targets

🆘 Troubleshooting

"make: command not found"

Tools Fail to Download

Test Environment Issues

Docker Build Failures

🔗 Related Documentation

💡 Tips and Best Practices

`make manifests`

`make generate`

`make fmt`

`make vet`

`make lint`

`make test`

`make build`

`make run`

`make docker-build`

`make docker-push`

`make docker-buildx`

`make build-installer`

`make install`

`make uninstall`

`make deploy`

`make undeploy`

`make kustomize`

`make controller-gen`

`make setup-envtest`

`make golangci-lint`