From 4575c5fbacc192400a3663b432033e9117cf7f78 Mon Sep 17 00:00:00 2001 From: Premek Vysoky Date: Wed, 8 Apr 2026 10:22:53 +0200 Subject: [PATCH] Refactor `ChoosingAMachinePool.md` --- Documentation/ChoosingAMachinePool.md | 101 ++++++++++++++++++++------ 1 file changed, 78 insertions(+), 23 deletions(-) diff --git a/Documentation/ChoosingAMachinePool.md b/Documentation/ChoosingAMachinePool.md index 4d1bec2589f..65d96ccb882 100644 --- a/Documentation/ChoosingAMachinePool.md +++ b/Documentation/ChoosingAMachinePool.md @@ -1,41 +1,96 @@ # Choosing a Machine Pool ## Builds -All Azure Pipelines builds should use the following agent queues - * Pull Request validation and Public CI - * Windows - [dotnet-external-temp] - * Linux - [dnceng-linux-external-temp] - * Mac - [Hosted macOS](https://docs.microsoft.com/en-us/azure/devops/pipelines/agents/hosted?view=vsts&tabs=yaml) - * Official Signed Builds - * Windows - [dotnet-internal-temp] - * Linux - [dnceng-linux-internal-temp] - * Mac - [Hosted mac Internal](https://docs.microsoft.com/en-us/azure/devops/pipelines/agents/hosted?view=vsts&tabs=yaml) -Pools for an Azure DevOps Pipeline can be specified at the build and/or job level in the yaml file ([documentation](https://docs.microsoft.com/en-us/azure/devops/pipelines/process/phases?view=vsts&tabs=yaml)). +Arcade repos should use the shared **pool provider variables** from the repo templates instead of hard-coding legacy queue names. -Detailed information about the machines in an agent queue can be found in the [dotnet-helix-machines] repo. Additional dependencies not available on the machines should be bootstrapped in using our [Bootstrapping System]. If bootstrapping doesn't work for a specific dependency contact [@dotnet/dnceng] for guidance. +### Pull Request validation and public CI + +Import: + +```yaml +variables: +- template: /eng/common/templates/variables/pool-providers.yml +``` + +Use: + +- **Pool**: `$(DncEngPublicBuildPool)` +- This resolves to: + - `NetCore-Public` for `main` and other non-release branches + - `NetCore-Svc-Public` for `release/*` branches + +Typical images used in this repo: + +- **Windows**: `windows.vs2026.amd64.open` +- **Linux**: `build.azurelinux.3.amd64.open` +- **Mac**: [Hosted macOS](https://docs.microsoft.com/en-us/azure/devops/pipelines/agents/hosted?view=vsts&tabs=yaml) + +Example: + +```yaml +pool: + name: $(DncEngPublicBuildPool) + demands: ImageOverride -equals windows.vs2026.amd64.open +``` + +### Official / signed builds + +Import: + +```yaml +variables: +- template: /eng/common/templates-official/variables/pool-providers.yml +``` + +Use: + +- **Pool**: `$(DncEngInternalBuildPool)` +- This resolves to: + - `NetCore1ESPool-Internal` for `main` and other non-release branches + - `NetCore1ESPool-Svc-Internal` for `release/*` branches + +Typical images used in this repo: + +- **Windows**: `windows.vs2026.amd64` +- **Linux**: `build.azurelinux.3.amd64` +- **Mac**: [Hosted mac Internal](https://docs.microsoft.com/en-us/azure/devops/pipelines/agents/hosted?view=vsts&tabs=yaml) + +For official 1ES pipelines, prefer the `image` syntax: + +```yaml +pool: + name: $(DncEngInternalBuildPool) + image: windows.vs2026.amd64 + os: windows +``` + +For job templates that still use queue demands, use the equivalent `ImageOverride` demand instead. + +## Choosing an image + +- Prefer the same image already used by similar jobs in this repo. +- Linux images generally boot faster than Windows images. +- For a live list of approved images, see [helix.dot.net/#1esPools](https://helix.dot.net/#1esPools). +- For official builds (with the exception of macOS), **avoid hosted images** (such as `windows-latest` or `ubuntu-latest`). ## Test Execution -All test execution should run through helix. An up to date list of helix queues can be obtained from the [Helix Queue Info Api] using the following steps. - * Perform an HTTP GET of https://helix.dot.net/api/2018-03-14/info/queues with your http requesting software of choice. (A web browser works fine) - * You will be presented with a json array containing descriptions of all the queues available in helix. - * All of the queues in the list are available for use in helix. Detailed information about machine setup can be found in the [dotnet-helix-machines] repo. - * Submit your test jobs to helix using the [Helix Sdk]. +All test execution should run through **Helix**. + +To view the available Helix queues: + +1. Perform an HTTP GET of `https://helix.dot.net/api/2018-03-14/info/queues`. +2. Review the returned JSON array of queue descriptions. +3. Use the [dotnet-helix-machines] repo and the queue info API to confirm machine capabilities. +4. Submit test jobs through the [Helix Sdk]. [Helix Sdk]: /Documentation/AzureDevOps/SendingJobsToHelix.md [Bootstrapping System]: /Documentation/NativeToolBootstrapping.md [@dotnet/dnceng]: https://github.com/orgs/dotnet/teams/dnceng - -[dotnet-internal-temp]: https://dev.azure.com/dnceng/internal/_settings/agentqueues?queueId=67&_a=agents -[dnceng-linux-internal-temp]: https://dev.azure.com/dnceng/internal/_settings/agentqueues?queueId=61&_a=agents -[dnceng-linux-external-temp]: https://dev.azure.com/dnceng/public/_settings/agentqueues?queueId=65&_a=agents -[dotnet-external-temp]: https://dev.azure.com/dnceng/internal/_settings/agentqueues?queueId=47&_a=agents - [dotnet-helix-machines]: https://dev.azure.com/dnceng/internal/internal%20Team/_git/dotnet-helix-machines?path=%2FREADME.md&version=GBmain [Helix Queue Info Api]: https://helix.dot.net/swagger/ui/index#!/Information/Information_QueueInfoList - Was this helpful? [![Yes](https://helix.dot.net/f/ip/5?p=Documentation%5CChoosingAMachinePool.md)](https://helix.dot.net/f/p/5?p=Documentation%5CChoosingAMachinePool.md) [![No](https://helix.dot.net/f/in)](https://helix.dot.net/f/n/5?p=Documentation%5CChoosingAMachinePool.md)