docs: fix docs links and CI, fetch mintlify changes, actualize some docs and comments

Author: GrigoryPervakov

.github/workflows/ci.yaml

@@ -13,8 +13,27 @@ permissions:
   pull-requests: write
 
 jobs:
+  changes:
+    runs-on: ubuntu-latest
+    outputs:
+      code: ${{ steps.filter.outputs.code }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+      - name: Detect non-docs changes
+        uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            code:
+              - '**'
+              - '!**/*.md'
+              - '!**/*.mdx'
+
   lint:
     runs-on: ubuntu-latest
+    needs: [ changes ]
+    if: needs.changes.outputs.code == 'true'
     steps:
       - name: Checkout code
         uses: actions/checkout@v6
@@ -55,7 +74,9 @@ jobs:
     # Only run on pull requests, and skip when the PR is explicitly labeled as
     # an intentional CRD-breaking change. The job is not part of ci-success-check,
     # so a failure here does not block the aggregate gate.
+    needs: [ changes ]
     if: |
+      needs.changes.outputs.code == 'true' &&
       github.event_name == 'pull_request' &&
       !contains(github.event.pull_request.labels.*.name, 'crd-breaking-change')
     runs-on: ubuntu-latest
@@ -75,6 +96,8 @@ jobs:
 
   bundle:
     runs-on: ubuntu-latest
+    needs: [ changes ]
+    if: needs.changes.outputs.code == 'true'
     env:
       VERSION: 0.0.1
     steps:
@@ -109,6 +132,8 @@ jobs:
 
   build_and_test:
     runs-on: ubuntu-latest
+    needs: [ changes ]
+    if: needs.changes.outputs.code == 'true'
     steps:
       - name: Checkout code
         uses: actions/checkout@v6
@@ -143,6 +168,8 @@ jobs:
 
   fuzz_specs:
     runs-on: ubuntu-latest
+    needs: [ changes ]
+    if: needs.changes.outputs.code == 'true'
     steps:
       - name: Checkout code
         uses: actions/checkout@v6
@@ -160,6 +187,8 @@ jobs:
 
   helm-test:
     runs-on: ubuntu-latest
+    needs: [ changes ]
+    if: needs.changes.outputs.code == 'true'
     steps:
       - name: Checkout code
         uses: actions/checkout@v6
@@ -189,6 +218,8 @@ jobs:
 
   compat-e2e-test:
     runs-on: [ubuntu-latest]
+    needs: [ changes ]
+    if: needs.changes.outputs.code == 'true'
     strategy:
       fail-fast: false
       matrix:
@@ -259,7 +290,8 @@ jobs:
           overwrite: true
 
   e2e-test:
-    needs: [ lint ]
+    needs: [ lint, changes ]
+    if: needs.changes.outputs.code == 'true'
     strategy:
       fail-fast: false
       matrix:
@@ -301,9 +333,9 @@ jobs:
           overwrite: true
 
   e2e-report:
-    needs: [compat-e2e-test, e2e-test]
+    needs: [ changes, compat-e2e-test, e2e-test ]
     runs-on: ubuntu-latest
-    if: ${{ !cancelled() }}
+    if: ${{ !cancelled() && needs.changes.outputs.code == 'true' }}
     steps:
       - name: Checkout code
         uses: actions/checkout@v6
@@ -325,8 +357,10 @@ jobs:
           path: "**/*-report.xml"
 
   openshift-compat:
-    needs: [ compat-e2e-test, e2e-test ]
-    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+    needs: [ changes, compat-e2e-test, e2e-test ]
+    if: |
+      needs.changes.outputs.code == 'true' &&
+      ( github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository )
     runs-on: [self-hosted, openshift, operator]
     continue-on-error: true
     timeout-minutes: 60
@@ -390,7 +424,7 @@ jobs:
   ci-success-check:
     name: All CI checks passed
     runs-on: ubuntu-latest
-    needs: [ lint, bundle, build_and_test, fuzz_specs, helm-test, compat-e2e-test, e2e-test, check-crd-compat ]
+    needs: [ changes, lint, bundle, build_and_test, fuzz_specs, helm-test, compat-e2e-test, e2e-test, check-crd-compat ]
     if: always()
     steps:
       - name: Determine CI status

.github/workflows/docs-lint.yaml

@@ -22,11 +22,19 @@ jobs:
           fail_on_error: 'true'
           filter_mode: nofilter
 
-  markdown-link-check:
+  doc-links:
+    name: Doc links
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
-      - uses: UmbrellaDocs/action-linkspector@v1
+      - uses: dorny/paths-filter@v3
+        id: changes
+        with:
+          filters: |
+            docs:
+              - 'docs/**'
+      - if: steps.changes.outputs.docs == 'true'
+        uses: UmbrellaDocs/action-linkspector@v1
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           reporter: github-pr-review
@@ -54,7 +62,7 @@ jobs:
   ci-success-check:
     name: All Docs CI checks passed
     runs-on: ubuntu-latest
-    needs: [ vale, markdown-link-check, api-reference-generated ]
+    needs: [ vale, doc-links, api-reference-generated ]
     if: always()
     steps:
       - name: Determine CI status

.linkspector.yml

@@ -1,17 +1,22 @@
+# Link check for the docs/ tree. Run from the repo root so the self-link
+# rewrite resolves against the local source.
+#   - relative + external links: checked normally
+#   - operator self-links (/products/kubernetes-operator/...): resolved against
+#     the local docs/ source, including anchors
+#   - other Mintlify site-absolute links (/reference, /concepts, ...): resolved
+#     against ClickHouse/mintlify-docs-dev main via raw GitHub (page existence;
+#     anchors are not checked over HTTP)
 dirs:
-  - .
-useGitIgnore: true
+  - docs
+useGitIgnore: false
 fileExtensions:
   - md
   - mdx
-excludedDirs:
-  - ./node_modules
-  - ./bin
-  - ./dist
-
+replacementPatterns:
+  - pattern: '^/products/kubernetes-operator/(.+?)(#.*)?$'
+    replacement: '/docs/$1.mdx$2'
+  - pattern: '^/(?!docs/)([^#]+?)(#.*)?$'
+    replacement: 'https://raw.githubusercontent.com/ClickHouse/mintlify-docs-dev/main/$1.mdx'
 ignorePatterns:
-  # Mintlify absolute routes — resolved at deploy time by Mintlify,
-  # not present as files in this repo.
-  - pattern: '^/(products|core|cloud|operations)/'
-  # Cloudflare bot protection returns 403 to programmatic checkers.
+  - pattern: '^/(_site|images|assets)/'
   - pattern: '^https://trust\.clickhouse\.com'

AGENTS.md

@@ -105,21 +105,23 @@ After modifying types, always run `make generate manifests generate-helmchart-ci
 ### Controllers (`internal/controller/`)
 Both controllers follow the same pattern, extending a shared base:
 
-- `reconcilerbase.go` — Base reconciliation logic shared by both controllers
+- `step.go` — ReconcileStep pipeline primitives (StepResult, RunSteps)
 - `clickhouse/controller.go` — ClickHouseCluster reconciler (manages StatefulSets, ConfigMaps, Services)
 - `keeper/controller.go` — KeeperCluster reconciler
-- `clickhouse/sync.go`, `keeper/sync.go` — Sync desired state to Kubernetes
+- `clickhouse/sync.go`, `keeper/sync.go` — Build the step pipeline; sync desired state to Kubernetes
 - `clickhouse/templates.go`, `keeper/templates.go` — Generate Kubernetes resource specs
 - `clickhouse/config.go` — Generate ClickHouse YAML configuration
 - `clickhouse/commands.go`, `keeper/commands.go` — Interfaces to communicate to running containers
 - `overrides.go` — Pod/container spec overrides helpers via strategic merge patch
 - `versionprobe.go` — Creates Jobs to detect actual ClickHouse/Keeper versions
 - `upgradecheck.go` — Checks for newer version availability
-- `resources.go` — Shared Kubernetes resource creation helpers
-- `status.go` — Status update logic
+- `resourcemanager.go` — Shared Kubernetes resource create/update with spec-hash idempotency
+- `statusmanager.go` — Status/condition manager (retry-on-conflict, events on transition)
+- `replicastate.go` — Per-replica readiness / rolling-update state
+- `securitycontext.go` — Pod/container SecurityContext defaults
 
 ### Reconciliation Pattern
-Controllers execute reconcile as a sequence of step functions (`func(ctx, log) (*Result, error)`). Steps are defined in `sync()` and executed sequentially.
+`sync()` builds an ordered `[]ReconcileStep` (see `step.go`), executed by `RunSteps`. Each step's `Fn` is `func(ctx, log) (StepResult, error)`. `StepResult{RequeueAfter, Blocked}` controls flow: `Blocked=true` is a *valid wait* (e.g. version-probe Job not finished) — return it, not an error; it skips subsequent non-`Always` steps. Steps with `Always: true` run even while the pipeline is blocked. `RunSteps` returns the minimum `RequeueAfter`; the first error aborts.
 
 ### Resource Change Detection
 Resources are tracked via annotation hashes (`checksum/spec`, `checksum/configuration`). Before updating a K8s resource, compare `util.DeepHashResource()` output against the stored annotation. Skip updates when hashes match. Always call `util.AddSpecHashToObject()` on reconciled resources.

README.md

@@ -29,7 +29,7 @@ The Operator handles the full lifecycle of ClickHouse clusters, including scalin
 ## Getting Started
 
 ### Prerequisites
-- go version v1.25.0+
+- go version v1.26.0+
 - docker version 17.03+
 - `kubectl` version v1.28.0+
 - Access to a Kubernetes v1.28.0+ cluster

api/v1alpha1/keepercluster_types.go

@@ -46,7 +46,7 @@ type KeeperClusterSpec struct {
 
 	// PodDisruptionBudget configures the PDB created for the Keeper cluster.
 	// When unset, the operator defaults to maxUnavailable=replicas/2
-	// (preserving quorum for a 2F+1 cluster).
+	// (preserving quorum for a 2F+1 cluster); single-replica clusters use maxUnavailable=1.
 	// +optional
 	PodDisruptionBudget *PodDisruptionBudgetSpec `json:"podDisruptionBudget,omitempty"`
 
@@ -155,7 +155,7 @@ type KeeperClusterStatus struct {
 	// CurrentRevision indicates latest applied KeeperCluster spec revision.
 	// +operator-sdk:csv:customresourcedefinitions:type=status
 	CurrentRevision string `json:"currentRevision,omitempty"`
-	// CurrentRevision indicates latest requested KeeperCluster spec revision.
+	// UpdateRevision indicates latest requested KeeperCluster spec revision.
 	// +operator-sdk:csv:customresourcedefinitions:type=status
 	UpdateRevision string `json:"updateRevision,omitempty"`
 	// ObservedGeneration indicates latest generation observed by controller.

config/crd/bases/clickhouse.com_keeperclusters.yaml

@@ -1099,7 +1099,7 @@ spec:
                 description: |-
                   PodDisruptionBudget configures the PDB created for the Keeper cluster.
                   When unset, the operator defaults to maxUnavailable=replicas/2
-                  (preserving quorum for a 2F+1 cluster).
+                  (preserving quorum for a 2F+1 cluster); single-replica clusters use maxUnavailable=1.
                 properties:
                   maxUnavailable:
                     anyOf:
@@ -6865,7 +6865,7 @@ spec:
                   for every replica.
                 type: string
               updateRevision:
-                description: CurrentRevision indicates latest requested KeeperCluster
+                description: UpdateRevision indicates latest requested KeeperCluster
                   spec revision.
                 type: string
               version:

dist/chart-cluster/values.yaml

@@ -139,7 +139,7 @@ keeper:
 
     # PodDisruptionBudget configures the PDB created for the Keeper cluster.
     # When unset, the operator defaults to maxUnavailable=replicas/2
-    # (preserving quorum for a 2F+1 cluster).
+    # (preserving quorum for a 2F+1 cluster); single-replica clusters use maxUnavailable=1.
     # podDisruptionBudget: {}
 
     # Parameters passed to the Keeper pod spec.

dist/chart/templates/crd/keeperclusters.clickhouse.com.yaml

@@ -1102,7 +1102,7 @@ spec:
                 description: |-
                   PodDisruptionBudget configures the PDB created for the Keeper cluster.
                   When unset, the operator defaults to maxUnavailable=replicas/2
-                  (preserving quorum for a 2F+1 cluster).
+                  (preserving quorum for a 2F+1 cluster); single-replica clusters use maxUnavailable=1.
                 properties:
                   maxUnavailable:
                     anyOf:
@@ -6868,7 +6868,7 @@ spec:
                   for every replica.
                 type: string
               updateRevision:
-                description: CurrentRevision indicates latest requested KeeperCluster
+                description: UpdateRevision indicates latest requested KeeperCluster
                   spec revision.
                 type: string
               version:

docs/guides/configuration.mdx

@@ -1,14 +1,12 @@
 ---
 position: 2
 slug: /clickhouse-operator/guides/configuration
-title: 'Configuration'
+title: ClickHouse Operator configuration guide
 keywords: ['kubernetes']
 description: 'This guide covers how to configure ClickHouse and Keeper clusters using the ClickHouse operator.'
 doc_type: 'guide'
 ---
 
-# ClickHouse Operator configuration guide
-
 This guide covers how to configure ClickHouse and Keeper clusters using the operator.
 
 ## ClickHouseCluster configuration {#clickhousecluster-configuration}
@@ -389,7 +387,7 @@ stringData:
 
 | Policy | Behavior on missing keys |
 |---|---|
-| `Observe` (default) | Reconciliation is **blocked** until every required key is present. The operator reports each missing key — and the format hint for it — via the `ExternalSecretValid` status condition and a `Warning` event. |
+| `Observe` (default) | Reconciliation is **blocked** until every required key is present. The operator reports each missing key — and the format hint for it — via the `ExternalSecretValid` condition (with reason `ExternalSecretInvalid`) and a `Warning` event. |
 | `Manage` | The operator **generates** any missing required keys and writes them back to the same Secret. Useful for bootstrapping: create an empty Secret, let the operator fill it, then optionally tighten access. The operator still never deletes the Secret. |
 
 <Note>
@@ -562,7 +560,7 @@ Two conditions surface the result of the probe and the upgrade check:
 | Condition | Reason | Meaning |
 |---|---|---|
 | `VersionInSync` | `VersionMatch` | All replicas report the same version as the image |
-| `VersionInSync` | `VersionMismatch` | Replicas are running different versions. This reason is suppressed during a planned rolling upgrade. It typically surfaces when a mutable image tag has been pinned (for example `latest` or a bare major like `26.3`) and the underlying registry has shifted between pulls, so different replicas ended up on different patches of the same tag. |
+| `VersionInSync` | `VersionMismatch` | Replicas are running different versions. The warning event is suppressed during a planned rolling upgrade. It typically surfaces when a mutable image tag has been pinned (for example `latest` or a bare major like `26.3`) and the underlying registry has shifted between pulls, so different replicas ended up on different patches of the same tag. |
 | `VersionInSync` | `VersionPending` | Version probe Job has not finished yet |
 | `VersionInSync` | `VersionProbeFailed` | Probe Job failed; the operator cannot determine the running version |
 | `VersionUpgraded` | `UpToDate` | The cluster is on the latest version available in the selected channel |
@@ -778,8 +776,8 @@ spec:
 ```
 
 #### Useful links:
-* [YAML configuration examples](/core/concepts/features/configuration/server-config/configuration-files#example-1)
-* [All server settings](/core/reference/settings/server-settings/settings)
+* [YAML configuration examples](/concepts/features/configuration/server-config/configuration-files#example-1)
+* [All server settings](/reference/settings/server-settings/settings)
 
 ### Embedded extra users configuration {#embedded-extra-users-configuration}
 
@@ -811,7 +809,7 @@ spec:
 The `extraUsersConfig` is stored in k8s ConfigMap object. Avoid plain text secrets there.
 </Note>
 
-#### See [documentation](/core/concepts/features/configuration/settings/settings-users) for all supported ClickHouse users configuration options.
+#### See [documentation](/concepts/features/configuration/settings/settings-users) for all supported ClickHouse users configuration options.
 
 ### Configuration example {#configuration-example}