Create a New VM Role Instance from the Gallery [SPFSDK][VMROLE]
Applies To: Windows Azure Pack
VM roles are created from a VM role gallery item. The gallery item provides a template that must be customized. Then, after the VM role object is created, the object is sent to the Service Management API Tenant service where it is verified and processed.
To create a new VM role from a gallery item, follow these steps, which are detailed below:
Get or create a cloud service object
Get reference to a VM role gallery item
Get the resource definition from the VM role gallery item
Gather the resource definition parameters
Build a resource configuration JSON object from the resource definition parameters
Build and submit a VM role instance JSON object
Tip
For more information about the placeholders used in the URL, see URL Cheat Sheet for VM Roles [SPFSDK][VMROLE].
Important
Anytime you access a resource within cloud services, you must append the api-version=2013-03 query string. The query string always starts with the ? character after the URL.
Get or create a cloud service object
First, you must get or create a cloud service. For more information, seeCreate a Cloud Service to Host VM Roles [SPFSDK][VMROLE]. This step is required because every VM role is hosted in a cloud service. The cloud service is only used when you want to retrieve VM role instances, or when you create a new VM role instance. After you have identified the cloud service to work with, find the VM role gallery item, which acts like a template. You use the VM role gallery item to create the VM role.
Get reference to a VM role gallery item
The VM role that you want to instantiate must be offered to the tenant subscription with which you are currently working. Use the HTTP GET operation with the Gallery/GalleryItems collection. This collection is available at https://server-name:server-port/subscription-id/Gallery/GalleryItems/$/MicrosoftCompute.VMRoleGalleryItem?api-version=2013-03.
HTTP POST request
GET https://smapi-server:30006/01274684-6afa-4f3f-b62f-353c6202fed1/Gallery/GalleryItems/$/MicrosoftCompute.VMRoleGalleryItem?api-version=2013-03 HTTP/1.1
x-ms-principal-id: user@domain.com
Accept: application/json
Host: smapi-server:30006
Connection: Keep-Alive
HTTP POST response
HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Length: 973
Content-Type: application/json; odata=minimalmetadata; streaming=true; charset=utf-8
Content-Language: en-US
Server: Microsoft-IIS/8.5
X-Content-Type-Options: nosniff
DataServiceVersion: 3.0;
Server: Microsoft-IIS/8.5
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
X-Powered-By: ASP.NET
Date: Mon, 16 Sep 2013 22:32:49 GMT
{
"odata.metadata": "https://spf-server:8090/SC2012R2/VMM/GalleryService.svc/$metadata#GalleryItems/MicrosoftCompute.VMRoleGalleryItem",
"value": [{
"ContentUrl": "Gallery/GalleryItems(Name%3d%27CentOS6LAMP%27,Version%3d%271.0.0.0%27,Publisher%3d%27Microsoft%27)/Content",
"Description": "Deploy a CentOS 6 VM role with Apache, MySQL and PHP installed.",
"IconUrl": null,
"Label": "CentOS6 LAMP Role",
"Name": "CentOS6LAMP",
"PublishDate": "2013-09-05T18:35:00.967",
"Publisher": "Microsoft",
"PublisherLabel": "Microsoft",
"ResourceDefinition@odata.mediaContentType": "application/json",
"ResourceDefinitionUrl": "Gallery/GalleryItems(Name%3d%27CentOS6LAMP%27,Version%3d%271.0.0.0%27,Publisher%3d%27Microsoft%27)/MicrosoftCompute.ResourceDefinitionGalleryItem/ResourceDefinition",
"Version": "1.0.0.0",
"ViewDefinitionUrl": "Gallery/ViewDefinitions(Name%3d%27CentOS6LAMP%27,Version%3d%271.0.0.0%27,Publisher%3d%27Microsoft%27)/%24value",
"odata.type": "MicrosoftCompute.VMRoleGalleryItem"
}]
}
Get the resource definition from the VM role gallery item
A VM role gallery item, MicrosoftCompute.VMRoleGalleryItem, has a property named ResourceDefinitionUrl. This URL represents the location of the resource definition for the gallery item. A resource definition is the template that is used when you create a new instance of a VM role. Generally, a resource definition has a list of parameters for which you must supply values. These parameters are used to configure the VM role when an instance is created.
With reference to an existing VM role gallery item, use the HTTP GET operation on the URL that is identified from the ResourceDefinitionUrl property. This URL is appended after the subscription of the tenant URL: https://server:30006/subscription-id/ResourceDefinitionUrl?api-version=2013-03. For more information about the ResourceDefinition object, see ResourceDefinition [SPFSDK][VMROLE].
HTTP POST request
GET https://smapi-server:30006/01274684-6afa-4f3f-b62f-353c6202fed1/Gallery/GalleryItems(Name%3d%27CentOS6LAMP%27,Version%3d%271.0.0.0%27,Publisher%3d%27Microsoft%27)/MicrosoftCompute.ResourceDefinitionGalleryItem/ResourceDefinition?api-version=2013-03 HTTP/1.1
x-ms-principal-id: user@domain.com
Accept: application/json
Host: smapi-server:30006
HTTP POST response
HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Length: 2009
Content-Type: application/json
Content-Language: en-US
Server: Microsoft-IIS/8.5
X-Content-Type-Options: nosniff
DataServiceVersion: 1.0;
Server: Microsoft-IIS/8.5
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
X-Powered-By: ASP.NET
Date: Thu, 19 Sep 2013 20:00:23 GMT
{
"IntrinsicSettings": {
"HardwareProfile": { "VMSize": "[Param.VMRoleVMSize]" },
"NetworkProfile": { ... removed for brevity ... }
},
"Name": "CentOS6LAMP",
"Publisher": "Microsoft",
"ResourceExtensionReferences": [{ ... removed for brevity ... }],
"ResourceParameters": [{
"Description": "Computer size",
"Name": "VMRoleVMSize",
"Type": "String"
},
{
"Description": "Operating system disk",
"Name": "VMRoleOSVirtualHardDiskImage",
"Type": "String"
},
{
"Description": "Network reference",
"Name": "VMRoleNetworkRef",
"Type": "String"
},
{
"Description": "Resource Extension CentOS6LAMP. Parameter MySQLRootPassword. Run conce command parameter",
"Name": "CentOS6LAMPMySQLRootPassword",
"Type": "SecureString"
},
{
"Description": "Compute name pattern",
"Name": "VMRoleComputerNamePattern",
"Type": "String"
},
{
"Description": "Time zone",
"Name": "VMRoleTimeZone",
"Type": "String"
},
{
"Description": "Administrator credential",
"Name": "VMRoleAdminCredential",
"Type": "Credential"
},
{
"Description": "DNS domain name",
"Name": "VMRoleDNSDomainName",
"Type": "String"
},
{
"Description": "SSH public key",
"Name": "VMRoleSSHPublicKey",
"Type": "String"
}
],
"SchemaVersion": "1.0",
"Type": "Microsoft.Compute/VMRole/1.0",
"Version": "1.0.0.0"
};
Gather the resource definition parameters
Each resource definition can have a list of parameters for which you must supply a value. First, you must check if there are any parameters. If there are, you provide values for each of the parameters and pack the resulting list into another object. After you have retrieved the resource definition from the previous step, check the ResourceParameters property. This property holds the list of parameters that are defined and used by the resource definition. This list can be blank. If it is not, you must provide a value for each parameter.
The resource definition parameters and the values that you provide, are packed into a JSON-encoded string. The format of the string is: { "parameter1 name" : "parameter1 value", "parameter2 name" : "parameter2 value", ... }.
"ResourceParameters": [{
"Description": "Computer size",
"Name": "VMRoleVMSize",
"Type": "String"
},
{
"Description": "Operating system disk",
"Name": "VMRoleOSVirtualHardDiskImage",
"Type": "String"
}
]
For example, if the parameters of the resource definition are as shown in the previous code example, the packed JSON-encoded string could be as follows.
"{\"VMRoleVMSize\":\"ExtraSmall\",\"VMRoleOSVirtualHardDiskImage\":\"CentOS Linux 6 (64-bit):1.0.0.0\"}"
For more information about the ResourceParameters property, see ResourceDefinition [SPFSDK][VMROLE].
Build a resource configuration JSON object from the resource definition parameters
The ResourceConfiguration object represents the values of the parameters that are used to create a VM role. The ResourceConfiguration object also contains a version field, which represents the version of the provided parameter values. For example, by using the parameter values from the previous section, the sample code shows the ResourceConfiguration object.
{
"Version": "1.0.0.0",
"ParameterValues": "{\"VMRoleVMSize\":\"ExtraSmall\",\"VMRoleOSVirtualHardDiskImage\":\"CentOS Linux 6 (64-bit):1.0.0.0\"}"
}
For more information about the ResourceConfiguration object, see ResourceConfiguration [SPFSDK][VMROLE].
Build and submit a VM role instance JSON object
With references to the existing ResourceDefinition object and the ResourceConfiguration object that you created, a new VirtualMachineRole object can be created. The VirtualMachineRole object is then submitted to the server as the body of an HTTP POST operation. The URL to POST to is https://server:30006/subscription-id/CloudServices/cloudservice-name/Resources/MicrosoftCompute/VMRoles?api-version=2013-03
The following JSON object is an example of a VM role that is submitted to the server. Notice the ResourceConfiguration, ResourceDefinition, Label, and Name properties have been provided. For more information about the VirtualMachineRole object, see VirtualMachineRole (Instance) [SPFSDK][VMROLE].
{
"InstanceView": null,
"Label": "Description of the VM Role Instance",
"Name": "MyVMRole",
"ProvisioningState": null,
"ResourceConfiguration": {
"ParameterValues": "{\"VMRoleVMSize\" : \"ExtraSmall\",\"VMRoleOSVirtualHardDiskImage\" : \"CentOS Linux 6 (64-bit):1.0.0.0\",\"VMRoleNetworkRef\" : \"My VM Network\",\"CentOS6LAMPMySQLRootPassword\" : \"!!pass3abc12\",\"VMRoleComputerNamePattern\" : \"LAMP###\",\"VMRoleTimeZone\" : \"Pacific Standard Time\",\"VMRoleAdminCredential\" : \"root:!!pass3abc12\",\"VMRoleDNSDomainName\" : \"mydns\",\"VMRoleSSHPublicKey\" : \"key123\"}",
"Version": "1.0.0.0"
},
"ResourceDefinition": {
"IntrinsicSettings": {
"HardwareProfile": { "VMSize": "[Param.VMRoleVMSize]" },
"NetworkProfile": {
"NetworkAdapters": [{
"IPAddresses": [{
"AllocationMethod": "Dynamic",
"ConfigurationName": "IPV4Configuration",
"LoadBalancerConfigurations": [],
"Type": "IPV4"
}],
"Name": "NIC1",
"NetworkRef": "[Param.VMRoleNetworkRef]"
}]
},
"OperatingSystemProfile": {
"AdminCredential": "[Param.VMRoleAdminCredential]",
"ComputerNamePattern": "[Param.VMRoleComputerNamePattern]",
"LinuxOperatingSystemProfile": {
"DNSDomainName": "[Param.VMRoleDNSDomainName]",
"SSHPublicKey": "[Param.VMRoleSSHPublicKey]"
},
"TimeZone": "[Param.VMRoleTimeZone]",
"WindowsOperatingSystemProfile": null
},
"ScaleOutSettings": {
"InitialInstanceCount": "1",
"MaximumInstanceCount": "5",
"MinimumInstanceCount": "1",
"UpgradeDomainCount": "1"
},
"StorageProfile": {
"DataVirtualHardDisks": [],
"OSVirtualHardDiskImage": "[Param.VMRoleOSVirtualHardDiskImage]"
}
},
"Name": "CentOS6LAMP",
"Publisher": "Microsoft",
"ResourceExtensionReferences": [{
"Name": "CentOS6LAMP",
"Publisher": "Microsoft",
"ReferenceName": "CentOS6LAMP",
"ResourceExtensionParameterValues": "{\"MySQLRootPassword\":\"[Param.CentOS6LAMPMySQLRootPassword]\"}",
"Version": "1.0.0.0"
}],
"ResourceParameters": [{
"Description": "Computer size",
"Name": "VMRoleVMSize",
"Type": "String"
},
{
"Description": "Operating system disk",
"Name": "VMRoleOSVirtualHardDiskImage",
"Type": "String"
},
{
"Description": "Network reference",
"Name": "VMRoleNetworkRef",
"Type": "String"
},
{
"Description": "Resource Extension CentOS6LAMP. Parameter MySQLRootPassword. Run conce command parameter",
"Name": "CentOS6LAMPMySQLRootPassword",
"Type": "SecureString"
},
{
"Description": "Compute name pattern",
"Name": "VMRoleComputerNamePattern",
"Type": "String"
},
{
"Description": "Time zone",
"Name": "VMRoleTimeZone",
"Type": "String"
},
{
"Description": "Administrator credential",
"Name": "VMRoleAdminCredential",
"Type": "Credential"
},
{
"Description": "DNS domain name",
"Name": "VMRoleDNSDomainName",
"Type": "String"
},
{
"Description": "SSH public key",
"Name": "VMRoleSSHPublicKey",
"Type": "String"
}
],
"SchemaVersion": "1.0",
"Type": "Microsoft.Compute/VMRole/1.0",
"Version": "1.0.0.0"
},
"Substate": null
}
HTTP POST request
POST https://smapi-server:30006/01274684-6afa-4f3f-b62f-353c6202fed1/CloudServices/TestVM/Resources/MicrosoftCompute/VMRoles?api-version=2013-03 HTTP/1.1
x-ms-principal-id: user@domain.com
Accept: application/json
Content-Type: application/json
Host: smapi-server:30006
Content-Length: 2676
Expect: 100-continue
Connection: Keep-Alive
{"InstanceView":null,"Label":"Description Value Here","Name":"ExampleVMRole","ProvisioningState":null,"ResourceConfiguration":{"ParameterValues":"{\"VMRoleVMSize\" : \"ExtraSmall\",\"VMRoleOSVirtualHardDiskImage\" : \"CentOS Linux 6 (64-bit):1.0.0.0\",\"VMRoleNetworkRef\" : \"My VM Network\",\"CentOS6LAMPMySQLRootPassword\" : \"!!pass3abc12\",\"VMRoleComputerNamePattern\" : \"LAMP###\",\"VMRoleTimeZone\" : \"Pacific Standard Time\",\"VMRoleAdminCredential\" : \"root:!!pass3abc12\",\"VMRoleDNSDomainName\" : \"mydns\",\"VMRoleSSHPublicKey\" : \"andy\"}","Version":"1.0.0.0"},"ResourceDefinition":{"IntrinsicSettings":{"HardwareProfile":{"VMSize":"[Param.VMRoleVMSize]"},"NetworkProfile":{"NetworkAdapters":[{"IPAddresses":[{"AllocationMethod":"Dynamic","ConfigurationName":"IPV4Configuration","LoadBalancerConfigurations":[],"Type":"IPV4"}],"Name":"NIC1","NetworkRef":"[Param.VMRoleNetworkRef]"}]},"OperatingSystemProfile":{"AdminCredential":"[Param.VMRoleAdminCredential]","ComputerNamePattern":"[Param.VMRoleComputerNamePattern]","LinuxOperatingSystemProfile":{"DNSDomainName":"[Param.VMRoleDNSDomainName]","SSHPublicKey":"[Param.VMRoleSSHPublicKey]"},"TimeZone":"[Param.VMRoleTimeZone]","WindowsOperatingSystemProfile":null},"ScaleOutSettings":{"InitialInstanceCount":"1","MaximumInstanceCount":"5","MinimumInstanceCount":"1","UpgradeDomainCount":"1"},"StorageProfile":{"DataVirtualHardDisks":[],"OSVirtualHardDiskImage":"[Param.VMRoleOSVirtualHardDiskImage]"}},"Name":"CentOS6LAMP","Publisher":"Microsoft","ResourceExtensionReferences":[{"Name":"CentOS6LAMP","Publisher":"Microsoft","ReferenceName":"CentOS6LAMP","ResourceExtensionParameterValues":"{\"MySQLRootPassword\":\"[Param.CentOS6LAMPMySQLRootPassword]\"}","Version":"1.0.0.0"}],"ResourceParameters":[{"Description":"Computer size","Name":"VMRoleVMSize","Type":"String"},{"Description":"Operating system disk","Name":"VMRoleOSVirtualHardDiskImage","Type":"String"},{"Description":"Network reference","Name":"VMRoleNetworkRef","Type":"String"},{"Description":"Resource Extension CentOS6LAMP. Parameter MySQLRootPassword. Run conce command parameter","Name":"CentOS6LAMPMySQLRootPassword","Type":"SecureString"},{"Description":"Compute name pattern","Name":"VMRoleComputerNamePattern","Type":"String"},{"Description":"Time zone","Name":"VMRoleTimeZone","Type":"String"},{"Description":"Administrator credential","Name":"VMRoleAdminCredential","Type":"Credential"},{"Description":"DNS domain name","Name":"VMRoleDNSDomainName","Type":"String"},{"Description":"SSH public key","Name":"VMRoleSSHPublicKey","Type":"String"}],"SchemaVersion":"1.0","Type":"Microsoft.Compute\/VMRole\/1.0","Version":"1.0.0.0"},"Substate":null}
HTTP POST response
HTTP/1.1 201 Created
Cache-Control: no-cache
Content-Length: 4839
Content-Type: application/json; odata=minimalmetadata; streaming=true; charset=utf-8
Location: https://spf-server:8090/SC2012R2/VMM/Microsoft.Management.Odata.svc/VMRole/ExampleVMRole
Server: Microsoft-IIS/8.5
x-ms-request-id: 01095ac2-df63-4930-8782-691a8c365319
X-Content-Type-Options: nosniff
request-id: 68d9b05b-a9da-0000-2f56-de68daa9ce01
DataServiceVersion: 3.0;
Server: Microsoft-IIS/8.5
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
X-Powered-By: ASP.NET
Date: Thu, 19 Sep 2013 22:17:57 GMT
{"odata.metadata":"https://spf-server:8090/SC2012R2/VMM/Microsoft.Management.Odata.svc/$metadata#VMRole/@Element","Name":"ExampleVMRole","Label":"Description Value Here","ResourceDefinition":{"Name":"CentOS6LAMP","Version":"1.0.0.0","Publisher":"Microsoft","SchemaVersion":"1.0","Type":"Microsoft.Compute/VMRole/1.0","ResourceParameters":[{"Name":"VMRoleVMSize","Type":"String","Description":"Computer size"},{"Name":"VMRoleOSVirtualHardDiskImage","Type":"String","Description":"Operating system disk"},{"Name":"VMRoleNetworkRef","Type":"String","Description":"Network reference"},{"Name":"CentOS6LAMPMySQLRootPassword","Type":"SecureString","Description":"Resource Extension CentOS6LAMP. Parameter MySQLRootPassword. Run conce command parameter"},{"Name":"VMRoleComputerNamePattern","Type":"String","Description":"Compute name pattern"},{"Name":"VMRoleTimeZone","Type":"String","Description":"Time zone"},{"Name":"VMRoleAdminCredential","Type":"Credential","Description":"Administrator credential"},{"Name":"VMRoleDNSDomainName","Type":"String","Description":"DNS domain name"},{"Name":"VMRoleSSHPublicKey","Type":"String","Description":"SSH public key"}],"ResourceExtensionReferences":[{"ReferenceName":"CentOS6LAMP","Name":"CentOS6LAMP","Version":"1.0.0.0","Publisher":"Microsoft","ResourceExtensionParameterValues":"{\"MySQLRootPassword\":\"[Param.CentOS6LAMPMySQLRootPassword]\"}"}],"IntrinsicSettings":{"ScaleOutSettings":{"InitialInstanceCount":"1","MaximumInstanceCount":"5","MinimumInstanceCount":"1","UpgradeDomainCount":"1"},"HardwareProfile":{"VMSize":"[Param.VMRoleVMSize]"},"StorageProfile":{"OSVirtualHardDiskImage":"[Param.VMRoleOSVirtualHardDiskImage]","DataVirtualHardDisks":[]},"OperatingSystemProfile":{"ComputerNamePattern":"[Param.VMRoleComputerNamePattern]","TimeZone":"[Param.VMRoleTimeZone]","AdminCredential":"[Param.VMRoleAdminCredential]","WindowsOperatingSystemProfile":{"WorkgroupName":null,"DomainJoin":null},"LinuxOperatingSystemProfile":{"DNSDomainName":"[Param.VMRoleDNSDomainName]","SSHPublicKey":"[Param.VMRoleSSHPublicKey]"}},"NetworkProfile":{"NetworkAdapters":[{"Name":"NIC1","NetworkRef":"[Param.VMRoleNetworkRef]","IPAddresses":[{"AllocationMethod":"Dynamic","Type":"IPV4","ConfigurationName":"IPV4Configuration","LoadBalancerConfigurations":[]}]}]}}},"ResourceConfiguration":{"Version":"1.0.0.0","ParameterValues":"{\"VMRoleVMSize\":\"ExtraSmall\",\"VMRoleOSVirtualHardDiskImage\":\"CentOS Linux 6 (64-bit):1.0.0.0\",\"VMRoleNetworkRef\":\"My VM Network\",\"CentOS6LAMPMySQLRootPassword\":\"__**__\",\"VMRoleComputerNamePattern\":\"LAMP###\",\"VMRoleTimeZone\":\"Pacific Standard Time\",\"VMRoleAdminCredential\":\"root:__**__\",\"VMRoleDNSDomainName\":\"mydns\",\"VMRoleSSHPublicKey\":\"andy\"}"},"ProvisioningState":"Provisioning","Substate":{"VMRoleMessages":[]},"InstanceView":{"VIPs":[],"InstanceCount":"0","ResolvedResourceDefinition":{"Name":"CentOS6LAMP","Version":"1.0.0.0","Publisher":"Microsoft","SchemaVersion":"1.0","Type":"Microsoft.Compute/VMRole/1.0","ResourceParameters":[{"Name":"VMRoleVMSize","Type":"String","Description":"Computer size"},{"Name":"VMRoleOSVirtualHardDiskImage","Type":"String","Description":"Operating system disk"},{"Name":"VMRoleNetworkRef","Type":"String","Description":"Network reference"},{"Name":"CentOS6LAMPMySQLRootPassword","Type":"SecureString","Description":"Resource Extension CentOS6LAMP. Parameter MySQLRootPassword. Run conce command parameter"},{"Name":"VMRoleComputerNamePattern","Type":"String","Description":"Compute name pattern"},{"Name":"VMRoleTimeZone","Type":"String","Description":"Time zone"},{"Name":"VMRoleAdminCredential","Type":"Credential","Description":"Administrator credential"},{"Name":"VMRoleDNSDomainName","Type":"String","Description":"DNS domain name"},{"Name":"VMRoleSSHPublicKey","Type":"String","Description":"SSH public key"}],"ResourceExtensionReferences":[{"ReferenceName":"CentOS6LAMP","Name":"CentOS6LAMP","Version":"1.0.0.0","Publisher":"Microsoft","ResourceExtensionParameterValues":"{\"MySQLRootPassword\":\"__**__\"}"}],"IntrinsicSettings":{"ScaleOutSettings":{"InitialInstanceCount":"1","MaximumInstanceCount":"5","MinimumInstanceCount":"1","UpgradeDomainCount":"1"},"HardwareProfile":{"VMSize":"ExtraSmall"},"StorageProfile":{"OSVirtualHardDiskImage":"CentOS Linux 6 (64-bit):1.0.0.0","DataVirtualHardDisks":[]},"OperatingSystemProfile":{"ComputerNamePattern":"LAMP###","TimeZone":"Pacific Standard Time","AdminCredential":"root:__**__","WindowsOperatingSystemProfile":{"WorkgroupName":null,"DomainJoin":null},"LinuxOperatingSystemProfile":{"DNSDomainName":"mydns","SSHPublicKey":"andy"}},"NetworkProfile":{"NetworkAdapters":[{"Name":"NIC1","NetworkRef":"My VM Network","IPAddresses":[{"AllocationMethod":"Dynamic","Type":"IPV4","ConfigurationName":"IPV4Configuration","LoadBalancerConfigurations":[]}]}]}}}}}
See Also
Provisioning VM Roles [SPFSDK][VMROLE]
Create a Cloud Service to Host VM Roles [SPFSDK][VMROLE]
Inspect a VM Role for Provisioning Errors [SPFSDK][VMROLE]