Labs - Create Or Update

Service:: Lab Services

API Version:: 2023-06-07

Operation to create or update a lab resource.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.LabServices/labs/{labName}?api-version=2023-06-07

URI Parameters

Name	In	Required	Type	Description
labName	path	True	string minLength: 1 maxLength: 100	The name of the lab that uniquely identifies it within containing lab plan. Used in resource URIs.
resourceGroupName	path	True	string minLength: 1 maxLength: 90	The name of the resource group. The name is case insensitive.
subscriptionId	path	True	string minLength: 1	The ID of the target subscription.
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.autoShutdownProfile	True	AutoShutdownProfile	The resource auto shutdown configuration for the lab. This controls whether actions are taken on resources that are sitting idle.
properties.connectionProfile	True	ConnectionProfile	The connection profile for the lab. This controls settings such as web access to lab resources or whether RDP or SSH ports are open.
properties.securityProfile	True	SecurityProfile	The lab security profile.
properties.virtualMachineProfile	True	VirtualMachineProfile	The profile used for creating lab virtual machines.
properties.description		string	The description of the lab.
properties.labPlanId		string minLength: 3 maxLength: 2000	The ID of the lab plan. Used during resource creation to provide defaults and acts as a permission container when creating a lab via labs.azure.com. Setting a labPlanId on an existing lab provides organization..
properties.networkProfile		LabNetworkProfile	The network profile for the lab, typically applied via a lab plan. This profile cannot be modified once a lab has been created.
properties.rosterProfile		RosterProfile	The lab user list management profile.
properties.title		string minLength: 1 maxLength: 120	The title of the lab.
tags		object	Resource tags.

Responses

Name	Type	Description
200 OK	Lab	The update was successful; response contains the Lab.
201 Created	Lab	The create was successful; response contains the Lab.
202 Accepted	Lab	The update was successful and has a long running operation; response contains the Lab.
Other Status Codes	ErrorResponse	The default error response.

Examples

putLab

Sample request

HTTP

PUT https://management.azure.com/subscriptions/34adfa4f-cedf-4dc0-ba29-b6d1a69ab345/resourceGroups/testrg123/providers/Microsoft.LabServices/labs/testlab?api-version=2023-06-07

{
  "location": "westus",
  "properties": {
    "connectionProfile": {
      "webSshAccess": "None",
      "webRdpAccess": "None",
      "clientSshAccess": "Public",
      "clientRdpAccess": "Public"
    },
    "autoShutdownProfile": {
      "shutdownOnDisconnect": "Enabled",
      "shutdownWhenNotConnected": "Enabled",
      "shutdownOnIdle": "UserAbsence",
      "disconnectDelay": "PT5M",
      "noConnectDelay": "PT5M",
      "idleDelay": "PT5M"
    },
    "securityProfile": {
      "openAccess": "Disabled"
    },
    "networkProfile": {
      "subnetId": "/subscriptions/34adfa4f-cedf-4dc0-ba29-b6d1a69ab345/resourceGroups/testrg123/providers/Microsoft.Network/virtualNetworks/test-vnet/subnets/default"
    },
    "virtualMachineProfile": {
      "createOption": "TemplateVM",
      "imageReference": {
        "offer": "WindowsServer",
        "publisher": "Microsoft",
        "sku": "2019-Datacenter",
        "version": "2019.0.20190410"
      },
      "sku": {
        "name": "Medium"
      },
      "additionalCapabilities": {
        "installGpuDrivers": "Disabled"
      },
      "usageQuota": "PT10H",
      "useSharedPassword": "Disabled",
      "adminUser": {
        "username": "test-user"
      }
    },
    "title": "Test Lab",
    "description": "This is a test lab.",
    "labPlanId": "/subscriptions/34adfa4f-cedf-4dc0-ba29-b6d1a69ab345/resourceGroups/testrg123/providers/Microsoft.LabServices/labPlans/testlabplan",
    "state": "Draft"
  }
}

Sample response

Status code:: 200

{
  "id": "/subscriptions/34adfa4f-cedf-4dc0-ba29-b6d1a69ab345/resourceGroups/testrg123/providers/Microsoft.LabServices/labs/testlab",
  "name": "testlabplan",
  "type": "Microsoft.LabServices/Lab",
  "location": "westus",
  "systemData": {
    "createdBy": "identity123",
    "createdByType": "User",
    "createdAt": "2020-05-01T10:00:00Z",
    "lastModifiedBy": "identity123",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2020-06-01T09:12:28Z"
  },
  "properties": {
    "provisioningState": "Succeeded",
    "connectionProfile": {
      "webSshAccess": "None",
      "webRdpAccess": "None",
      "clientSshAccess": "Public",
      "clientRdpAccess": "Public"
    },
    "autoShutdownProfile": {
      "shutdownOnDisconnect": "Enabled",
      "shutdownWhenNotConnected": "Enabled",
      "shutdownOnIdle": "UserAbsence",
      "disconnectDelay": "PT5M",
      "noConnectDelay": "PT5M",
      "idleDelay": "PT5M"
    },
    "securityProfile": {
      "registrationCode": "fAkEcodE",
      "openAccess": "Disabled"
    },
    "networkProfile": {
      "subnetId": "/subscriptions/34adfa4f-cedf-4dc0-ba29-b6d1a69ab345/resourceGroups/testrg123/providers/Microsoft.Network/virtualNetworks/test-vnet/subnets/default"
    },
    "virtualMachineProfile": {
      "createOption": "TemplateVM",
      "imageReference": {
        "offer": "WindowsServer",
        "publisher": "Microsoft",
        "sku": "2019-Datacenter",
        "version": "2019.0.20190410"
      },
      "osType": "Windows",
      "sku": {
        "name": "Medium",
        "capacity": 20
      },
      "additionalCapabilities": {
        "installGpuDrivers": "Disabled"
      },
      "usageQuota": "PT10H",
      "useSharedPassword": "Disabled",
      "adminUser": {
        "username": "test-user"
      }
    },
    "title": "Test Lab",
    "description": "This is a test lab.",
    "labPlanId": "/subscriptions/34adfa4f-cedf-4dc0-ba29-b6d1a69ab345/resourceGroups/testrg123/providers/Microsoft.LabServices/labPlans/testlabplan",
    "state": "Draft"
  }
}

Status code:: 201

Location: https://management.azure.com/subscriptions/34adfa4f-cedf-4dc0-ba29-b6d1a69ab345/providers/Microsoft.LabServices/operationresults/a64149d8-84cb-4566-ab8e-b4ee1a074174

{
  "id": "/subscriptions/34adfa4f-cedf-4dc0-ba29-b6d1a69ab345/resourceGroups/testrg123/providers/Microsoft.LabServices/labs/testlab",
  "name": "testlabplan",
  "type": "Microsoft.LabServices/Lab",
  "location": "westus",
  "systemData": {
    "createdBy": "identity123",
    "createdByType": "User",
    "createdAt": "2020-05-01T10:00:00Z",
    "lastModifiedBy": "identity123",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2020-06-01T09:12:28Z"
  },
  "properties": {
    "provisioningState": "Creating",
    "connectionProfile": {
      "webSshAccess": "None",
      "webRdpAccess": "None",
      "clientSshAccess": "Public",
      "clientRdpAccess": "Public"
    },
    "autoShutdownProfile": {
      "shutdownOnDisconnect": "Enabled",
      "shutdownWhenNotConnected": "Enabled",
      "shutdownOnIdle": "UserAbsence",
      "disconnectDelay": "PT5M",
      "noConnectDelay": "PT5M",
      "idleDelay": "PT5M"
    },
    "securityProfile": {
      "registrationCode": "fAkEcodE",
      "openAccess": "Disabled"
    },
    "networkProfile": {
      "subnetId": "/subscriptions/34adfa4f-cedf-4dc0-ba29-b6d1a69ab345/resourceGroups/testrg123/providers/Microsoft.Network/virtualNetworks/test-vnet/subnets/default"
    },
    "virtualMachineProfile": {
      "createOption": "TemplateVM",
      "imageReference": {
        "offer": "WindowsServer",
        "publisher": "Microsoft",
        "sku": "2019-Datacenter",
        "version": "2019.0.20190410"
      },
      "osType": "Windows",
      "sku": {
        "name": "Medium",
        "capacity": 20
      },
      "additionalCapabilities": {
        "installGpuDrivers": "Disabled"
      },
      "usageQuota": "PT10H",
      "useSharedPassword": "Disabled",
      "adminUser": {
        "username": "test-user"
      }
    },
    "title": "Test Lab",
    "description": "This is a test lab.",
    "labPlanId": "/subscriptions/34adfa4f-cedf-4dc0-ba29-b6d1a69ab345/resourceGroups/testrg123/providers/Microsoft.LabServices/labPlans/testlabplan",
    "state": "Draft"
  }
}

Status code:: 202

Location: https://management.azure.com/subscriptions/34adfa4f-cedf-4dc0-ba29-b6d1a69ab345/providers/Microsoft.LabServices/operationresults/a64149d8-84cb-4566-ab8e-b4ee1a074174

{
  "id": "/subscriptions/34adfa4f-cedf-4dc0-ba29-b6d1a69ab345/resourceGroups/testrg123/providers/Microsoft.LabServices/labs/testlab",
  "name": "testlabplan",
  "type": "Microsoft.LabServices/Lab",
  "location": "westus",
  "systemData": {
    "createdBy": "identity123",
    "createdByType": "User",
    "createdAt": "2020-05-01T10:00:00Z",
    "lastModifiedBy": "identity123",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2020-06-01T09:12:28Z"
  },
  "properties": {
    "provisioningState": "Updating",
    "connectionProfile": {
      "webSshAccess": "None",
      "webRdpAccess": "None",
      "clientSshAccess": "Public",
      "clientRdpAccess": "Public"
    },
    "autoShutdownProfile": {
      "shutdownOnDisconnect": "Enabled",
      "shutdownWhenNotConnected": "Enabled",
      "shutdownOnIdle": "UserAbsence",
      "disconnectDelay": "PT5M",
      "noConnectDelay": "PT5M",
      "idleDelay": "PT5M"
    },
    "securityProfile": {
      "registrationCode": "fAkEcodE",
      "openAccess": "Disabled"
    },
    "networkProfile": {
      "subnetId": "/subscriptions/34adfa4f-cedf-4dc0-ba29-b6d1a69ab345/resourceGroups/testrg123/providers/Microsoft.Network/virtualNetworks/test-vnet/subnets/default"
    },
    "virtualMachineProfile": {
      "createOption": "TemplateVM",
      "imageReference": {
        "offer": "WindowsServer",
        "publisher": "Microsoft",
        "sku": "2019-Datacenter",
        "version": "2019.0.20190410"
      },
      "osType": "Windows",
      "sku": {
        "name": "Medium",
        "capacity": 20
      },
      "additionalCapabilities": {
        "installGpuDrivers": "Disabled"
      },
      "usageQuota": "PT10H",
      "useSharedPassword": "Disabled",
      "adminUser": {
        "username": "test-user"
      }
    },
    "title": "Test Lab",
    "description": "This is a test lab.",
    "labPlanId": "/subscriptions/34adfa4f-cedf-4dc0-ba29-b6d1a69ab345/resourceGroups/testrg123/providers/Microsoft.LabServices/labPlans/testlabplan",
    "state": "Draft"
  }
}

Definitions

Name	Description
AutoShutdownProfile	Profile for how to handle shutting down virtual machines.
ConnectionProfile	Connection profile for how users connect to lab virtual machines.
ConnectionType	The enabled access level for Web Access over SSH.
createdByType	The type of identity that created the resource.
CreateOption	Indicates what lab virtual machines are created from.
Credentials	Credentials for a user on a lab VM.
EnableState	Whether shutdown on disconnect is enabled
ErrorAdditionalInfo	The resource management error additional info.
ErrorDetail	The error detail.
ErrorResponse	Error response
ImageReference	Image reference information. Used in the virtual machine profile.
Lab	The lab resource.
LabNetworkProfile	Profile for how to handle networking for Labs.
LabState	The state of a virtual machine.
OsType	The OS type of the image
ProvisioningState	Current provisioning state of the lab.
ResourceOperationError	Error details of the latest operation failure on this resource
RosterProfile	The lab user list management profile.
SecurityProfile	The lab security profile.
shutdownOnIdleMode	Defines whether to shut down VM on idle and the criteria for idle detection.
Sku	The resource model definition representing 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.
systemData	Metadata pertaining to creation and last modification of the resource.
VirtualMachineAdditionalCapabilities	The additional capabilities for a lab VM.
VirtualMachineProfile	The base virtual machine configuration for a lab.

