Pools - Create Or Update

Service:: Managed DevOps Pools

API Version:: 2025-01-21

Create a Pool

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DevOpsInfrastructure/pools/{poolName}?api-version=2025-01-21

URI Parameters

Name	In	Required	Type	Description
poolName	path	True	string pattern: ^[a-zA-Z0-9][a-zA-Z0-9-.]*$	Name of the pool. It needs to be globally unique.
resourceGroupName	path	True	string minLength: 1 maxLength: 90	The name of the resource group. The name is case insensitive.
subscriptionId	path	True	string (uuid)	The ID of the target subscription. The value must be an UUID.
api-version	query	True	string minLength: 1	The API version to use for this operation.

Request Body

Name	Required	Type	Description
location	True	string	The geo-location where the resource lives
properties.agentProfile	True	AgentProfile: Stateful StatelessAgentProfile	Defines how the machine will be handled once it executed a job.
properties.devCenterProjectResourceId	True	string	The resource id of the DevCenter Project the pool belongs to.
properties.fabricProfile	True	FabricProfile: VmssFabricProfile	Defines the type of fabric the agent will run on.
properties.maximumConcurrency	True	integer (int32) minimum: 1 maximum: 10000	Defines how many resources can there be created at any given time.
properties.organizationProfile	True	OrganizationProfile: AzureDevOpsOrganizationProfile GitHubOrganizationProfile	Defines the organization in which the pool will be used.
identity		ManagedServiceIdentity	The managed service identities assigned to this resource.
properties.provisioningState		ProvisioningState	The status of the current operation.
tags		object	Resource tags.

Responses

Name	Type	Description
200 OK	Pool	Resource 'Pool' update operation succeeded
201 Created	Pool	Resource 'Pool' create operation succeeded Headers Retry-After: integer
Other Status Codes	ErrorResponse	An unexpected error response.

Name

Type

Description

200 OK

Pool

Resource 'Pool' update operation succeeded

201 Created

Pool

Resource 'Pool' create operation succeeded

Headers

Retry-After: integer

Other Status Codes

ErrorResponse

An unexpected error response.

Security

azure_auth

Azure Active Directory OAuth2 Flow.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
user_impersonation	impersonate your user account

Examples

Pools_CreateOrUpdate

Sample request

HTTP

PUT https://management.azure.com/subscriptions/a2e95d27-c161-4b61-bda4-11512c14c2c2/resourceGroups/rg/providers/Microsoft.DevOpsInfrastructure/pools/pool?api-version=2025-01-21

{
  "location": "eastus",
  "properties": {
    "provisioningState": "Succeeded",
    "maximumConcurrency": 10,
    "devCenterProjectResourceId": "/subscriptions/222e81d0-cf38-4dab-baa5-289bf16baaa4/resourceGroups/rg-1es-devcenter/providers/Microsoft.DevCenter/projects/1ES",
    "organizationProfile": {
      "kind": "AzureDevOps",
      "organizations": [
        {
          "url": "https://mseng.visualstudio.com",
          "openAccess": true
        }
      ]
    },
    "agentProfile": {
      "kind": "Stateless"
    },
    "fabricProfile": {
      "kind": "Vmss",
      "sku": {
        "name": "Standard_D4ads_v5"
      },
      "images": [
        {
          "resourceId": "/MicrosoftWindowsServer/WindowsServer/2019-Datacenter/latest",
          "ephemeralType": "Automatic"
        }
      ],
      "osProfile": {
        "secretsManagementSettings": {
          "certificateStoreName": "Root",
          "observedCertificates": [
            "https://abc.vault.azure.net/secrets/one"
          ],
          "keyExportable": false
        }
      }
    }
  }
}

Sample response

Status code:: 201

Azure-AsyncOperation: https://contoso.com/operationstatus

{
  "properties": {
    "provisioningState": "Succeeded",
    "maximumConcurrency": 10,
    "devCenterProjectResourceId": "/subscriptions/222e81d0-cf38-4dab-baa5-289bf16baaa4/resourceGroups/rg-1es-devcenter/providers/Microsoft.DevCenter/projects/1ES",
    "organizationProfile": {
      "kind": "AzureDevOps",
      "organizations": [
        {
          "url": "https://mseng.visualstudio.com"
        }
      ]
    },
    "agentProfile": {
      "kind": "Stateless"
    },
    "fabricProfile": {
      "kind": "Vmss",
      "sku": {
        "name": "Standard_D4ads_v5"
      },
      "images": [
        {
          "resourceId": "/MicrosoftWindowsServer/WindowsServer/2019-Datacenter/latest"
        }
      ],
      "osProfile": {
        "secretsManagementSettings": {
          "certificateStoreName": "Root",
          "observedCertificates": [
            "https://abc.vault.azure.net/secrets/one"
          ],
          "keyExportable": false
        }
      }
    }
  },
  "id": "/subscriptions/a2e95d27-c161-4b61-bda4-11512c14c2c2/resourceGroups/rg/providers/Microsoft.DevOpsInfrastructure/Pools/pool",
  "location": "eastus"
}

Status code:: 200

{
  "properties": {
    "provisioningState": "Succeeded",
    "maximumConcurrency": 10,
    "devCenterProjectResourceId": "/subscriptions/222e81d0-cf38-4dab-baa5-289bf16baaa4/resourceGroups/rg-1es-devcenter/providers/Microsoft.DevCenter/projects/1ES",
    "organizationProfile": {
      "kind": "AzureDevOps",
      "organizations": [
        {
          "url": "https://mseng.visualstudio.com"
        }
      ]
    },
    "agentProfile": {
      "kind": "Stateless"
    },
    "fabricProfile": {
      "kind": "Vmss",
      "sku": {
        "name": "Standard_D4ads_v5"
      },
      "images": [
        {
          "resourceId": "/MicrosoftWindowsServer/WindowsServer/2019-Datacenter/latest"
        }
      ],
      "osProfile": {
        "secretsManagementSettings": {
          "certificateStoreName": "Root",
          "observedCertificates": [
            "https://abc.vault.azure.net/secrets/one"
          ],
          "keyExportable": false
        }
      }
    }
  },
  "id": "/subscriptions/a2e95d27-c161-4b61-bda4-11512c14c2c2/resourceGroups/rg/providers/Microsoft.DevOpsInfrastructure/Pools/pool",
  "location": "eastus"
}

Definitions

Name	Description
AutomaticResourcePredictionsProfile	The stand-by agent scheme is determined based on historical demand.
AzureDevOpsOrganizationProfile	Azure DevOps organization profile
AzureDevOpsPermissionProfile	Defines the type of Azure DevOps pool permission.
AzureDevOpsPermissionType	Determines who has admin permissions to the Azure DevOps pool.
CachingType	The type of caching in a data disk.
CertificateStoreNameOption	The certificate store name type
createdByType	The type of identity that created the resource.
DataDisk	The data disk of the VMSS.
DevOpsAzureSku	The Azure SKU of the machines in the pool.
EphemeralType	The type of Ephemeral option the pool will use on underlying VMs when loading this image.
ErrorAdditionalInfo	The resource management error additional info.
ErrorDetail	The error detail.
ErrorResponse	Error response
GitHubOrganization	Defines a GitHub organization
GitHubOrganizationProfile	GitHub organization profile
LogonType	Determines how the service should be run.
ManagedServiceIdentity	Managed service identity (system assigned and/or user assigned identities)
ManagedServiceIdentityType	Type of managed service identity (where both SystemAssigned and UserAssigned types are allowed).
ManualResourcePredictionsProfile	Customer provides the stand-by agent scheme.
NetworkProfile	The network profile of the machines in the pool.
Organization	Defines an Azure DevOps organization.
OsDiskStorageAccountType	The storage account type of the OS disk.
OsProfile	The OS profile of the machines in the pool.
Pool	Concrete tracked resource types can be created by aliasing this type using a specific property type.
PoolImage	The VM image of the machines in the pool.
PredictionPreference	Determines the balance between cost and performance.
ProvisioningState	The status of the current operation.
ResourcePredictionsProfileType	Determines how the stand-by scheme should be provided.
SecretsManagementSettings	The secret management settings of the machines in the pool.
Stateful	Stateful profile meaning that the machines will be returned to the pool after running a job.
StatelessAgentProfile	Stateless profile meaning that the machines will be cleaned up after running a job.
StorageAccountType	StorageAccountType enums
StorageProfile	The storage profile of the VMSS.
systemData	Metadata pertaining to creation and last modification of the resource.
UserAssignedIdentity	User assigned identity properties
VmssFabricProfile	The agents will run on Virtual Machine Scale Sets.

AutomaticResourcePredictionsProfile

Object

The stand-by agent scheme is determined based on historical demand.

Name	Type	Description
kind	string: Automatic	Determines how the stand-by scheme should be provided.
predictionPreference	PredictionPreference	Determines the balance between cost and performance.

AzureDevOpsOrganizationProfile

Object

Azure DevOps organization profile

Name	Type	Description
kind	string: AzureDevOps	Discriminator property for OrganizationProfile.
organizations	Organization[]	The list of Azure DevOps organizations the pool should be present in.
permissionProfile	AzureDevOpsPermissionProfile	The type of permission which determines which accounts are admins on the Azure DevOps pool.

AzureDevOpsPermissionProfile

Object

Defines the type of Azure DevOps pool permission.

Name	Type	Description
groups	string[]	Group email addresses
kind	AzureDevOpsPermissionType	Determines who has admin permissions to the Azure DevOps pool.
users	string[]	User email addresses

AzureDevOpsPermissionType

Enumeration

Determines who has admin permissions to the Azure DevOps pool.

Value	Description
Inherit	Pool will inherit permissions from the project or organization.
CreatorOnly	Only the pool creator will be an admin of the pool.
SpecificAccounts	Only the specified accounts will be admins of the pool.

CachingType

Enumeration

The type of caching in a data disk.

Value	Description
None	Don't use host caching.
ReadOnly	For workloads that only do read operations.
ReadWrite	For workloads that do a balance of read and write operations.

CertificateStoreNameOption

Enumeration

The certificate store name type

Value	Description
My	The X.509 certificate store for personal certificates.
Root	The X.509 certificate store for trusted root certificate authorities (CAs).

createdByType

Enumeration

The type of identity that created the resource.

Value	Description
User
Application
ManagedIdentity
Key

DataDisk

Object

The data disk of the VMSS.

Name	Type	Description
caching	CachingType	The type of caching to be enabled for the data disks. The default value for caching is readwrite. For information about the caching options see: https://blogs.msdn.microsoft.com/windowsazurestorage/2012/06/27/exploring-windows-azure-drives-disks-and-images/.
diskSizeGiB	integer (int32)	The initial disk size in gigabytes.
driveLetter	string	The drive letter for the empty data disk. If not specified, it will be the first available letter.
storageAccountType	StorageAccountType	The storage Account type to be used for the data disk. If omitted, the default is "standard_lrs".

DevOpsAzureSku

Object

The Azure SKU of the machines in the pool.

Name	Type	Description
name	string	The Azure SKU name of the machines in the pool.

EphemeralType

Enumeration

The type of Ephemeral option the pool will use on underlying VMs when loading this image.

Value	Description
Automatic	Ephemeral is handled by Managed DevOps Pools service.
CacheDisk	CacheDisk ephemeral only, requires that the SKU has a cache that is large enough for the image.
ResourceDisk	ResourceDisk ephemeral only, requires only that the SKU supports it.

ErrorAdditionalInfo

Object

The resource management error additional info.

Name	Type	Description
info	object	The additional info.
type	string	The additional info type.

ErrorDetail

Object

The error detail.

Name	Type	Description
additionalInfo	ErrorAdditionalInfo[]	The error additional info.
code	string	The error code.
details	ErrorDetail[]	The error details.
message	string	The error message.
target	string	The error target.

ErrorResponse

Object

Error response

Name	Type	Description
error	ErrorDetail	The error object.

GitHubOrganization

Object

Defines a GitHub organization

Name	Type	Description
repositories	string[]	Optional list of repositories in which the pool should be created.
url	string (uri)	The GitHub organization URL in which the pool should be created.

GitHubOrganizationProfile

Object

GitHub organization profile

Name	Type	Description
kind	string: GitHub	Discriminator property for OrganizationProfile.
organizations	GitHubOrganization[]	The list of GitHub organizations/repositories the pool should be present in.

LogonType

Enumeration

Determines how the service should be run.

Value	Description
Service	Run as a service.
Interactive	Run in interactive mode.

ManagedServiceIdentity

Object

Managed service identity (system assigned and/or user assigned identities)

Name	Type	Description
principalId	string (uuid)	The service principal ID of the system assigned identity. This property will only be provided for a system assigned identity.
tenantId	string (uuid)	The tenant ID of the system assigned identity. This property will only be provided for a system assigned identity.
type	ManagedServiceIdentityType	Type of managed service identity (where both SystemAssigned and UserAssigned types are allowed).
userAssignedIdentities	<string, UserAssignedIdentity>	User-Assigned Identities The set of user assigned identities associated with the resource. The userAssignedIdentities dictionary keys will be ARM resource ids in the form: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}. The dictionary values can be empty objects ({}) in requests.

ManagedServiceIdentityType

Enumeration

Type of managed service identity (where both SystemAssigned and UserAssigned types are allowed).

Value	Description
None
SystemAssigned
UserAssigned
SystemAssigned,UserAssigned

ManualResourcePredictionsProfile

Object

Customer provides the stand-by agent scheme.

Name	Type	Description
kind	string: Manual	Determines how the stand-by scheme should be provided.

NetworkProfile

Object

The network profile of the machines in the pool.

Name	Type	Description
subnetId	string	The subnet id on which to put all machines created in the pool.

Organization

Object

Defines an Azure DevOps organization.

Name	Type	Description
openAccess	boolean	Determines if the pool should have open access to all projects in this organization.
parallelism	integer (int32)	How many machines can be created at maximum in this organization out of the maximumConcurrency of the pool.
projects	string[]	Optional list of projects in which the pool should be created.
url	string (uri)	The Azure DevOps organization URL in which the pool should be created.

OsDiskStorageAccountType

Enumeration

The storage account type of the OS disk.

Value	Description
Standard	Standard OS disk type.
Premium	Premium OS disk type.
StandardSSD	Standard SSD OS disk type.

OsProfile

Object

The OS profile of the machines in the pool.

Name	Type	Description
logonType	LogonType	Determines how the service should be run. By default, this will be set to Service.
secretsManagementSettings	SecretsManagementSettings	The secret management settings of the machines in the pool.

Pool

Object

Concrete tracked resource types can be created by aliasing this type using a specific property type.

Name	Type	Description
id	string (arm-id)	Fully qualified resource ID for the resource. E.g. "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}"
identity	ManagedServiceIdentity	The managed service identities assigned to this resource.
location	string	The geo-location where the resource lives
name	string	The name of the resource
properties.agentProfile	AgentProfile: Stateful StatelessAgentProfile	Defines how the machine will be handled once it executed a job.
properties.devCenterProjectResourceId	string	The resource id of the DevCenter Project the pool belongs to.
properties.fabricProfile	FabricProfile: VmssFabricProfile	Defines the type of fabric the agent will run on.
properties.maximumConcurrency	integer (int32) minimum: 1 maximum: 10000	Defines how many resources can there be created at any given time.
properties.organizationProfile	OrganizationProfile: AzureDevOpsOrganizationProfile GitHubOrganizationProfile	Defines the organization in which the pool will be used.
properties.provisioningState	ProvisioningState	The status of the current operation.
systemData	systemData	Azure Resource Manager metadata containing createdBy and modifiedBy information.
tags	object	Resource tags.
type	string	The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts"

PoolImage

Object

The VM image of the machines in the pool.

Name	Type	Default value	Description
aliases	string[]		List of aliases to reference the image by.
buffer	string	*	The percentage of the buffer to be allocated to this image.
ephemeralType	EphemeralType		The ephemeral type of the image.
resourceId	string		The resource id of the image.
wellKnownImageName	string		The image to use from a well-known set of images made available to customers.

PredictionPreference

Enumeration

Determines the balance between cost and performance.

Value	Description
Balanced	Balance between cost and performance.
MostCostEffective	Optimizes for cost over performance.
MoreCostEffective	Halfway through cost and balanced.
MorePerformance	Halfway through balanced and performance.
BestPerformance	Optimizes for performance over cost.

ProvisioningState

Enumeration

The status of the current operation.

Value	Description
Succeeded	Represents a succeeded operation.
Failed	Represents a failed operation.
Canceled	Represents a canceled operation.
Provisioning	Represents a pending operation.
Updating	Represents a pending operation.
Deleting	Represents an operation under deletion.
Accepted	Represents an accepted operation.

ResourcePredictionsProfileType

Enumeration

Determines how the stand-by scheme should be provided.

Value	Description
Manual	Customer provides the stand-by agent scheme.
Automatic	The stand-by agent scheme is determined based on historical demand.

SecretsManagementSettings

Object

The secret management settings of the machines in the pool.

Name	Type	Description
certificateStoreLocation	string	Where to store certificates on the machine.
certificateStoreName	CertificateStoreNameOption	Name of the certificate store to use on the machine, currently 'My' and 'Root' are supported.
keyExportable	boolean	Defines if the key of the certificates should be exportable.
observedCertificates	string[] (uri)	The list of certificates to install on all machines in the pool.

Stateful

Object

Stateful profile meaning that the machines will be returned to the pool after running a job.

Name	Type	Description
gracePeriodTimeSpan	string	How long should the machine be kept around after it ran a workload when there are no stand-by agents. The maximum is one week.
kind	string: Stateful	Discriminator property for AgentProfile.
maxAgentLifetime	string	How long should stateful machines be kept around. The maximum is one week.
resourcePredictions	object	Defines pool buffer/stand-by agents.
resourcePredictionsProfile	ResourcePredictionsProfile: AutomaticResourcePredictionsProfile ManualResourcePredictionsProfile	Defines how the pool buffer/stand-by agents is provided.

StatelessAgentProfile

Object

Stateless profile meaning that the machines will be cleaned up after running a job.

Name	Type	Description
kind	string: Stateless	Discriminator property for AgentProfile.
resourcePredictions	object	Defines pool buffer/stand-by agents.
resourcePredictionsProfile	ResourcePredictionsProfile: AutomaticResourcePredictionsProfile ManualResourcePredictionsProfile	Defines how the pool buffer/stand-by agents is provided.

StorageAccountType

Enumeration

StorageAccountType enums

Value	Description
Standard_LRS	The data disk should use standard locally redundant storage.
Premium_LRS	The data disk should use premium locally redundant storage.
StandardSSD_LRS	The data disk should use standard SSD locally redundant storage.
Premium_ZRS	The data disk should use premium SSD zonal redundant storage.
StandardSSD_ZRS	The data disk should use standard SSD zonal redundant storage.

StorageProfile

Object

The storage profile of the VMSS.

Name	Type	Description
dataDisks	DataDisk[]	A list of empty data disks to attach.
osDiskStorageAccountType	OsDiskStorageAccountType	The Azure SKU name of the machines in the pool.

systemData

Object

Metadata pertaining to creation and last modification of the resource.

Name	Type	Description
createdAt	string (date-time)	The timestamp of resource creation (UTC).
createdBy	string	The identity that created the resource.
createdByType	createdByType	The type of identity that created the resource.
lastModifiedAt	string (date-time)	The timestamp of resource last modification (UTC)
lastModifiedBy	string	The identity that last modified the resource.
lastModifiedByType	createdByType	The type of identity that last modified the resource.

UserAssignedIdentity

Object

User assigned identity properties

Name	Type	Description
clientId	string (uuid)	The client ID of the assigned identity.
principalId	string (uuid)	The principal ID of the assigned identity.

VmssFabricProfile

Object

The agents will run on Virtual Machine Scale Sets.

Name	Type	Description
images	PoolImage[]	The VM images of the machines in the pool.
kind	string: Vmss	Discriminator property for FabricProfile.
networkProfile	NetworkProfile	The network profile of the machines in the pool.
osProfile	OsProfile	The OS profile of the machines in the pool.
sku	DevOpsAzureSku	The Azure SKU of the machines in the pool.
storageProfile	StorageProfile	The storage profile of the machines in the pool.

Share via

Pools - Create Or Update

URI Parameters

Request Body

Responses

Security

azure_auth

Scopes

Examples

Pools_CreateOrUpdate

Sample request

Sample response

Definitions

AutomaticResourcePredictionsProfile

AzureDevOpsOrganizationProfile

AzureDevOpsPermissionProfile

AzureDevOpsPermissionType

CachingType

CertificateStoreNameOption

createdByType

DataDisk

DevOpsAzureSku

EphemeralType

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

GitHubOrganization

GitHubOrganizationProfile

LogonType

ManagedServiceIdentity

ManagedServiceIdentityType

ManualResourcePredictionsProfile

NetworkProfile

Organization

OsDiskStorageAccountType

OsProfile

Pool

PoolImage

PredictionPreference

ProvisioningState

ResourcePredictionsProfileType

SecretsManagementSettings

Stateful

StatelessAgentProfile

StorageAccountType

StorageProfile

systemData

UserAssignedIdentity

VmssFabricProfile