fix(library): make the operator importable as a Go module (vendor sunsingerus mergo fork) by sks · Pull Request #2150 · Altinity/clickhouse-operator

sks · 2026-11-12T16:40:31Z

Problem

This repository cannot be imported as a Go library module. Any consumer that requires it fails to compile:

undefined: mergo.WithSliceDeepMerge
    pkg/apis/clickhouse.altinity.com/v1/type_templates.go:92:34

Root cause: mergo.WithSliceDeepMerge exists only in the sunsingerus/mergo fork, and the fork is wired in via a go.mod replace directive — but per the Go modules spec, replace directives apply only to the main module and do not propagate to consumers. Upstream imdario/mergo v0.3.15 has no WithSliceDeepMerge, so consumers resolve the wrong module.

Importing github.com/sunsingerus/mergo directly is not an option: that fork's own go.mod declares module github.com/imdario/mergo, so Go refuses to resolve it under the fork's path (parsing go.mod: module declares its path as ... but was required as ...).

Fix

Vendor the fork at pkg/util/mergo (provenance + license included) and repoint the four API-package import sites:

pkg/apis/clickhouse.altinity.com/v1/type_templates.go
pkg/apis/clickhouse.altinity.com/v1/type_chi.go
pkg/apis/clickhouse.altinity.com/v1/type_configuration_chop.go
pkg/apis/clickhouse-keeper.altinity.com/v1/type_chk.go

The vendored copy is ~840 lines, stdlib-only (errors/fmt/reflect/unicode), unmodified, with its BSD-3-Clause LICENSE and a provenance.go documenting upstream, pinned commit (fc6fffa94450, 2023-05-07, fork of v0.3.15) and a do-not-modify policy. The mergo replace is dropped from go.mod.

The remaining replaces (glog, go-restful) stay: they are not part of the exported API surface, and consumer builds succeed without them (verified — mergo was the only load-bearing one).

Verification

Out-of-tree consumer module with require github.com/altinity/clickhouse-operator and zero consumer-side replaces:

pristine master: build fails with undefined: mergo.WithSliceDeepMerge (exactly as above)
this branch: consumer builds clean

Operator's own suites pass unchanged: pkg/apis/..., pkg/model/chi/... (config, normalizer, labeler).

Why vendoring rather than upstreaming mergo changes

The delta is fork-specific behavior (WithSliceDeepMerge, WithSliceDeepCopy, doSliceDeepMerge). Attempting to move to upstream mergo (v1.x) would be a semantic change to template merging and is out of scope; this PR makes the existing, intended dependency graph consumable as-is.

Use case

Downstream tooling (e.g. an EC2/VMSS-based cluster control plane that reuses the operator's normalizer, config generators and schemer off-Kubernetes can now depend on a fork at a pinned commit without mirroring the replace block. The module in does exactly this.
EOF
)

…s a Go module Importing this repository as a library module failed for every consumer: the exported API packages call mergo.WithSliceDeepMerge, which exists only in the sunsingerus fork of imdario/mergo, and the go.mod `replace` that points at the fork does NOT propagate to library consumers (Go spec: replace directives apply only to the main module). Consumers hit: undefined: mergo.WithSliceDeepMerge (pkg/apis/clickhouse.altinity.com/v1/type_templates.go:92) Direct-importing github.com/sunsingerus/mergo is not an alternative — that fork's own go.mod declares module path github.com/imdario/mergo, so Go refuses to resolve it under the fork's path. Fix: vendor the fork's stdlib-only sources (~840 lines, zero dependencies) at pkg/util/mergo with its BSD-3-Clause license and a provenance note, and point the four API-package import sites at it. Drop the mergo replace from go.mod. The remaining replaces (glog, go-restful) stay: they are build-graph conveniences, not part of the exported API surface, and builds succeed without them when required from a consumer. Verified with an out-of-tree consumer module requiring the operator with no replaces: pristine master fails with the undefined-symbol error above; this branch builds the consumer clean. Operator's own pkg test suites (apis, model/chi) pass unchanged. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Single fork commit on top of upstream release-0.27.4 (a89fa9e): chctl (cmd/chctl + pkg/chctl + docs/chctl.md + release workflow) - Off-cluster control CLI exposing the operator behavior on any ClickHouse deployment - VMs, EC2 ASGs, VMSS, bare metal: chctl config render operator config generators -> config.d XML from a CHI/CHK spec chctl schema sync HostCreateTables on a scaled-out host chctl replica drop HostDropReplica via a live peer chctl replica sync HostSyncTables on a restarted host chctl keeper safe-to-stop Raft-quorum gate (controller math + mntr); exit 0/2/3 for lifecycle hooks - Domain (entities/ports/services) + infra adapters (operator machinery, keeper 4lw probe); operator types never leave pkg/chctl/infra/operator - stdlib flag, no new dependencies; testify suites cover normalization, 0.27.4 RemovedSecretRefSyntax rejection, render groups, keeper wire protocol, and the quorum decision table - .github/workflows/release-chctl.yaml publishes binaries (linux/arm64+amd64, darwin/arm64+amd64) + SHA256SUMS on chctl-v* tags Library consumption fix (pkg/util/mergo) - Vendored the sunsingerus mergo fork (~840 stdlib-only lines, BSD-3, provenance doc) so the operator imports as a Go module: upstream wires mergo.WithSliceDeepMerge via a replace directive, which does not propagate to library consumers - every require of upstream failed with "undefined: mergo.WithSliceDeepMerge". Proposed upstream as Altinity#2150 (closed). CI fork-safety (build_master, build_branch) - Docker build jobs skip login/push when DOCKER_* secrets are absent (forks): single-platform --load keeps the Dockerfile validation gate without a registry; release-evidence capture skips registry lookups. Same pattern cosign_sign already used. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

sks closed this Nov 12, 2026

Navigation Menu

Repository navigation

fix(library): make the operator importable as a Go module (vendor sunsingerus mergo fork) - #2150

fix(library): make the operator importable as a Go module (vendor sunsingerus mergo fork)#2150
sks wants to merge 1 commit into
Altinity:masterfrom
sks:fix/direct-sunsingerus-mergo-import

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

Problem

Fix

Verification

Why vendoring rather than upstreaming mergo changes

Use case

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant