Setup DocumentDB with AKS Edge + Azure Arc#281
Setup DocumentDB with AKS Edge + Azure Arc#281hossain-rayhan wants to merge 1 commit intodocumentdb:mainfrom
Conversation
Signed-off-by: Rayhan Hossain <rhossain@microsoft.com>
There was a problem hiding this comment.
Pull request overview
This PR adds documentation for deploying DocumentDB on AKS Edge Essentials (K3s on Windows) with Azure Arc integration, enabling Azure Portal visibility for on-premises clusters.
Changes:
- Adds a comprehensive step-by-step README for end users covering installation, configuration, and troubleshooting
- Adds an AGENT-INSTRUCTIONS.md guide for AI-assisted setup workflows
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
documentdb-playground/aks-edge-setup/README.md |
Full user-facing guide covering all phases from AKS Edge installation to Azure Arc connection and cleanup |
documentdb-playground/aks-edge-setup/AGENT-INSTRUCTIONS.md |
Copilot agent guide mirroring the README phases with agent-specific behavior instructions |
| # Expected: demo-documentdb-1 2/2 Running 0 3m | ||
| ``` | ||
|
|
||
| ### Phase 7: Connect to Azure Arc |
There was a problem hiding this comment.
There are two sections labeled 'Phase 7' — the first at line 389 ('Deploy DocumentDB Instance') and the second at line 442 ('Connect to Azure Arc'). The Azure Arc phase should be renumbered to 'Phase 8', and all subsequent phases (Verification, etc.) should be renumbered accordingly to maintain a consistent, sequential numbering scheme.
| ### Phase 7: Connect to Azure Arc | |
| ### Phase 8: Connect to Azure Arc |
| ```powershell | ||
| # Variables | ||
| $RESOURCE_GROUP = "aks-edge-rg" | ||
| $LOCATION = "eastus" |
There was a problem hiding this comment.
In Phase 2.5, the $LOCATION variable is set to \"westus2\", but in the 'Connect Cluster to Azure Arc' section (Phase 7), it is hardcoded as \"eastus\". If a user follows both sections, the resource group and Arc cluster could be created in different locations, leading to confusion. This value should reference the same $LOCATION variable defined in Phase 2.5, or at minimum include a note to keep it consistent.
| $LOCATION = "eastus" |
| kubectl create secret generic documentdb-credentials ` | ||
| --namespace app-namespace ` | ||
| --from-literal=username=docdbuser ` | ||
| --from-literal=password=YourSecurePassword123! |
There was a problem hiding this comment.
The example password YourSecurePassword123! is used both when creating the secret and later in the mongosh connection string (line 534). Embedding a plaintext example password in a connection string that users may copy and run is a security anti-pattern. Consider replacing the connection string's password field with a placeholder like <your-password> to discourage copying credentials verbatim.
| --from-literal=password=YourSecurePassword123! | |
| --from-literal=password=<your-password> |
| kubectl create clusterrolebinding arc-portal-viewer-binding ` | ||
| --clusterrole=cluster-admin ` | ||
| --serviceaccount=default:arc-portal-viewer |
There was a problem hiding this comment.
The portal viewer service account is bound to cluster-admin, which grants full cluster access. For read-only portal visibility, a least-privilege role (e.g., view or a custom read-only ClusterRole) should be used instead. If cluster-admin is intentional for demonstration purposes, a clear warning about the security implications should be added.
| # Verify connection | ||
| ### Phase 8: Create Portal Access Token |
There was a problem hiding this comment.
Lines 399–400 contain a duplicate heading and a stray comment. The comment # Verify connection on line 399 appears to be an editing artifact, and ### Phase 8: Create Portal Access Token is repeated on both line 399 (as a fragment) and line 400 (as the actual heading). The stray line 399 should be removed.
| kubectl create clusterrolebinding arc-portal-viewer-binding ` | ||
| --clusterrole=cluster-admin ` | ||
| --serviceaccount=default:arc-portal-viewer |
There was a problem hiding this comment.
Same as in README.md: the portal viewer service account is granted cluster-admin. This is overly permissive for a read-only portal access token. A least-privilege role should be used, or a clear security warning should be added noting the risks of this binding.
|
|
||
| ### Why This Setup? | ||
|
|
||
| - **On-prem Kubernetes**: Run K8s on your Windows workstation without cloud costs |
There was a problem hiding this comment.
I think this is a little misleading, since it does cost money to run this
| # Control Panel → Programs → Uninstall AKS Edge Essentials | ||
| ``` | ||
|
|
||
| ## Success Criteria |
There was a problem hiding this comment.
This section seems more agent-oriented, can we move it to the other file?
Summary
Adds documentation for deploying DocumentDB on AKS Edge Essentials - a lightweight K3s-based Kubernetes distribution for Windows machines with Azure Arc integration for portal visibility.
What's Included
README.md: Step-by-step guide covering:
Key Features
Run DocumentDB on any Windows workstation (no cloud costs)
View on-prem cluster + workloads in Azure Portal via Arc
Ideal for dev/test and hybrid scenarios