update makefile help and docs for local development

Rearrange make targets to separate basic from advanced targets. Add some
more developer documentation to help new contributors.

Modify 'make deploy' for easier local development. Modify Kustomize
resource definitions to make it easier to create a local-specific
kustomize.yaml file for an individual development environment.
Add a script to help deploy a locally-built COSI controller without risk
of accidentally committing changes to git.

Add local controller dev workflow to developer doc.

Signed-off-by: Blaine Gardner <[email protected]>

Author: BlaineEXE

Makefile

@@ -17,8 +17,8 @@
 SHELL = /usr/bin/env bash
 
 .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)
+help: ## Display this help
+	@awk 'BEGIN {FS = " *:.*## *"; printf "\nUsage:\n  make \033[36m<target>\033[0m [\033[32mVAR\033[0m=val]\n"} /^##.*:##/ { gsub(/^## /,"",$$1) ; printf "  \033[32m%s\033[0m (\"%s\")\n    └ %s\n", $$1, ENVIRON[$$1], $$2} /^[.a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-18s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
 
 # If GOARCH is not set in the env, find it
 GOARCH ?= $(shell go env GOARCH)
@@ -27,66 +27,33 @@ GOARCH ?= $(shell go env GOARCH)
 # ==== ARGS =====
 #
 
-# Container build tool compatible with `docker` API
+##@ Environment args
+
+## DOCKER :## Container build tool compatible with `docker` API
 DOCKER ?= docker
 
-# Tool compatible with `kubectl` API
+## KUBECTL :## Tool compatible with `kubectl` API
 KUBECTL ?= kubectl
 
-# Platform for 'build'
+## PLATFORM :## Platform for builds
 PLATFORM ?= linux/$(GOARCH)
 
-# Additional args for 'build'
+## BUILD_ARGS :## Additional args for builds
 BUILD_ARGS ?=
 
-# Image tag for controller image build
+## CONTROLLER_TAG :## Image tag for controller image build and deploy
 CONTROLLER_TAG ?= cosi-controller:latest
 
-# Image tag for sidecar image build
+## SIDECAR_TAG :## Image tag for sidecar image build
 SIDECAR_TAG ?= cosi-provisioner-sidecar:latest
 
-##@ Development
-
-.PHONY: generate
-generate: crds controller/Dockerfile sidecar/Dockerfile ## Generate files
-
-.PHONY: crds
-crds: controller-gen
-	cd ./client && $(CONTROLLER_GEN) rbac:roleName=manager-role crd paths="./apis/objectstorage/..."
-
-%/Dockerfile: hack/Dockerfile.in hack/gen-dockerfile.sh
-	hack/gen-dockerfile.sh $* > "$@"
-
-.PHONY: codegen
-codegen: codegen.client codegen.proto  ## Generate code
-
-.PHONY: codegen.client codegen.proto
-codegen.client: controller-gen
-	cd ./client && $(CONTROLLER_GEN) object:headerFile="hack/boilerplate.go.txt" paths="./apis/objectstorage/..."
-codegen.proto:
-	$(MAKE) -C proto codegen
-
-.PHONY: fmt
-fmt: fmt.client fmt.controller fmt.sidecar ## Format code
-fmt.%: FORCE
-	cd $* && go fmt ./...
-
-.PHONY: vet
-vet: vet.client vet.controller vet.sidecar ## Vet code
-vet.%: FORCE
-	cd $* && go vet ./...
+export
 
-.PHONY: test
-test: .test.proto test.client test.controller test.sidecar ## Run all unit tests including vet and fmt
-test.%: fmt.% vet.% FORCE
-	cd $* && go test ./...
-.PHONY: .test.proto
-.test.proto: # gRPC proto has a special unit test
-	$(MAKE) -C proto check
+##@ Core (Basic)
 
-.PHONY: test-e2e
-test-e2e: chainsaw # Run e2e tests against the K8s cluster specified in ~/.kube/config. It requires both controller and driver deployed. If you need to create a cluster beforehand, consider using 'cluster' and 'deploy' targets.
-	$(CHAINSAW) test --values ./test/e2e/values.yaml
+.PHONY: all
+.NOTPARALLEL: all # all generators must run before build
+all: prebuild build ## Build all container images, plus their prerequisites (faster with 'make -j')
 
 .PHONY: lint
 lint: golangci-lint.client golangci-lint.controller golangci-lint.sidecar spell-lint dockerfiles-lint ## Run all linters (suggest `make -k`)
@@ -102,22 +69,29 @@ lint-fix: golangci-lint-fix.client golangci-lint-fix.controller golangci-lint-fi
 golangci-lint-fix.%: golangci-lint
 	cd $* && $(GOLANGCI_LINT) run $(GOLANGCI_LINT_RUN_OPTS) --config $(CURDIR)/.golangci.yaml --new --fix
 
-.PHONY: vendor
-vendor: tidy.client tidy.proto ## Update go vendor dir
-	go mod tidy
-	go mod vendor
-tidy.%: FORCE
-	cd $* && go mod tidy
+.PHONY: test
+test: .test.proto test.client test.controller test.sidecar ## Run all unit tests including vet and fmt
+test.%: fmt.% vet.% FORCE
+	cd $* && go test ./...
+.PHONY: .test.proto
+.test.proto: # gRPC proto has a special unit test
+	$(MAKE) -C proto check
+
+.PHONY: clean
+clean: ## Clean build environment
+	$(MAKE) -C proto clean
 
-##@ Build
+.PHONY: clobber
+clobber: ## Clean build environment and cached tools
+	$(MAKE) -C proto clobber
+	rm -rf $(TOOLBIN)
+	rm -rf $(CURDIR)/.cache
 
-.PHONY: all
-.NOTPARALLEL: all # all generators must run before build
-all: prebuild build ## Build all container images, plus their prerequisites (faster with 'make -j')
+##@ Development (Advanced)
 
 .PHONY: prebuild .gen .doc-vendor
 .gen: generate codegen # can be done in parallel with 'make -j'
-.doc-vendor: build-docs vendor # can be done in parallel
+.doc-vendor: docs vendor # can be done in parallel
 .NOTPARALLEL: prebuild # codegen must be finished before fmt
 prebuild: .gen fmt .doc-vendor ## Run all pre-build prerequisite steps (faster with 'make -j')
 
@@ -130,8 +104,37 @@ build.controller: controller/Dockerfile ## Build only the controller container i
 build.sidecar: sidecar/Dockerfile ## Build only the sidecar container image
 	$(DOCKER) build --file sidecar/Dockerfile --platform $(PLATFORM) $(BUILD_ARGS) --tag $(SIDECAR_TAG) .
 
-.PHONY: build-docs
-build-docs: generate crd-ref-docs mdbook
+.PHONY: generate
+generate: crds controller/Dockerfile sidecar/Dockerfile ## Generate files
+
+.PHONY: crds
+crds: controller-gen
+	cd ./client && $(CONTROLLER_GEN) rbac:roleName=manager-role crd paths="./apis/objectstorage/..."
+
+%/Dockerfile: hack/Dockerfile.in hack/gen-dockerfile.sh
+	hack/gen-dockerfile.sh $* > "$@"
+
+.PHONY: codegen
+codegen: codegen.client codegen.proto ## Generate code
+
+.PHONY: codegen.client codegen.proto
+codegen.client: controller-gen
+	cd ./client && $(CONTROLLER_GEN) object:headerFile="hack/boilerplate.go.txt" paths="./apis/objectstorage/..."
+codegen.proto:
+	$(MAKE) -C proto codegen
+
+.PHONY: fmt
+fmt: fmt.client fmt.controller fmt.sidecar
+fmt.%: FORCE
+	cd $* && go fmt ./...
+
+.PHONY: vet
+vet: vet.client vet.controller vet.sidecar
+vet.%: FORCE
+	cd $* && go vet ./...
+
+.PHONY: docs
+docs: generate crd-ref-docs mdbook ## Build docs
 	$(CRD_REF_DOCS) \
 		--config=./docs/.crd-ref-docs.yaml \
 		--source-path=./client/apis \
@@ -141,21 +144,21 @@ build-docs: generate crd-ref-docs mdbook
 
 MDBOOK_PORT ?= 3000
 
-.PHONY: serve-docs
-serve-docs: generate mdbook build-docs
+.PHONY: docs.serve
+docs.serve: generate mdbook docs ## Serve locally built docs
 	cd docs; $(MDBOOK) serve --port $(MDBOOK_PORT)
 
-.PHONY: clean
-clean: ## Clean build environment
-	$(MAKE) -C proto clean
+.PHONY: vendor
+vendor: tidy.client tidy.proto ## Update go vendor dir
+	go mod tidy
+	go mod vendor
+tidy.%: FORCE
+	cd $* && go mod tidy
 
-.PHONY: clobber
-clobber: ## Clean build environment and cached tools
-	$(MAKE) -C proto clobber
-	rm -rf $(TOOLBIN)
-	rm -rf $(CURDIR)/.cache
+.PHONY: test-e2e
+test-e2e: chainsaw ## Run e2e tests against the local K8s cluster (requires both controller and driver deployed)
 
-##@ Deployment
+##@ Deployment (Advanced)
 
 .PHONY: cluster
 cluster: kind ctlptl ## Create Kind cluster and local registry
@@ -166,12 +169,12 @@ cluster-reset: kind ctlptl ## Delete Kind cluster
 	PATH=$(TOOLBIN):$(PATH) $(CTLPTL) delete -f ctlptl.yaml
 
 .PHONY: deploy
-deploy: kustomize ## Deploy controller to the K8s cluster specified in ~/.kube/config
-	$(KUSTOMIZE) build . | $(KUBECTL) apply -f -
+deploy: kustomize ## Deploy controller (CONTROLLER_TAG) to the local K8s cluster
+	./hack/dev-kustomize.sh && $(KUSTOMIZE) build $(CURDIR)/.cache | $(KUBECTL) apply -f -
 
 .PHONY: undeploy
-undeploy: kustomize ## Undeploy controller from the K8s cluster specified in ~/.kube/config
-	$(KUSTOMIZE) build . | $(KUBECTL) delete --ignore-not-found=true -f -
+undeploy: kustomize ## Undeploy controller (CONTROLLER_TAG) from the local K8s cluster
+	./hack/dev-kustomize.sh && $(KUSTOMIZE) build $(CURDIR)/.cache | $(KUBECTL) delete --ignore-not-found=true -f -
 
 #
 # ===== Tools =====

README.md

@@ -35,16 +35,12 @@ Participation in the Kubernetes community is governed by the [Kubernetes Code of
 
 ## Developer Guide
 
-Before contributing a Pull Request, ensure a [GitHub
-issue](https://github.com/kubernetes-sigs/container-object-storage-interface/issues) exists corresponding to the change.
-
 All API definitions and behavior must follow the [`v1alpha2` KEP PR](https://github.com/kubernetes/enhancements/pull/4599).
 Minor deviation from the KEP is acceptable in order to fix bugs.
 
 `v1alpha2` is currently pre-release.
 Changes may break compatibility up until `v1alpha2` is released with a semver tag.
 After the first `v1alpha2` semver release (e.g., 0.3.0), all changes must be backwards compatible.
 
-### Build and Test
-
-See `make help` for assistance
+Before making a COSI contribution, please read and follow the
+[core developer guide](https://container-object-storage-interface.sigs.k8s.io/developing/core.html).

client/config/crd/kustomization.yaml

@@ -0,0 +1,9 @@
+---
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - objectstorage.k8s.io_bucketaccessclasses.yaml
+  - objectstorage.k8s.io_bucketaccesses.yaml
+  - objectstorage.k8s.io_bucketclaims.yaml
+  - objectstorage.k8s.io_bucketclasses.yaml
+  - objectstorage.k8s.io_buckets.yaml

controller/resources/deployment.yaml

@@ -23,5 +23,4 @@ spec:
       containers:
         - name: objectstorage-controller
           image: gcr.io/k8s-staging-sig-storage/objectstorage-controller:v20251003-controllerv0.2.0-rc1-145-ge3bc25e
-          args:
-            - "--v=5"
+          args: []

docs/src/developing/core.md

@@ -4,4 +4,26 @@ With “core” COSI we refer to the common set of API and controllers that are
 
 Before your first contribution, you should follow [the Kubernetes Contributor Guide](https://www.kubernetes.dev/docs/guide/#contributor-guide).
 
-To further understand the COSI architecture, please refer to [KEP-1979: Object Storage Support](https://github.com/kubernetes/enhancements/tree/master/keps/sig-storage/1979-object-storage-support).
+To further understand the COSI architecture, please refer to [KEP-1979: Object Storage
+Support](https://github.com/kubernetes/enhancements/tree/master/keps/sig-storage/1979-object-storage-support).
+
+Before contributing a Pull Request, ensure a [GitHub issue](https://github.com/kubernetes-sigs/container-object-storage-interface/issues) exists corresponding to the change.
+
+## Local code development
+
+For new contributors, use `make help`, and use **Core** targets as needed.
+These targets ensure changes build successfully, pass basic checks, and are ready for end-to-end tests run in COSI's automated CI.
+
+Other more advanced targets are available and also described in `make help` output.
+
+Some specific workflows are documented below.
+
+### Building and deploying COSI controller changes locally
+
+```sh
+export CONTROLLER_TAG="$MY_REPO"/cosi-controller:latest # replace MY_REPO with desired dev repo
+make -j prebuild
+make build.controller
+docker push "$CONTROLLER_TAG"
+make deploy
+```

hack/dev-kustomize.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+set -o errexit
+set -o nounset
+set -o xtrace
+
+#
+# generate a kustomization file for local development use
+# use the Makefile's CONTROLLER_TAG as the image used for dev deployment
+#
+
+# store generated file(s) in cache dir not checked into git
+SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+ROOT="$SCRIPT_DIR"/..
+CACHE_DIR="$ROOT"/.cache
+mkdir -p "$CACHE_DIR"
+
+# copy root kustomization.yaml file to cache dir, and...
+# replace './' in root kustomization.yaml with '../' for usage from cache dir
+DEV_KUSTOMIZE_FILE="$CACHE_DIR"/kustomization.yaml
+sed -e 's|\./|../|g' "$ROOT"/kustomization.yaml > "$DEV_KUSTOMIZE_FILE"
+
+# process Makefile's CONTROLLER_TAG into name and tag components
+#   e.g., CONTROLLER_TAG="localhost:5000/cosi-controller:latest"
+NEW_NAME="${CONTROLLER_TAG%:*}" # e.g., "localhost:5000/cosi-controller"
+NEW_TAG="${CONTROLLER_TAG##*:}" # e.g., "latest"
+
+# replace the default controller image with one for local dev
+cat <<EOF >> "$DEV_KUSTOMIZE_FILE"
+
+images:
+  - name: gcr.io/k8s-staging-sig-storage/objectstorage-controller
+    newName: "$NEW_NAME"
+    newTag: "$NEW_TAG"
+EOF

kustomization.yaml

@@ -9,9 +9,6 @@ commonAnnotations:
   api-approved.kubernetes.io: https://github.com/kubernetes/enhancements/tree/master/keps/sig-storage/1979-object-storage-support
 
 resources:
-  - client/config/crd/objectstorage.k8s.io_bucketaccesses.yaml
-  - client/config/crd/objectstorage.k8s.io_bucketaccessclasses.yaml
-  - client/config/crd/objectstorage.k8s.io_bucketclasses.yaml
-  - client/config/crd/objectstorage.k8s.io_bucketclaims.yaml
-  - client/config/crd/objectstorage.k8s.io_buckets.yaml
-  - controller
+  # ensure all resources begin with './'
+  - ./client/config/crd
+  - ./controller

netlify.toml

@@ -1,6 +1,6 @@
 # Netlify build instructions
 [build]
-    command = "make build-docs"
+    command = "make docs"
     publish = "docs/book"
 
 [build.environment]