search

Azure / Enterprise-Scale

The Azure Landing Zones (Enterprise-Scale) architecture provides prescriptive guidance coupled with Azure best practices, and it follows design principles across the critical design areas for organizations to define their Azure architecture
https://aka.ms/alz
MIT License
1.73k stars 980 forks source link

Minor documentation update to clarify pre-reqs #1713

Open soderholmd opened 4 months ago

soderholmd commented 4 months ago

This is a suggestion for a minor documentation update to three pages. It is intended to make sure that pre-requisite resource providers are obvious when following the Learn documentation, as they are not currently mentioned. It is therefore possible that a user follows the link directly from Learn to the Portal and initiates an ALZ deployment without being aware that RPs need enabling, as they are documented separately on the Github wiki.

Current state:

  1. https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/#azure-landing-zone-accelerator has a 'click here to deploy landing zones' button that launches the portal ALZ deployment wizard. It does not make any reference to pre-reqs other than the permissions required at / scope
  2. https://github.com/Azure/Enterprise-Scale/wiki/Deploying-ALZ-Pre-requisites discusses the / scoped permissions but makes only a passing reference to resource providers in the context of AMBA and no link to the pre-reqs page
  3. https://github.com/Azure/Enterprise-Scale/wiki/ALZ-Resource-Provider-Recommendations has a full list of required resource providers
  4. Page 3 above also has a line "To successfully deploy an Enterprise-Scale with a predefined [template] (https://aka.ms/caf/ready/accelerator)...", but the 'template' link is directly to the ALZ portal wizard, not to the Bicep or Terraform templates

From these documents it is unclear when reading the first two that the resource provider pre-reqs exist, and so it is easy to miss them.

Suggestion:

  1. Update the pre-reqs document (no. 2) to include a reference to all pre-reqs including a full list of all required resource providers (i.e. consolidate all pre-reqs into a single doc)
  2. Update the Learn doc (no. 1) with an explicit link to the pre-reqs documentation
  3. Update page no 3. above to link 'template' to a Bicep/Terraform/Portal options landing page, not directly to the portal
jtracey93 commented 4 months ago

Thanks @soderholmd, would you be willing to make these updates?

soderholmd commented 4 months ago

@jtracey93 happy to as long as it looks good to you!

jtracey93 commented 4 months ago

Yup LGTM

soderholmd commented 3 months ago

Two PRs raised:

https://github.com/MicrosoftDocs/cloud-adoption-framework-pr/pull/5751 https://github.com/Azure/Enterprise-Scale/pull/1735