Host Pools - Create Or Update

Create or update a host pool.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DesktopVirtualization/hostPools/{hostPoolName}?api-version=2022-02-10-preview

URI Parameters

Name In Required Type Description
hostPoolName
path True
  • string

The name of the host pool within the specified resource group

resourceGroupName
path True
  • string

The name of the resource group. The name is case insensitive.

subscriptionId
path True
  • string

The ID of the target subscription.

api-version
query True
  • string

The API version to use for this operation.

Request Body

Name Required Type Description
properties.hostPoolType True

HostPool type for desktop.

properties.loadBalancerType True

The type of the load balancer.

properties.preferredAppGroupType True

The type of preferred application group type, default to Desktop Application Group

identity
kind
  • string

Metadata used by portal/tooling/etc to render different UX experiences for resources of the same type; e.g. ApiApps are a kind of Microsoft.Web/sites type. If supported, the resource provider must validate and persist this value.

location
  • string

The geo-location where the resource lives

managedBy
  • string

The fully qualified resource ID of the resource that manages this resource. Indicates if this resource is managed by another Azure resource. If this is present, complete mode deployment will not delete the resource if it is removed from the template since it is managed by another resource.

plan
properties.agentUpdate

The preferred settings for updating the agent components (RDAgent, Geneva Monitoring agent, and side-by-side stack) on session hosts.

properties.customRdpProperty
  • string

Custom rdp property of HostPool.

properties.description
  • string

Description of HostPool.

properties.friendlyName
  • string

Friendly name of HostPool.

properties.maxSessionLimit
  • integer

The max session limit of HostPool.

properties.migrationRequest

The registration info of HostPool.

properties.personalDesktopAssignmentType

PersonalDesktopAssignment type for HostPool.

properties.publicNetworkAccess

Enabled allows this resource to be accessed from both public and private networks, Disabled allows this resource to only be accessed via private endpoints

properties.registrationInfo

The registration info of HostPool.

properties.ring
  • integer

The ring number of HostPool.

properties.ssoClientId
  • string

ClientId for the registered Relying Party used to issue WVD SSO certificates.

properties.ssoClientSecretKeyVaultPath
  • string

Path to Azure KeyVault storing the secret used for communication to ADFS.

properties.ssoSecretType

The type of single sign on Secret Type.

properties.ssoadfsAuthority
  • string

URL to customer ADFS server for signing WVD SSO certificates.

properties.startVMOnConnect
  • boolean

The flag to turn on/off StartVMOnConnect feature.

properties.validationEnvironment
  • boolean

Is validation environment.

properties.vmTemplate
  • string

VM template for sessionhosts configuration within hostpool.

sku
tags
  • object

Resource tags.

Responses

Name Type Description
200 OK

Successfully updated host pool.

201 Created

Successfully created host pool.

Other Status Codes

Automation error response describing why the operation failed.

Examples

HostPool_Create

Sample Request

PUT https://management.azure.com/subscriptions/daefabc0-95b4-48b3-b645-8a753a63c4fa/resourceGroups/resourceGroup1/providers/Microsoft.DesktopVirtualization/hostPools/hostPool1?api-version=2022-02-10-preview

{
  "location": "centralus",
  "tags": {
    "tag1": "value1",
    "tag2": "value2"
  },
  "properties": {
    "friendlyName": "friendly",
    "description": "des1",
    "hostPoolType": "Pooled",
    "personalDesktopAssignmentType": "Automatic",
    "customRdpProperty": null,
    "maxSessionLimit": 999999,
    "loadBalancerType": "BreadthFirst",
    "registrationInfo": {
      "expirationTime": "2020-10-01T14:01:54.9571247Z",
      "registrationTokenOperation": "Update"
    },
    "vmTemplate": "{json:json}",
    "ssoadfsAuthority": "https://adfs",
    "ssoClientId": "client",
    "ssoClientSecretKeyVaultPath": "https://keyvault/secret",
    "ssoSecretType": "SharedKey",
    "preferredAppGroupType": "Desktop",
    "startVMOnConnect": false,
    "migrationRequest": {
      "migrationPath": "TenantGroups/{defaultV1TenantGroup.Name}/Tenants/{defaultV1Tenant.Name}/HostPools/{sessionHostPool.Name}",
      "operation": "Start"
    },
    "publicNetworkAccess": "Enabled",
    "agentUpdate": {
      "type": "Scheduled",
      "useSessionHostLocalTime": false,
      "maintenanceWindowTimeZone": "Alaskan Standard Time",
      "maintenanceWindows": [
        {
          "hour": 7,
          "dayOfWeek": "Friday"
        },
        {
          "hour": 8,
          "dayOfWeek": "Saturday"
        }
      ]
    }
  }
}

