docs cleanup (#1004)

Author: AndrewChubatiuk

.DS_Store

@@ -45,7 +45,7 @@ jobs:
 
       - name: Generate vars and api doc
         run: |
-          make doc
+          make docs
         working-directory: "__vm-operator-repo"
 
       - name: Update operator docs in VM repo
@@ -63,7 +63,7 @@ jobs:
             \cp -f $png ../__vm-docs-repo/$newpng
           done
           # Autogenerated files
-          cat ./vars.md > ../__vm-docs-repo/docs/operator/vars.md
+          cat ./docs/vars.md > ../__vm-docs-repo/docs/operator/vars.md
           cat ./docs/api.md > ../__vm-docs-repo/docs/operator/api.md
         working-directory: "__vm-operator-repo"
 

.github/workflows/docs.yaml

@@ -8,6 +8,11 @@ on:
   pull_request:
     branches:
       - master
+    types:
+      - opened
+      - reopened
+      - ready_for_review
+      - converted_to_draft
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
@@ -23,7 +28,6 @@ jobs:
         with:
           go-version: "1.22"
         id: go
-
       - name: Run Trivy vulnerability scanner in repo mode
         uses: aquasecurity/trivy-action@master
         with:
@@ -38,18 +42,21 @@ jobs:
         uses: github/codeql-action/upload-sarif@v2
         with:
           sarif_file: "trivy-results.sarif"
-
+      - name: Set output variables
+        id: vars
+        run: |
+          IMAGE_TAG=${GITHUB_SHA:0:7}
+          echo "IMAGE_TAG=$IMAGE_TAG" >> $GITHUB_OUTPUT
       - name: lint and test
+        if: github.event.pull_request.draft == false
         env:
           GO111MODULE: on
+          DOCKER_BUILD_ARGS: --cache-from=type=gha --cache-to=type=gha,mode=max
+          TAG: ${{ steps.vars.outputs.IMAGE_TAG }}
         run: |
           make lint
           make test
-      - name: Set output variables
-        id: vars
-        run: |
-          IMAGE_TAG=${GITHUB_SHA:0:7}
-          echo "IMAGE_TAG=$IMAGE_TAG" >> $GITHUB_OUTPUT
+          TAG=${TAG} make test-e2e
       - name: build binary
         env:
           GO111MODULE: on

.github/workflows/main.yaml

@@ -22,15 +22,12 @@ jobs:
           make lint
           make test
           make build
-          make test-e2e
-
       - name: build crosscompile and push to remote registry
         env:
           TAG: "${{ github.event.release.tag_name }}"
         run: |
           echo ${{secrets.REPO_KEY}} | docker login --username ${{secrets.REPO_USER}} --password-stdin
           make publish
-
       - name: Upload Release CRDs
         id: upload-release-crds
         uses: actions/upload-release-asset@v1

.github/workflows/release.yaml

@@ -1,4 +1,5 @@
 # Temporary Build Files
+.DS_Store
 Dockerfile.cross
 .idea
 bin/

.gitignore

@@ -2,27 +2,24 @@
 ## Required programs
 
 for developing you need:
-- golang 1.15+
-- operator-sdk v1.33.0
+- kubebuilder v4
+- golang 1.22+
 - docker
-- minikube or kind for e2e tests
-- golangci-lint
-
+- kubectl
 
 ## installing local env
 
-- make install-develop-tools
-- kind create cluster
+```bash
+# make install-tools
+```
 
 ## local build and run
 
 Use `make build` - it will generate new crds and build binary
 
-
-for running locally you need minikube and run two commands:
+for running locally on kind you need to run:
 ```bash
-make install
-make run
+make deploy-kind
 ```
 or you can run it from IDE with ```main.go```
 
@@ -33,40 +30,21 @@ before creating merge request, ensure that tests passed locally:
 make build # it will update crds
 make lint # linting project
 make test #unit tests
-make e2e-local #e2e tests with minikube
+make test-e2e #e2e tests with minikube
 ```
 
 ## adding new api
 
-For adding new kind - KIND_NAME, you have to execute command:
+For adding new kind - `KIND_NAME`, you have to execute command:
 
 ```bash
-operator-sdk create api --group operator --version v1beta1 --kind KIND_NAME
+kubebuilder create api --group operator --version v1beta1 --kind KIND_NAME
 ```
 
-This will scaffold api and controller. Then you have to edit code at `api` and `controllers` folder.
-
-## create olm package
+For adding new webhook for a `KIND_NAME`, you have to execute command:
 
-Choose version (release tag at github) and generate or update corresponding csv file
 ```bash
-TAG=v0.36.0 make bundle
-```
-
-it will generate files at directories: `bundle/`
-
-### publish to operator-hub
-
-checkout to the latest release:
-1) `git checkout tags/v0.36.0`
-2) build package manifest: `TAG=v0.36.0 make bundle`
-3) add replacement for a previous version to generated cluster csv:
-`vi bundle/manifests/victoriametrics-operator.clusterserviceversion`
-```yaml
-spec:
-  replaces: victoriametrics-operator.v0.35.0
+kubebuilder create webhook --group operator --version v1beta1 --kind KIND_NAME --conversion --programmatic-validation
 ```
-Now you have to fork two repos and create pull requests to them with new version `/bundle`:
-1) https://github.com/k8s-operatorhub/community-operators for OperatorHub.io
-2) https://github.com/redhat-openshift-ecosystem/community-operators-prod for Embedded OperatorHub in OpenShift and OKD.
 
+This will scaffold api and controller. Then you have to edit code at `api/operator/v1beta1` and `internal/controller/operator` folder.

CONTRIBUTING.md

@@ -8,10 +8,6 @@ BUILDINFO_TAG ?= $(shell echo $$(git describe --long --all | tr '/' '-')$$( \
 	git diff-index --quiet HEAD -- || echo '-dirty-'$$(git diff-index -u HEAD | openssl sha1 | cut -d' ' -f2 | cut -c 1-8)))
 OVERLAY ?= config/default
 
-COMMA = ,
-EMPTY =
-SPACE = $(EMPTY) $(EMPTY)
-
 # ENVTEST_K8S_VERSION refers to the version of kubebuilder assets to be downloaded by envtest binary.
 ENVTEST_K8S_VERSION = 1.30.0
 
@@ -89,12 +85,14 @@ api-gen: client-gen lister-gen informer-gen
 		--go-header-file hack/boilerplate.go.txt
 	rm api/go.*
 
-.PHONY: doc
-doc: envconfig-docs doc-print
-	cat hack/doc/header.md > docs/api.md
-	$(DOC_PRINT) --paths=$(subst $(SPACE),$(COMMA),$(wildcard ./api/operator/v1beta1/*_types.go)) --owner VictoriaMetrics >> docs/api.md
-	cat hack/doc/vars.md > vars.md
-	$(ENVCONFIG_DOCS) --input internal/config/config.go --truncate=false >> vars.md
+.PHONY: docs
+docs: envconfig-docs crd-ref-docs manifests
+	$(CRD_REF_DOCS) --config ./docs/config.yaml \
+		--templates-dir ./docs/templates/api \
+		--renderer markdown
+	mv out.md docs/api.md
+	cat docs/headers/vars.md > docs/vars.md
+	$(ENVCONFIG_DOCS) --input internal/config/config.go --truncate=false >> docs/vars.md
 
 .PHONY: fmt
 fmt: ## Run go fmt against code.
@@ -124,7 +122,7 @@ lint-fix: golangci-lint ## Run golangci-lint linter and perform fixes
 ##@ Build
 
 .PHONY: build
-build: manifests generate fmt vet ## Build manager binary.
+build: docs generate fmt vet ## Build manager binary.
 	go build -o bin/$(REPO) ./cmd/$(REPO)/...
 
 .PHONY: run
@@ -138,6 +136,7 @@ run: manifests generate fmt vet ## Run a controller from your host.
 docker-build: ## Build docker image with the manager.
 	$(CONTAINER_TOOL) build \
 		--build-arg REPO=$(REPO) \
+		${DOCKER_BUILD_ARGS} \
 		-t $(REGISTRY)/$(ORG)/$(REPO):$(TAG) \
 		-t $(REGISTRY)/$(ORG)/$(REPO):$(BUILDINFO_TAG) .
 
@@ -165,6 +164,7 @@ docker-buildx: ## Build and push docker image for the manager for cross-platform
 		--push \
 		--platform=$(PLATFORMS) \
 		--build-arg REPO=$(REPO) \
+		$(DOCKER_BUILD_ARGS) \
 		--tag $(REGISTRY)/$(ORG)/$(REPO):$(TAG) \
 		--tag $(REGISTRY)/$(ORG)/$(REPO):$(BUILDINFO_TAG) \
 		-f Dockerfile.cross .
@@ -238,7 +238,7 @@ LISTER_GEN = $(LOCALBIN)/lister-gen-$(CODEGENERATOR_VERSION)
 INFORMER_GEN = $(LOCALBIN)/informer-gen-$(CODEGENERATOR_VERSION)
 KIND = $(LOCALBIN)/kind-$(KIND_VERSION)
 ENVCONFIG_DOCS = $(LOCALBIN)/envconfig-docs-$(ENVCONFIG_DOCS_VERSION)
-DOC_PRINT = $(LOCALBIN)/doc-print-$(DOC_PRINT_VERSION)
+CRD_REF_DOCS = $(LOCALBIN)/crd-ref-docs-$(CRD_REF_DOCS_VERSION)
 
 ## Tool Versions
 KUSTOMIZE_VERSION ?= v5.4.1
@@ -248,7 +248,7 @@ GOLANGCI_LINT_VERSION ?= v1.59.1
 CODEGENERATOR_VERSION ?= v0.30.2
 KIND_VERSION ?= v0.23.0
 ENVCONFIG_DOCS_VERSION ?= latest
-DOC_PRINT_VERSION ?= latest
+CRD_REF_DOCS_VERSION ?= latest
 
 .PHONY: kustomize
 kustomize: $(KUSTOMIZE) ## Download kustomize locally if necessary.
@@ -261,17 +261,17 @@ $(CONTROLLER_GEN): $(LOCALBIN)
 	$(call go-install-tool,$(CONTROLLER_GEN),sigs.k8s.io/controller-tools/cmd/controller-gen,$(CONTROLLER_TOOLS_VERSION))
 
 .PHONY: install-tools
-install-tools: envconfig-docs doc-print client-gen lister-gen informer-gen controller-gen kustomize envtest
+install-tools: envconfig-docs crd-ref-docs client-gen lister-gen informer-gen controller-gen kustomize envtest
 
 .PHONY: envconfig-docs
 envconfig-docs: $(ENVCONFIG_DOCS)
 $(ENVCONFIG_DOCS): $(LOCALBIN)
 	$(call go-install-tool,$(ENVCONFIG_DOCS),github.com/f41gh7/envconfig-docs,$(ENVCONFIG_DOCS_VERSION))
 
-.PHONY: doc-print
-doc-print: $(DOC_PRINT)
-$(DOC_PRINT): $(LOCALBIN)
-	$(call go-install-tool,$(DOC_PRINT),github.com/f41gh7/doc-print,$(DOC_PRINT_VERSION))
+.PHONY: crd-ref-docs
+crd-ref-docs: $(CRD_REF_DOCS)
+$(CRD_REF_DOCS): $(LOCALBIN)
+	$(call go-install-tool,$(CRD_REF_DOCS),github.com/elastic/crd-ref-docs,$(CRD_REF_DOCS_VERSION))
 
 .PHONY: client-gen
 client-gen: $(CLIENT_GEN)

Makefile

@@ -61,17 +61,7 @@ VictoriaMetrics provides [helm charts](https://github.com/VictoriaMetrics/helm-c
 
 ## Kubernetes' compatibility versions
 
-operator tested at kubernetes versions
-from 1.25 to 1.29
-
-## Troubleshooting
-
-- cannot apply crd at kubernetes 1.18 + version and kubectl reports error:
-```bash
-Error from server (Invalid): error when creating "release/crds/crd.yaml": CustomResourceDefinition.apiextensions.k8s.io "vmalertmanagers.operator.victoriametrics.com" is invalid: [spec.validation.openAPIV3Schema.properties[spec].properties[initContainers].items.properties[ports].items.properties[protocol].default: Required value: this property is in x-kubernetes-list-map-keys, so it must have a default or be a required property, spec.validation.openAPIV3Schema.properties[spec].properties[containers].items.properties[ports].items.properties[protocol].default: Required value: this property is in x-kubernetes-list-map-keys, so it must have a default or be a required property]
-Error from server (Invalid): error when creating "release/crds/crd.yaml": CustomResourceDefinition.apiextensions.k8s.io "vmalerts.operator.victoriametrics.com" is invalid: [
-```
-  upgrade to the latest release version. There is a bug with kubernetes objects at the early releases.
+operator tested on officially supported Kubernetes versions
 
 ## Community and contributions
 
@@ -86,22 +76,23 @@ Feel free asking any questions regarding VictoriaMetrics:
 
 ## Development
 
-- operator-sdk verson v1.0.0 +  [https://github.com/operator-framework/operator-sdk]
-- golang 1.15 +
-- minikube or kind
+Dependencies:
+- kubebuilder v4
+- golang 1.22+
+- kubectl
+- docker
 
 start:
 ```bash
 make run
 ```
 
-for test execution run:
+### to run unit tests
 ```bash
-#unit tests
-
 make test
+```
 
-# you need minikube or kind for e2e, do not run it on live cluster
-#e2e tests with local binary
-make e2e-local
+### to run e2e tests on automatically configured Kind cluster
+```bash
+# make test-e2e
 ```

README.md

@@ -64,7 +64,6 @@ type VMAgentSpec struct {
 	// eventually make the size of the running cluster equal to the expected
 	// size.
 	// NOTE enable VMSingle deduplication for replica usage
-	// +operator-sdk:csv:customresourcedefinitions:type=spec,displayName="Number of pods",xDescriptors="urn:alm:descriptor:com.tectonic.ui:podCount,urn:alm:descriptor:io.kubernetes:custom"
 	// +optional
 	ReplicaCount *int32 `json:"replicaCount,omitempty"`
 	// The number of old ReplicaSets to retain to allow rollback in deployment or
@@ -84,7 +83,6 @@ type VMAgentSpec struct {
 	VolumeMounts []v1.VolumeMount `json:"volumeMounts,omitempty"`
 	// Resources container resource request and limits, https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
 	// if not specified - default setting will be used
-	// +operator-sdk:csv:customresourcedefinitions:type=spec,displayName="Resources",xDescriptors="urn:alm:descriptor:com.tectonic.ui:resourceRequirements"
 	// +optional
 	Resources v1.ResourceRequirements `json:"resources,omitempty"`
 	// Affinity If specified, the pod's scheduling constraints.
@@ -100,7 +98,6 @@ type VMAgentSpec struct {
 	// ServiceAccountName is the name of the ServiceAccount to use to run the
 	// VMAgent Pods.
 	// +optional
-	// +operator-sdk:csv:customresourcedefinitions:type=spec,displayName="ServiceAccount name",xDescriptors="urn:alm:descriptor:io.kubernetes:ServiceAccount"
 	ServiceAccountName string `json:"serviceAccountName,omitempty"`
 	// SchedulerName - defines kubernetes scheduler name
 	// +optional
@@ -186,15 +183,13 @@ type VMAgentSpec struct {
 	// for vm it must looks like: http://victoria-metrics-single:8429/api/v1/write
 	// or for cluster different url
 	// https://github.com/VictoriaMetrics/VictoriaMetrics/tree/master/app/vmagent#splitting-data-streams-among-multiple-systems
-	// +optional
 	RemoteWrite []VMAgentRemoteWriteSpec `json:"remoteWrite"`
 	// RemoteWriteSettings defines global settings for all remoteWrite urls.
-	// + optional
+	// +optional
 	RemoteWriteSettings *VMAgentRemoteWriteSettings `json:"remoteWriteSettings,omitempty"`
 	// RelabelConfig ConfigMap with global relabel config -remoteWrite.relabelConfig
 	// This relabeling is applied to all the collected metrics before sending them to remote storage.
 	// +optional
-	// +operator-sdk:csv:customresourcedefinitions:type=spec,displayName="Key at Configmap with relabelConfig name",xDescriptors="urn:alm:descriptor:io.kubernetes:ConfigMapKeySelector"
 	RelabelConfig *v1.ConfigMapKeySelector `json:"relabelConfig,omitempty"`
 	// InlineRelabelConfig - defines GlobalRelabelConfig for vmagent, can be defined directly at CRD.
 	// +optional
@@ -493,7 +488,6 @@ type VMAgentRemoteWriteSpec struct {
 
 	// ConfigMap with relabeling config which is applied to metrics before sending them to the corresponding -remoteWrite.url
 	// +optional
-	// +operator-sdk:csv:customresourcedefinitions:type=spec,displayName="Key at Configmap with relabelConfig for remoteWrite",xDescriptors="urn:alm:descriptor:io.kubernetes:ConfigMapKeySelector"
 	UrlRelabelConfig *v1.ConfigMapKeySelector `json:"urlRelabelConfig,omitempty"`
 	// InlineUrlRelabelConfig defines relabeling config for remoteWriteURL, it can be defined at crd spec.
 	// +optional
@@ -567,13 +561,10 @@ type VMAgentStatus struct {
 
 // VMAgent - is a tiny but brave agent, which helps you collect metrics from various sources and stores them in VictoriaMetrics
 // or any other Prometheus-compatible storage system that supports the remote_write protocol.
-// +operator-sdk:gen-csv:customresourcedefinitions.displayName="VMAgent App"
-// +operator-sdk:gen-csv:customresourcedefinitions.resources="Deployment,apps"
-// +operator-sdk:gen-csv:customresourcedefinitions.resources="Service,v1"
-// +operator-sdk:gen-csv:customresourcedefinitions.resources="Secret,v1"
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 // +genclient
 // +k8s:openapi-gen=true
+// +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
 // +kubebuilder:resource:path=vmagents,scope=Namespaced
 // +kubebuilder:subresource:scale:specpath=.spec.shardCount,statuspath=.status.shards,selectorpath=.status.selector