docs: add configuration documentation guides

[WentingWu666666]

Summary

Adds comprehensive configuration documentation for the DocumentDB Kubernetes Operator, covering TLS, storage, networking, and resource management. This replaces scattered configuration details with organized, cross-linked guides that follow Material for MkDocs best practices.

Changes

New documentation pages

• configuration/tls.md TLS modes (Disabled/SelfSigned/CertManager/Provided), certificate rotation, Azure Key Vault integration, and troubleshooting
• configuration/storage.md Storage classes by provider, PVC sizing, volume expansion, reclaim policies, benchmarking, and disk encryption (AKS/EKS/GKE)
• configuration/networking.md Service types (ClusterIP/LoadBalancer), cloud-specific LB annotations, DNS configuration, and Network Policies
• configuration/resource-management.md CPU/memory sizing, QoS classes, workload profiles (dev/prod/high-load), and monitoring
• configuration/cluster-configuration.md Guided CRD overview with full spec YAML, field tables, and cross-references

Documentation improvements

• Reorganize mkdocs.yml nav with Configuration section and sub-items
• Add Material for MkDocs features (tabs, code copy, admonitions, annotations)
• Cross-link all config guides to auto-generated API Reference
• Remove redundant Backup/ScheduledBackup from cluster-configuration.md (already in backup-and-restore.md and api-reference.md)
• Slim down index.md Configuration section with links to new guides
• Add "Further reading" section and FAQ entry pointing to API Reference
• Add .gitignore entry for MkDocs site/ build output

Testing

• Verified all internal cross-links between config guides and API Reference
• Built docs locally with mkdocs serve all pages render correctly
• Verified Material for MkDocs tabs, admonitions, and code annotations work

Checklist

• Code follows project conventions
• No unintended debug code or TODOs left in
• Documentation is cross-linked and consistent

Related Issues

Refs #248

[Copilot]

Pull request overview

This PR reorganizes and expands the operator’s public documentation by introducing a dedicated “Configuration” section (TLS, storage, networking, resource management, and CRD walkthrough) and wiring it into the MkDocs Material site structure.

Changes:

• Add new configuration guides under docs/operator-public-documentation/preview/configuration/ and link them from the docs landing pages.
• Update mkdocs.yml navigation and enable additional Material/MkDocs markdown features (tabs, annotations, etc.).
• Add cross-references from existing docs (index/FAQ/backup/advanced-configuration) to the new guides and API reference.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
mkdocs.yml	Adds MkDocs Material features, markdown extensions, and a new “Configuration” nav subtree.
docs/operator-public-documentation/preview/index.md	Replaces scattered config snippets with links to the new configuration guides.
docs/operator-public-documentation/preview/faq.md	Adds FAQ entry pointing to API Reference + Cluster Configuration guide.
docs/operator-public-documentation/preview/configuration/tls.md	New TLS guide (modes, rotation/monitoring, troubleshooting, Key Vault notes).
docs/operator-public-documentation/preview/configuration/storage.md	New storage guide (classes, sizing, expansion, reclaim policy, encryption).
docs/operator-public-documentation/preview/configuration/networking.md	New networking guide (service types, DNS, annotations, NetworkPolicy examples).
docs/operator-public-documentation/preview/configuration/resource-management.md	New resource sizing/QoS/monitoring guide and workload profiles.
docs/operator-public-documentation/preview/configuration/cluster-configuration.md	New guided CRD overview with YAML + field tables and links to API reference.
docs/operator-public-documentation/preview/backup-and-restore.md	Adds a tip linking to the API Reference section for Backup CRDs.
docs/operator-public-documentation/preview/advanced-configuration/README.md	Removes duplicated config sections and points readers to the new guides.
.gitignore	Ignores MkDocs site/ build output.

[Copilot]

The label selector app.kubernetes.io/name=documentdb likely won’t match DocumentDB/CNPG pods created by the operator. The operator’s Service selector uses app: <documentdb-name> (plus cnpg.io/instanceRole=primary), so these examples should use -l app=<cluster-name> (or document the correct labels) to make the commands work.

Suggested change

	# View resource usage for DocumentDB pods
	kubectl top pods -n default -l app.kubernetes.io/name=documentdb
	# View resource usage for primary DocumentDB pods (replace <cluster-name> with your DocumentDB cluster name)
	kubectl top pods -n default -l app=<cluster-name>,cnpg.io/instanceRole=primary

