docs: add gateway connection integration guide#126
Open
prjhawar wants to merge 3 commits into
Open
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds a new end-to-end documentation guide for integrating Connector Namespace resources (API connections and MCP server configs) into ACA sandbox groups/sandboxes via gatewayConnections[], including setup steps, in-sandbox consumption, operation discovery, and troubleshooting guidance.
Changes:
- Add a new integration guide describing gateway connection wiring (ACLs + sandbox-group/sandbox configuration).
- Document in-sandbox usage via
/connections/connections.jsonand how runtime URL auth is handled. - Add quick-reference endpoints/commands plus troubleshooting and access policy matrix.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
rarayudu
reviewed
Jun 4, 2026
| 2. Connections and MCP server configs are wired to a **sandbox group** via its | ||
| `gatewayConnections[]` property. | ||
| 3. Each **sandbox** references the same gateway connections at creation time. | ||
| 4. The platform generates `/connections/connections.json` inside the sandbox |
Collaborator
There was a problem hiding this comment.
Should we also add add the path about where this file is? is /Connections folder at root location?
| 2. Connections and MCP server configs are wired to a **sandbox group** via its | ||
| `gatewayConnections[]` property. | ||
| 3. Each **sandbox** references the same gateway connections at creation time. | ||
| 4. The platform generates `/connections/connections.json` inside the sandbox |
Collaborator
There was a problem hiding this comment.
Can we also add where the mcp config is ?
| } | ||
| ``` | ||
|
|
||
| ### CLI alternative (ACA CLI) |
Collaborator
There was a problem hiding this comment.
What is this alternative for? I dont see any section of Portal / API based approach above
|
|
||
| - Maximum **10** gateway connections per sandbox. | ||
| - All connections must reference the **same** connector gateway. | ||
| - All connections must use the **same** authentication type. |
Collaborator
There was a problem hiding this comment.
is this a restriction we enforce?
| teams = response.json()["value"] | ||
| ``` | ||
|
|
||
| ### How the egress proxy handles auth |
Collaborator
There was a problem hiding this comment.
this section has duplicate information that is already mentioned / shared in before sections
| - All connections must use the **same** authentication type. | ||
| - `SystemAssignedManagedIdentity` requires the sandbox group to have a system-assigned MI. | ||
| - Gateway connections on sandboxes are **immutable** — set at creation, cannot be changed. | ||
| - MCP server config connections are only supported with `copilot` or `claude` disk images, private disk images, or snapshots. |
Collaborator
There was a problem hiding this comment.
Should we also mention about the skill we have on sandboxes?
|
|
||
| --- | ||
|
|
||
| ## Access policies |
Collaborator
There was a problem hiding this comment.
I feel the sections are not properly ordered - should this be before the section of how to use from sandboxes?
Comprehensive doc covering setup (gatewayConnections wiring, ACLs, CLI), consumption (/connections/connections.json, egress proxy auth), operation discovery (metadata URL), MCP server configs, and available skills. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Fix wiring checklist to mention both connectionRuntimeUrl and mcpRuntimeUrl - Add note about aca CLI --connection-id availability with az rest fallback - Fix mcpServerConfigs casing to match canonical ARM path (camelCase) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Step 4 (How it works): document /connections/connections.json and /root/.copilot/mcp-config.json with which file is for what (verified against InstanceManager.cs in ADC) - Step 5 (How it works): clarify managed identity can be system-assigned or user-assigned - Rename 'CLI alternative (ACA CLI)' -> 'ACA CLI' with bridging text explaining its relationship to the ARM PATCH above - Validation rules: add preamble noting these are platform-enforced; expand auth-type rule to cover both SystemAssignedManagedIdentity and UserAssignedManagedIdentity (with identityResourceId requirement) - Wiring checklist row 4: broaden MI wording to system/user-assigned - gatewayConnections[] entry shape: add UserAssignedManagedIdentity JSON example alongside the system-assigned one - Move Access policies section before Consumption for better ordering - Remove duplicate 'How the egress proxy handles auth' subsection (content already covered in How it works step 5) Addresses review comments from @rarayudu on PR #126. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
prjhawar
force-pushed
the
docs/sandbox-connector-integration
branch
from
ad4d331 to
abb1f83
Compare
Comment on lines
+90
to
+108
| ```bash | ||
| # Add a gateway connection to a sandbox group (creates ACLs automatically) | ||
| aca sandboxgroup connector add \ | ||
| --group {sg} \ | ||
| --connection-id {arm-resource-id} \ | ||
| --authorization system | ||
|
|
||
| # List configured connections on a sandbox group | ||
| aca sandboxgroup connector list --group {sg} | ||
|
|
||
| # Create sandbox with gateway connections (must already be configured on the group) | ||
| aca sandbox create --disk copilot \ | ||
| --connection-id {resource-id-1} {resource-id-2} | ||
| ``` | ||
|
|
||
| > **Note:** `aca sandbox create --connection-id` passes `gatewayConnections` in | ||
| > the data-plane request. If the ACA CLI version does not support this flag, | ||
| > use `az rest` with a data-plane PUT instead — see | ||
| > [gateway-connections.md](../plugin/skills/aca-sandboxes/references/gateway-connections.md) Step 5. |
Comment on lines
+262
to
+263
| # List connections on a namespace | ||
| az rest --method GET --url ".../connectorGateways/{ns}/connections?api-version=2026-05-01-preview" |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a doc covering end-to-end gateway connection integration with ACA sandboxes: