Skip to content

docs: port-forward snippets target a specific Pod instead of the gateway Service #355

@xgerman

Description

@xgerman

Summary

Four getting-started / quickstart docs instruct users to port-forward a specific numbered Pod (pod/<cr-name>-1) to reach the DocumentDB gateway. This is wrong for any cluster with instancesPerNode > 1 and also breaks when the named pod is rotated.

The operator creates a stable Service (documentdb-service-<cr-name>) that selects the current primary. All docs should consistently point users at the Service.

Affected files

  • docs/operator-public-documentation/preview/getting-started/connecting-to-documentdb.md:69
  • docs/operator-public-documentation/preview/getting-started/quickstart-kind.md:167
  • docs/operator-public-documentation/preview/getting-started/quickstart-k3s.md:176
  • docs/operator-public-documentation/preview/index.md:194

Each contains a variant of:

kubectl port-forward pod/my-documentdb-1 10260:10260 -n documentdb-ns

Why this is wrong

  1. HA correctness. With multiple replicas, <cr-name>-1 may be a hot standby — users will hit a read-only member unpredictably.
  2. Survives pod churn. A rolling restart or failover evicts that specific pod and the port-forward dies. The Service is stable across failovers.
  3. Contradicts other parts of the same docs. connecting-to-documentdb.md explicitly advises users to "Get the connection string from the DocumentDB cluster status", which the operator sets to the Service DNS name. Then two sections later, the port-forward snippet pins the user to a specific pod.
  4. Inconsistent with other docs and the e2e test suite. configuration/networking.md, multi-region-deployment/failover-procedures.md, and test/e2e/pkg/e2eutils/portforward/portforward.go all correctly forward to the Service.

Proposed fix

Replace each occurrence with:

kubectl port-forward svc/documentdb-service-<cr-name> 10260:10260 -n documentdb-ns

(For index.md that's svc/documentdb-service-documentdb-preview; for the quickstarts it's svc/documentdb-service-my-documentdb.)

Reference: e2e helper comment

The e2e port-forward helper already documents the correct contract:

The DocumentDB operator creates a Service named documentdb-service-<dd.Name> in the same namespace as the CR, with a port named gateway targeting the gateway sidecar (default port 10260).

Source: test/e2e/pkg/e2eutils/portforward/portforward.go:5-9.

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type

Projects

Status

Backlog

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions