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
- HA correctness. With multiple replicas,
<cr-name>-1 may be a hot standby — users will hit a read-only member unpredictably.
- Survives pod churn. A rolling restart or failover evicts that specific pod and the port-forward dies. The Service is stable across failovers.
- 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.
- 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.
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 withinstancesPerNode > 1and 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:69docs/operator-public-documentation/preview/getting-started/quickstart-kind.md:167docs/operator-public-documentation/preview/getting-started/quickstart-k3s.md:176docs/operator-public-documentation/preview/index.md:194Each contains a variant of:
Why this is wrong
<cr-name>-1may be a hot standby — users will hit a read-only member unpredictably.connecting-to-documentdb.mdexplicitly 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.configuration/networking.md,multi-region-deployment/failover-procedures.md, andtest/e2e/pkg/e2eutils/portforward/portforward.goall correctly forward to the Service.Proposed fix
Replace each occurrence with:
(For
index.mdthat'ssvc/documentdb-service-documentdb-preview; for the quickstarts it'ssvc/documentdb-service-my-documentdb.)Reference: e2e helper comment
The e2e port-forward helper already documents the correct contract:
Source:
test/e2e/pkg/e2eutils/portforward/portforward.go:5-9.