[Copilot]

Docs state that Provided mode requires ca.crt, but the operator currently only validates presence of tls.crt and tls.key on the Secret. Either update the docs to clarify ca.crt is required for client verification (but not enforced by the operator), or update the operator behavior/validation to match the documented requirement.

Suggested change

	- **Provided mode**: A Kubernetes TLS Secret containing `tls.crt`, `tls.key`, and `ca.crt`
	- **Provided mode**: A Kubernetes TLS Secret containing `tls.crt` and `tls.key` (required by the operator). Include `ca.crt` if clients need a CA bundle for server certificate verification; the operator does not enforce its presence.

[Copilot]

These NetworkPolicy examples select pods via app.kubernetes.io/name: documentdb, but the operator-created Service targets pods labeled app: <documentdb-name> (and CNPG sets cnpg.io/instanceRole). Update the podSelector.matchLabels to use the labels actually applied to the database pods so the policies affect the intended workloads.

Suggested change

	app.kubernetes.io/name: documentdb
	app: <documentdb-name> # Matches the app label on DocumentDB pods
	cnpg.io/instanceRole: primary # Target the primary instance role

[Copilot]

This NetworkPolicy uses app.kubernetes.io/name: documentdb in the pod selector; it likely won’t match the operator-managed database pods (which are labeled with app: <documentdb-name>). Adjust the selector (and placeholders) so the policy actually applies to the intended DocumentDB pods.

[Copilot]

The inter-pod NetworkPolicy example uses app.kubernetes.io/name: documentdb for both selectors, but operator-managed CNPG pods are selected by app: <documentdb-name> (and roles via cnpg.io/instanceRole). Update the selectors so the policy actually permits traffic among the correct pods.

[Copilot]

The Secret name here is hard-coded as documentdb-gateway-cert-tls, but the operator’s cert-manager Secret name is derived from the DocumentDB name (for my-documentdb, it would be my-documentdb-gateway-cert-tls unless overridden). Update the example to use the correct name/pattern so the command works as-written.

Suggested change

	kubectl get secret documentdb-gateway-cert-tls -n default \
	kubectl get secret my-documentdb-gateway-cert-tls -n default \

[Copilot]

This link is labeled “Configuration Guides” and the description lists multiple guides, but it points specifically to the TLS page. Consider linking to a more general configuration landing page (e.g., Cluster Configuration) or renaming the link text to reflect that it goes to TLS.

Suggested change

	- [Configuration Guides](../configuration/tls.md) — TLS, Storage, Networking, and Resource Management
	- [TLS Configuration Guide](../configuration/tls.md) — TLS modes, certificate rotation, and troubleshooting

[Copilot]

The link text “Configuration” points directly to the TLS page, which is only one of the configuration guides listed below. Consider linking to a more general entry point (e.g., Cluster Configuration) or adjusting the link text to “TLS configuration” to avoid implying it’s a configuration overview.

[Copilot]

The note implies that running 3 instances results in Guaranteed QoS, but QoS class is determined by CPU/memory requests and limits (requests==limits => Guaranteed), not by replica count. Consider rewording this note to describe HA/failover benefits, and keep QoS guidance tied to resource requests/limits.

Suggested change

	1. Three instances provide Guaranteed QoS with one primary and two replicas for automatic failover.
	1. Three instances provide high availability with one primary and two replicas for automatic failover.

[Copilot]

The tls.gateway.mode setting documents Disabled as the default ("Disabled" (default)), which means new DocumentDB clusters are created with TLS turned off unless users explicitly opt in. This default leaves database credentials and data in transit unencrypted by default, so anyone with network access to the gateway service (e.g., via a LoadBalancer or compromised pod) can passively capture or tamper with traffic. Consider making a secure mode (such as SelfSigned or another TLS-enabled option) the default and requiring an explicit opt-out for non-production use, so production deployments are not left without transport encryption by mistake.

Suggested change

	| `Disabled` (default) | No TLS encryption | Development and testing only |
	| `SelfSigned` | Automatic certificates via cert-manager with a self-signed CA | Development, testing, and environments without external PKI (Public Key Infrastructure) |
	| `Disabled` | No TLS encryption (not recommended; must be explicitly opted into) | Development and testing only, never production |
	| `SelfSigned` (default) | Automatic certificates via cert-manager with a self-signed CA | Development, testing, and secure-by-default environments without external PKI (Public Key Infrastructure) |