Add testing guidelines with fork repos by hossain-rayhan · Pull Request #358 · documentdb/documentdb-kubernetes-operator

hossain-rayhan · 2026-04-24T20:00:22Z

No description provided.

Signed-off-by: Rayhan Hossain <rhossain@microsoft.com>

Copilot

Pull request overview

Adds a new developer guide describing how to run end-to-end tests using container images built from a contributor’s fork (GHCR) and installing the local Helm chart to validate changes on a real Kubernetes cluster.

Changes:

Introduces a step-by-step “fork images” workflow for building operator images and (intended) database images.
Documents Helm install/upgrade commands and iterative update approaches.
Adds an example DocumentDB manifest and cleanup steps.

Copilot · 2026-04-24T20:06:18Z

+3. **In your operator fork**, run **Actions → `RELEASE - Build DocumentDB Candidate Images` → Run workflow**. Provide these inputs:
+    - `version`: `0.110.0` (or whatever you released in step 2)
+    - `documentdb_extension_github_repo`: `<your-gh-user>/documentdb`
+    - `documentdb_gateway_image_repo`: `ghcr.io/<your-gh-user>/documentdb/documentdb-local`
+


Step 1 instructs passing documentdb_extension_github_repo and documentdb_gateway_image_repo inputs to RELEASE - Build DocumentDB Candidate Images, but .github/workflows/build_documentdb_images.yml currently only defines a version input and hardcodes DOCUMENTDB_RELEASE_REPO / GATEWAY_SOURCE_IMAGE_REPO. Either update the workflow to accept these inputs or adjust the guide to match the actual workflow behavior.

Suggested change

3. **In your operator fork**, run **Actions → `RELEASE - Build DocumentDB Candidate Images` → Run workflow**. Provide these inputs:

- `version`: `0.110.0` (or whatever you released in step 2)

- `documentdb_extension_github_repo`: `<your-gh-user>/documentdb`

- `documentdb_gateway_image_repo`: `ghcr.io/<your-gh-user>/documentdb/documentdb-local`

3. **In your operator fork**, run **Actions → `RELEASE - Build DocumentDB Candidate Images` → Run workflow**. Provide this input:

- `version`: `0.110.0` (or whatever you released in step 2)

The workflow currently only exposes `version` as a manual input. The DocumentDB release repository and gateway source image repository are set inside the workflow, so you do **not** need to provide `documentdb_extension_github_repo` or `documentdb_gateway_image_repo` when starting the run.

Copilot · 2026-04-24T20:06:18Z

+metadata:
+  name: dev-test
+  namespace: documentdb-test
+spec:
+  nodeCount: 1
+  instancesPerNode: 1
+  documentDbCredentialSecret: documentdb-credentials
+  documentDBImage: ghcr.io/<your-gh-user>/documentdb-kubernetes-operator/documentdb:0.110.0
+  gatewayImage:    ghcr.io/<your-gh-user>/documentdb-kubernetes-operator/gateway:0.110.0


The example DocumentDB manifest uses namespace: documentdb-test and references a credentials Secret, but the guide doesn’t include creating the namespace and documentdb-credentials Secret first. Add a short “create namespace + Secret” step (similar to docs/operator-public-documentation/preview/getting-started/quickstart-kind.md) to make the end-to-end flow runnable.

Copilot · 2026-04-24T20:06:18Z

+    ghcr.io/<your-gh-user>/documentdb-kubernetes-operator/documentdb:0.110.0
+    ghcr.io/<your-gh-user>/documentdb-kubernetes-operator/gateway:0.110.0
+    ```
+
+    (The actual published tag is the `image_tag` output computed by the workflow — usually `<version>-build-<run_id>-<attempt>-<sha>`. The workflow also retags it with the bare `<version>` for convenience; check the run summary.)


The example output tags in Step 1 (e.g. .../documentdb:0.110.0) and the note about the workflow retagging to the bare <version> don’t match the current build_documentdb_images.yml behavior: it produces only the computed image_tag (<version>-build-...) and does not retag to <version> (retagging happens in release_documentdb_images.yml). Please update the example image references and wording accordingly.

Suggested change

ghcr.io/<your-gh-user>/documentdb-kubernetes-operator/documentdb:0.110.0

ghcr.io/<your-gh-user>/documentdb-kubernetes-operator/gateway:0.110.0

```

(The actual published tag is the `image_tag` output computed by the workflow — usually `<version>-build-<run_id>-<attempt>-<sha>`. The workflow also retags it with the bare `<version>` for convenience; check the run summary.)

ghcr.io/<your-gh-user>/documentdb-kubernetes-operator/documentdb:0.110.0-build-<run_id>-<attempt>-<sha>

ghcr.io/<your-gh-user>/documentdb-kubernetes-operator/gateway:0.110.0-build-<run_id>-<attempt>-<sha>

```

(The workflow publishes the computed `image_tag` output — usually `<version>-build-<run_id>-<attempt>-<sha>`. It does not retag these candidate images to the bare `<version>`; that happens later in [`release_documentdb_images.yml`](../../.github/workflows/release_documentdb_images.yml). Check the run summary for the exact tag.)

Copilot · 2026-04-24T20:06:19Z

+The Helm chart in this repo (`operator/documentdb-helm-chart/`) lets you point each image at your fork via `--set` flags.
+
+```bash
+GH_USER=<your-gh-user>
+OP_TAG=0.2.0-tls-test-1-test            # from Step 2
+DB_TAG=0.110.0                          # from Step 1, or upstream e.g. 0.110.0


Step 3 says the Helm chart lets you point “each image” at your fork via --set flags, but the chart values only allow overriding operator/sidecar (and documentDbVersion), not the documentdb/gateway repositories (those are fixed in code unless overridden per-CR via spec.documentDBImage / spec.gatewayImage). Also DB_TAG is defined but unused in the Helm command. Please clarify what is controlled by Helm vs the DocumentDB CR, and either use or remove DB_TAG.

Suggested change

The Helm chart in this repo (`operator/documentdb-helm-chart/`) lets you point each image at your fork via `--set` flags.

```bash

GH_USER=<your-gh-user>

OP_TAG=0.2.0-tls-test-1-test # from Step 2

DB_TAG=0.110.0 # from Step 1, or upstream e.g. 0.110.0

The Helm chart in this repo (`operator/documentdb-helm-chart/`) lets you point the **operator** and **sidecar** images at your fork via `--set` flags. The `documentdb` and `gateway` container images are not redirected by this Helm command; if you need to test forked database images, set them on the `DocumentDB` custom resource with `spec.documentDBImage` and `spec.gatewayImage`.

```bash

GH_USER=<your-gh-user>

OP_TAG=0.2.0-tls-test-1-test # from Step 2

Copilot · 2026-04-24T20:06:19Z

+> **Helm doesn't auto-update CRDs**, so reapply them whenever the API types change:
+>
+> ```bash
+> kubectl apply -f operator/documentdb-helm-chart/crds/


In Step 3 you cd operator/documentdb-helm-chart, but the CRD reapply command uses operator/documentdb-helm-chart/crds/ (which will be a wrong path from inside that directory). Use ./crds/ (or explicitly state the command should be run from the repo root).

Suggested change

> kubectl apply -f operator/documentdb-helm-chart/crds/

> kubectl apply -f ./crds/

Copilot · 2026-04-24T20:06:19Z

+    ```
+- **Full reinstall**: `helm uninstall documentdb-operator -n documentdb-operator` then rerun the `helm upgrade --install` block above.
+
+If the CRD changed between iterations, reapply: `kubectl apply -f operator/documentdb-helm-chart/crds/`.


The iteration section repeats kubectl apply -f operator/documentdb-helm-chart/crds/. Depending on the reader’s current working directory (Step 3 cds into the chart), this path may be wrong. Consider using a consistent relative path (./crds/) or stating “from repo root”.

Suggested change

If the CRD changed between iterations, reapply: `kubectl apply -f operator/documentdb-helm-chart/crds/`.

If the CRD changed between iterations, reapply: `kubectl apply -f ./crds/`.

Copilot · 2026-04-24T20:06:19Z

+If your change is purely Go controller code, skip Step 1 entirely and use the upstream `0.110.0` (or any released) database images.
+


This guide hardcodes 0.110.0 in multiple places, but the repo defaults/workflow examples currently use 0.109.0 (e.g., operator/documentdb-helm-chart/values.yaml and build_documentdb_images.yml). Consider using placeholders (<version>) or referencing the current default to avoid the doc going stale.

Copilot · 2026-04-24T20:06:20Z

