From d687faaac7e20d894705cf6a83787034c9bc101a Mon Sep 17 00:00:00 2001 From: dipeshpandit12 Date: Wed, 15 Jul 2026 17:15:42 -0500 Subject: [PATCH 1/2] docs: document runtime network endpoints azd contacts (#4415) Add docs/reference/network-endpoints.md cataloguing the external hosts azd may contact at runtime (control plane, auth, telemetry, tool downloads, templates, extensions, self-update, CI/CD), plus a minimum allowlist for firewalled environments. Link it from the docs Reference index and add the new host-name terms to the misc cspell dictionary. Fixes #4415 --- .vscode/cspell.misc.yaml | 7 + docs/README.md | 1 + docs/reference/network-endpoints.md | 270 ++++++++++++++++++++++++++++ 3 files changed, 278 insertions(+) create mode 100644 docs/reference/network-endpoints.md diff --git a/.vscode/cspell.misc.yaml b/.vscode/cspell.misc.yaml index 4517fcbdac0..8af2d07f73c 100644 --- a/.vscode/cspell.misc.yaml +++ b/.vscode/cspell.misc.yaml @@ -118,7 +118,10 @@ overrides: words: - appinit - appservice + - buildpack - Buildpacks + - centralus + - chinacloudapi - containerapp - dcount - dependson @@ -128,11 +131,14 @@ overrides: - exegraph - firstrun - javac + - livediagnostics + - microsoftonline - oneauth - postprovision - preprovision - postdeploy - pseudonymized + - redirector - remotebuild - resourcegroup - springapp @@ -141,5 +147,6 @@ overrides: - toreal - tostring - unhashed + - usgovcloudapi - vsrpc - whatif diff --git a/docs/README.md b/docs/README.md index a36a0eff4fe..62ed080bf87 100644 --- a/docs/README.md +++ b/docs/README.md @@ -33,6 +33,7 @@ Schemas, flags, environment variables, and configuration details. - [azure.yaml Schema](reference/azure-yaml-schema.md) — Project configuration file reference - [Feature Status](reference/feature-status.md) — Current maturity status of all features - [Telemetry Data Reference](reference/telemetry-data.md) — Complete schema of all telemetry events and fields +- [Network Endpoints](reference/network-endpoints.md) — External hosts `azd` contacts at runtime (for firewall allowlisting) ## Architecture diff --git a/docs/reference/network-endpoints.md b/docs/reference/network-endpoints.md new file mode 100644 index 00000000000..d089eefe076 --- /dev/null +++ b/docs/reference/network-endpoints.md @@ -0,0 +1,270 @@ +# Network Endpoints Reference — Hosts `azd` Connects To + +> The external hosts and endpoints the Azure Developer CLI (`azd`) may contact at +> runtime. Use this to configure firewalls, proxies, or other traffic-filtering +> systems when running `azd` in a restricted network environment. + +Every host below is derived from constants in the `azd` source. Endpoints that +depend on the target Azure cloud (public, US Government, China) are listed per +cloud in [Azure control plane](#1-azure-control-plane-per-cloud). Host names that +contain `<...>` are constructed at runtime from user- or resource-specific values. + +> [!NOTE] +> Not every command contacts every host. `azd` only reaches a host when the +> corresponding feature runs — for example, template hosts are only contacted by +> `azd init`, and tool-download hosts only when a required CLI is missing. The +> [minimum allowlist](#minimum-allowlist-public-cloud) at the end summarizes the +> hosts a typical `provision` + `deploy` flow needs. + +--- + +## 1. Azure control plane (per cloud) + +`azd` selects a cloud from the `cloud` configuration (default `AzureCloud`). The +ARM Resource Manager and Entra (AAD) authority hosts come from the Azure SDK's +well-known cloud configuration; the storage, container-registry, Key Vault, and +portal suffixes are defined in [`cli/azd/pkg/cloud/cloud.go`](../../cli/azd/pkg/cloud/cloud.go). + +### AzureCloud (public) — default + +| Host / suffix | Purpose | +|---|---| +| `management.azure.com` | ARM control plane (resource manager) | +| `login.microsoftonline.com` | Entra ID (AAD) authority — sign-in and token acquisition | +| `graph.microsoft.com` | Microsoft Graph — app / service-principal management (see note below) | +| `portal.azure.com` | Portal deep links shown in output | +| `*.core.windows.net` | Storage endpoint suffix (blobs, queues, tables) | +| `*.azurecr.io` | Azure Container Registry suffix | +| `*.vault.azure.net` | Key Vault suffix | + +### AzureUSGovernment + +| Host / suffix | Purpose | +|---|---| +| `management.usgovcloudapi.net` | ARM control plane | +| `login.microsoftonline.us` | Entra ID authority | +| `portal.azure.us` | Portal deep links | +| `*.core.usgovcloudapi.net` | Storage suffix | +| `*.azurecr.us` | Container Registry suffix | +| `*.vault.usgovcloudapi.net` | Key Vault suffix | + +### AzureChinaCloud + +| Host / suffix | Purpose | +|---|---| +| `management.chinacloudapi.cn` | ARM control plane | +| `login.chinacloudapi.cn` | Entra ID authority | +| `portal.azure.cn` | Portal deep links | +| `*.core.chinacloudapi.cn` | Storage suffix | +| `*.azurecr.cn` | Container Registry suffix | +| `*.vault.azure.cn` | Key Vault suffix | + +> [!IMPORTANT] +> **Microsoft Graph is not cloud-aware.** `graph.microsoft.com` is hardcoded to +> the public-cloud endpoint in +> [`cli/azd/pkg/graphsdk/graphsdk.go`](../../cli/azd/pkg/graphsdk/graphsdk.go) +> and is used regardless of the selected cloud (for example, when creating or +> assigning service principals during `azd pipeline config`). + +The exact per-cloud endpoint metadata for a subscription can be queried at +`https:///metadata/endpoints?api-version=2023-12-01`. + +--- + +## 2. Authentication + +The Entra ID (AAD) authority host is chosen per cloud (see section 1) and used to +build MSAL sign-in and token URLs in +[`cli/azd/pkg/auth/manager.go`](../../cli/azd/pkg/auth/manager.go). + +| Host | Purpose | +|---|---| +| `login.microsoftonline.com` (public) / `login.microsoftonline.us` (US Gov) / `login.chinacloudapi.cn` (China) | Interactive, device-code, and service-principal sign-in; token acquisition | +| `token.actions.githubusercontent.com` | OIDC issuer for GitHub Actions **federated credentials** — configured on Entra during `azd pipeline config`. Defined in [`cli/azd/pkg/entraid/entraid.go`](../../cli/azd/pkg/entraid/entraid.go) and [`cli/azd/pkg/pipeline/github_provider.go`](../../cli/azd/pkg/pipeline/github_provider.go) | + +When running in Azure Cloud Shell, `azd` obtains tokens from the local managed +identity endpoint (provided via environment, not a fixed public host) — see +[`cli/azd/pkg/auth/cloudshell_credential.go`](../../cli/azd/pkg/auth/cloudshell_credential.go). + +--- + +## 3. Telemetry + +`azd` sends usage telemetry to Application Insights unless telemetry is disabled +(`AZURE_DEV_COLLECT_TELEMETRY=no`). Endpoints are defined in +[`cli/azd/internal/telemetry/telemetry.go`](../../cli/azd/internal/telemetry/telemetry.go). + +| Host | Purpose | +|---|---| +| `centralus-2.in.applicationinsights.azure.com` | Telemetry ingestion (production builds) | +| `centralus.livediagnostics.monitor.azure.com` | Live-metrics stream (production builds) | +| `westus-0.in.applicationinsights.azure.com` | Telemetry ingestion (dev builds only) | +| `westus.livediagnostics.monitor.azure.com` | Live-metrics stream (dev builds only) | + +See the [Telemetry Data Reference](telemetry-data.md) for what is collected and +[Environment Variables](environment-variables.md) for how to opt out. + +--- + +## 4. Feature experimentation (flighting) + +`azd` queries an experimentation (TAS) service at startup to resolve feature +flags. Defined in +[`cli/azd/cmd/middleware/experimentation.go`](../../cli/azd/cmd/middleware/experimentation.go). + +| Host | Purpose | +|---|---| +| `default.exp-tas.com` | Experimentation / feature-flighting assignment service | + +The endpoint can be overridden with `AZD_DEBUG_EXPERIMENTATION_TAS_ENDPOINT`. +If the host is unreachable, `azd` logs the failure and continues with default +feature enablement. + +--- + +## 5. External tools (auto-download) + +When a required CLI tool is missing, `azd` downloads a pinned version to its +config directory. These are the download sources: + +| Host | Tool | Source | +|---|---|---| +| `downloads.bicep.azure.com` | Bicep CLI | [`cli/azd/pkg/tools/bicep/bicep.go`](../../cli/azd/pkg/tools/bicep/bicep.go) | +| `github.com` | GitHub CLI (`gh`) release assets — `github.com/cli/cli/releases/...` | [`cli/azd/pkg/tools/github/github.go`](../../cli/azd/pkg/tools/github/github.go) | +| `github.com` | `pack` (Cloud Native Buildpacks) release assets — `github.com/buildpacks/pack/releases/...` | [`cli/azd/pkg/tools/pack/pack.go`](../../cli/azd/pkg/tools/pack/pack.go) | +| `mcr.microsoft.com` | Default buildpack builder image (`oryx/builder`) pulled by `pack build` when no Dockerfile is present. Overridable with `AZD_BUILDER_IMAGE`. | [`cli/azd/pkg/project/container_helper.go`](../../cli/azd/pkg/project/container_helper.go) | + +> [!NOTE] +> GitHub release downloads redirect to GitHub's asset CDN, so +> `objects.githubusercontent.com` (and, for some flows, +> `raw.githubusercontent.com`) must also be reachable when downloading `gh` or +> `pack`. + +Tools that `azd` does **not** download — Docker/Podman, Terraform, `kubectl`, +Helm, Kustomize, Azure CLI — must be installed separately. When one is missing, +`azd` prints an `aka.ms` install-help link (see section 8); those links are +informational and not contacted automatically. + +--- + +## 6. Templates + +Used by `azd init` and `azd template list`. + +| Host | Purpose | +|---|---| +| `aka.ms` → `aka.ms/awesome-azd/templates.json` | Default template gallery source. Defined in [`cli/azd/pkg/templates/source_manager.go`](../../cli/azd/pkg/templates/source_manager.go) | +| `github.com` | Cloning template repositories (e.g. `github.com/Azure-Samples/