Merge pull request #155 from BlaineEXE/dev-deployment

 update makefile help and docs for local development

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]