docs: add Azure provider ecosystem guide

[joeduffy]

Summary

Adds a holistic guide covering the full Pulumi Azure provider ecosystem, addressing issue #17745. Users often don't understand why multiple Azure providers exist, which API surface each targets, or how they compose together in real deployments.

Changes

New content files:

• content/docs/iac/clouds/azure/guides/_index.md — Guides section landing page for the Azure docs, matching the pattern established for Google Cloud
• content/docs/iac/clouds/azure/guides/providers.md — Comprehensive provider ecosystem guide covering:
  • azure-native (ARM API, recommended primary provider, v1/v2/v3 versioning)
  • azure-classic (Terraform-bridged, not recommended for new projects)
  • azuread (Microsoft Graph API, Entra ID resources — with note on the Azure AD rebrand to Entra ID)
  • azuredevops (Azure DevOps REST API, pipeline and project management)
  • azapi (community-maintained, largely superseded by azure-native)
  • Decision table for common tasks
  • Multi-provider composition example (azure-native + azuread together)

New static programs (all 6 languages):

• static/programs/azure-providers-{typescript,python,go,csharp,java,yaml}/
  • Demonstrates creating an Azure resource group (azure-native) alongside an Entra ID application and service principal (azuread), showing how the providers compose in practice

Notes

• Registry page changes (items 2-5 in the original issue) are out of scope for this PR, as registry pages for azure-native, azuread, azuredevops, and azapi are auto-generated or maintained separately
• The guide follows the same structure and conventions as the GCP provider guide (PR Add GCP provider comparison guide and fix overview page bugs (issue #17741) #18541)

Closes #17745

---

🧠 This PR was created by workprentice on behalf of @joeduffy.

[claude]

Docs Review — PR #18568

Scope: All 19 new files (2 content docs, 17 static program files across 6 languages).

This is a well-structured guide that fills a real gap in the Azure documentation. The content is accurate, clearly written, and follows the established pattern from the GCP provider guide. A few items to address:

---

Issues

1. Stale time reference in the AzAPI section — content/docs/iac/clouds/azure/guides/providers.md line 217

As of mid-2024, the package has had little maintenance activity.

This is nearly two years old and may no longer be accurate. Consider rephrasing to avoid a point-in-time reference that will age:

The package has historically seen limited maintenance activity.

Or verify the current maintenance status and update accordingly.

2. Likely incorrect .NET package casing for Azure DevOps — content/docs/iac/clouds/azure/guides/providers.md line 40

The table lists Pulumi.Azuredevops, but Pulumi NuGet packages follow PascalCase conventions (e.g., Pulumi.AzureNative, Pulumi.AzureAD). The correct package name is likely:

`Pulumi.AzureDevOps`

Please verify the actual NuGet package name and correct the casing.

3. Go module uses azure-native-sdk v2 while text says v3 is current — static/programs/azure-providers-go/go.mod line 6

github.com/pulumi/pulumi-azure-native-sdk/resources/v2 v2.42.1

The guide text at providers.md line 78 says "The current major version is v3, and all new projects should target it." If v3 of the Go SDK module exists, the example program should use it to be consistent with the recommendation. If the Go module path /v2 is still correct for provider v3 (due to Go module versioning conventions), a brief note in the guide clarifying this discrepancy would help avoid confusion.

---

Minor suggestions

4. _index.md refers to "Azure Active Directory / Entra ID provider" — content/docs/iac/clouds/azure/guides/_index.md line 27

Since Microsoft completed the rebrand to "Entra ID" in 2023, consider leading with the current name:

- [Entra ID provider (`@pulumi/azuread`)](/registry/packages/azuread/) — a provider for
  managing Microsoft Entra ID (formerly Azure Active Directory) resources such as users, groups, service
  principals, and app registrations

This would be consistent with the note in providers.md that explains the rebrand.

5. The "Packages at a glance" table is extremely wide — providers.md lines 35–46

The five-column table with full Go import paths will likely overflow or require horizontal scrolling on smaller viewports. This is a minor presentation concern — no action required, but worth confirming it renders acceptably on the live site.

---

What looks good

• Frontmatter is complete and correct on both content files (title_tag, meta_desc, meta_image, menu, aliases).
• Menu hierarchy is correct: azure-clouds → azure-clouds-guides → azure-guides-providers.
• Heading case follows style guide (H1 Title Case, H2+ sentence case).
• All six language examples have complete project structures (Pulumi.yaml, dependency files, source files).
• The {{< example-program path="azure-providers" >}} shortcode usage is correct — the shortcode auto-discovers available languages.
• Code examples use correct language-idiomatic conventions (camelCase for TS, snake_case for Python, PascalCase for C#/Go).
• Internal links to /docs/iac/get-started/azure/, /registry/packages/azure-native/, etc. reference known paths.
• Content structure mirrors the existing GCP guides section.

---

Mention @claude if you'd like additional reviews or help fixing any of the above items.

[CamSoper]

Thanks for the guide, Joe -- the prose and structure are solid. A handful of concrete fixes before merge, mostly around the failing CI:

CI failures

Lint -- trailing blank line at EOF in both content files:

• content/docs/iac/clouds/azure/guides/_index.md:37
• content/docs/iac/clouds/azure/guides/providers.md:261

Go program won't compile -- pulumi-azuread/sdk/v4 uses the legacy ApplicationId field name, but the program code uses ClientId. The cleanest fix is to bump both Azure module versions in static/programs/azure-providers-go/go.mod to match the current ecosystem and the v3 recommendation in the guide:

github.com/pulumi/pulumi-azure-native-sdk/resources/v3 v3.16.0
github.com/pulumi/pulumi-azuread/sdk/v6 v6.9.0

Then update the import in main.go from sdk/v4/go/azuread to sdk/v6/go/azuread. That also resolves the v2-vs-v3 inconsistency noted in the earlier review.

Java program won't run -- static/programs/azure-providers-java/pom.xml declares <mainClass> under <properties> but doesn't wire it to the exec-maven-plugin that the test harness invokes via mvn exec:java. Copy the org.codehaus.mojo:exec-maven-plugin block from static/programs/aws-providers-combine-java/pom.xml (or gcp-providers-classic-java/pom.xml).

From the earlier review, still unaddressed

• providers.md:40 -- the table lists Pulumi.Azuredevops; the canonical NuGet package id is Pulumi.AzureDevOps.
• providers.md:217 -- "As of mid-2024, the package has had little maintenance activity." -- the azapi repo's most recent commit is 2025-07-01, so the mid-2024 framing is stale. Consider a non-dated phrasing: "The package has historically seen limited maintenance activity."

[joeduffy]

Thanks for the thorough review, @CamSoper. All items addressed in the latest push (579050d):

• Trailing blank lines: Removed from both _index.md and providers.md
• Go program: Upgraded to pulumi-azure-native-sdk/resources/v3 and pulumi-azuread/sdk/v6, correcting both the version inconsistency and the ClientId field compatibility issue. Also updated the Go package path in the comparison table to reflect v6.
• Java pom.xml: Added exec-maven-plugin (matching the GCP guide pattern) and aligned assembly plugin config with the established template
• Pulumi.AzureDevOps casing: Fixed in the comparison table
• azapi date phrasing: Replaced "As of mid-2024" with "The package has historically seen limited maintenance activity"

[pulumi-bot]

Your site preview for commit 097213b is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-18568-097213b9.s3-website.us-west-2.amazonaws.com

[joeduffy]

CI is now green on both checks. All review feedback from @CamSoper has been addressed — requesting a re-review when you have a moment.

[CamSoper]

Thanks for the quick turn on the prior feedback, Joe -- CI is green, the Go module bump to v3/v6 resolved both the build failure and the version consistency, and the Java pom now wires exec-maven-plugin. Casing and the stale date reference are fixed.

One small accuracy follow-up landed directly on the branch: the AzAPI warning block called out "limited maintenance activity," but a fact-check turned up that dirien/pulumi-azapi was archived on 2025-07-01 with a README caution redirecting users to the Azure Native provider. Swapped the phrasing to say that outright.

Optional nit (not blocking, feel free to ignore): the inline AKS example at providers.md:118-154 still uses servicePrincipalProfile with clientId/secret. That's valid in azure-native v3, but Microsoft's current guidance for new AKS clusters is managed identity. Since the example's whole point is to motivate azuread as a companion provider, swapping to managed identity would undercut that -- so no action needed unless you want to add a one-liner noting managed identity is the modern default.

Approving with auto-merge on squash.