diff --git a/docs/wiki/overlay-authoring-guide.md b/docs/wiki/overlay-authoring-guide.md new file mode 100644 index 0000000..2280350 --- /dev/null +++ b/docs/wiki/overlay-authoring-guide.md @@ -0,0 +1,201 @@ +# Overlay Authoring Guide + +Azure NoOps Accelerator Overlays are self-contained Bicep deployment templates that allows to extend AzResources services with specific configurations or combine them to create more useful objects. Therefore, deploying an overlay will result in an enahancing a Azure landing zone that can be scaled and refined based on business or deployment need. + +The goal of this authoring guide is to provide step-by-step instructions to create new and update existing overlays. + +## Table of Contents + +- [Overlay Authoring Guide](#overlay-authoring-guide) + - [Table of Contents](#table-of-contents) + - [Folder structure](#folder-structure) + - [Create a new overlays](#create-a-new-overlays) + - [Build new overlays](#build-new-overlays) + - [Requirements for overlays](#requirements-for-overlays) + - [Approach](#approach) + - [Common features](#common-features) + +--- + +## Folder structure + +Overlays are located in [`overlays`](../../overlays) folder and organized as folder per overlay. Here are the current overlays with links to documentation: + +- Management Group overlay + - [`management-groups`](../src/bicep/../../../src/bicep/overlays/management-groups/readme.md) - Deploys a management group hierarchy in a tenant under the `Tenant Root Group`. +- Management Service overlays + - [`app-service-plan`](../src/bicep/../../../src/bicep/overlays/management-services/app-service-plan/readme.md) - Deploys a app service plan. + - [`applicationGateway`](../src/bicep/../../../src/bicep/overlays/management-services/applicationGateway/readme.md) - Deploys a application gateway. + - [`automation`](../src/bicep/../../../src/bicep/overlays/management-services/automation/readme.md) - Deploys a automation account. + - [`azureSecurityCenter`](../src/bicep/../../../src/bicep/overlays/management-services/azureSecurityCenter/readme.md) - Deploys Azure Security Center. + - [`bastion`](../src/bicep/../../../src/bicep/overlays/management-services/bastion/readme.md) - Deploys a Bastion host for Remote Access. + - [`containerRegistry`](../src/bicep/../../../src/bicep/overlays/management-services/containerRegistry/readme.md) - Deploys a Azure Container Registry. + - [`dataBricksWorkspace`](readme.md) - Deploys a Azure Data Bricks Workspace. + - [`keyVault`](../src/bicep/../../../src/bicep/overlays/management-services/keyvault/readme.md) - Deploys a Azure Key Vault. + - [`KubernetesPrivateCluster-Kubenet`](../src/bicep/../../../src/bicep/overlays/management-services/kubernetesPrivateCluster-Kubnet/readme.md) - Deploys a Azure Kubernetes Private Cluster with Kubenet. +- Policy overlay + - [`policy`](../src/bicep/../../../src/bicep/overlays/policy/readme.md) - Deploys a policy definitions/assignments in a specific `Management Group`. +- Roles overlay + - [`roles`](../src/bicep/../../../src/bicep/overlays/roles/readme.md) - Deploys a role definitions in a specific `Management Group`. + +--- + +## Create a new overlays + +Overlays are are self-contained Bicep deployment templates that allows you to extend AzResources services with specific configurations or combine them to create more useful objects. + +Overlays provide the ability to build new azure resources with an use case specific architecture in a repeatable method. One Overlay can be used to configure many different deployment sceniros. + +### Build new overlays + +You should develop new overlays when a common deployment need or azure service need emerges within your organization. The return on investment increases when the overlays is used in workloads and deployed to 10s or 100s of subscriptions. + +New features can be placed behind feature flags to provide customization/choices of Azure services to configure at deployment time. For example, we use feature flags to control Bastion and VM Instance deployment in the Remote Access - Bastion Overlay. + +The `parRemoteAccess.enable` feature flag for Bastion deployment: + +```json + "parRemoteAccess": { + "value": { + "enable": true, + "bastion": { + // excluded + } + } + } +``` + +The `parRemoteAccess.linux.enable` feature flag for VM Instance deployment: + +```json +"linux": { + "enable": true, + "vmName": "bastion-linux", + } + +"windows": { + "enable": true, + "vmName": "bastion-windows", + } +``` + +### Requirements for overlays + +Each overlay is intended to be self-contained and provides all deployment templates required to deployed to a subscription. + +Key requirements for each overlay are: + +- overlay folder must contain the overlay name. For example `app-service-plan`. +- Entrypoint for an overlay is `deploy.bicep`. Every overlay must provide `deploy.bicep` in its respective folder. +- Every overlay must provide `deploy.paramters.json` in its respective parameters folder. +- Deployment must be scoped to `subscription`. Scope is set in `deploy.bicep` using `targetScope` declaration. + + ```bicep + targetScope = 'subscription' + ``` + +- Implements [common features](#common-features). + +### Approach + +1. Identify at least 5 use cases that can benefit from an overlay and label all common features. This is the MVP for the overlay. An application team would receive the implementation of the MVP features deployed in their subscription. Use case specific features can be added to a deployment by the application team as they adapt their environment. + +2. Design what spoke virtual network to support the overlay. You must consider Hub & Spoke network topology or another network topology. + +3. Scaffold the overlay: + + - Create a new folder under `management-services` prefixed with the name. For example, `sqlServer`. + - Create `deploy.bicep`, set the `targetScope` as `subscription` + - Create required parameters for [common features](#common-features) + - Create a deploy.parameters.json and run a subscription scoped deployment through Azure CLI. + + ```bash + az deployment sub create --template-file --parameters @ --subscription-id --location eastus + ``` + + This is a validation that the overlay scaffolding is in-place. + +4. Add overlay specific deployment instructions and incrementally verify through deployment. + +5. Debug deployment failures. + + - Navigate to the subscription in Azure Portal + - Navigate to **Deployments** under **Settings** + - Identify the failed deployment step & troubleshoot + +6. Update documentation. + +## Common features + +An overlay can deploy & configure any number of Azure services. For consistency across all overlays, We recommend the following common features: + +- **Required** - all required fields for the deployment module. +- **Resource Tags** - configures tags on resource groups +- **Target Subscription Id** - configures the overlay target subscription. +- **Target Resource Group** - configures the overlay target resource group for the subscription +- **Subscription Role Assignments to Security Groups** - configures role-based access control at subscription scope +- **Hub Subscription Resource Group** - configures Hub subscription resource group +- **Hub VNet Name** - configures Hub subscription Virtual Netwrok Name. +- **Subscription Tags** - configures subscription tags + +> **Log Analytics Workspace integration**: `deploy.bicep` must accept an input parameter named `parLogAnalyticsWorkspaceResourceId`. This parameter is used to link Microsoft Defender for Cloud to Log Analytics Workspace. + +> **NOTE:** Some overlays will have some or all common features. This is depending on how the overlay is being used. + +Input parameters for common features are: + +```bicep +// Log Analytics +@description('Log Analytics Resource Id to integrate Microsoft Defender for Cloud.') +param logAnalyticsWorkspaceResourceId string + +// Target Resource Group Name +@description('The name of the resource group in which the overlay will be deployed. If unchanged or not specified, the NoOps Accelerator will create an resource group to be used.') +param parTargetResourceGroup string + +// Hub Subnet Resource Id +@description('The name of the The Hub Subnet Resource Id') +param parHubSubnetResourceId string + +// Hub Virtual Network Name +@description('The Hub Virtual Network Name for the Hub Network.') +param parHubVirtualNetworkName string + +// Hub Network Security Group Resource Id +@description('The Hub Network Security Group Resource Id') +param parHubNetworkSecurityGroupResourceId string + +@description('Required tags values used with all resources.') +param parTags object + +@description('Required values used with all resources.') +param parRequired object +``` + +These features are packaged into a Bicep module and can be invoked by the overlay (i.e. by `deploy.bicep`). + +Example module parameters from `deploy.parameters.json`: + +```bicep +// REQUIRED PARAMETERS +"parRequired": { + "value": { + "orgPrefix": "anoa", + "templateVersion": "v1.0", + "deployEnvironment": "mlz" + } +} + +// REQUIRED TAGS +"parTags": { + "value": { + "organization": "anoa", + "region": "eastus", + "templateVersion": "v1.0", + "deployEnvironment": "platforms", + "deploymentType": "NoOpsBicep" + } +} +``` + +--- diff --git a/src/bicep/overlays/Policy/readme.md b/src/bicep/overlays/Policy/readme.md index 7c01ce8..ba911c9 100644 --- a/src/bicep/overlays/Policy/readme.md +++ b/src/bicep/overlays/Policy/readme.md @@ -1,4 +1,4 @@ -# Overlays: NoOps Accelerator - Azure Policy for Guardrails +# Overlays: Azure Policy for Guardrails > **IMPORTANT: This is currenly work in progress.** diff --git a/src/bicep/overlays/management-services/app-service-plan/readme.md b/src/bicep/overlays/management-services/app-service-plan/readme.md index a0639f9..59a6289 100644 --- a/src/bicep/overlays/management-services/app-service-plan/readme.md +++ b/src/bicep/overlays/management-services/app-service-plan/readme.md @@ -1,4 +1,4 @@ -# Overlays: NoOps Accelerator - App Service Plan +# Overlays: App Service Plan ## Overview diff --git a/src/bicep/overlays/management-services/applicationGateway/readme.md b/src/bicep/overlays/management-services/applicationGateway/readme.md index f9908a8..1d9101b 100644 --- a/src/bicep/overlays/management-services/applicationGateway/readme.md +++ b/src/bicep/overlays/management-services/applicationGateway/readme.md @@ -1,4 +1,4 @@ -# Overlays: NoOps Accelerator - Application Gateway +# Overlays: Application Gateway ## Overview diff --git a/src/bicep/overlays/management-services/automation/readme.md b/src/bicep/overlays/management-services/automation/readme.md index aab3489..75b7b4a 100644 --- a/src/bicep/overlays/management-services/automation/readme.md +++ b/src/bicep/overlays/management-services/automation/readme.md @@ -1,4 +1,4 @@ -# Overlays: NoOps Accelerator - Automation Account +# Overlays: Automation Account ## Overview diff --git a/src/bicep/overlays/management-services/azureSecurityCenter/readme.md b/src/bicep/overlays/management-services/azureSecurityCenter/readme.md index 0e79d0f..1fdc590 100644 --- a/src/bicep/overlays/management-services/azureSecurityCenter/readme.md +++ b/src/bicep/overlays/management-services/azureSecurityCenter/readme.md @@ -1,4 +1,4 @@ -# Overlay: NoOps Accelerator - Microsoft Azure Security Center +# Overlays: Microsoft Azure Security Center ## Overview diff --git a/src/bicep/overlays/management-services/bastion/readme.md b/src/bicep/overlays/management-services/bastion/readme.md index 01ad8df..03626c4 100644 --- a/src/bicep/overlays/management-services/bastion/readme.md +++ b/src/bicep/overlays/management-services/bastion/readme.md @@ -1,4 +1,4 @@ -# Overlays: NoOps Accelerator - Remote Access - Bastion +# Overlays: Remote Access - Bastion ## Overview diff --git a/src/bicep/overlays/management-services/containerRegistry/readme.md b/src/bicep/overlays/management-services/containerRegistry/readme.md index 51fd6ce..adb6a00 100644 --- a/src/bicep/overlays/management-services/containerRegistry/readme.md +++ b/src/bicep/overlays/management-services/containerRegistry/readme.md @@ -1,4 +1,4 @@ -# Overlay: NoOps Accelerator - Azure Container Registry +# Overlays: Azure Container Registry ## Overview diff --git a/src/bicep/overlays/management-services/dataBricksWorkspace/readme.md b/src/bicep/overlays/management-services/dataBricksWorkspace/readme.md index 5780f8f..9190309 100644 --- a/src/bicep/overlays/management-services/dataBricksWorkspace/readme.md +++ b/src/bicep/overlays/management-services/dataBricksWorkspace/readme.md @@ -1,4 +1,4 @@ -# Overlay: NoOps Accelerator - Azure Data Bricks Workspace +# Overlays: Azure Data Bricks Workspace ## Overview diff --git a/src/bicep/overlays/management-services/keyvault/readme.md b/src/bicep/overlays/management-services/keyvault/readme.md index 6a18253..39697c5 100644 --- a/src/bicep/overlays/management-services/keyvault/readme.md +++ b/src/bicep/overlays/management-services/keyvault/readme.md @@ -1,4 +1,4 @@ -# Overlay: NoOps Accelerator - Azure Key Vault +# Overlays: Azure Key Vault ## Overview diff --git a/src/bicep/overlays/management-services/kubernetesPrivateCluster-Kubnet/readme.md b/src/bicep/overlays/management-services/kubernetesPrivateCluster-Kubnet/readme.md index fb8eb7d..ed3668b 100644 --- a/src/bicep/overlays/management-services/kubernetesPrivateCluster-Kubnet/readme.md +++ b/src/bicep/overlays/management-services/kubernetesPrivateCluster-Kubnet/readme.md @@ -1,4 +1,4 @@ -# Overlay: NoOps Accelerator - Azure Kubernetes Service - Private Cluster - Kubenet +# Overlays: Azure Kubernetes Service - Private Cluster - Kubenet ## Overview diff --git a/src/bicep/overlays/management-services/readme.md b/src/bicep/overlays/management-services/readme.md index 5359bfc..98389fd 100644 --- a/src/bicep/overlays/management-services/readme.md +++ b/src/bicep/overlays/management-services/readme.md @@ -1,8 +1,8 @@ -# Module: NoOps Accelerator - Management Services +# Overlays: Management Services ## Overview -NoOps Accelerator management services overlays are module templates that can be deployed to extend an existing Platform Landing Zones or Enclave. +Azure NoOps Accelerator management services overlays are module templates that can be used to extend an new or existing Platform Landing Zones or Enclave. ## Management Services Explanations @@ -11,9 +11,14 @@ Service | Description | Link| Azure App Service Plan | This overlay module deploys an App Service Plan (AKA: Web Server Cluster) to support simple web accessible linux docker containers. It also optionally supports the use of dynamic (up and down) scale settings based on CPU percentage up to a max of 10 compute instances. | [Azure App Service Plan](../management-services/app-service-plan/deploy.bicep) Azure Application Gateway | This overlay module adds an web traffic load balancer that enables you to manage traffic to your web applications. This application gateway is meant to be in the Hub Network. | [Azure Application Gateway](../management-services/applicationGateway/deploy.bicep) Azure Automation Account | This overlay module deploys an Platform Landing Zone compatible Azure Automation account, with diagnostic logs pointed to the Platform Landing Zone Log Analytics Workspace (LAWS) instance. | [Azure Automation Account](../management-services/automation/deploy.bicep) +Azure Security Center | This overlay module adds a standard/defender sku which enables a greater depth of awareness including more recomendations and threat analytics. | [Azure Security Center](../management-services/azureSecurityCenter/deploy.bicep) Bastion Host | This overlay module adds a linux and windows virtual machines to the Hub resource group to serve as a jumpbox into the network using Azure Bastion Host as the remote desktop solution without exposing the virtual machine via a Public IP address. | [Bastion Host](../management-services/bastion/deploy.bicep) Azure Container Registry | This overlay module deploys a premium Azure Container Registry suitable for hosting docker containers. The registry will be deployed to the Hub/Spoke shared services resource group using default naming unless alternative values are provided at run time. | [Azure Container Registry](../management-services/bastion/deploy.bicep) -Microsoft Defender for Cloud | This overlay module adds a standard/defender sku which enables a greater depth of awareness including more recomendations and threat analytics. | [Microsoft Defender for Cloud](../management-services/defender/deploy.bicep) -Microsoft Front Door Service | Module to deploy the Microsoft Front Door Service to the Hub Network -Network Security Groups | Module to deploy the Microsoft Front Door Service to the Hub Network +Azure Data Bricks Workspace (In Progress) | This overlay module deploys a premium Azure Data Bricks Workspace. | [Azure Data Bricks Workspace](../management-services/dataBricksWorkspace/deploy.bicep) +Azure Key Vault | This overlay module deploys a premium Azure Key Vault with RBAC enabled to support secret, key, and certificate management. A premium key vault utilizes hardware security modules to protect key material. | [Azure Key Vault](../management-services/keyvault/deploy.bicep) +Azure Kubernetes Service - Private Cluster | This overlay module deploys a Azure Kubernetes Service - Private Cluster - Kubenet suitable for hosting docker containers apps. The cluster will be deployed to the Hub/Spoke shared services resource group or Tier 3 spoke using default naming unless alternative values are provided at run time. | [Azure Kubernetes Service](../management-services/kubernetesPrivateCluster-Kubnet/deploy.bicep) +Microsoft Service Health Alerts | This overlay module deploys Microsoft Service Health Alerts to the target resource group.| [Microsoft Service Health Alerts](../management-services/service-health/deploy.bicep) + Azure Storage Account | This overlay module deploys a premium Azure Storage Account with RBAC enabled to support secret, key, and certificate management. | [Azure Storage Account](../management-services/storageAccount/deploy.bicep) +Subscription Budgets | This overlay module adds a standard/defender sku which enables a greater depth of awareness including more recomendations and threat analytics.This overlay module deploys a budget for an Azure Enterprise Agreement (EA) subscription. | [Subscription Budgets](../management-services/subscription-budget/deploy.bicep) +Tier 3 Workload Spoke Network | This overlay module deploys Tier 3 Workload network deployment based on the recommendations from the Azure Mission Landing Zone Conceptual Architecture. | [Tier 3 Workload Spoke Network](../management-services/workloadSpoke/deploy.bicep) diff --git a/src/bicep/overlays/management-services/service-health/readme.md b/src/bicep/overlays/management-services/service-health/readme.md index 6184e86..cde48f1 100644 --- a/src/bicep/overlays/management-services/service-health/readme.md +++ b/src/bicep/overlays/management-services/service-health/readme.md @@ -1,4 +1,4 @@ -# Overlay: NoOps Accelerator - Microsoft Service Health Alerts +# Overlays: Microsoft Service Health Alerts ## Overview diff --git a/src/bicep/overlays/management-services/storageAccount/readme.md b/src/bicep/overlays/management-services/storageAccount/readme.md index 3d4e563..214d3d8 100644 --- a/src/bicep/overlays/management-services/storageAccount/readme.md +++ b/src/bicep/overlays/management-services/storageAccount/readme.md @@ -1,4 +1,4 @@ -# Module: NoOps Accelerator - Azure Storage Account +# Overlays: Azure Storage Account ## Overview diff --git a/src/bicep/overlays/management-services/subscription-budget/readme.md b/src/bicep/overlays/management-services/subscription-budget/readme.md index 314ee52..8b0de80 100644 --- a/src/bicep/overlays/management-services/subscription-budget/readme.md +++ b/src/bicep/overlays/management-services/subscription-budget/readme.md @@ -1,4 +1,4 @@ -# Module: NoOps Accelerator - Subscription Budgets +# Overlays: Subscription Budgets ## Overview diff --git a/src/bicep/overlays/management-services/workloadSpoke/README.md b/src/bicep/overlays/management-services/workloadSpoke/README.md index 2fc6569..a9398a3 100644 --- a/src/bicep/overlays/management-services/workloadSpoke/README.md +++ b/src/bicep/overlays/management-services/workloadSpoke/README.md @@ -1,4 +1,4 @@ -# Module: NoOps Accelerator - Tier 3 Workload Network +# Overlay: Tier 3 Workload Spoke Network ## Overview