Build and test¶

To use Replicove, start with prebuilt release downloads. That page also shows how to build a CLI from an exact release tag. The instructions below are for developing and testing the current source.

Clone main and use the Go version pinned in go.mod. Current development uses Go 1.27.1. For docs, use Python 3.12 and the pinned documentation requirements. Real cluster tests require Docker.

git clone --branch main https://github.com/nimeshbuilds/replicove.git
cd replicove
make build

bin/replicove is the CLI. bin/cluster-replica is the operator binary (the original internal name is retained). The Go module/API group also retain their original identifiers during the alpha.

Repository layout¶

Path	Purpose
`api/v1alpha1`	CRD types, defaults and validation markers
`cmd/operator`, `cmd/replicove`	Operator and human/CI command line
`internal/policy`, `capture`, `planner`	Delegation, bounded reads and transformation/dependency planning
`internal/state`	Encryption, durable intent/inventory and explicit key bootstrap
`internal/workflow`, `target`	Apply/readiness/refresh/access/cleanup and verified guest clients
`internal/database`, `chaos`	Optional PostgreSQL staging/sanitization and bounded fault controllers
`internal/testrun`, `capacity`	Local recipe lifecycle and durable destination admission
`internal/diagnostics`, `agentapi`, `dashboard`	Metadata evidence, namespace-scoped stdio MCP and local read-only UI
`internal/catalog`, `runtime/helm`	Exact upstream profiles and runtime lifecycle
`charts/replicove`, `config/install`	Chart and generated native installer
`examples/yaml`	Public kubectl-only walkthrough inputs
`test/integration`, `test/e2e`, `test/workloads`, `test/database`	API contracts and live fixtures
`docs`, `mkdocs.yml`, `hack/docs.py`	Documentation content, navigation and generated references

Read architecture before adding behavior across boundaries.

Local checks¶

make generate
make check

make generate regenerates DeepCopy code, CRD schemas, embedded chart CRDs, and native installation YAML. It formats Go sources. Review the resulting diff.

make check runs race-enabled Go tests, actual pinned chart contracts, a real local envtest API server, vet, and both builds. Downloader scripts verify pinned inputs and use ignored .cache/ storage. Chart contracts cover values, ownership, images and namespaced RBAC; API tests validate admission, immutable requests, status/finalizers, authorization and target identity.

No Docker engine is needed for those local checks. They do not prove a live vCluster can start.

Live disposable-cluster tests¶

./hack/fetch-e2e-tools.sh
make test-e2e
./hack/e2e-yaml.sh
./hack/e2e-replication.sh
./hack/e2e-workload.sh cert-manager
./hack/e2e-workload.sh spark
./hack/e2e-workload.sh trino
./hack/e2e-workload.sh policy

Each script creates and deletes its own uniquely named kind host. Use a machine with sufficient Docker CPU, memory and disk for the selected workload. The portable workflow defaults to the pinned 1.36.4 host; CI also runs it on 1.35.8. Scripts store private connection files under .cache/, remove them during cleanup, and retain only sanitized evidence for upload.

The YAML scenario uses the public manifests and no Replicove/Helm CLI. It checks real bootstrap Job execution and key reuse as well as runtime creation, copied configuration, a bounded viewer credential, revocation and cleanup.

Test a change at the right boundary¶

Policy and transformation changes: exercise allowed behavior and denied cases, including dependency and ownership conflicts.
State or access changes: verify restart/retry, UID reuse, expiration and failure recovery without exposing credentials.
Chart/RBAC changes: regenerate native manifests, run chart and real-API authorization checks, then live installation.
Runtime/profile changes: qualify actual provision, access, restart/rescheduling, TTL and deletion with the pinned chart.
Documentation changes: run the strict site build and link checks.

A unit test of a mock runtime is useful but is not evidence that an actual vCluster works. Record the commit and matching live run when making a support claim.

Submit a change¶

Keep generated files, docs, and examples aligned with behavior. Run relevant checks and explain their scope in the PR. Follow Contributing, report security issues through Security, and use runtime maintenance for upstream releases.

Mirror module verification¶

go test -race ./internal/mirror ./cmd/replicove ./internal/runtime/helm covers mirror recovery, source/target ownership, partial restore cleanup, active revision retention, storage dependency pins and tunnel reconnect behavior. make test-integration validates mirror admission and the checked-in example manifests against a real API server. make docs discovers the full CLI tree and generates all CRD fields before building and checking links.

With Docker, run ./hack/fetch-e2e-tools.sh, ./hack/fetch-helm.sh, then ./hack/e2e-mirror.sh. The script owns a fresh kind cluster, installs pinned Calico and CSI host-path fixtures, and removes that cluster on exit. It is also a mandatory CI job and a published-artifact release gate. Do not point the fixture at a production cluster. Evidence is written under .cache/mirror-e2e/run.*/artifacts/; credential files are excluded. Cloud labs remain separate qualification.

The mirror suite first enables the module on a previously installed release while preserving a persistent ordinary replica. REPLICOVE_MIRROR_BASE=current starts with published 0.2.0-alpha.1; previous starts with published 0.1.0-alpha.1; native starts with rendered 0.2.0-alpha.1 YAML and tests bootstrap Job replacement. CI and release verification require all three. enable-later.json records transition checks separately from the mirror lifecycle's report.json.

Additional feature verification¶

Version v0.3.0-alpha.1 introduced the following test paths. Build the CLI and operator from the same revision, regenerate all six CRDs and native manifests, and use an explicit source-built image when testing before release publication. The operator runtime image supplies PostgreSQL 17 pg_dump; a bare operator binary needs that executable available when database copying is enabled.

Run the relevant local suites, then their live boundary checks:

go test -race ./internal/database ./internal/chaos ./internal/testrun ./internal/capacity ./internal/diagnostics ./internal/agentapi ./internal/dashboard ./cmd/replicove
./examples/postgresql/test-disposable.sh
./hack/e2e-database.sh
./hack/e2e-chaos.sh
./hack/e2e-testrun.sh

The PostgreSQL Docker test creates only disposable containers with generated fixture data, no host mounts or external network. It checks actual pg_dump/restore, masks, explicit table subsets, foreign keys, source preservation and absence of the raw fixture value from final database files. It does not exercise Kubernetes or the production operator. Its diagnostic output is test-only; production database stderr remains suppressed.

The PostgreSQL kind suite covers the operator, late enablement, host CNI isolation, blocked application/access startup during preparation, restart/refresh gating and owned PVC/PV/policy cleanup. The chaos kind suite checks real workload effects, rollback and host isolation. The test-runner suite checks fresh environments, execution outcomes, reports and verified cleanup. These scripts create their own disposable hosts; never repoint them at an existing user cluster. They are qualification gates, not evidence of success until their exact-revision runs pass.

For admission changes, exercise overlapping requests and confirm queued work cannot provision a second managed runtime or lose its reservation on restart. For MCP/dashboard changes, check namespace confinement, caller RBAC, absent Secret payloads and default read-only behavior. Pool rendering is offline installation output; review shared CRD/snapshot ownership and quota settings before applying it.