+- A Kubernetes cluster with cert-manager installed (`v1.13.2+`) and Kubernetes `1.35+`
+- `kubectl`, `helm 3.x`, `git`


The prerequisites list cert-manager as v1.13.2+, but the rest of the repo docs/version matrix call out cert-manager 1.19+ (e.g. docs/operator-public-documentation/preview/getting-started/before-you-start.md, AGENTS.md). Please align this guide’s minimum cert-manager version (and consider noting the container runtime requirement for ImageVolume: containerd/CRI-O; Docker runtime won’t work).

Suggested change

- A Kubernetes cluster with cert-manager installed (`v1.13.2+`) and Kubernetes `1.35+`

- `kubectl`, `helm 3.x`, `git`

- A Kubernetes cluster with cert-manager installed (`v1.19+`) and Kubernetes `1.35+`

- `kubectl`, `helm 3.x`, `git`

- If your test path uses `ImageVolume`, use a cluster runtime backed by `containerd` or `CRI-O`; Docker runtime will not work.

Copilot · 2026-04-24T20:06:20Z

+    ```bash
+    TOKEN=$(curl -s "https://ghcr.io/token?service=ghcr.io&scope=repository:<your-gh-user>/documentdb-kubernetes-operator/operator:pull" | jq -r .token)
+    curl -sI -H "Authorization: Bearer $TOKEN" \
+      https://ghcr.io/v2/<your-gh-user>/documentdb-kubernetes-operator/operator/manifests/0.2.0-tls-test-1-test \
+      | head -3


This GHCR tag verification snippet uses curl and jq, but those tools aren’t listed in the prerequisites. Add them (or adjust the snippet) so readers don’t hit missing-command errors.

documentdb-triage-tool · 2026-04-25T19:24:11Z

🤖 Auto-triaged by documentdb-triage-tool.

Applied: documentation, enhancement
Project fields suggested: Component docs · Priority P3 · Effort M · Status Needs Review
Confidence: 0.60 (mixed)

Reasoning

component from path globs (docs); effort from diff stats (181+0 LOC, 1 files); LLM: PR adds testing guidelines documentation with no body details, likely a small markdown addition covering fork repo workflows.

If a label is wrong, remove it manually and ping @patty-chow so the rules can be tuned. The bot will not re-label items that already have component labels.

Add testing guidelines with fork repos

e6e81c5

Signed-off-by: Rayhan Hossain <rhossain@microsoft.com>

Copilot AI review requested due to automatic review settings April 24, 2026 20:00

hossain-rayhan requested review from WentingWu666666, alaye-ms and xgerman as code owners April 24, 2026 20:00

Copilot started reviewing on behalf of hossain-rayhan April 24, 2026 20:02 View session

Copilot AI reviewed Apr 24, 2026

View reviewed changes

documentdb-triage-tool Bot added documentation Improvements or additions to documentation enhancement New feature or request labels Apr 25, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add testing guidelines with fork repos#358

Add testing guidelines with fork repos#358
hossain-rayhan wants to merge 1 commit intodocumentdb:mainfrom
hossain-rayhan:rayhan/testing-with-fork-images

hossain-rayhan commented Apr 24, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 24, 2026

Uh oh!

Copilot AI Apr 24, 2026

Uh oh!

Copilot AI Apr 24, 2026

Uh oh!

Copilot AI Apr 24, 2026

Uh oh!

Copilot AI Apr 24, 2026

Uh oh!

Copilot AI Apr 24, 2026

Uh oh!

Copilot AI Apr 24, 2026

Uh oh!

Copilot AI Apr 24, 2026

Uh oh!

Copilot AI Apr 24, 2026

Uh oh!

documentdb-triage-tool Bot commented Apr 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	> kubectl apply -f operator/documentdb-helm-chart/crds/
	> kubectl apply -f ./crds/

	If the CRD changed between iterations, reapply: `kubectl apply -f operator/documentdb-helm-chart/crds/`.
	If the CRD changed between iterations, reapply: `kubectl apply -f ./crds/`.

		If your change is purely Go controller code, skip Step 1 entirely and use the upstream `0.110.0` (or any released) database images.

		- A Kubernetes cluster with cert-manager installed (`v1.13.2+`) and Kubernetes `1.35+`
		- `kubectl`, `helm 3.x`, `git`

Conversation

hossain-rayhan commented Apr 24, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

documentdb-triage-tool Bot commented Apr 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants