Edit

Set up the Microsoft Discovery onboarding tool

Get the latest onboarding tool and prepare the resources needed for Stage 1. This task doesn't deploy Discovery or configure its final networking.

Prerequisites

  • PowerShell 7 or later on Windows, macOS, or Linux.
  • Git, or an approved way to download and extract the complete Discovery repository.
  • For live checks and execution: Azure CLI, an enabled Discovery subscription, and the appropriate stage permissions.
  • To create resources: permission to create the target resource group, user-assigned managed identity (UAMI), and storage account. Reader access isn't enough.

Offline previews of Stages 2-5 need only PowerShell, the tool files, and a configuration. They don't need Azure access. Stage 1 can parse a workbook offline, but skipped Azure checks don't prove readiness.

Obtain the complete tool

  1. Get the latest files from the repository's main branch:

    git clone --branch main https://github.com/microsoft/discovery.git
Set-Location .\discovery

    If you already cloned the repository, run these commands from its root directory instead:

    git switch main
git pull --ff-only origin main

    Resolve any local changes or branch conflicts before updating. Don't check out a specific commit.

  2. Enter the scripts directory:

    Set-Location .\utilities\onboarding-tool\scripts
pwsh --version
Get-ChildItem

    Confirm that the five stage directories and lib are present. Keep the complete utilities/onboarding-tool folder: the scripts need its modules, workbooks, dependency specifications, and templates.

Run all stage examples from a PowerShell 7 prompt in this directory. On macOS or Linux, you can also run a script from bash or zsh with pwsh ./<stage>/<script>.ps1.

The stage scripts read .xlsx files without ImportExcel. The separate persona-role assignment utility has its own module requirements.

Confirm deployment choices

Confirm your deployment path in the planning overview. Before filling in the workbook, review network choices and resource naming rules.

Stage 2 registers the providers it needs. A container registry is needed for custom tool images, not for this guide's Q&A test. These linked procedures aren't additional onboarding stages.

Select the live Azure context

Skip this section for an offline preview.

  1. Sign in and select the intended subscription:

    az login
az account set --subscription "<subscription-id>"
az account show --query "{tenantId:tenantId,name:name,id:id}" -o table

  2. Confirm the tenant and subscription. If Microsoft.Discovery isn't available, contact your Microsoft account representative to request service access. Provider registration alone doesn't enable the service.

  3. Review permissions by stage. Activate elevated access only when needed, and keep it active until the task and cleanup finish.

Identify or create the initial dependencies

Before Stage 1, create or identify a platform resource group, UAMI, and project storage account. The tool doesn't create the identity or account. You can create storage before the Discovery network; Stage 2 configures its networking later.

  1. Identify the approved resource group and region. For a new group, run:

    az group create --name "<platform-resource-group>" --location "<region>"

  2. Create or identify a UAMI and save its full resource ID:

    az identity show --resource-group "<platform-resource-group>" --name "<uami-name>" --query "{id:id,principalId:principalId}" -o json

    If needed, use the linked procedure to create it. Stage 2 assigns its roles after the network and storage exist.

  3. Create or identify a StorageV2 account and save its name, resource group, and resource ID:

    az storage account show --resource-group "<storage-resource-group>" --name "<storage-account-name>" --query "{id:id,name:name,location:location}" -o json

    Project storage is required even without Bookshelf. Get owner approval for a shared account: Stage 2 changes its firewall, CORS, containers, and private endpoints.

  4. Check quota and capacity in the selected region. Supported Discovery home regions are East US, Sweden Central, and UK South. Region support doesn't guarantee model or VM capacity.

Set controlPlaneRegion for Discovery control-plane resources and workloadRegion for the VNet, subnets, and managed-resource-group resources. The regions can differ. For an existing network, prepare it in workloadRegion before Stage 1. Otherwise, Stage 2 can create it from your approved plan.

Prepare runner access and output handling

The computer running live stages must reach Azure control-plane endpoints. For a private workspace, run Stage 5 from a location with access to its private data-plane endpoint. Users viewing project outputs also need browser access to blob storage.

The examples save reports in .\out, which the tool creates when needed. Treat configuration and reports as sensitive customer data. Don't commit them, even though out is git-ignored.

Before continuing, confirm the Azure context, resource IDs, network plan, and required permissions.

For help with results or failures, see reports and artifacts and onboarding troubleshooting.

Next step

Create an onboarding configuration

  • Last updated on