Black lives matter.

We stand in solidarity with the Black community.

Racism is unacceptable.

It conflicts with the core values of the Kubernetes project and our community does not tolerate it.

What’s in a basic project?

When scaffolding out a new project, Kubebuilder provides us with a few basic pieces of boilerplate.

Build Infrastructure

First up, basic infrastructure for building your project:

`go.mod`: A new Go module matching our project, with basic dependencies

go 1.19

require ( v1.16.5 v1.18.1 v1.2.0 v0.24.0 v0.24.0 v0.24.0 v0.12.1

require ( v0.81.0 // indirect v14.2.0+incompatible // indirect v0.11.18 // indirect v0.9.13 // indirect v0.3.0 // indirect v0.2.1 // indirect v0.6.0 // indirect v1.1.1 // indirect v0.0.0-20170810143723-de5bf2ad4578 // indirect v1.0.1 // indirect v2.1.2 // indirect v1.1.1 // indirect v2.9.5+incompatible // indirect v4.12.0+incompatible // indirect v3.2.3+incompatible // indirect v1.5.1 // indirect v1.2.0 // indirect v1.2.0 // indirect v0.19.5 // indirect v0.19.5 // indirect v0.19.14 // indirect v1.3.2 // indirect v0.0.0-20210331224755-41bb18bfe9da // indirect v1.5.2 // indirect v0.5.7-v3refs // indirect v0.5.5 // indirect v1.1.0 // indirect v1.1.2 // indirect v0.3.12 // indirect v1.0.0 // indirect v1.1.12 // indirect v0.7.6 // indirect v1.0.2-0.20181231171920-c182affec369 // indirect v0.0.0-20180306012644-bacd9c7ef1dd // indirect v1.0.2 // indirect v0.0.0-20191010083416-a7dc8b61c822 // indirect v1.4.8 // indirect v0.9.1 // indirect v1.12.1 // indirect v0.2.0 // indirect v0.32.1 // indirect v0.7.3 // indirect v1.0.5 // indirect v1.7.0 // indirect v1.6.0 // indirect v1.19.1 // indirect v0.0.0-20220214200702-86341886e292 // indirect v0.0.0-20220127200216-cd36cc0744dd // indirect v0.0.0-20211104180415-d3ed0bb246c8 // indirect v0.0.0-20220209214540-3681064d5158 // indirect v0.0.0-20210927222741-03fcf44c2211 // indirect v0.3.7 // indirect v0.0.0-20220210224613-90d013bbcef8 // indirect v2.2.0 // indirect v1.6.7 // indirect v1.27.1 // indirect v0.9.1 // indirect v1.0.0-20141024135613-dd632973f1e7 // indirect v2.4.0 // indirect v3.0.0-20210107192922-496545a6307b // indirect v0.24.0 // indirect v0.24.0 // indirect v2.60.1 // indirect v0.0.0-20220328201542-3ee0da9b0b42 // indirect v0.0.0-20220210201930-3a6ce19ff2f9 // indirect v0.0.0-20211208200746-9f7c6b3444d2 // indirect v4.2.1 // indirect v1.3.0 // indirect
`Makefile`: Make targets for building and deploying your controller

# Image URL to use all building/pushing image targets
IMG ?= controller:latest
# ENVTEST_K8S_VERSION refers to the version of kubebuilder assets to be downloaded by envtest binary.

# Get the currently used golang install path (in GOPATH/bin, unless GOBIN is set)
ifeq (,$(shell go env GOBIN))
GOBIN=$(shell go env GOPATH)/bin
GOBIN=$(shell go env GOBIN)

# Setting SHELL to bash allows bash commands to be executed by recipes.
# Options are set to exit when a recipe line exits non-zero or a piped command fails.
SHELL = /usr/bin/env bash -o pipefail

.PHONY: all
all: build

##@ General

# The help target prints out all targets with their descriptions organized
# beneath their categories. The categories are represented by '##@' and the
# target descriptions by '##'. The awk commands is responsible for reading the
# entire set of makefiles included in this invocation, looking for lines of the
# file as xyz: ## something, and then pretty-format the target and help. Then,
# if there's a line with ##@ something, that gets pretty-printed as a category.
# More info on the usage of ANSI control characters for terminal formatting:
# More info on the awk command:

.PHONY: help
help: ## Display this help.
	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)

##@ Development

.PHONY: manifests
manifests: controller-gen ## Generate WebhookConfiguration, ClusterRole and CustomResourceDefinition objects.
	$(CONTROLLER_GEN) rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases

.PHONY: generate
generate: controller-gen ## Generate code containing DeepCopy, DeepCopyInto, and DeepCopyObject method implementations.
	$(CONTROLLER_GEN) object:headerFile="hack/boilerplate.go.txt" paths="./..."

.PHONY: fmt
fmt: ## Run go fmt against code.
	go fmt ./...

.PHONY: vet
vet: ## Run go vet against code.
	go vet ./...

.PHONY: test
test: manifests generate fmt vet envtest ## Run tests.
	KUBEBUILDER_ASSETS="$(shell $(ENVTEST) use $(ENVTEST_K8S_VERSION) -p path)" go test ./... -coverprofile cover.out

##@ Build

.PHONY: build
build: generate fmt vet ## Build manager binary.
	go build -o bin/manager main.go

.PHONY: run
run: manifests generate fmt vet ## Run a controller from your host.
	go run ./main.go

.PHONY: docker-build
docker-build: test ## Build docker image with the manager.
	docker build -t ${IMG} .

.PHONY: docker-push
docker-push: ## Push docker image with the manager.
	docker push ${IMG}

##@ Deployment

ifndef ignore-not-found
  ignore-not-found = false

.PHONY: install
install: manifests kustomize ## Install CRDs into the K8s cluster specified in ~/.kube/config.
	$(KUSTOMIZE) build config/crd | kubectl apply -f -

.PHONY: uninstall
uninstall: manifests kustomize ## Uninstall CRDs from the K8s cluster specified in ~/.kube/config. Call with ignore-not-found=true to ignore resource not found errors during deletion.
	$(KUSTOMIZE) build config/crd | kubectl delete --ignore-not-found=$(ignore-not-found) -f -

.PHONY: deploy
deploy: manifests kustomize ## Deploy controller to the K8s cluster specified in ~/.kube/config.
	cd config/manager && $(KUSTOMIZE) edit set image controller=${IMG}
	$(KUSTOMIZE) build config/default | kubectl apply -f -

.PHONY: undeploy
undeploy: ## Undeploy controller from the K8s cluster specified in ~/.kube/config. Call with ignore-not-found=true to ignore resource not found errors during deletion.
	$(KUSTOMIZE) build config/default | kubectl delete --ignore-not-found=$(ignore-not-found) -f -

##@ Build Dependencies

## Location to install dependencies to
LOCALBIN ?= $(shell pwd)/bin
	mkdir -p $(LOCALBIN)

## Tool Binaries
KUSTOMIZE ?= $(LOCALBIN)/kustomize
CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen
ENVTEST ?= $(LOCALBIN)/setup-envtest

## Tool Versions

.PHONY: kustomize
kustomize: $(KUSTOMIZE) ## Download kustomize locally if necessary.
	test -s $(LOCALBIN)/kustomize || { curl -Ss $(KUSTOMIZE_INSTALL_SCRIPT) | bash -s -- $(subst v,,$(KUSTOMIZE_VERSION)) $(LOCALBIN); }

.PHONY: controller-gen
controller-gen: $(CONTROLLER_GEN) ## Download controller-gen locally if necessary.
	test -s $(LOCALBIN)/controller-gen || GOBIN=$(LOCALBIN) go install$(CONTROLLER_TOOLS_VERSION)

.PHONY: envtest
envtest: $(ENVTEST) ## Download envtest-setup locally if necessary.
	test -s $(LOCALBIN)/setup-envtest || GOBIN=$(LOCALBIN) go install
`PROJECT`: Kubebuilder metadata for scaffolding new components
projectName: project
- api:
    crdVersion: v1
    namespaced: true
  controller: true
  group: batch
  kind: CronJob
  version: v1
    defaulting: true
    validation: true
    webhookVersion: v1
version: "3"

Launch Configuration

We also get launch configurations under the config/ directory. Right now, it just contains Kustomize YAML definitions required to launch our controller on a cluster, but once we get started writing our controller, it’ll also hold our CustomResourceDefinitions, RBAC configuration, and WebhookConfigurations.

config/default contains a Kustomize base for launching the controller in a standard configuration.

Each other directory contains a different piece of configuration, refactored out into its own base:

  • config/manager: launch your controllers as pods in the cluster

  • config/rbac: permissions required to run your controllers under their own service account

The Entrypoint

Last, but certainly not least, Kubebuilder scaffolds out the basic entrypoint of our project: main.go. Let’s take a look at that next...