From 22393e15be8fea7dc477524b2d1f44eb0919282d Mon Sep 17 00:00:00 2001 From: Jack Tracey <41163455+jtracey93@users.noreply.github.com> Date: Thu, 21 Oct 2021 18:06:02 +0100 Subject: [PATCH] FAQ Update (#828) * changes/updates to FAQ to align with planned CAF FAQ * minor name update * remove old faq * changes from KN review * Update docs/wiki/FAQ.md Co-authored-by: Johan Dahlbom * DA review changes Co-authored-by: Johan Dahlbom --- README.md | 2 +- docs/EnterpriseScale-FAQ.md | 86 ----------------------------- docs/wiki/FAQ.md | 107 ++++++++++++++++++++++++++++++++++++ docs/wiki/Whats-new.md | 2 + docs/wiki/_Sidebar.md | 1 + 5 files changed, 111 insertions(+), 87 deletions(-) delete mode 100644 docs/EnterpriseScale-FAQ.md create mode 100644 docs/wiki/FAQ.md diff --git a/README.md b/README.md index c5fc4157..20c61ee1 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ * [Getting started with Infrastructure-as-Code](https://github.com/Azure/AzOps-Accelerator/wiki) * [Known Issues](./docs/EnterpriseScale-Known-Issues.md) * [How Do I Contribute?](./docs/EnterpriseScale-Contribution.md) -* [FAQ](./docs/EnterpriseScale-FAQ.md) +* [Frequently Asked Questions (FAQ)](https://github.com/Azure/Enterprise-Scale/wiki/FAQ) * [Roadmap](./docs/EnterpriseScale-Roadmap.md) * [Microsoft Support Policy](./SUPPORT.md) diff --git a/docs/EnterpriseScale-FAQ.md b/docs/EnterpriseScale-FAQ.md deleted file mode 100644 index 007cb4e6..00000000 --- a/docs/EnterpriseScale-FAQ.md +++ /dev/null @@ -1,86 +0,0 @@ -## FAQ - -This page will list frequently asked question for Enterprise-Scale reference implementations. - -### What does "Landing Zone" map to in Azure in the context of Enterprise-Scale? - -From Enterprise-Scale point of view, subscriptions are the "Landing Zones" in Azure. - -### Why do Enterprise-Scale ARM templates require permission at Tenant root '/' scope? - -Management Group creation, Subscription creation, and Subscription placement into Management Groups are APIs that operates at the tenant root (/). So in order to create the management group hierarchy, the subscriptions, and organize them accordingly into the management groups, the initial deployment must also be invoked at the tenant root (/) scope. -Once you have deployed Enterprise-Scale, you can remove the Owner permission from the tenant root (/) scope, as you will be Owner at the intermediate root management group that Enterprise-Scale is creating. - -### Enterprise-Scale Landing Zones deployment UX do not display all subscriptions in subscription picker drop down list - -When deploying Enterprise-Scale, the UX is populateing the list of subscriptions to bring in for deployment of the platform subscriptions (management, connectivity, identity), as well as the landing zones (corp and online). When there are 50+ subscriptions, API do not enumerate all subscription in the subscription picker UI. As a workaround, perform the following steps: - -1) Go through the portal experience to select all the options that should be on and select any visible subscription as a placeholder to view all options (some options have dependency on a subscription being selected before they are visible). -2) Once done, go back to the ‘basics’ page, and click ‘edit parameters’ -3) Change the value for the specific *subscriptionId parameters per the subscription Id’s the customer want to bring -4) Click Save -5) Click Review + create, and submit the deployment - -### Can we take the ARM templates for Enterprise-Scale reference implementations and check them into our repository and deploy it from there, instead of via the Azure Portal? - -All ARM templates for the Enterprise-Scale Landing Zones reference implementations are developed for - and optimized for a curated self-service deployment experience in the Azure portal. -We do not recommend nor support customization of these templates, as they are rather complex given the options we provide, which also leads to a lot of logical operators and conditions in the expressions we are using. Further, as they are optimized for portal deployment and to setup the entire Azure tenant with platform and landing zones, there's a lot of sequencing that are happening across the various ARM scopes (management groups, subscriptions, and resource groups). Taking the same templates for day 2 and day N operations will require you to re-deploy the entire tenant for minor changes, and also require permanent Owner permission on the tenant root (/) scope. - -### What if we don't want to deploy using the Azure Portal experience, but prefer to deploy using infrastructure as code? - -We provide two options: - -* 1st party Enterprise-Scale Landing Zones reference implementation (this repository) leads with the portal experience based on ARM templates, and also enable you to integrate and bootstrap the CI/CD pipeline during the deployment. The outcome of that is that you will have a GitHub repository with GitHub Actions, or Azure DevOps pipeline with *all* the resource deployments organized as composite ARM templates, represented at their respective scopes (management groups, subscriptions, resource groups). See the [Enterprise-Scale Landing Zones User Guide](https://github.com/Azure/Enterprise-Scale/wiki/Deploying-Enterprise-Scale#reference-implementation-deployment) for more information of how this is being done. - -* 3rd party Enterprise-Scale Landing Zones [Terraform module](https://github.com/Azure/terraform-azurerm-caf-enterprise-scale#terraform-module-for-cloud-adoption-framework-enterprise-scale), that has parity with 1st party implementation, where you can deploy, manage, and operationalize the Azure platform. - -### What if I have already deployed Enterprise-Scale Landing Zones without the CI/CD integration, do I have to start over to have infrastructure as code? - -Absolutely not! We acknowledge that infrastructure as code is a journey, and that organizations need to transition/start with IaC when they are ready. At any point in time, you can integrate [AzOps](https://github.com/Azure/AzOps-Accelerator) to your environment, and get the representation of your Azure environment into Git and start using the existing ARM templates, and bring your own ARM templates to ongoing deployment and operations. - -### How long does it take to deploy Enterprise-Scale? - -Depending on the reference implementation and which options you enable, it vary from 40~ minutes, to 5~ minutes. -Examples: - -* Deploying Adventure Works with all options enabled, including connecvitity with zonal deployment of VPN and ER Gateways, with corp connected (peered) landing zones can take 40~ minutes. - -* Deploying Adventure Works (also Wingtip) without connectivity will take 5~ minutes. - -### Why are there custom policy definitions as part of Enterprise-Scale Landing Zones? - -We work with - and learn from our customers and partners, and ensures that we evolve and enhance the reference implementations to meet customer requirements. The primary approach of the policies as part of Entperprise-Scale is to be proactive (deployIfNotExist, and modify), and preventive (deny), and we are continiously moving these policies to built-ins. - -### What does Policy Driven Governance means, and how does it work? - -Azure Policy and deployIfNotExist enables the autonomy in the platform, and reduces the operational burden as you scale your deployments and subscriptions in the Enterprise-Scale architecture. The primary purpose is to ensure that subscriptions and resources are compliant, while empowering application teams to use their own preferred tools/clients to deploy. -Some examples: - -* A new subscription (landing zone) is created and placed into the targeted management group (online, corp, sandbox etc.). Azure Policy will then ensure that Azure Security Center is enabled for the subscription, the diagnostic setting for the Activity Log is routed to the platform Log Analytics Workspace, budget is applied, and virtual network peering is done properly back to the connectivity subscription. Instead of repeating and duplicating code and efforts when a new subscription is being created, Azure Policy is assigned at the management group to automatically bring the subscriptions into their compliant goal state. - -* An application team is deploying a workload composed of SQL Databases, Virtual Machines, Network Security Groups, and Load Balancers into their landing zone. Azure Policy will ensure that all these resources have the right logging and security enabled from a platform perspective (e.g., NetworkSecurityGroupEvent log category for Network Security Group is routed to the platform Log Analytics workspace, Azure Monitor VM Extensions are added to the Virtual Machine, auditing is enabled for the SQL Database). - -### Are we supposed to use Azure Policy for workload deployments? - -The short answer to this is: No. -Azure Policy is not doing workload deployments, but ensures workloads that are being deployed (regardless of *how*) will be compliant per the organization's security and compliance requirements. Also, it ensures application teams can chose their preferred tooling and clients for deployments, instead of relying on central IT to provide artifacts, pipelines, tools etc. - -### What if I already have resources in my landing zones, and later add a policy? - -This is very common, and expected as new Azure services are being enabled and used, and you need to govern them. When assigning a policy to a scope (management group) that contains subscriptoins with resources subject to that policy, the assignment will start an initial *scan* of the scope, and report on compliant and non-compliant resources. Depending on the policy effect (deny, audit, append, modify, deployIfNotExist, and auditIfNotExist), you can remediate and bring the resources into a compliant state automatically. - -Once a policy is assigned, it will take immediate effect for all new *writes* (create/update) to that scope subject to the policy rule. -Example: - -* Assigning a policy that deploys Azure Monitor VM extension to a management group containing subscriptions with virtual machines, will detect all virtual machines that does not have the Azure Monitor VM extenstion enabled, and mark them as non-compliant. These virtual machines can now be remediated so the Azure Monitor VM extension gets enabled, and the virtual machines will be compliant. - -* For all new VM create/update requests to those subscriptions subject to the policy, the policy will act as soon as the VM create request has completed successfully, and there is no need to remediate or take any actions. - -### Where can I see the policies used by Enterprise-Scale Landing Zones reference implementation? - -We maintain the index [here](./ESLZ-Policies.md), and will update the tables when: - -* A custom policy is moved to built-in policy -* When a custom policy is deprecated -* When there's a major update to a policy definition/ policy set definition -* When we update the reference implementations to assign new/existing built-in policies as part of the deployment diff --git a/docs/wiki/FAQ.md b/docs/wiki/FAQ.md new file mode 100644 index 00000000..8d2ac854 --- /dev/null +++ b/docs/wiki/FAQ.md @@ -0,0 +1,107 @@ +## In this Section + +- [How long does enterprise-scale architecture take to deploy?](#how-long-does-enterprise-scale-architecture-take-to-deploy) +- [Why are there custom policy definitions as part of enterprise-scale architecture?](#why-does-enterprise-scale-architecture-require-permission-at-tenant-root--scope) +- [Where can I see the policy definitions used by enterprise-scale landing zones reference implementation?](#where-can-i-see-the-policy-definitions-used-by-enterprise-scale-landing-zones-reference-implementation) +- [Why does enterprise-scale architecture require permission at tenant root '/' scope?](#why-does-enterprise-scale-architecture-require-permission-at-tenant-root--scope) +- [The Azure landing zone accelerator portal-based deployment doesn't display all subscriptions in the drop-down lists?](#the-azure-landing-zone-accelerator-portal-based-deployment-doesnt-display-all-subscriptions-in-the-drop-down-lists) +- [Can we use and customize the ARM templates for enterprise-scale architecture and check them into our repository and deploy it from there?](#can-we-use-and-customize-the-arm-templates-for-enterprise-scale-architecture-and-check-them-into-our-repository-and-deploy-it-from-there) +- [What if we can't deploy by using the Azure landing zone accelerator portal-based experience, but can deploy via infrastructure-as-code?](#what-if-we-cant-deploy-by-using-the-azure-landing-zone-accelerator-portal-based-experience-but-can-deploy-via-infrastructure-as-code) +- [If we already deployed enterprise-scale architecture without using infrastructure-as-code, do we have to delete everything and start again to use infrastructure-as-code?](#if-we-already-deployed-enterprise-scale-architecture-without-using-infrastructure-as-code-do-we-have-to-delete-everything-and-start-again-to-use-infrastructure-as-code) + +--- + +## Enterprise-scale FAQ + +This article answers frequently asked questions relating to Enterprise-scale. + +Some FAQ questions that relate more to the architecture are based over in the CAF docs here: [Enterprise-scale architecture FAQ](https://docs.microsoft.com/azure/cloud-adoption-framework/ready/enterprise-scale/faq) + +## How long does enterprise-scale architecture take to deploy? + +Deployment time depends on the options you select during the implementation experience. It varies from around five minutes to 40 minutes, depending on the options selected. + +For example: + +- Reference implementation without any networking or connectivity options can take around five minutes to deploy. +- Reference implementation with the hub and spoke networking options, including VPN and ExpressRoute gateways, can take around 40 minutes to deploy. + +## Why are there custom policy definitions as part of enterprise-scale reference implementation? + +We work with and learn from our customers and partners. This collaboration helps us evolve and enhance the reference implementations to meet customer and partner requirements. As part of this interaction with customers and partners, we might notice policy definition gaps. In those cases, we create and test a definition to fill the gap and include it in enterprise-scale architecture for everyone to use. + +We then work with the Azure Policy and associated engineering teams to continuously transition the new custom policy definitions into built-in policy definitions. + +## Where can I see the policy definitions used by the enterprise-scale landing zones reference implementation? + +You can find a list of policy definitions here: [Policies included in enterprise-scale landing zones reference implementations](https://github.com/Azure/Enterprise-Scale/blob/main/docs/ESLZ-Policies.md) + +We also add changes to our [What's New? wiki page](https://github.com/Azure/Enterprise-Scale/wiki/Whats-new). + + + +## Why does the enterprise-scale reference implementation require permission at tenant root '/' scope? + +Management group creation, subscription creation, and placing subscriptions into management groups are APIs that operate at the tenant root "`/`" scope. + +To establish the management group hierarchy and create subscriptions and place them into the defined management groups, the initial deployment must be invoked at the tenant root "`/`" scope. Once you deploy enterprise-scale architecture, you can remove the owner permission from the tenant root "`/`" scope. The user deploying the enterprise-scale reference implementation is made an owner at the intermediate root management group (for example "Contoso"). + +For more information about tenant-level deployments in Azure, see [Deploy resources to tenant](https://docs.microsoft.com/azure/azure-resource-manager/templates/deploy-to-tenant). + +## The enterprise-scale (also known as the Azure landing zone accelerator) portal-based deployment doesn't display all subscriptions in the drop-down lists? + +When you deploy enterprise-scale via the portal-based deployment (also known as the Azure landing zone accelerator), the portal lists subscriptions to be selected for deployment from the platform subscriptions (management, connectivity, identity) and the landing zones (corp and online). When there are more than 50 subscriptions, the API can't display all of them in the drop-down lists. + +Follow these steps as a workaround: + +1. Select or enable your usual options in the portal-based experience. In the subscription drop-downs, select any visible subscription as a placeholder so that you can see and select all options (some options don't appear until you select a subscription). +1. After you've gone through each page, go back to the **Basics** page, and then select **Edit parameters**. +1. Change the value for the specific `subscriptionId` parameter inputs with the actual subscription IDs you want to use. +1. Select **Save**. +1. Select **Review + create**, and then submit the deployment. + +## Can we use and customize the ARM templates for enterprise-scale architecture and check them into our repository and deploy it from there? + +All of the ARM templates for enterprise-scale architecture are developed and optimized for the Azure landing zone accelerator portal-based experience. We don't recommend or support customization of these templates because they're complex. To handle all of the options and variations we provide for the Azure landing zone accelerator portal-based experience, ARM template expressions would need numerous logical operators and conditions. ARM deployments (nested templates) need to deploy in a specific order to be successful. + +Finally, taking the same templates for future operations requires you to redeploy to the entire tenant for any change, and also requires permanent owner role-based access control assignment on the tenant root "`/`" scope. + +However, if you want to deploy and manage enterprise-scale architecture via infrastructure-as-code, see [What if we can't deploy using the Azure landing zone accelerator portal-based experience, but want to deploy via infrastructure-as-code?](#what-if-we-cant-deploy-by-using-the-azure-landing-zone-accelerator-portal-based-experience-but-can-deploy-via-infrastructure-as-code). + +## What if we can't deploy by using the Azure landing zone accelerator portal-based experience, but can deploy via infrastructure-as-code? + +The following implementation options are available when you use infrastructure-as-code: + +- The [Azure landing zone accelerator](https://docs.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/#azure-landing-zone-accelerator) portal-based experience can integrate and bootstrap a CI/CD pipeline using GitHub with [AzOps](https://github.com/Azure/AzOps) as documented at [Deploying Enterprise Scale](https://github.com/Azure/Enterprise-Scale/wiki/Deploying-Enterprise-Scale). +- The [Enterprise-scale Do-It-Yourself (DIY) ARM templates](https://github.com/Azure/Enterprise-Scale/tree/main/eslzArm#enterprise-scale-landing-zones-arm-templates) method +- The [Terraform Module for Cloud Adoption Framework Enterprise-scale](https://github.com/Azure/terraform-azurerm-caf-enterprise-scale#terraform-module-for-cloud-adoption-framework-enterprise-scale) + +> The Bicep implementation option for Enterprise-scale is coming soon! + +## If we already deployed enterprise-scale architecture without using infrastructure-as-code, do we have to delete everything and start again to use infrastructure-as-code? + +If you used the Azure landing zone accelerator portal-based experience to deploy enterprise-scale architecture into your Azure tenant, see the guidance for the infrastructure-as-code tooling you want to use. + +### ARM Templates + +To use ARM templates to deploy, manage, and operate your enterprise-scale deployment, you don't have to delete everything and start again. You can configure and connect [AzOps](https://github.com/Azure/AzOps) tooling by using the [AzOps Accelerator](https://github.com/Azure/AzOps-Accelerator) and associated instructions, regardless of the stage of your Azure tenant. + +Once configured, AzOps connects to your Azure tenant, scans it, and then pulls individual ARM templates into your repository in a structure that represents the [four Azure scopes](https://docs.microsoft.com/azure/azure-resource-manager/management/overview#understand-scope). + +To see a demo of AzOps being used, check out this YouTube video on the Microsoft DevRadio channel: [Enterprise-scale landing zones DevOps and automation step by step](https://www.youtube.com/watch?v=wWLxxj-uMsY) + +### Bicep + +The [AzOps](https://github.com/Azure/AzOps) tooling supports deploying Bicep files at the [four Azure scopes](https://docs.microsoft.com/azure/azure-resource-manager/management/overview#understand-scope). Its pull process only stores the scan of your Azure tenants resources in ARM templates that use JSON. + +Leave us feedback via [GitHub issues on the AzOps repository](https://github.com/Azure/AzOps/issues) if you want to see something added to AzOps. + +### Terraform + +Terraform builds its own [state](https://www.terraform.io/docs/language/state/index.html) file to track and configure resources. If you already deployed enterprise-scale architecture to your Azure tenant, [import](https://www.terraform.io/docs/cli/import/index.html) each resource into the state file to learn what it manages as part of your Terraform code. Then you can deploy, manage, and operate your enterprise-scale deployment via Terraform. + +Terraform import is currently done on a per resource basis and can be time consuming and complex to do at scale. It's often easier to delete and redeploy via Terraform than to import everything that's been deployed by the Azure landing zone accelerator portal-based experience. Most customers know from the start that they want to use Terraform to manage their Azure tenant, so this scenario is uncommon. + +To deploy enterprise-scale architecture by using Terraform, you might want to use the Terraform module we provide. It deploys everything that the Azure landing zone accelerator portal-based experience does. The module, [Terraform Module for Cloud Adoption Framework Enterprise-scale](https://registry.terraform.io/modules/Azure/caf-enterprise-scale/azurerm/0.0.4-preview), is available from the Terraform Registry page. + +To see a demo of Terraform being used, check out this YouTube video on the Microsoft DevRadio channel: [Terraform Module for Cloud Adoption Framework Enterprise-scale Walkthrough](https://www.youtube.com/watch?v=5pJxM1O4bys) diff --git a/docs/wiki/Whats-new.md b/docs/wiki/Whats-new.md index ed5e2e0c..48107875 100644 --- a/docs/wiki/Whats-new.md +++ b/docs/wiki/Whats-new.md @@ -37,6 +37,8 @@ Here's what's changed in Enterprise Scale: #### Docs - Updated Deploying Enterprise Scale wiki page with updated workflow steps. (https://github.com/Azure/Enterprise-Scale/pull/827) +- Updated [implementation FAQ](https://github.com/Azure/Enterprise-Scale/wiki/FAQ) and moved to the Wiki +- Added [architecture FAQ](https://docs.microsoft.com/azure/cloud-adoption-framework/ready/enterprise-scale/faq) to the CAF docs #### Tooling diff --git a/docs/wiki/_Sidebar.md b/docs/wiki/_Sidebar.md index f7b13389..81e9db30 100644 --- a/docs/wiki/_Sidebar.md +++ b/docs/wiki/_Sidebar.md @@ -3,6 +3,7 @@ * [Home](./Home) * [What's New?](./Whats-new) * [Community Calls](./Community-Calls) +* [Frequently Asked Questions (FAQ)](./FAQ) * [What is Enterprise-Scale](./What-is-Enterprise-Scale) * [What is Enterprise-Scale reference implementation?](./What-is-Enterprise-Scale#what-is-enterprise-scale-reference-implementation) * [Pricing](./What-is-Enterprise-Scale#pricing)