Sample Response

{
  "name": "hostPool1",
  "id": "/subscriptions/daefabc0-95b4-48b3-b645-8a753a63c4fa/resourceGroups/resourceGroup1/providers/Microsoft.DesktopVirtualization/hostPools/hostPool1",
  "type": "/Microsoft.DesktopVirtualization/hostPools",
  "location": "centralus",
  "tags": {
    "key1": "value1",
    "key2": "value2"
  },
  "systemData": {
    "createdBy": "user1",
    "createdByType": "User",
    "createdAt": "2020-01-01T17:18:19.1234567Z",
    "lastModifiedBy": "user2",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2020-01-02T17:18:19.1234567Z"
  },
  "properties": {
    "objectId": "7877fb31-4bde-49fd-9df3-c046e0ec5325",
    "friendlyName": "friendly",
    "description": "des1",
    "hostPoolType": "Pooled",
    "personalDesktopAssignmentType": "Automatic",
    "customRdpProperty": null,
    "maxSessionLimit": 999999,
    "loadBalancerType": "BreadthFirst",
    "validationEnvironment": null,
    "ring": null,
    "registrationInfo": {
      "expirationTime": "2020-10-01T14:01:54.9571247Z",
      "token": "token",
      "registrationTokenOperation": "Update"
    },
    "vmTemplate": "{json:json}",
    "ssoadfsAuthority": "https://adfs",
    "ssoClientId": "client",
    "ssoClientSecretKeyVaultPath": "https://keyvault/secret",
    "ssoSecretType": "SharedKey",
    "preferredAppGroupType": "Desktop",
    "startVMOnConnect": false,
    "cloudPcResource": false,
    "migrationRequest": {
      "migrationPath": "TenantGroups/{defaultV1TenantGroup.Name}/Tenants/{defaultV1Tenant.Name}/HostPools/{sessionHostPool.Name}",
      "operation": "Start"
    },
    "publicNetworkAccess": "Enabled",
    "agentUpdate": {
      "type": "Scheduled",
      "useSessionHostLocalTime": false,
      "maintenanceWindowTimeZone": "Alaskan Standard Time",
      "maintenanceWindows": [
        {
          "hour": 7,
          "dayOfWeek": "Friday"
        },
        {
          "hour": 8,
          "dayOfWeek": "Saturday"
        }
      ]
    }
  }
}
{
  "name": "hostPool1",
  "id": "/subscriptions/daefabc0-95b4-48b3-b645-8a753a63c4fa/resourceGroups/resourceGroup1/providers/Microsoft.DesktopVirtualization/hostPools/hostPool1",
  "type": "/Microsoft.DesktopVirtualization/hostPools",
  "location": "centralus",
  "tags": {
    "key1": "value1",
    "key2": "value2"
  },
  "systemData": {
    "createdBy": "user1",
    "createdByType": "User",
    "createdAt": "2020-01-01T17:18:19.1234567Z",
    "lastModifiedBy": "user2",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2020-01-02T17:18:19.1234567Z"
  },
  "properties": {
    "objectId": "7877fb31-4bde-49fd-9df3-c046e0ec5325",
    "friendlyName": "friendly",
    "description": "des1",
    "hostPoolType": "Pooled",
    "personalDesktopAssignmentType": "Automatic",
    "customRdpProperty": null,
    "maxSessionLimit": 999999,
    "loadBalancerType": "BreadthFirst",
    "validationEnvironment": null,
    "ring": null,
    "registrationInfo": {
      "expirationTime": "2020-10-01T14:01:54.9571247Z",
      "token": "token",
      "registrationTokenOperation": "Update"
    },
    "vmTemplate": "{json:json}",
    "ssoadfsAuthority": "https://adfs",
    "ssoClientId": "client",
    "ssoClientSecretKeyVaultPath": "https://keyvault/secret",
    "ssoSecretType": "SharedKey",
    "preferredAppGroupType": "Desktop",
    "startVMOnConnect": false,
    "cloudPcResource": false,
    "migrationRequest": {
      "migrationPath": "TenantGroups/{defaultV1TenantGroup.Name}/Tenants/{defaultV1Tenant.Name}/HostPools/{sessionHostPool.Name}",
      "operation": "Start"
    },
    "publicNetworkAccess": "Enabled",
    "agentUpdate": {
      "type": "Scheduled",
      "useSessionHostLocalTime": false,
      "maintenanceWindowTimeZone": "Alaskan Standard Time",
      "maintenanceWindows": [
        {
          "hour": 7,
          "dayOfWeek": "Friday"
        },
        {
          "hour": 8,
          "dayOfWeek": "Saturday"
        }
      ]
    }
  }
}

Definitions

AgentUpdateProperties

The preferred settings for updating the agent components (RDAgent, Geneva Monitoring agent, and side-by-side stack) on session hosts.

CloudError

Cloud error object.

CloudErrorProperties

Cloud error object properties.

createdByType

The type of identity that created the resource.

DayOfWeek

The day of the week (Monday-Sunday).

HostPool

Represents a HostPool definition.

HostpoolPublicNetworkAccess

Enabled allows this resource to be accessed from both public and private networks, Disabled allows this resource to only be accessed via private endpoints

HostPoolType

HostPool type for desktop.

Identity
LoadBalancerType

The type of the load balancer.

MaintenanceWindowProperties

Maintenance window starting hour and day of week.

MigrationRequestProperties

Properties for arm migration.

Operation

The type of operation for migration.

PersonalDesktopAssignmentType

PersonalDesktopAssignment type for HostPool.

Plan
PreferredAppGroupType

The type of preferred application group type, default to Desktop Application Group

PrivateEndpoint

The Private Endpoint resource.

PrivateEndpointConnection

The Private Endpoint Connection resource.

PrivateEndpointConnectionProvisioningState

The current provisioning state.

PrivateEndpointServiceConnectionStatus

The private endpoint connection status.

PrivateLinkServiceConnectionState

A collection of information about the state of the connection between service consumer and provider.

RegistrationInfo

Represents a RegistrationInfo definition.

RegistrationTokenOperation

The type of resetting the token.

ResourceIdentityType

The identity type.

SessionHostComponentUpdateType

The preferred mechanism for updating the agent components. This is either Scheduled or Default.

Sku
SkuTier

This field is required to be implemented by the Resource Provider if the service has more than one tier, but is not required on a PUT.

SSOSecretType

The type of single sign on Secret Type.

systemData

Metadata pertaining to creation and last modification of the resource.

AgentUpdateProperties

The preferred settings for updating the agent components (RDAgent, Geneva Monitoring agent, and side-by-side stack) on session hosts.

Name Type Description
maintenanceWindowTimeZone
  • string

The time zone for updating the agent components. Valid time zones can be found here: https://docs.microsoft.com/en-us/dotnet/api/system.timezoneinfo.findsystemtimezonebyid?view=net-5.0. A time zone must be specified if useSessionHostLocalTime is false.

maintenanceWindows

The maintenance windows (day and time) for updating the agent components. At least 1 window must be specified. Optionally, a 2nd window can be specified.

type

The preferred mechanism for updating the agent components. This is either Scheduled or Default.

useSessionHostLocalTime
  • boolean

Boolean indicating whether to update the agent components in the local time zone of each session host in the host pool. By default, this is false.

CloudError

Cloud error object.

Name Type Description
error

Cloud error object properties.

CloudErrorProperties

Cloud error object properties.

Name Type Description
code
  • string

Error code

message
  • string

Error message indicating why the operation failed.

createdByType

The type of identity that created the resource.

Name Type Description
Application
  • string
Key
  • string
ManagedIdentity
  • string
User
  • string

DayOfWeek

The day of the week (Monday-Sunday).

Name Type Description
Friday
  • string
Monday
  • string
Saturday
  • string
Sunday
  • string
Thursday
  • string
Tuesday
  • string
Wednesday
  • string

HostPool

Represents a HostPool definition.

Name Type Description
etag
  • string

The etag field is not required. If it is provided in the response body, it must also be provided as a header per the normal etag convention. Entity tags are used for comparing two or more entities from the same requested resource. HTTP/1.1 uses entity tags in the etag (section 14.19), If-Match (section 14.24), If-None-Match (section 14.26), and If-Range (section 14.27) header fields.

id
  • string

Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}

identity
kind
  • string

Metadata used by portal/tooling/etc to render different UX experiences for resources of the same type; e.g. ApiApps are a kind of Microsoft.Web/sites type. If supported, the resource provider must validate and persist this value.

location
  • string

The geo-location where the resource lives

managedBy
  • string

The fully qualified resource ID of the resource that manages this resource. Indicates if this resource is managed by another Azure resource. If this is present, complete mode deployment will not delete the resource if it is removed from the template since it is managed by another resource.

name
  • string

The name of the resource

plan
properties.agentUpdate

The preferred settings for updating the agent components (RDAgent, Geneva Monitoring agent, and side-by-side stack) on session hosts.

properties.applicationGroupReferences
  • string[]

List of applicationGroup links.

properties.cloudPcResource
  • boolean

Is cloud pc resource.

properties.customRdpProperty
  • string

Custom rdp property of HostPool.

properties.description
  • string

Description of HostPool.

properties.friendlyName
  • string

Friendly name of HostPool.

properties.hostPoolType

HostPool type for desktop.

properties.loadBalancerType

The type of the load balancer.

properties.maxSessionLimit
  • integer

The max session limit of HostPool.

properties.migrationRequest

The registration info of HostPool.

properties.objectId
  • string

ObjectId of HostPool. (internal use)

properties.personalDesktopAssignmentType

PersonalDesktopAssignment type for HostPool.

properties.preferredAppGroupType

The type of preferred application group type, default to Desktop Application Group

properties.privateEndpointConnections

List of private endpoint connection associated with the specified resource

properties.publicNetworkAccess

Enabled allows this resource to be accessed from both public and private networks, Disabled allows this resource to only be accessed via private endpoints

properties.registrationInfo

The registration info of HostPool.

properties.ring
  • integer

The ring number of HostPool.

properties.ssoClientId
  • string

ClientId for the registered Relying Party used to issue WVD SSO certificates.

properties.ssoClientSecretKeyVaultPath
  • string

Path to Azure KeyVault storing the secret used for communication to ADFS.

properties.ssoSecretType

The type of single sign on Secret Type.

properties.ssoadfsAuthority
  • string

URL to customer ADFS server for signing WVD SSO certificates.

properties.startVMOnConnect
  • boolean

The flag to turn on/off StartVMOnConnect feature.

properties.validationEnvironment
  • boolean

Is validation environment.

properties.vmTemplate
  • string

VM template for sessionhosts configuration within hostpool.

sku
systemData

Metadata pertaining to creation and last modification of the resource.

tags
  • object

Resource tags.

type
  • string

The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts"

HostpoolPublicNetworkAccess

Enabled allows this resource to be accessed from both public and private networks, Disabled allows this resource to only be accessed via private endpoints

Name Type Description
Disabled
  • string
Enabled
  • string
EnabledForClientsOnly
  • string
EnabledForSessionHostsOnly
  • string

HostPoolType

HostPool type for desktop.

Name Type Description
BYODesktop
  • string

Users assign their own machines, load balancing logic remains the same as Personal. PersonalDesktopAssignmentType must be Direct.

Personal
  • string

Users will be assigned a SessionHost either by administrators (PersonalDesktopAssignmentType = Direct) or upon connecting to the pool (PersonalDesktopAssignmentType = Automatic). They will always be redirected to their assigned SessionHost.

Pooled
  • string

Users get a new (random) SessionHost every time it connects to the HostPool.

Identity

Name Type Description
principalId
  • string

The principal ID of resource identity.

tenantId
  • string

The tenant ID of resource.

type

The identity type.

LoadBalancerType

The type of the load balancer.

Name Type Description
BreadthFirst
  • string
DepthFirst
  • string
Persistent
  • string

MaintenanceWindowProperties

Maintenance window starting hour and day of week.

Name Type Description
dayOfWeek

The day of the week (Monday-Sunday).

hour
  • integer

The starting hour of the maintenance window (0-23). Note that maintenance windows are 2 hours long. This means that updates can be applied anytime from the specified start hour to 2 hours after.

MigrationRequestProperties

Properties for arm migration.

Name Type Description
migrationPath
  • string

The path to the legacy object to migrate.

operation

The type of operation for migration.

Operation

The type of operation for migration.

Name Type Description
Complete
  • string

Complete the migration.

Hide
  • string

Hide the hostpool.

Revoke
  • string

Revoke the migration.

Start
  • string

Start the migration.

Unhide
  • string

Unhide the hostpool.

PersonalDesktopAssignmentType

PersonalDesktopAssignment type for HostPool.

Name Type Description
Automatic
  • string
Direct
  • string

Plan

Name Type Description
name
  • string

A user defined name of the 3rd Party Artifact that is being procured.

product
  • string

The 3rd Party artifact that is being procured. E.g. NewRelic. Product maps to the OfferID specified for the artifact at the time of Data Market onboarding.

promotionCode
  • string

A publisher provided promotion code as provisioned in Data Market for the said product/artifact.

publisher
  • string

The publisher of the 3rd Party Artifact that is being bought. E.g. NewRelic

version
  • string

The version of the desired product/artifact.

PreferredAppGroupType

The type of preferred application group type, default to Desktop Application Group

Name Type Description
Desktop
  • string
None
  • string
RailApplications
  • string

PrivateEndpoint

The Private Endpoint resource.

Name Type Description
id
  • string

The ARM identifier for Private Endpoint

PrivateEndpointConnection

The Private Endpoint Connection resource.

Name Type Description
id
  • string

Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}

name
  • string

The name of the resource

properties.privateEndpoint

The resource of private end point.

properties.privateLinkServiceConnectionState

A collection of information about the state of the connection between service consumer and provider.

properties.provisioningState

The provisioning state of the private endpoint connection resource.

type
  • string

The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts"

PrivateEndpointConnectionProvisioningState

The current provisioning state.

Name Type Description
Creating
  • string
Deleting
  • string
Failed
  • string
Succeeded
  • string

PrivateEndpointServiceConnectionStatus

The private endpoint connection status.

Name Type Description
Approved
  • string
Pending
  • string
Rejected
  • string

PrivateLinkServiceConnectionState

A collection of information about the state of the connection between service consumer and provider.

Name Type Description
actionsRequired
  • string

A message indicating if changes on the service provider require any updates on the consumer.

description
  • string

The reason for approval/rejection of the connection.

status

Indicates whether the connection has been Approved/Rejected/Removed by the owner of the service.

RegistrationInfo

Represents a RegistrationInfo definition.

Name Type Description
expirationTime
  • string

Expiration time of registration token.

registrationTokenOperation

The type of resetting the token.

token
  • string

The registration token base64 encoded string.

RegistrationTokenOperation

The type of resetting the token.

Name Type Description
Delete
  • string
None
  • string
Update
  • string

ResourceIdentityType

The identity type.

Name Type Description
SystemAssigned
  • string

SessionHostComponentUpdateType

The preferred mechanism for updating the agent components. This is either Scheduled or Default.

Name Type Description
Default
  • string

The agent components are updated according to the AVD infrastructure flighting. For more information, see https://aka.ms/avdagent.

Scheduled
  • string

This enables the Scheduled Agent Updates feature which allows the agent components to get updated according to the schedule that the admin define. For more information, see https://aka.ms/avdsau.

Sku

Name Type Description
capacity
  • integer

If the SKU supports scale out/in then the capacity integer should be included. If scale out/in is not possible for the resource this may be omitted.

family
  • string

If the service has different generations of hardware, for the same SKU, then that can be captured here.

name
  • string

The name of the SKU. Ex - P3. It is typically a letter+number code

size
  • string

The SKU size. When the name field is the combination of tier and some other value, this would be the standalone code.

tier

This field is required to be implemented by the Resource Provider if the service has more than one tier, but is not required on a PUT.

SkuTier

This field is required to be implemented by the Resource Provider if the service has more than one tier, but is not required on a PUT.

Name Type Description
Basic
  • string
Free
  • string
Premium
  • string
Standard
  • string

SSOSecretType

The type of single sign on Secret Type.

Name Type Description
Certificate
  • string
CertificateInKeyVault
  • string
SharedKey
  • string
SharedKeyInKeyVault
  • string

systemData

Metadata pertaining to creation and last modification of the resource.

Name Type Description
createdAt
  • string

The timestamp of resource creation (UTC).

createdBy
  • string

The identity that created the resource.

createdByType

The type of identity that created the resource.

lastModifiedAt
  • string

The timestamp of resource last modification (UTC)

lastModifiedBy
  • string

The identity that last modified the resource.

lastModifiedByType

The type of identity that last modified the resource.