RavenDB-26535 Kubernetes Operator: Release Process

.claude/skills/pre-release-report.md

@@ -0,0 +1,90 @@
+---
+name: pre-release-report
+description: Run if user wants to prepare for release. Six-pass audit of the repo before cutting a release. Passes 1-2 (CSV markers, samples) propose changes for user approval and commit them. Passes 3-6 (breaking changes, Helm parity, reviewers, dependencies) report findings; the user directs follow-up.
+---
+
+Six-pass pre-release audit. Run them in order. End with a structured summary.
+
+Use the current branch's ticket prefix (e.g., `RavenDB-26535`) for any commit subjects. Determine it from `git branch --show-current`.
+
+## Pass 1 — CSV markers (action: propose → confirm → apply → commit)
+
+Walk `api/v1/*.go`. For every exported field with a JSON tag, decide whether it needs a `+operator-sdk:csv:customresourcedefinitions:` marker.
+
+**Skip:**
+- `Spec`, `Status`, `Items`, `TypeMeta`, `ObjectMeta`, `ListMeta` — structural plumbing.
+- Embedded k8s core types (`corev1.VolumeSource`, `corev1.EnvVar`, `corev1.SecretReference`).
+- Pure container fields whose descriptors come from nested children (e.g., `Data`, `Logs`, `RavenDB`, `Audit` in `StorageSpec` — descriptors live on `Size`, `StorageClassName`, etc., reached via `storage.data.size` etc.).
+
+**Mark:** spec fields → `type=spec`, status fields → `type=status`. Format:
+`// +operator-sdk:csv:customresourcedefinitions:type=<spec|status>,displayName="<DisplayName>"`
+
+DisplayName: CamelCase → "Space-Separated Words"; keep acronyms (URL, ID, IP, EIP, CA, TCP, DNS); prefer domain-clear (`CertSecretRef` → "Certificate Secret"). Match the style of existing markers in the same file. Do NOT add `description="..."` — operator-sdk's parser rejects it at this level.
+
+Show proposals as `file:line  field  →  marker`, ask for confirmation/overrides, apply, run `make verify-samples` and (if available) `make bundle` in WSL to verify operator-sdk parses everything. Commit: `<ticket>: refresh CSV markers in api/v1`.
+
+## Pass 2 — Samples (action: validate + propose updates → confirm → apply → commit)
+
+First, run `make verify-samples`. If it fails, the strict-unmarshal error names the file/field — fix and re-run.
+
+Then, judgment pass: diff `api/v1/` spec types against the most recent release tag (`git describe --tags --abbrev=0`).
+
+For incremental additions (new optional fields, new array entries on existing types), ask: "Should this field appear in `ravendb_v1_ravendbcluster_letsencrypt.yaml`, `..._selfsigned.yaml`, both, or neither?"
+
+For changes that introduce a fundamentally distinct use case — a new `mode:` value, a new external-access provider type, a new storage backend, a new auth scheme — propose adding a NEW sample file: `ravendb_v1_ravendbcluster_<scenario>.yaml`. The user may also request a new sample even for incremental changes if they want a separate example. Register any new sample in `config/samples/kustomization.yaml` so operator-sdk folds it into alm-examples.
+
+Apply approved additions/files. Re-run `make verify-samples`. Commit: `<ticket>: update config/samples for new spec fields`.
+
+## Pass 3 — CRD breaking-change review (report only)
+
+Render the CRD at the most recent release tag and at HEAD, then diff. Render with `kustomize build config/crd | yq` (or operator-sdk equivalent). Surface:
+
+| Change | Severity | Why it matters |
+|---|---|---|
+| Removed field | High | Breaks users who set it |
+| Type change | High | Wire-incompatible |
+| New required field, no default | High | Breaks existing CRs on upgrade |
+| Narrowed enum or smaller min/max | Medium | Breaks users at the boundary |
+| Changed default | Medium | Silent behavior change |
+
+Output severity, field path, before → after. Do NOT auto-fix — these are deliberate decisions (keep with a major version bump, document migration, or revert).
+
+## Pass 4 — Helm chart parity (report only)
+
+`helm/chart/templates/` and `config/` are maintained in parallel. Diff them across:
+- **RBAC**: verbs/resources/apiGroups in `config/rbac/role.yaml` vs `helm/chart/templates/rbac.yaml` (or equivalent).
+- **Manager Deployment**: env vars, volume mounts, args, resource limits in `config/manager/manager.yaml` vs `helm/chart/templates/deployment.yaml`.
+- **Webhook**: cert-manager Issuer/Certificate refs, service ports.
+
+Report drift as `area | config has | helm has | risk`. Do NOT auto-fix — which side is canonical depends on what the change was for.
+
+## Pass 5 — Reviewer list (report + interactive)
+
+Read `bundle/ravendb-operator/ci.yaml`. Surface the current `reviewers:` list (or note absence — without it OperatorHub auto-merge doesn't fire). Ask: "Is this list current? Anyone to add or remove?" If the user wants edits, propose, confirm, apply, commit `<ticket>: refresh OperatorHub reviewers list`.
+
+## Pass 6 — Dependencies audit (report + interactive, top-level only)
+
+Surface pin vs latest for these only — don't go deep into transitive Go modules:
+
+- `OPERATOR_SDK_VERSION` in `Makefile` vs latest `operator-framework/operator-sdk` GitHub release.
+- `CONTROLLER_TOOLS_VERSION`, `KUSTOMIZE_VERSION`, `ENVTEST_VERSION`, `GOLANGCI_LINT_VERSION` in `Makefile`.
+- `go` directive in `go.mod` vs current stable Go.
+- cert-manager version in `.github/workflows/release.yml` smoke-test URL.
+- GitHub Action versions in `.github/workflows/*.yml` — surface floating tags (`@v3`, `@v4`); recommend SHA pinning where missing.
+
+Report as `dep | pinned | latest | gap | recommendation`. Recommendation tone: "consider bumping" or "looks current". Do NOT auto-bump — bumps need a deliberate test cycle, not a release-prep slipstream. Ask the user if they want to schedule any bumps as separate work.
+
+## Final summary
+
+```
+Pre-release report — <ticket>
+=============================
+Pass 1 (CSV markers):     <committed sha | "no gaps">
+Pass 2 (Samples):         <committed sha | "no updates needed">
+Pass 3 (CRD breaking):    <N items by severity>
+Pass 4 (Helm parity):     <N drift items>
+Pass 5 (Reviewers):       <committed sha | "current">
+Pass 6 (Dependencies):    <N items behind>
+```
+
+After this report, the user has a clear picture of what's actionable before invoking `prepare-release.yml`.

.github/kind-config.yaml

@@ -0,0 +1,11 @@
+kind: Cluster
+apiVersion: kind.x-k8s.io/v1alpha4
+# Enable per-host containerd registry config via /etc/containerd/certs.d.
+# We populate certs.d/localhost:5000/hosts.toml after cluster startup so pulls of
+# `localhost:5000/...` redirect to http://kind-registry:5000 (the registry container
+# attached to the kind Docker network). Standard kind+local-registry pattern:
+# https://kind.sigs.k8s.io/docs/user/local-registry/
+containerdConfigPatches:
+  - |-
+    [plugins."io.containerd.grpc.v1.cri".registry]
+      config_path = "/etc/containerd/certs.d"

.github/workflows/lint-workflows.yml

@@ -0,0 +1,26 @@
+name: Lint workflows
+
+# Runs on every workflow-touching PR. Catches YAML errors, deprecated action versions,
+# unset secrets, and shellcheck warnings on inline `run:` blocks.
+
+on:
+  pull_request:
+    paths:
+      - '.github/workflows/**'
+
+permissions:
+  contents: read
+
+jobs:
+  actionlint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download actionlint
+        run: |
+          bash <(curl -sSL https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash) 1.7.7
+          ./actionlint -version
+
+      - name: Run actionlint
+        run: ./actionlint -color

.github/workflows/operator-ci.yml

@@ -36,7 +36,7 @@ jobs:
 
       - name: Install gotestsum (if cache miss)
         if: steps.cache-gts.outputs.cache-hit != 'true'
-        run: go install gotest.tools/gotestsum@${GOTESTSUM_VERSION}
+        run: go install "gotest.tools/gotestsum@${GOTESTSUM_VERSION}"
 
       - name: Install setup-envtest tool
         run: go install sigs.k8s.io/controller-runtime/tools/setup-envtest@latest
@@ -49,7 +49,7 @@ jobs:
           key: ${{ runner.os }}-envtest-${{ env.K8S_VER }}
 
       - name: Select envtest Kubernetes assets
-        run: echo "KUBEBUILDER_ASSETS=$(setup-envtest use -p path ${K8S_VER})" >> "$GITHUB_ENV"
+        run: echo "KUBEBUILDER_ASSETS=$(setup-envtest use -p path "${K8S_VER}")" >> "$GITHUB_ENV"
 
       - name: Cache Go build and module download
         uses: actions/cache@v4
@@ -100,8 +100,8 @@ jobs:
           set -euo pipefail
           common_args=(
             --namespace ravendb-operator-system
-            --set controllerManager.image.repository=ravendb/ravendb-operator 
-            --set controllerManager.image.tag=ci-${GITHUB_SHA}
+            --set controllerManager.image.repository=ravendb/ravendb-operator
+            --set controllerManager.image.tag="ci-${GITHUB_SHA}"
             --set targetNamespace=test-namespace
             --set provisioning.mode=LetsEncrypt
             --set "provisioning.nodeTags={a,b,c}"

.github/workflows/prepare-release.yml

@@ -0,0 +1,153 @@
+name: Prepare Release
+
+# Phase 1 of the two-phase release flow.
+# Trigger: Actions tab -> Run workflow with target version.
+# Output: a `release: vX.Y.Z` PR labeled `release:auto`, carrying source bumps + helm chart.
+# Merge fires the Release workflow; remove the label first to delay publishing.
+#
+# Action pinning policy: third-party actions SHOULD be pinned to commit SHA with a
+# trailing comment naming the version (e.g. `uses: foo/bar@<sha>  # v1.2.3`).
+# First-party actions/* and github/* may stay on major tag. peter-evans below is
+# already SHA-pinned; remaining third-party actions (azure/setup-helm) are tracked
+# for a follow-up SHA-pinning pass.
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to release (e.g. 1.1.0, no v prefix)'
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  prepare:
+    runs-on: ubuntu-latest
+    env:
+      VERSION: ${{ inputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: azure/setup-helm@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.24.3'
+          cache: true
+
+      # Stale samples ship a broken "Try sample CR" form to OperatorHub. Gate first.
+      - name: Verify config/samples are current
+        run: make verify-samples
+
+      - name: Read previous version from Makefile
+        id: prev
+        run: |
+          OLD=$(awk -F'?= ' '/^VERSION \?=/ {print $2}' Makefile)
+          echo "old=$OLD" >> "$GITHUB_OUTPUT"
+          echo "Previous version: $OLD"
+          echo "New version:      $VERSION"
+
+      - name: Bump source files
+        run: |
+          sed -i "s/^VERSION ?=.*/VERSION ?= ${VERSION}/" Makefile
+          sed -i "s/^version:.*/version: ${VERSION}/"   helm/chart/Chart.yaml
+          sed -i "s/^appVersion:.*/appVersion: \"${VERSION}\"/" helm/chart/Chart.yaml
+          # SECURITY.md is bumped manually after the GitHub Release is published.
+
+      # release-bundle = bundle + bundle-relocate + bundle-finalize, with $(OLD)
+      # cleanup. CSV containerImage injection and nodes[0]→nodes[] descriptor
+      # rewrite live in `make bundle-finalize`. The bundle and build-installer
+      # targets trap-revert config/manager/kustomization.yaml on EXIT, so the
+      # working tree is clean after this step.
+      - name: Regenerate OLM bundle
+        env:
+          OLD: ${{ steps.prev.outputs.old }}
+        run: |
+          make release-bundle \
+            VERSION="${VERSION}" \
+            OLD="${OLD}" \
+            IMG="docker.io/ravendb/ravendb-operator:${VERSION}" \
+            CHANNELS=stable \
+            DEFAULT_CHANNEL=stable
+
+      # Bundle generation is the most likely failure point. On failure, dump the
+      # state we'd want to debug: working tree, what got touched, the rewritten
+      # CSV head (sed insertion failures are non-obvious otherwise).
+      - name: Bundle diagnostics (on failure)
+        if: failure()
+        run: |
+          set +e
+          echo "::group::git status"
+          git status --short
+          echo "::endgroup::"
+          echo "::group::git diff --stat"
+          git diff --stat
+          echo "::endgroup::"
+          echo "::group::Bundle dir contents"
+          ls -la "bundle/ravendb-operator/${VERSION}/" 2>/dev/null || echo "(bundle dir missing)"
+          ls -la "bundle/ravendb-operator/${VERSION}/manifests/" 2>/dev/null || true
+          echo "::endgroup::"
+          echo "::group::CSV head (first 100 lines)"
+          head -100 "bundle/ravendb-operator/${VERSION}/manifests/ravendb-operator.clusterserviceversion.yaml" 2>/dev/null || echo "(CSV missing)"
+          echo "::endgroup::"
+
+      - name: Package helm chart
+        run: |
+          helm package helm/chart -d helm/
+          helm repo index helm/ \
+            --url https://ravendb.github.io/ravendb-operator/helm \
+            --merge helm/index.yaml
+
+      - name: Ensure release:auto label exists
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh label create "release:auto" \
+            --description "On merge, fires the Release workflow automatically. Remove before merging to delay publishing." \
+            --color "0e8a16" \
+            || true   # already exists is fine
+
+      - name: Open release PR
+        id: pr
+        # peter-evans/create-pull-request v8.1.1 — pinned to SHA per supply-chain best practice.
+        # Auto-stages modified files, commits as github-actions[bot], pushes, opens (or
+        # updates) the PR. Idempotent: re-running for the same VERSION updates in place.
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1
+        with:
+          branch: release/v${{ env.VERSION }}
+          base: main
+          title: "release: v${{ env.VERSION }}"
+          commit-message: "release: v${{ env.VERSION }}"
+          labels: release:auto
+          body: |
+            Auto-generated bumps for v${{ env.VERSION }}.
+
+            On merge with the **release:auto** label still attached, the Release workflow fires:
+            multi-arch image push, kind smoke test, tag, GitHub Release with `install.yaml`.
+            Remove the label before merging to delay publishing. SECURITY.md is bumped
+            manually after publishing.
+
+      - name: Summary
+        env:
+          OLD: ${{ steps.prev.outputs.old }}
+          PR_URL: ${{ steps.pr.outputs.pull-request-url }}
+          PR_NUM: ${{ steps.pr.outputs.pull-request-number }}
+          PR_OP:  ${{ steps.pr.outputs.pull-request-operation }}
+        run: |
+          {
+            echo "## Prepare Release v${VERSION}"
+            echo ""
+            echo "| Field | Value |"
+            echo "| --- | --- |"
+            echo "| Previous version | \`${OLD}\` |"
+            echo "| New version | \`${VERSION}\` |"
+            echo "| Bundle dir | \`bundle/ravendb-operator/${VERSION}/\` |"
+            echo "| Helm chart | \`helm/ravendb-operator-${VERSION}.tgz\` |"
+            echo "| Release branch | \`release/v${VERSION}\` |"
+            echo "| Release PR | ${PR_URL:-(not opened)} (#${PR_NUM:--}, ${PR_OP:-unknown}) |"
+            echo ""
+            echo "Merge the PR with the **release:auto** label still attached to fire the Release workflow."
+          } >> "$GITHUB_STEP_SUMMARY"