Conversation
Add three new getting-started guides per issue documentdb#247: - quickstart-kind.md: Local development with Kind, including local registry setup for operator development - quickstart-k3s.md: Lightweight K3s deployment for edge and resource-constrained environments, with ServiceLB support - connecting-to-documentdb.md: Connection strings, driver examples (Python, Node.js, Go, Java), connection pooling best practices, TLS configuration, and troubleshooting All guides verified against source code for technical accuracy: - Port 10260 (gateway), K8s 1.35+ requirement, connection string format, service naming (documentdb-service-<name>), TLS modes, credential Secret structure Closes documentdb#247 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
… guides Show users how to retrieve the connection string from the DocumentDB cluster status output instead of only hardcoding credentials. The CONNECTION STRING column in 'kubectl get documentdb' output provides the canonical connection string with embedded credential resolution. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…DNS details Replace the thin multi-cloud DNS note with a full section covering: - Istio multi-cluster mesh (east-west gateways, remote secrets) - Azure Fleet networking (ServiceExport/MultiClusterService, fleet-system DNS) - Azure DNS zone with A/CNAME per cluster and SRV record for mongodb+srv:// Uses content tabs for Istio vs Fleet strategies and a collapsible tip for the Azure DNS production setup. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add a section for the DocumentDB for VS Code extension with install link, connection string entry, and a tip for devcontainer users. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Testing against a real DocumentDB cluster revealed two issues:
Go driver:
- replicaSet=rs0 + directConnection=true causes empty topology
- tlsAllowInvalidCertificates URI param insufficient; need SetTLSConfig()
- Fixed: use explicit tls.Config{InsecureSkipVerify: true}
Java driver:
- tlsAllowInvalidCertificates URI param ignored by JVM SSL stack
- replicaSet=rs0 + directConnection=true causes connection timeout
- Fixed: use explicit SSLContext with trust-all TrustManager
All four drivers (Python, Node.js, Go, Java) now verified working
against a live DocumentDB cluster on Kind.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Replace crds.install=true with installCRDs=true in Kind and K3s quickstarts to match existing docs and cert-manager chart defaults - Fix TLS wording: 'always serves TLS' -> 'serves TLS by default' since the Disabled mode exists (Threads 3 & 4) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Updates the public “Preview” documentation site navigation and adds new getting-started guides to help users deploy and connect to DocumentDB in local Kubernetes environments.
Changes:
- Restructures the Preview docs navigation (adds “Home”, groups “Operations”, adds new quickstarts and connection guide).
- Adds new Quickstart guides for Kind and K3s.
- Adds a new “Connecting to DocumentDB” guide with mongosh and driver examples.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
mkdocs.yml |
Updates nav structure and links to the new getting-started pages. |
docs/operator-public-documentation/preview/getting-started/quickstart-kind.md |
New local dev quickstart using Kind, including install/deploy/connect steps. |
docs/operator-public-documentation/preview/getting-started/quickstart-k3s.md |
New lightweight K3s quickstart, including LoadBalancer option and sizing notes. |
docs/operator-public-documentation/preview/getting-started/connecting-to-documentdb.md |
New connectivity guide with access methods, TLS notes, and driver examples. |
| For `LoadBalancer` services, the gateway is reachable through the external IP: | ||
|
|
||
| ```bash | ||
| kubectl get svc documentdb-service-my-documentdb -n documentdb-ns \ | ||
| -o jsonpath='{.status.loadBalancer.ingress[0].ip}' |
There was a problem hiding this comment.
The LoadBalancer access example only reads .status.loadBalancer.ingress[0].ip, but many environments (notably AWS/EKS) populate hostname instead of ip. As written, this command can return an empty value even when the service is ready; consider documenting a hostname fallback (or a jsonpath that selects either field).
| For `LoadBalancer` services, the gateway is reachable through the external IP: | |
| ```bash | |
| kubectl get svc documentdb-service-my-documentdb -n documentdb-ns \ | |
| -o jsonpath='{.status.loadBalancer.ingress[0].ip}' | |
| For `LoadBalancer` services, the gateway is reachable through the external IP or hostname: | |
| ```bash | |
| kubectl get svc documentdb-service-my-documentdb -n documentdb-ns \ | |
| -o jsonpath='{.status.loadBalancer.ingress[0].ip}{.status.loadBalancer.ingress[0].hostname}' |
| The `CONNECTION STRING` column in `kubectl get documentdb` output contains embedded `kubectl` commands that extract the username and password from the credentials Secret at runtime. You can copy and `eval` the full string, or substitute your known credentials directly as shown above. | ||
|
|
There was a problem hiding this comment.
This section suggests copying the status connection string and using eval. Since the status field is effectively a shell snippet (it contains command substitutions), recommending eval can train users into unsafe patterns. Consider removing the eval suggestion and instead show a safe way to resolve username/password (like the explicit kubectl get secret ... | base64 -d approach).
| The `CONNECTION STRING` column in `kubectl get documentdb` output contains embedded `kubectl` commands that extract the username and password from the credentials Secret at runtime. You can copy and `eval` the full string, or substitute your known credentials directly as shown above. | |
| The `CONNECTION STRING` column in `kubectl get documentdb` output contains embedded `kubectl` commands that extract the username and password from the credentials Secret at runtime. Instead of using `eval` on the full string, copy and run the credential lookups explicitly, for example: | |
| ```bash | |
| # Example: resolve username and password from the credentials Secret | |
| kubectl get secret <credentials-secret-name> -n documentdb-ns -o jsonpath='{.data.username}' | base64 -d | |
| kubectl get secret <credentials-secret-name> -n documentdb-ns -o jsonpath='{.data.password}' | base64 -d | |
| ``` | |
| Then plug the resolved values into your `mongosh` connection string as shown above. |
| Install K3s with the required Kubernetes version: | ||
|
|
||
| ```bash | ||
| curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION="v1.35.0+k3s1" sh - |
There was a problem hiding this comment.
The K3s install command is shown without sudo/root context. On most systems the installer needs root privileges (writes to /usr/local, /etc, systemd). Consider adding sudo (or explicitly stating the command must be run as root) to avoid a copy/paste failure.
| Install K3s with the required Kubernetes version: | |
| ```bash | |
| curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION="v1.35.0+k3s1" sh - | |
| Install K3s with the required Kubernetes version (requires root privileges, for example via `sudo`): | |
| ```bash | |
| curl -sfL https://get.k3s.io | sudo INSTALL_K3S_VERSION="v1.35.0+k3s1" sh - |
| type: Opaque | ||
| stringData: | ||
| username: dev_user | ||
| password: DevPassword123 | ||
| EOF |
There was a problem hiding this comment.
The example Secret uses a hard-coded password (DevPassword123). Since this is a quickstart, it would help to explicitly call out that users should replace it with a strong unique password and avoid reusing it beyond local dev/testing.
| password: DevPassword123 | ||
| EOF | ||
| ``` | ||
|
|
There was a problem hiding this comment.
The example Secret uses a hard-coded password (DevPassword123). Consider adding a short warning that this is an example only and users should replace it with a strong unique password (especially if they expose the service via LoadBalancer).
| > **Important:** The `DevPassword123` value above is for example purposes only. Before using this in any real environment, replace it with a strong, unique password (especially if you expose the service externally, for example via a `LoadBalancer` Service). |
| ``` | ||
|
|
||
| !!! note "Go driver and `replicaSet`" | ||
| Do not include `replicaSet=rs0` in the URI when using `directConnection=true` with the Go driver. The combination creates a conflicting topology configuration that prevents the driver from connecting. The `directConnection=true` parameter alone is sufficient. |
There was a problem hiding this comment.
This note says not to include replicaSet=rs0 when using directConnection=true with the Go driver, but earlier the doc recommends using the operator-generated .status.connectionString (which includes replicaSet=rs0). Please reconcile these instructions (e.g., explain that Go users may need to remove replicaSet when starting from the status string, or adjust/remove the note if it’s not accurate).
| Do not include `replicaSet=rs0` in the URI when using `directConnection=true` with the Go driver. The combination creates a conflicting topology configuration that prevents the driver from connecting. The `directConnection=true` parameter alone is sufficient. | |
| When using the Go driver with `directConnection=true`, do not include `replicaSet=rs0` in the URI. This combination can create a conflicting topology configuration that prevents the driver from connecting, and `directConnection=true` alone is sufficient. If you start from the operator-generated `.status.connectionString` (which includes `replicaSet=rs0`), remove the `replicaSet` parameter before adding `directConnection=true` for Go. |
Tested and Rebased PR 302