Merge branch 'main' into fix/olm-webhookdefinitions

Author: stubbi

.github/workflows/ci.yaml

@@ -27,3 +27,42 @@ jobs:
         env:
           ENVTEST_K8S_VERSION: ${{ matrix.k8s }}.0
         run: make test
+
+  docs-build:
+    name: Docs Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: docs-site/requirements.txt
+      - name: Install docs deps
+        run: pip install -r docs-site/requirements.txt
+      - name: Build docs site (strict)
+        run: mkdocs build --strict -f docs-site/mkdocs.yml
+      - name: Upload built site as artifact
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-preview-${{ github.event.pull_request.number }}
+          path: docs-site/site/
+          retention-days: 7
+
+  api-docs-sync:
+    name: API Docs Sync
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v6
+        with: { go-version: "1.26" }
+      - name: Regenerate api-reference-generated.md
+        run: make api-docs
+      - name: Verify no drift
+        run: |
+          if ! git diff --exit-code docs/api-reference-generated.md; then
+            echo "::error::docs/api-reference-generated.md is out of sync with the API types."
+            echo "::error::Run 'make api-docs' locally and commit the result."
+            exit 1
+          fi

.github/workflows/operatorhub-submit.yaml

@@ -32,12 +32,23 @@ jobs:
           VERSION="${{ steps.version.outputs.version }}"
           TAG="${{ steps.version.outputs.tag }}"
           BUNDLE_DIR="submission/operators/hermes-operator/${VERSION}"
+
+          # Resolve the published image to an immutable digest reference so the
+          # submitted bundle is pinned (OLM best practice). Fall back to the
+          # floating tag if the digest cannot be resolved (e.g. registry hiccup).
+          # The single sed below rewrites the deployment image and the operator
+          # relatedImage entry in the CSV to the same pinned reference.
+          IMG="ghcr.io/paperclipinc/hermes-operator"
+          DIGEST="$(docker buildx imagetools inspect "${IMG}:${TAG}" --format '{{ .Manifest.Digest }}' 2>/dev/null || true)"
+          if [ -n "${DIGEST}" ]; then IMG_REF="${IMG}@${DIGEST}"; else IMG_REF="${IMG}:${TAG}"; fi
+          echo "Pinning image to: ${IMG_REF}"
+
           mkdir -p "${BUNDLE_DIR}/manifests" "${BUNDLE_DIR}/metadata"
 
           # Copy and version the CSV.
           sed \
             -e "s/hermes-operator\.v[0-9]\+\.[0-9]\+\.[0-9]\+/hermes-operator.v${VERSION}/g" \
-            -e "s|ghcr.io/paperclipinc/hermes-operator:v[0-9]\+\.[0-9]\+\.[0-9]\+|ghcr.io/paperclipinc/hermes-operator:${TAG}|g" \
+            -e "s|ghcr.io/paperclipinc/hermes-operator:v[0-9]\+\.[0-9]\+\.[0-9]\+|${IMG_REF}|g" \
             -e "s/createdAt: .*/createdAt: \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"/" \
             -e "s/^  version: [0-9]\+\.[0-9]\+\.[0-9]\+/  version: ${VERSION}/" \
             bundle/manifests/hermes-operator.clusterserviceversion.yaml \
@@ -130,10 +141,21 @@ jobs:
           VERSION="${{ steps.version.outputs.version }}"
           TAG="${{ steps.version.outputs.tag }}"
           BUNDLE_DIR="submission/operators/hermes-operator/${VERSION}"
+
+          # Resolve the published image to an immutable digest reference so the
+          # submitted bundle is pinned (OLM best practice). Fall back to the
+          # floating tag if the digest cannot be resolved (e.g. registry hiccup).
+          # The single sed below rewrites the deployment image and the operator
+          # relatedImage entry in the CSV to the same pinned reference.
+          IMG="ghcr.io/paperclipinc/hermes-operator"
+          DIGEST="$(docker buildx imagetools inspect "${IMG}:${TAG}" --format '{{ .Manifest.Digest }}' 2>/dev/null || true)"
+          if [ -n "${DIGEST}" ]; then IMG_REF="${IMG}@${DIGEST}"; else IMG_REF="${IMG}:${TAG}"; fi
+          echo "Pinning image to: ${IMG_REF}"
+
           mkdir -p "${BUNDLE_DIR}/manifests" "${BUNDLE_DIR}/metadata"
           sed \
             -e "s/hermes-operator\.v[0-9]\+\.[0-9]\+\.[0-9]\+/hermes-operator.v${VERSION}/g" \
-            -e "s|ghcr.io/paperclipinc/hermes-operator:v[0-9]\+\.[0-9]\+\.[0-9]\+|ghcr.io/paperclipinc/hermes-operator:${TAG}|g" \
+            -e "s|ghcr.io/paperclipinc/hermes-operator:v[0-9]\+\.[0-9]\+\.[0-9]\+|${IMG_REF}|g" \
             -e "s/createdAt: .*/createdAt: \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"/" \
             -e "s/^  version: [0-9]\+\.[0-9]\+\.[0-9]\+/  version: ${VERSION}/" \
             bundle/manifests/hermes-operator.clusterserviceversion.yaml \

.gitignore

@@ -28,3 +28,7 @@ go.work
 *.swp
 *.swo
 *~
+
+# docs site build output and local virtualenv
+docs-site/site/
+docs-site/.venv/

Makefile

@@ -69,6 +69,36 @@ test: manifests generate fmt vet envtest ## Run tests.
 test-e2e:
 	go test ./test/e2e/ -v -ginkgo.v
 
+.PHONY: bench
+bench: ## Run benchmarks for resource builders.
+	go test ./internal/resources/ -bench=. -benchmem -run=^$$ -count=1
+
+##@ Docs Site
+
+.PHONY: api-docs
+api-docs: manifests crd-ref-docs ## Regenerate docs/api-reference-generated.md from the API types.
+	$(CRD_REF_DOCS) \
+	  --config docs-site/crd-ref-docs.yaml \
+	  --source-path api/v1 \
+	  --output-path docs/api-reference-generated.md \
+	  --renderer markdown
+
+.PHONY: docs-venv
+docs-venv: docs-site/.venv/bin/activate ## Create the docs-site Python virtualenv.
+docs-site/.venv/bin/activate: docs-site/requirements.txt
+	python3 -m venv docs-site/.venv
+	docs-site/.venv/bin/pip install --upgrade pip
+	docs-site/.venv/bin/pip install -r docs-site/requirements.txt
+	touch docs-site/.venv/bin/activate
+
+.PHONY: docs-serve
+docs-serve: docs-venv ## Serve the docs site locally (http://127.0.0.1:8000).
+	docs-site/.venv/bin/mkdocs serve -f docs-site/mkdocs.yml
+
+.PHONY: docs-build
+docs-build: docs-venv ## Build the docs site in strict mode (fails on warnings).
+	docs-site/.venv/bin/mkdocs build --strict -f docs-site/mkdocs.yml
+
 .PHONY: lint
 lint: golangci-lint ## Run golangci-lint linter
 	$(GOLANGCI_LINT) run
@@ -210,12 +240,14 @@ KUSTOMIZE ?= $(LOCALBIN)/kustomize
 CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen
 ENVTEST ?= $(LOCALBIN)/setup-envtest
 GOLANGCI_LINT = $(LOCALBIN)/golangci-lint
+CRD_REF_DOCS ?= $(LOCALBIN)/crd-ref-docs
 
 ## Tool Versions
 KUSTOMIZE_VERSION ?= v5.4.2
 CONTROLLER_TOOLS_VERSION ?= v0.21.0
 ENVTEST_VERSION ?= release-0.24
 GOLANGCI_LINT_VERSION ?= v2.12.2
+CRD_REF_DOCS_VERSION ?= v0.3.0
 
 .PHONY: kustomize
 kustomize: $(KUSTOMIZE) ## Download kustomize locally if necessary.
@@ -237,6 +269,11 @@ golangci-lint: $(GOLANGCI_LINT) ## Download golangci-lint locally if necessary.
 $(GOLANGCI_LINT): $(LOCALBIN)
 	$(call go-install-tool,$(GOLANGCI_LINT),github.com/golangci/golangci-lint/v2/cmd/golangci-lint,$(GOLANGCI_LINT_VERSION))
 
+.PHONY: crd-ref-docs
+crd-ref-docs: $(CRD_REF_DOCS) ## Download crd-ref-docs locally if necessary.
+$(CRD_REF_DOCS): $(LOCALBIN)
+	$(call go-install-tool,$(CRD_REF_DOCS),github.com/elastic/crd-ref-docs,$(CRD_REF_DOCS_VERSION))
+
 # go-install-tool will 'go install' any package with custom target and name of binary, if it doesn't exist
 # $1 - target path with name of binary
 # $2 - package url which can be installed

api/v1/hermesinstance_types.go

@@ -77,6 +77,21 @@ type HermesInstanceSpec struct {
 	// +optional
 	Scheduling SchedulingSpec `json:"scheduling,omitempty"`
 
+	// ShareProcessNamespace enables PID namespace sharing between all containers
+	// in the pod. When true (the default), the infrastructure (pause) container
+	// becomes PID 1 and reaps zombie processes, preventing accumulation of defunct
+	// helper processes (git, plugins, shells) spawned under the agent entrypoint
+	// when it does not call waitpid().
+	//
+	// Security note: enabling this lets every container in the pod see and signal
+	// every other container's processes. A compromised sidecar could send signals
+	// to the agent and vice versa. Set to false to keep per-container PID isolation;
+	// you are then responsible for reaping zombies (e.g. by baking tini or dumb-init
+	// into the image).
+	// +kubebuilder:default=true
+	// +optional
+	ShareProcessNamespace *bool `json:"shareProcessNamespace,omitempty"`
+
 	// InitContainers is a user-supplied list of init containers appended after
 	// any operator-managed init containers (e.g. runtime-init from Plan 3).
 	// +optional
@@ -159,15 +174,23 @@ type HermesInstanceSpec struct {
 }
 
 // ImageSpec selects an OCI image.
+// +kubebuilder:validation:XValidation:rule="(has(self.tag) && size(self.tag) > 0 && self.tag != 'latest') || (has(self.digest) && size(self.digest) > 0)",message="spec.image: one of tag or digest must be set and the tag must not be the floating ':latest' (pick a specific upstream release tag or pin a digest)"
 type ImageSpec struct {
 	// +kubebuilder:default="ghcr.io/paperclipinc/hermes-agent"
 	// +optional
 	Repository string `json:"repository,omitempty"`
 
-	// +kubebuilder:default="latest"
+	// Tag is the container image tag. Either tag or digest must be set; there is
+	// no default, because pinning to a mutable tag like :latest can silently pull
+	// a broken upstream build.
 	// +optional
 	Tag string `json:"tag,omitempty"`
 
+	// Digest overrides the tag with an image digest (e.g. sha256:abc...). When set
+	// it takes precedence over the tag for the resolved image reference.
+	// +optional
+	Digest string `json:"digest,omitempty"`
+
 	// +kubebuilder:default=IfNotPresent
 	// +kubebuilder:validation:Enum=Always;IfNotPresent;Never
 	// +optional
@@ -568,6 +591,30 @@ type MetricsSpec struct {
 	// +kubebuilder:default=false
 	// +optional
 	Secure *bool `json:"secure,omitempty"`
+
+	// GrafanaDashboard configures auto-provisioned Grafana dashboard ConfigMaps
+	// (operator overview + per-instance). When enabled, the operator emits
+	// ConfigMaps labeled grafana_dashboard="1" so the Grafana sidecar provisioner
+	// picks them up automatically.
+	// +optional
+	GrafanaDashboard *GrafanaDashboardSpec `json:"grafanaDashboard,omitempty"`
+}
+
+// GrafanaDashboardSpec configures auto-provisioned Grafana dashboard ConfigMaps.
+type GrafanaDashboardSpec struct {
+	// Enabled enables Grafana dashboard ConfigMap creation.
+	// +kubebuilder:default=false
+	// +optional
+	Enabled *bool `json:"enabled,omitempty"`
+
+	// Labels to add to the dashboard ConfigMaps (in addition to grafana_dashboard: "1").
+	// +optional
+	Labels map[string]string `json:"labels,omitempty"`
+
+	// Folder is the Grafana folder to place the dashboards in.
+	// +kubebuilder:default="Hermes"
+	// +optional
+	Folder string `json:"folder,omitempty"`
 }
 
 // ServiceMonitorSpec controls Prometheus-Operator ServiceMonitor emission.
@@ -1000,18 +1047,19 @@ type MigrationStatus struct {
 
 // Condition type constants. Centralised so Plan 4-6 and docs/conditions.md stay aligned.
 const (
-	ConditionTypeReady               = "Ready"
-	ConditionTypeStorageReady        = "StorageReady"
-	ConditionTypeConfigReady         = "ConfigReady"
-	ConditionTypeSecretsReady        = "SecretsReady"
-	ConditionTypeNetworkPolicyReady  = "NetworkPolicyReady"
-	ConditionTypeRBACReady           = "RBACReady"
-	ConditionTypeServiceReady        = "ServiceReady"
-	ConditionTypePDBReady            = "PDBReady"
-	ConditionTypeHPAReady            = "HPAReady"
-	ConditionTypeIngressReady        = "IngressReady"
-	ConditionTypeServiceMonitorReady = "ServiceMonitorReady"
-	ConditionTypePrometheusRuleReady = "PrometheusRuleReady"
+	ConditionTypeReady                 = "Ready"
+	ConditionTypeStorageReady          = "StorageReady"
+	ConditionTypeConfigReady           = "ConfigReady"
+	ConditionTypeSecretsReady          = "SecretsReady"
+	ConditionTypeNetworkPolicyReady    = "NetworkPolicyReady"
+	ConditionTypeRBACReady             = "RBACReady"
+	ConditionTypeServiceReady          = "ServiceReady"
+	ConditionTypePDBReady              = "PDBReady"
+	ConditionTypeHPAReady              = "HPAReady"
+	ConditionTypeIngressReady          = "IngressReady"
+	ConditionTypeServiceMonitorReady   = "ServiceMonitorReady"
+	ConditionTypePrometheusRuleReady   = "PrometheusRuleReady"
+	ConditionTypeGrafanaDashboardReady = "GrafanaDashboardReady"
 
 	ConditionBackupReady          = "BackupReady"
 	ConditionRestoreApplied       = "RestoreApplied"

api/v1/zz_generated.deepcopy.go

@@ -55,6 +55,11 @@ spec:
               image:
                 description: Image defaults the instance's spec.image.
                 properties:
+                  digest:
+                    description: |-
+                      Digest overrides the tag with an image digest (e.g. sha256:abc...). When set
+                      it takes precedence over the tag for the resolved image reference.
+                    type: string
                   pullPolicy:
                     default: IfNotPresent
                     enum:
@@ -66,9 +71,18 @@ spec:
                     default: ghcr.io/paperclipinc/hermes-agent
                     type: string
                   tag:
-                    default: latest
+                    description: |-
+                      Tag is the container image tag. Either tag or digest must be set; there is
+                      no default, because pinning to a mutable tag like :latest can silently pull
+                      a broken upstream build.
                     type: string
                 type: object
+                x-kubernetes-validations:
+                - message: 'spec.image: one of tag or digest must be set and the tag
+                    must not be the floating '':latest'' (pick a specific upstream
+                    release tag or pin a digest)'
+                  rule: (has(self.tag) && size(self.tag) > 0 && self.tag != 'latest')
+                    || (has(self.digest) && size(self.digest) > 0)
               networking:
                 description: Networking defaults Service kind + NetworkPolicy enablement.
                 properties:
@@ -127,6 +141,30 @@ spec:
                       enabled:
                         default: true
                         type: boolean
+                      grafanaDashboard:
+                        description: |-
+                          GrafanaDashboard configures auto-provisioned Grafana dashboard ConfigMaps
+                          (operator overview + per-instance). When enabled, the operator emits
+                          ConfigMaps labeled grafana_dashboard="1" so the Grafana sidecar provisioner
+                          picks them up automatically.
+                        properties:
+                          enabled:
+                            default: false
+                            description: Enabled enables Grafana dashboard ConfigMap
+                              creation.
+                            type: boolean
+                          folder:
+                            default: Hermes
+                            description: Folder is the Grafana folder to place the
+                              dashboards in.
+                            type: string
+                          labels:
+                            additionalProperties:
+                              type: string
+                            description: 'Labels to add to the dashboard ConfigMaps
+                              (in addition to grafana_dashboard: "1").'
+                            type: object
+                        type: object
                       port:
                         default: 9090
                         description: Port for the /metrics endpoint.