AutoShutdownProfile

Object

Profile for how to handle shutting down virtual machines.

Name	Type	Default value	Description
disconnectDelay	string (duration)		The amount of time a VM will stay running after a user disconnects if this behavior is enabled.
idleDelay	string (duration)		The amount of time a VM will idle before it is shutdown if this behavior is enabled.
noConnectDelay	string (duration)		The amount of time a VM will stay running before it is shutdown if no connection is made and this behavior is enabled.
shutdownOnDisconnect	EnableState	Disabled	Whether shutdown on disconnect is enabled
shutdownOnIdle	shutdownOnIdleMode	None	Whether a VM will get shutdown when it has idled for a period of time.
shutdownWhenNotConnected	EnableState	Disabled	Whether a VM will get shutdown when it hasn't been connected to after a period of time.

ConnectionProfile

Object

Connection profile for how users connect to lab virtual machines.

Name	Type	Default value	Description
clientRdpAccess	ConnectionType	None	The enabled access level for Client Access over RDP.
clientSshAccess	ConnectionType	None	The enabled access level for Client Access over SSH.
webRdpAccess	ConnectionType	None	The enabled access level for Web Access over RDP.
webSshAccess	ConnectionType	None	The enabled access level for Web Access over SSH.

ConnectionType

Enumeration

The enabled access level for Web Access over SSH.

Value	Description
Public
Private
None

createdByType

Enumeration

The type of identity that created the resource.

Value	Description
User
Application
ManagedIdentity
Key

CreateOption

Enumeration

Indicates what lab virtual machines are created from.

Value	Description
Image	An image is used to create all lab user virtual machines. When this option is set, no template VM will be created.
TemplateVM	A template VM will be used to create all lab user virtual machines.

Credentials

Object

Credentials for a user on a lab VM.

Name	Type	Description
password	string	The password for the user. This is required for the TemplateVM createOption.
username	string	The username to use when signing in to lab VMs.

EnableState

Enumeration

Whether shutdown on disconnect is enabled

Value	Description
Enabled
Disabled

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.

ImageReference

Object

Image reference information. Used in the virtual machine profile.

Name	Type	Description
exactVersion	string	The actual version of the image after use.
id	string minLength: 3 maxLength: 2000	Image resource ID
offer	string	The image offer if applicable.
publisher	string	The image publisher
sku	string	The image SKU
version	string	The image version specified on creation.

Lab

Object

The lab resource.

Name	Type	Description
id	string	Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
location	string	The geo-location where the resource lives
name	string	The name of the resource
properties.autoShutdownProfile	AutoShutdownProfile	The resource auto shutdown configuration for the lab. This controls whether actions are taken on resources that are sitting idle.
properties.connectionProfile	ConnectionProfile	The connection profile for the lab. This controls settings such as web access to lab resources or whether RDP or SSH ports are open.
properties.description	string	The description of the lab.
properties.labPlanId	string minLength: 3 maxLength: 2000	The ID of the lab plan. Used during resource creation to provide defaults and acts as a permission container when creating a lab via labs.azure.com. Setting a labPlanId on an existing lab provides organization..
properties.networkProfile	LabNetworkProfile	The network profile for the lab, typically applied via a lab plan. This profile cannot be modified once a lab has been created.
properties.provisioningState	ProvisioningState	Current provisioning state of the lab.
properties.resourceOperationError	ResourceOperationError	Error details of last operation done on lab.
properties.rosterProfile	RosterProfile	The lab user list management profile.
properties.securityProfile	SecurityProfile	The lab security profile.
properties.state	LabState	The lab state.
properties.title	string minLength: 1 maxLength: 120	The title of the lab.
properties.virtualMachineProfile	VirtualMachineProfile	The profile used for creating lab virtual machines.
systemData	systemData	Metadata pertaining to creation and last modification of the lab.
tags	object	Resource tags.
type	string	The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts"

LabNetworkProfile

Object

Profile for how to handle networking for Labs.

Name	Type	Description
loadBalancerId	string minLength: 3 maxLength: 2000	The external load balancer resource id
publicIpId	string minLength: 3 maxLength: 2000	The external public IP resource id
subnetId	string minLength: 3 maxLength: 2000	The external subnet resource id

LabState

Enumeration

The state of a virtual machine.

Value	Description
Draft	The lab is currently in draft (has not been published).
Publishing	The lab is publishing.
Scaling	The lab is scaling.
Syncing	The lab is syncing users.
Published	The lab has been published.

OsType

Enumeration

The OS type of the image

Value	Description
Windows
Linux

ProvisioningState

Enumeration

Current provisioning state of the lab.

Value	Description
Creating	Resource is in the process of being created.
Updating	New property values are being applied to the resource.
Deleting	Resource is in the process of being deleted.
Succeeded	Resource is in healthy state after creation or update operation.
Failed	Previous operation on the resource has failed leaving resource in unhealthy state.
Locked	The resource is locked and changes are currently blocked. This could be due to maintenance or a scheduled operation. The state will go back to succeeded once the locking operation has finished.

ResourceOperationError

Object

Error details of the latest operation failure on this resource

Name	Type	Description
action	string	The operation action that failed
code	string	The code that corresponds to the type of operation failure
message	string	The operation failure message
timestamp	string (date-time)	The datetime of when the error occured

RosterProfile

Object

The lab user list management profile.

Name	Type	Description
activeDirectoryGroupId	string	The AAD group ID which this lab roster is populated from. Having this set enables AAD sync mode.
lmsInstance	string	The base URI identifying the lms instance.
ltiClientId	string	The unique id of the azure lab services tool in the lms.
ltiContextId	string	The unique context identifier for the lab in the lms.
ltiRosterEndpoint	string	The uri of the names and roles service endpoint on the lms for the class attached to this lab.

SecurityProfile

Object

The lab security profile.

Name	Type	Description
openAccess	EnableState	Whether any user or only specified users can register to a lab.
registrationCode	string	The registration code for the lab.

shutdownOnIdleMode

Enumeration

Defines whether to shut down VM on idle and the criteria for idle detection.

Value	Description
None	The VM won't be shut down when it is idle.
UserAbsence	The VM will be considered as idle when there is no keyboard or mouse input.
LowUsage	The VM will be considered as idle when user is absent and the resource (CPU and disk) consumption is low.

Sku

Object

The resource model definition representing SKU

Name	Type	Description
capacity	integer (int32)	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	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.

SkuTier

Enumeration

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.

Value	Description
Free
Basic
Standard
Premium

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.

VirtualMachineAdditionalCapabilities

Object

The additional capabilities for a lab VM.

Name	Type	Default value	Description
installGpuDrivers	EnableState	Disabled	Flag to pre-install dedicated GPU drivers.

VirtualMachineProfile

Object

The base virtual machine configuration for a lab.

Name	Type	Default value	Description
additionalCapabilities	VirtualMachineAdditionalCapabilities		Additional VM capabilities.
adminUser	Credentials		Credentials for the admin user on the VM.
createOption	CreateOption		Indicates what lab virtual machines are created from.
imageReference	ImageReference		The image configuration for lab virtual machines.
nonAdminUser	Credentials		Credentials for the non-admin user on the VM, if one exists.
osType	OsType		The OS type of the image
sku	Sku		The SKU for the lab. Defines the type of virtual machines used in the lab.
usageQuota	string (duration)		The initial quota alloted to each lab user. Must be a time span between 0 and 9999 hours.
useSharedPassword	EnableState	Disabled	Enabling this option will use the same password for all user VMs.

Share via

Labs - Create Or Update

URI Parameters

Request Body

Responses

Examples

putLab

Sample request

Sample response

Definitions

AutoShutdownProfile

ConnectionProfile

ConnectionType

createdByType

CreateOption

Credentials

EnableState

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

ImageReference

Lab

LabNetworkProfile

LabState

OsType

ProvisioningState

ResourceOperationError

RosterProfile

SecurityProfile

shutdownOnIdleMode

Sku

SkuTier

systemData

VirtualMachineAdditionalCapabilities

VirtualMachineProfile