From b22257d012a71522e2b7e08890afba44bf2518c2 Mon Sep 17 00:00:00 2001 From: Steve Keeler Date: Wed, 8 Dec 2021 07:29:56 -0500 Subject: [PATCH] Create Azure DevOps Setup onboarding guide (#116) --- CONTRIBUTING.md | 2 +- README.md | 6 +- docs/archetypes/generic-subscription.md | 2 +- docs/archetypes/healthcare.md | 42 ++++----- docs/archetypes/logging.md | 12 +-- docs/archetypes/machinelearning.md | 6 +- docs/architecture.md | 34 ++++---- .../{ado.md => azure-devops-pipelines.md} | 6 +- docs/onboarding/azure-devops-setup.md | 86 +++++++++++++++++++ docs/policy/readme.md | 6 +- 10 files changed, 144 insertions(+), 58 deletions(-) rename docs/onboarding/{ado.md => azure-devops-pipelines.md} (99%) create mode 100644 docs/onboarding/azure-devops-setup.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index db1313c..29b7d26 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,7 +24,7 @@ or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any addi ## Deployment to your environment -See [Onboarding Guide for Azure DevOps](docs/onboarding/ado.md) +See the onboarding guides for [Azure DevOps Setup](docs/onboarding/azure-devops-setup.md) and [Azure DevOps Pipelines](azure-devops-pipelines.md) ## Pull Requests diff --git a/README.md b/README.md index 794adbe..e53891d 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ The automation is built with [Project Bicep](https://github.com/Azure/bicep/blob ## Onboarding to Azure DevOps -See [onboarding guide for Azure DevOps](docs/onboarding/ado.md) for setup instructions. +See the [Azure DevOps Setup](docs/onboarding/azure-devops-setup.md) and [Azure DevOps Pipelines](docs/onboarding/azure-devops-pipelines.md) onboarding guides for setup instructions. ## Goals @@ -55,7 +55,7 @@ See [Contributing Reference Implementation](CONTRIBUTING.md) for information on > Microsoft can identify the deployments of the Azure Resource Manager and Bicep templates with the deployed Azure resources. Microsoft can correlate these resources used to support the deployments. Microsoft collects this information to provide the best experiences with their products and to operate their business. The telemetry is collected through [customer usage attribution](https://docs.microsoft.com/azure/marketplace/azure-partner-customer-usage-attribution). The data is collected and governed by Microsoft's privacy policies, located at [https://www.microsoft.com/trustcenter](https://www.microsoft.com/trustcenter). > -> If you don’t wish to send usage data to Microsoft, you can set the `customerUsageAttribution.enabled` setting to `false` in `config/telemetry.json`. Learn more in our [onboarding guide](docs/onboarding/ado.md#telemetry). +> If you don't wish to send usage data to Microsoft, you can set the `customerUsageAttribution.enabled` setting to `false` in `config/telemetry.json`. Learn more in our [Azure DevOps Pipelines](docs/onboarding/azure-devops-pipelines.md#telemetry) onboarding guide. > > Project Bicep [collects telemetry in some scenarios](https://github.com/Azure/bicep/blob/main/README.md#telemetry) as part of improving the product. @@ -72,4 +72,4 @@ Super-Linter in this project is provided as an example for enabling source code ## Trademark -This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/legal/intellectualproperty/trademarks). Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party’s policies. +This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/legal/intellectualproperty/trademarks). Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies. diff --git a/docs/archetypes/generic-subscription.md b/docs/archetypes/generic-subscription.md index 798b2c4..a2d9c00 100644 --- a/docs/archetypes/generic-subscription.md +++ b/docs/archetypes/generic-subscription.md @@ -311,7 +311,7 @@ This example configures: ### Deployment Instructions -> Use the [Onboarding Guide for Azure DevOps](../onboarding/ado.md) to configure the `subscription` pipeline. This pipeline will deploy workload archetypes such as Generic Subscription. +> Use the [Azure DevOps Pipelines](../onboarding/azure-devops-pipelines.md) onboarding guide to configure the `subscription` pipeline. This pipeline will deploy workload archetypes such as Generic Subscription. Parameter files for archetype deployment are configured in [config/subscription folder](../../config/subscriptions). The directory hierarchy is comprised of the following elements, from this directory downward: diff --git a/docs/archetypes/healthcare.md b/docs/archetypes/healthcare.md index fd36596..418106f 100644 --- a/docs/archetypes/healthcare.md +++ b/docs/archetypes/healthcare.md @@ -26,13 +26,13 @@ Azure Policies are used to provide governance, compliance and protection while e **CloudOps team will be required for** -1. Establishing connectivity to Hub virtual network (required for egress traffic flow & Azure Bastion). -2. Creating App Registrations (required for service principal accounts). This is optional based on whether App Registrations are disabled for all users or not. +1. Establishing connectivity to Hub virtual network (required for egress traffic flow & Azure Bastion). +2. Creating App Registrations (required for service principal accounts). This is optional based on whether App Registrations are disabled for all users or not. **Workflow** -* A new subscription is created through existing process (either via ea.azure.com or Azure Portal). -* The subscription will automatically be assigned to the **pubsecSandbox** management group. +* A new subscription is created through existing process (either via ea.azure.com or Azure Portal). +* The subscription will automatically be assigned to the **pubsecSandbox** management group. * CloudOps will create a Service Principal Account (via App Registration) that will be used for future DevOps automation. * CloudOps will scaffold the subscription with baseline configuration. * CloudOps will hand over the subscription to requesting team. @@ -92,14 +92,14 @@ Subscription can be moved to a target Management Group through Azure ARM Templat The intended cloud service workflows and data movements for this archetype include: -1. Data can be ingested from data sources using Data Factory with managed virtual network for its Azure hosted integration runtime -2. Streaming data can be ingested using Event Hub and Stream Analytics -3. The data would be stored in Azure Data Lake Gen 2. -4. Healthcare providers can connect to existing data sources with FHIR API. -5. Data engineering and transformation tasks can be done with Spark using Azure Databricks. Transformed data would be stored back in the data lake. -6. End to end analytics and data warehousing can be done with Azure Synapse Analytics. -7. Machine learning would be done using Azure Machine Learning. -8. Monitoring and logging would be through Application Insights. +1. Data can be ingested from data sources using Data Factory with managed virtual network for its Azure hosted integration runtime +2. Streaming data can be ingested using Event Hub and Stream Analytics +3. The data would be stored in Azure Data Lake Gen 2. +4. Healthcare providers can connect to existing data sources with FHIR API. +5. Data engineering and transformation tasks can be done with Spark using Azure Databricks. Transformed data would be stored back in the data lake. +6. End to end analytics and data warehousing can be done with Azure Synapse Analytics. +7. Machine learning would be done using Azure Machine Learning. +8. Monitoring and logging would be through Application Insights. ## Access Control @@ -123,7 +123,7 @@ Once the machine learning archetype is deployed and available to use, access con | Azure Key Vault | Network ACL Deny | Private endpoint on `vault` + DNS registration to either hub or spoke | `privateEndpoints`| | SQL Database | Deny public network access | Private endpoint on `sqlserver` + DNS registration to either hub or spoke | `privateEndpoints`| | Azure Data Lake Gen 2 | Network ACL deny | Private endpoint on `blob`, `dfs` + DNS registration to either hub or spoke | `privateEndpoints`| -| Synapse | Disabled public network access; managed virtual network | * Managed Private Endpoints & Synapse Studio Private Link Hub. Private endpoint DNS registration. | `privateEndpoints` | +| Synapse | Disabled public network access; managed virtual network | * Managed Private Endpoints & Synapse Studio Private Link Hub. Private endpoint DNS registration. | `privateEndpoints` | | Azure Databricks | No public IP enabled (secure cluster connectivity), load balancer for egress with IP and outbound rules, virtual network ibjection | N/A | `databricksPrivate`, `databricksPublic`| | Azure Machine Learning | No public workspace access | Private endpoint on `amlWorkspace` + DNS registration to either hub or spoke | `privateEndpoints`| | Azure Storage Account for Azure ML | Network ACL deny | Private endpoint on `blob`, `file` + DNS registration to either hub or spoke | `privateEndpoints`| @@ -184,13 +184,13 @@ The scripts are: * Upload some data to the default ADLS Gen 2 of Synapse * Run the integration tests for Synapse SQL Serverless Pool * Spark pool connectivity to data lake - * Ensure the user has storage blob data contributor role for the data lake - * Upload some data to the default ADLS Gen 2 of Synapse - * Run the integration tests for Synapse Spark Pool + * Ensure the user has storage blob data contributor role for the data lake + * Upload some data to the default ADLS Gen 2 of Synapse + * Run the integration tests for Synapse Spark Pool * Dedicated SQL (SQL Data warehouse) - * Ensure the user identity has a SQL Login (e.g. the admin user could be assigned the SQL AD admin) - * Upload some data to the default ADLS Gen 2 of Synapse - * Run the integration tests for Synapse SQL Dedicated Pool (DW) + * Ensure the user identity has a SQL Login (e.g. the admin user could be assigned the SQL AD admin) + * Upload some data to the default ADLS Gen 2 of Synapse + * Run the integration tests for Synapse SQL Dedicated Pool (DW) ### Test Scenarios @@ -383,7 +383,7 @@ This example configures: "aadLoginName":"DBA Group", "aadLoginObjectID":"4e4ea47c-ee21-4add-ad2f-a75d0d8014e0", "aadLoginType":"Group" - } + } }, "synapse": { "value": { @@ -462,7 +462,7 @@ This example configures: ### Deployment Instructions -> Use the [Onboarding Guide for Azure DevOps](../onboarding/ado.md) to configure the `subscription` pipeline. This pipeline will deploy workload archetypes such as Healthcare. +> Use the [Azure DevOps Pipelines](../onboarding/azure-devops-pipelines.md) onboarding guide to configure the `subscription` pipeline. This pipeline will deploy workload archetypes such as Healthcare. Parameter files for archetype deployment are configured in [config/subscription folder](../../config/subscriptions). The directory hierarchy is comprised of the following elements, from this directory downward: diff --git a/docs/archetypes/logging.md b/docs/archetypes/logging.md index ed55de4..e87b82c 100644 --- a/docs/archetypes/logging.md +++ b/docs/archetypes/logging.md @@ -14,12 +14,12 @@ Centralized logging landing zone allows a common subscription for managing Log A **Workflow** -* A new subscription is created through existing process (either via ea.azure.com or Azure Portal). -* The subscription will automatically be assigned to the **pubsecSandbox** management group. -* Update configuration in Azure DevOps Git repo. -* Execute the **Platform – Logging** Azure DevOps Pipeline. The pipeline will: +* A new subscription is created through existing process (either via ea.azure.com or Azure Portal). +* The subscription will automatically be assigned to the **pubsecSandbox** management group. +* Update configuration in Azure DevOps Git repo. +* Execute the **Platform – Logging** Azure DevOps Pipeline. The pipeline will: * Move it to the target management group. - * Scaffold the subscription with baseline configuration. + * Scaffold the subscription with baseline configuration. **Subscription Move** @@ -54,4 +54,4 @@ Reference implementation uses parameter files with `object` parameters to consol ## Deployment Instructions -Use the [Onboarding Guide for Azure DevOps](../onboarding/ado.md) to configure this archetype. \ No newline at end of file +Use the [Azure DevOps Pipelines](../onboarding/azure-devops-pipelines.md) onboarding guide to configure this archetype. \ No newline at end of file diff --git a/docs/archetypes/machinelearning.md b/docs/archetypes/machinelearning.md index 5fdec33..7a21ae9 100644 --- a/docs/archetypes/machinelearning.md +++ b/docs/archetypes/machinelearning.md @@ -34,8 +34,8 @@ Azure Policies are used to provide governance, compliance and protection while e **Workflow** -* A new subscription is created through existing process (either via ea.azure.com or Azure Portal). -* The subscription will automatically be assigned to the **pubsecSandbox** management group. +* A new subscription is created through existing process (either via ea.azure.com or Azure Portal). +* The subscription will automatically be assigned to the **pubsecSandbox** management group. * CloudOps will create a Service Principal Account (via App Registration) that will be used for future DevOps automation. * CloudOps will scaffold the subscription with baseline configuration. * CloudOps will hand over the subscription to requesting team. @@ -465,7 +465,7 @@ This example configures: ### Deployment Instructions -> Use the [Onboarding Guide for Azure DevOps](../onboarding/ado.md) to configure the `subscription` pipeline. This pipeline will deploy workload archetypes such as Machine Learning. +> Use the [Azure DevOps Pipelines](../onboarding/azure-devops-pipelines.md) onboarding guide to configure the `subscription` pipeline. This pipeline will deploy workload archetypes such as Machine Learning. Parameter files for archetype deployment are configured in [config/subscription folder](../../config/subscriptions). The directory hierarchy is comprised of the following elements, from this directory downward: diff --git a/docs/architecture.md b/docs/architecture.md index 0952fae..f67e2cc 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -30,7 +30,7 @@ This document describes the architecture and design decisions for building a **[ The table below outlines the key decisions each department must consider as part of adopting Azure. This list is provided to help guide and is not meant to be exhaustive. -| Topic | Scenario | Ownership | Complexity to change | Decision | +| Topic | Scenario | Ownership | Complexity to change | Decision | | --- | --- | --- | --- | --- | | Private IP range for Cloud | Based on [RFC 1918][rfc1918] and [RFC 6598][rfc6598], to allow seamless routing for hybrid connectivity. | | | | | Ground to Cloud Network Connectivity | Use either: Express Route; or SCED for hybrid connectivity. | | | | @@ -141,7 +141,7 @@ Azure Landing Zones for Canadian Public Sector assumes that Azure Active Directo * App Registration - Consider disabling for all users and created on-demand by CloudOps teams. * Sign-In Logs - Logs are exported to Log Analytics workspace & Microsoft Sentinel used for threat hunting (Security Monitoring Team). * Break-glass procedure - Process documented and implemented including 2 break glass accounts with different MFA devices & split up passwords. -* Azure Directory to Azure Active Directory synchronization - Are the identities synchronized or using cloud only account? +* Azure Directory to Azure Active Directory synchronization - Are the identities synchronized or using cloud only account? ### 4.1 Service Principal Accounts @@ -447,14 +447,14 @@ All pipelines are in **.pipelines/** folder. Pipelines are stored as YAML definitions in Git and imported into Azure DevOps Pipelines. This approach allows for portability and change tracking. To import a pipeline: -1. Go to Pipelines -2. New Pipeline -3. Choose Azure Repos Git -4. Select Repository -5. Select Existing Azure Pipeline YAML file -6. Identify the pipeline using the table below and add. +1. Go to Pipelines +2. New Pipeline +3. Choose Azure Repos Git +4. Select Repository +5. Select Existing Azure Pipeline YAML file +6. Identify the pipeline using the table below and add. -Use the [onboarding guide for Azure DevOps](onboarding/ado.md) to configure each pipeline. +Use the [Azure DevOps Pipelines](onboarding/azure-devops-pipelines.md) onboarding guide to configure each pipeline. > Imported pipelines should be renamed to match the names in the table. @@ -492,9 +492,9 @@ You can combine all three techniques within a release pipeline to fully achieve Manual validation can be done in one of two ways: -1. Add an agentless (server) job before the existing pipeline job(s) where you want to enforce pre-deployment user validation. +1. Add an agentless (server) job before the existing pipeline job(s) where you want to enforce pre-deployment user validation. -2. Create an Environment (or multiple environments) in your Azure DevOps project where you can specify pre-deployment user validations via “Approvals and checks”. +2. Create an Environment (or multiple environments) in your Azure DevOps project where you can specify pre-deployment user validations via "Approvals and checks". We will focus on the second option, as it allows for the following additional types of approvals and checks: @@ -502,17 +502,17 @@ We will focus on the second option, as it allows for the following additional ty Steps to implement user validation (approval) check: -1. Create an Environment named after the branch (e.g. “main”, “sandbox”) you want to protect. You can do this manually through the web UI or by running the pipeline (if the environment does not exist, it will be created). +1. Create an Environment named after the branch (e.g. "main", "sandbox") you want to protect. You can do this manually through the web UI or by running the pipeline (if the environment does not exist, it will be created). -2. In the web UI, navigate to Pipelines | Environments, select the environment corresponding to the branch you want to protect, and select “Approvals and checks” from the context menu. +2. In the web UI, navigate to Pipelines | Environments, select the environment corresponding to the branch you want to protect, and select "Approvals and checks" from the context menu. -3. Select the “Approval” option to add a new user validation approval. +3. Select the "Approval" option to add a new user validation approval. -4. Add user(s)/group(s) to the “Approvers” field. Approval check will require approval from all listed users/groups. For a group approval, any one member of the group is sufficient for approval. Note that you may use Azure DevOps and Azure Active Directory groups and may want to do this to minimize administrative overhead associated with managing individual users roles and responsibilities. +4. Add user(s)/group(s) to the "Approvers" field. Approval check will require approval from all listed users/groups. For a group approval, any one member of the group is sufficient for approval. Note that you may use Azure DevOps and Azure Active Directory groups and may want to do this to minimize administrative overhead associated with managing individual users roles and responsibilities. -5. Under “Advanced” options, decide if you want to allow users in the Approvers list to approve their own pipeline runs. +5. Under "Advanced" options, decide if you want to allow users in the Approvers list to approve their own pipeline runs. -6. Under “Control options”, set an appropriate “Timeout” after which approval requests will expire. The default is 30 days, however you may wish to reduce this time window. +6. Under "Control options", set an appropriate "Timeout" after which approval requests will expire. The default is 30 days, however you may wish to reduce this time window. [itsg33]: https://www.cyber.gc.ca/en/guidance/it-security-risk-management-lifecycle-approach-itsg-33 [itsg22]: https://www.cyber.gc.ca/sites/default/files/publications/itsg-22-eng.pdf diff --git a/docs/onboarding/ado.md b/docs/onboarding/azure-devops-pipelines.md similarity index 99% rename from docs/onboarding/ado.md rename to docs/onboarding/azure-devops-pipelines.md index 547d288..863da69 100644 --- a/docs/onboarding/ado.md +++ b/docs/onboarding/azure-devops-pipelines.md @@ -1,6 +1,6 @@ -# Onboarding Guide for Azure DevOps +# Azure DevOps Pipelines -This document provides steps required to onboard to the Azure Landing Zones design based on Azure DevOps Pipelines. +This document provides steps required to onboard to the Azure Landing Zones design using Azure DevOps Pipelines. **All steps will need to be repeated per Azure AD tenant.** @@ -14,7 +14,7 @@ Microsoft can identify the deployments of the Azure Resource Manager and Bicep t The automation is instrumented to identify the modules that are being deployed. At this time, we don't differentiate the deployments and tracked under a single GUID (`a83f6385-f514-415f-991b-2d9bd7aed658`). -If you don’t wish to send usage data to Microsoft, you can set the `customerUsageAttribution.enabled` setting to `false` in `config/telemetry.json`. +If you don't wish to send usage data to Microsoft, you can set the `customerUsageAttribution.enabled` setting to `false` in `config/telemetry.json`. **Example with telemetry disabled** diff --git a/docs/onboarding/azure-devops-setup.md b/docs/onboarding/azure-devops-setup.md new file mode 100644 index 0000000..933ded0 --- /dev/null +++ b/docs/onboarding/azure-devops-setup.md @@ -0,0 +1,86 @@ +# Azure DevOps Setup + +## Introduction + +This document provides guidance on considerations and recommended practices when creating and configuring your Azure DevOps Services environment. Keep in mind that there is no _one size fits all_ approach for determining the number of Azure DevOps Services organizations, projects, and teams. Use the information presented here in the context of your organization structure, policies, and processes. + +If you already have one or more Azure DevOps Services organizations, reviewing this information may help you identify ways to improve upon your existing configuration. + +## Structure considerations + +This section introduces some terminology, and examines logical boundaries at the organizational level in relation to the boundaries available for separating work efforts within Azure DevOps Services. + +- **Organization boundaries** + + - **`Division`**: a division is a logical grouping, at a higher level in an organization that consists of multiple `Groups`. A division may have its own dedicated Azure DevOps organization or have its own Azure DevOps project, depending on the overall organization size and number of end-state `Organizations` and `Projects`. + - **`Group`**: a group is an area within a `Division` that typically is responsible for multiple/many `Solutions`. A group may have its own dedicated `Project` or for smaller organizations share a `Project` with other `Groups` based on a consistent `Team` naming convention within the `Project`. + - **`Solution`**: a solution refers to a business solution that is possibly comprised of multiple components. Often, individuals will work on multiple solution efforts. At this level, `Solutions` are usually best implemented as `Teams` within a `Project`. + +- **Azure DevOps boundaries** + + - **`Organization`**: an Azure DevOps organization may have the same or different Azure AD tenant backing user authentication. Generally speaking, there little to no visibility between `Projects` (and `Teams`) that are located in different Azure DevOps organizations. Furthermore, it is difficult to track work efforts (e.g. using Agile Portfolio Management techniques) for `Projects` and `Teams` that are located in different Azure DevOps organizations. Where these boundaries are desirable, perhaps at higher levels in a large organization, having a separate Azure DevOps organization may be desirable. + - **`Project`**: a project within an Azure DevOps organization shares `Organization`-level administrative capabilities, such as work item process customization, access to the same set of extensions, a common billing source (Azure subscription), a common Azure AD tenant for identity/authentication, auditing, and a common set of security policies. Additionally, there is visibility between projects on elements such as work items, repositories. + - **`Team`**: a team within an Azure DevOps project shares `Project`-level administrative capabilities, but may customize many aspects of the interface to their teams requirements, for example: boards, repositories, wikis, etc. Pipelines do not have team-specific views, however it is possible to have multiple Git repositories per `Project` and organize them in a folder hierarchy by `Team`. Read more about this topic in [When to add a team or project](https://docs.microsoft.com/azure/devops/pipelines/create-first-pipeline) and [When to add another project](https://docs.microsoft.com/azure/devops/organizations/projects/about-projects#when-to-add-another-project). + +Generally, it is recommended to strive for fewer Azure DevOps organizations and projects where possible. For ideas on how to determine the right mix of `Organizations`, `Projects` and `Teams` for your business, refer to the Q&A in the next section. + +## Create a new team, project, or organization? + +Review the following questions and answers to help determine when it's most appropriate to create a new `Team` vs `Project` vs `Organization` in Azure DevOps. + +| # | Question | Answer +| :-: | -------------------- | -------------------- +| 1 | Is there a need for strict separation of all DevOps related material (e.g. for security reasons) between a `Group` or `Solution` and any existing Azure DevOps organizations or projects? | If `yes` then create a new Azure DevOps `Organization`, `Project`, and `Team` for this solution area. +| 2 | Is there a need for either: 1) performing user authentication against a different Azure AD tenant, and/or 2) using a separate Azure subscription to provide billing capabilities for user-licensing? | If `yes` then create a new Azure DevOps `Organization`, `Project`, and `Team` for this solution area. Note that for billing, it is possible to report on costs in Azure Cost Management by Azure DevOps `Organization` and `Project`, so you may not need to create a separate Azure DevOps `Organization` if the only billing requirement is to track expenditures. +| 3 | Does the `Group` responsible for the solution have other solutions in Azure DevOps? | If `yes` then use the existing project and create a new `Team` specifically for this solution. +| 4 | Does the `Group` require a different process template (i.e. Agile, Scrum, CMMI, Basic) than is available in any existing `Project` in their (or related) area? | If `yes` then create a new Azure DevOps `Project` with the required process template. +| 5 | Does the `Group` have very different policy/security requirements on pipelines and/or repositories from other `Groups` in any existing `Project` where they might otherwise colocate (e.g. pull request for check-ins on main branch? | If `yes` consider creating a new Azure DevOps `Project` (and `Team`) for them. Carefully consider this option and speak with the requestor in advance of doing this as it can result in inconsistent controls across projects. + +## Azure AD tenant configuration + +These activities should be completed once per Azure Active Directory tenant that is associated with one or more Azure DevOps organizations in your environment. + +| # | | Task +| :-: | - | -------------------- +| 1 | [Link](https://docs.microsoft.com/azure/devops/organizations/accounts/azure-ad-tenant-policy-restrict-org-creation#prerequisites) | Enable the Azure AD prerequisites for the `Restrict organization creation` policy. +| 2 | | Add users to the Azure AD group `Azure DevOps Administrators` who should have the ability to create new Azure DevOps organizations that are linked to your Azure AD tenant. + +## Creating an Azure DevOps organization + +These activities should be completed once per new Azure DevOps organization created in your environment. + +| # | | Task +| :-: | - | -------------------- +| 1 | [Link](https://docs.microsoft.com/azure/devops/organizations/accounts/create-organization) | Create a new Azure DevOps organization. Ensure you are signed in with the identity from the Azure AD tenant you want associated with the new Azure DevOps organization. During the creation process, ensure you select the Canada geography for [data location](https://docs.microsoft.com/azure/devops/organizations/security/data-location) - it should default to this setting based on nearest geography, but it's good to be aware of this configuration option just in case. +| 2 | [Link](https://docs.microsoft.com/azure/devops/organizations/security/set-project-collection-level-permissions) | Add one or more secondary users to the `Project Collection Administrators` group. This ensures continuity in the event the original creator (Owner) of the Azure DevOps organization is unavailable. Limit the total number of users assigned this role to the minium needed. +| 3 | [Link](https://docs.microsoft.com/azure/devops/organizations/accounts/azure-ad-tenant-policy-restrict-org-creation#turn-on-the-policy) | Turn on the `Restrict organization creation` policy. +| 4 | [Link](https://docs.microsoft.com/azure/devops/organizations/billing/set-up-billing-for-your-organization-vs) | Set up billing for your organization. This step associates your Azure DevOps organization with an Azure subscription as a means of payment for things like additional `Basic` access licensed users, additional parallel jobs for Azure Pipelines, and additional storage for Azure Artifacts. +| 5 | [Link](https://docs.microsoft.com/azure/devops/organizations/accounts/add-organization-users) | Add users who will need access to projects within this organization. As part of adding users you will specify an Access Level (Stakeholder, Basic, or Visual Studio Subscriber). Optionally, you may want to consider implementing one or more [Group Rules](https://docs.microsoft.com/azure/devops/organizations/accounts/assign-access-levels-by-group-membership) to automate Access Level and Project permission assignments based on user membership in either an Azure AD group or an Azure DevOps Services group. +| 6 | [Link](https://docs.microsoft.com/azure/devops/organizations/settings/work/manage-process#set-the-default-process) | Set/change the default process to one of the following values, based on your organization's process template standard or the process you anticipate will be most often used during Azure DevOps project creation: `Agile`, `Scrum`, `Basic`, or `CMMI`. You may also customize an existing process (inheritance) and set that to be the default process selected during Azure DevOps project creation. +| 7 | [Link](https://aka.ms/vsts-anon-access) | Turn off the option allowing public projects. +| 8 | [Link](https://docs.microsoft.com/azure/devops/organizations/settings/timezone-settings-usage) | Configure time zone settings. + +## Creating an Azure DevOps project + +These activities should be completed once per new Azure DevOps project created in your environment. Creating a new project can be done by members of the `Project Collection Administrators` role at the Azure DevOps organization level. The other activities in this section can be performed by either a member of the `Project Collection Administrators` role, or by any individual added to the `Project Administrators` role for the newly created project. + +| # | | Task +| :-: | - | -------------------- +| 1 | [Link](https://docs.microsoft.com/azure/devops/organizations/projects/create-project) | Create a new Azure DevOps project. You will need to have the following information available to configure the newly created project: project name, visibility (typically Private), version control (typically Git), and work item process (e.g. Agile, Scrum, Basic, or CMMI). You should develop and follow an standard naming convention for projects. This allows users to easily find and identify projects based on their usage within the organization. While you may use spaces in your project names, this is discouraged as it leads to special encoding requirements in reference URLs. E.g. the URL-encoded sequence for a space character is `%20`, which has the effect of visually cluttering URL references to elements of the project, such as pipelines, and generally makes it more difficult to write automation scripts. +| 2 | [Link](https://docs.microsoft.com/azure/devops/organizations/security/add-users-team-project) | Add users to the newly created project. When adding users to a project, you will place them into one of three roles: 1) Readers, 2) Contributors, or 3) Project Administrators. The list of users and their roles should be acquired from the group requesting the project as part of the intake process. Once one or more Project Administrators have been added to a project, they can complete any additional configuration for the project (e.g. the following steps in this list), or you may continue and do so on their behalf. +| 3 | [Link](https://docs.microsoft.com/azure/devops/organizations/settings/set-services) | **Optionally** disable visibility of any Azure DevOps services that are not required by the project members. For example, if no project members are using source control (Azure Repos), you can turn off its visibility in the menu at the project scope so it does not appear in the sidebar menu. +| 4 | [Link](https://docs.microsoft.com/azure/devops/organizations/projects/create-project#add-a-repository-to-your-project) | Add a repository to the project. Additionally you may also: [Clone an existing Git repo](https://docs.microsoft.com/azure/devops/repos/git/clone), [Import a Git repo](https://docs.microsoft.com/azure/devops/repos/git/import-git-repository), and [Import a repo from TFVC](https://docs.microsoft.com/azure/devops/repos/git/import-from-tfvc). +| 5 | [Link](https://docs.microsoft.com/azure/devops/boards/work-items/view-add-work-items) | Add new work items to the project. For example, populate an initial set of User Stories. +| 6 | [Link](https://docs.microsoft.com/azure/devops/organizations/settings/about-areas-iterations) | Configure `Area` and `Iteration` (sprint) paths. + +## Creating an Azure DevOps team in existing project + +These activities should be completed once per new `Team` created in an existing Azure DevOps project. They can be (and usually are) performed by a member of the `Project Administrators` role in the current project where the team will be created. They can also be performed optionally by any member of the `Project Collection Administrators` role at the Azure DevOps organization level. + +| # | | Task +| :-: | - | -------------------- +| 1 | [Link](https://docs.microsoft.com/azure/devops/organizations/settings/add-teams) | Add a new team. +| 2 | [Link](https://docs.microsoft.com/azure/devops/organizations/settings/add-team-administrator) | Add one or more team administrators. +| 3 | [Link](https://docs.microsoft.com/en-us/azure/devops/organizations/security/add-users-team-project) | Add users to the team. +| 4 | [Link](https://docs.microsoft.com/azure/devops/project/navigation/set-favorites) | Set team favorites. +| 5 | [Link](https://docs.microsoft.com/azure/devops/boards/plans/portfolio-management) | Determine if this team is part of a larger portfolio management effort, and if so follow the guidance in [Configure a hierarchy of team](https://docs.microsoft.com/azure/devops/boards/plans/configure-hierarchical-teams) to ensure the newly created team is configured in the hierarchy. diff --git a/docs/policy/readme.md b/docs/policy/readme.md index 02a59ea..a853674 100644 --- a/docs/policy/readme.md +++ b/docs/policy/readme.md @@ -44,7 +44,7 @@ Azure DevOps Pipeline ([.pipelines/policy.yml](../../.pipelines/policy.yml)) is workingDir: $(System.DefaultWorkingDirectory)/policy/builtin/assignments ``` -All policy set assignments are at the `pubsec` top level management group. This top level management group is retrieved from configuration parameter `var-topLevelManagementGroupName`. See [Onboarding Guide for Azure DevOps](../onboarding/ado.md) for instructions to setting up management groups & policy pipeline. +All policy set assignments are at the `pubsec` top level management group. This top level management group is retrieved from configuration parameter `var-topLevelManagementGroupName`. See the [Azure DevOps Pipelines](../onboarding/azure-devops-pipelines.md) onboarding guide for instructions to setting up management groups & policy pipeline. | Policy Set | Description | Deployment Template | Configuration | | --- | --- | --- | --- | @@ -53,7 +53,7 @@ All policy set assignments are at the `pubsec` top level management group. This | [NIST SP 800-53 Revision 5][nist80053R5policySet] | This initiative includes policies that address a subset of NIST SP 800-53 Rev. 5 controls. | [nist80053r5.bicep](../../policy/builtin/assignments/nist80053r5.bicep) | [nist80053r5.parameters.json](../../policy/builtin/assignments/nist80053r5.parameters.json) | | [Azure Security Benchmark][asbPolicySet] | The Azure Security Benchmark initiative represents the policies and controls implementing security recommendations defined in Azure Security Benchmark, see https://aka.ms/azsecbm. This also serves as the Microsoft Defender for Cloud default policy initiative. | [asb.bicep](../../policy/builtin/assignments/asb.bicep) | [asb.parameters.json](../../policy/builtin/assignments/asb.parameters.json) | | [CIS Microsoft Azure Foundations Benchmark 1.3.0][cisMicrosoftAzureFoundationPolicySet] | This initiative includes policies that address a subset of CIS Microsoft Azure Foundations Benchmark recommendations. | [cis-msft-130.bicep](../../policy/builtin/assignments/cis-msft-130.bicep) | [cis-msft-130.parameters.json](../../policy/builtin/assignments/cis-msft-130.parameters.json) | -| [FedRAMP Moderate][fedrampmPolicySet] | This initiative includes policies that address a subset of FedRAMP Moderate controls. | [fedramp-moderate.bicep](../../policy/builtin/assignments/fedramp-moderate.bicep) | [fedramp-moderate.parameters.json](../../policy/builtin/assignments/fedramp-moderate.parameters.json) | +| [FedRAMP Moderate][fedrampmPolicySet] | This initiative includes policies that address a subset of FedRAMP Moderate controls. | [fedramp-moderate.bicep](../../policy/builtin/assignments/fedramp-moderate.bicep) | [fedramp-moderate.parameters.json](../../policy/builtin/assignments/fedramp-moderate.parameters.json) | | [HIPAA / HITRUST 9.2][hipaaHitrustPolicySet] | This initiative includes audit and virtual machine extension deployment policies that address a subset of HITRUST/HIPAA controls. | [hitrust-hipaa.bicep](../../policy/builtin/assignments/hitrust-hipaa.bicep) | [hitrust-hipaa.parameters.json](../../policy/builtin/assignments/hitrust-hipaa.parameters.json) | Location | Restrict deployments to Canadian regions. | [location.bicep](../../policy/builtin/assignments/location.bicep) | [location.parameters.json](../../policy/builtin/assignments/location.parameters.json) | @@ -64,7 +64,7 @@ All policy set assignments are at the `pubsec` top level management group. This > **Note**: The custom policies & policy sets are used when built-in alternative does not exist. Automation is regularly revised to use built-in policies and policy sets as new options are made available. -All policies and policy set definitions & assignments are at the `pubsec` top level management group. This top level management group is retrieved from configuration parameter `var-topLevelManagementGroupName`. See [Onboarding Guide for Azure DevOps](../onboarding/ado.md) for instructions to setting up management groups & policy pipeline. +All policies and policy set definitions & assignments are at the `pubsec` top level management group. This top level management group is retrieved from configuration parameter `var-topLevelManagementGroupName`. See the [Azure DevOps Pipelines](../onboarding/azure-devops-pipelines.md) onboarding guide for instructions to setting up management groups & policy pipeline. ### Custom Policy Definitions