Get Deployment

The Get Deployment request can be used to retrieve information for a specific deployment or for all deployments in the staging or production environment. If you want to retrieve information about a specific deployment, you must first get the unique name for the deployment. This unique name is part of the response when you make a request to get all deployments in an environment.

For example, if you have a cloud service deployed to the production environment, you can get the unique name by making a request to …/deploymentslots/production. The response includes a list of all cloud services currently deployed to the production environment, and includes a Name element for each cloud service. That Name element value can be used to make a request to …/deployments/<Name> if you want to retrieve information about that specific deployment.

To generate the request URI, replace <subscription-id> with your subscription ID, <cloudservice-name> with the name of the cloud service, <deployment-slot> with staging or production, and <deployment-name> with the unique name of your deployment.

Method	Request URI	HTTP Version
GET	`https://management.core.windows.net/<subscription-id>/services/hostedservices/<cloudservice-name>/deploymentslots/<deployment-slot>`	HTTP/1.1
GET	`https://management.core.windows.net/<subscription-id>/services/hostedservices/<cloudservice-name>/deployments/<deployment-name>`	HTTP/1.1

URI Parameters

None.

Request Headers

The following table describes the request headers.

Request Header	Description
x-ms-version	Required. Specifies the version of the operation to use for this request. This header should be set to 2009-10-01 or later. For more information about versioning headers, see Service Management Versioning.

Request Body

None.

The response includes an HTTP status code, a set of response headers, and a response body.

Status Code

A successful operation returns status code 200 (OK). For information about status codes, see Service Management Status and Error Codes.

Response Headers

The response for this operation includes the following headers. The response may also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

Response Header	Description
x-ms-request-id	A value that uniquely identifies a request made against the management service.

Response Body

The following example shows the format of the response body:


<?xml version="1.0" encoding="utf-8"?>
<Deployment xmlns="http://schemas.microsoft.com/windowsazure">
  <Name>name-of-deployment</Name>
  <DeploymentSlot>current-deployment-environment</DeploymentSlot>
  <PrivateID>deployment-id</PrivateID>
  <Status>status-of-deployment</Status>
  <Label>base64-encoded-name-of-deployment</Label>
  <Url>deployment-url</Url>
  <Configuration>base-64-encoded-configuration-file</Configuration>
  <RoleInstanceList>
    <RoleInstance>
      <RoleName>name-of-role</RoleName>
      <InstanceName>name-of-role-instance</InstanceName>
      <InstanceStatus>status-of-role-instance</InstanceStatus>
      <InstanceUpgradeDomain>update-domain-of-role-instance</InstanceUpgradeDomain>
      <InstanceFaultDomain>fault-domain-of-role-instance</InstanceFaultDomain>
      <InstanceSize>size-of-role-instance</InstanceSize>
      <InstanceStateDetails>state-of-role-instance</InstanceStateDetails>
      <InstanceErrorCode>error-code-returned-for-role-instance</InstanceErrorCode>
      <IpAddress>ip-address-of-role-instance</IpAddress>
      <InstanceEndpoints>
        <InstanceEndpoint>
          <Name>name-of-endpoint</Name>
          <Vip>virtual-ip-address-of-instance-endpoint</Vip>
          <PublicPort>public-facing-port-of-instance-endpoint</PublicPort>
          <LocalPort>internal-facing-port-of-instance-endpoint</LocalPort>
          <Protocol>protocol-of-instance-endpoint</Protocol>
        </InstanceEndpoint>
      </InstanceEndpoints>
      <PowerState>state-of-role-instance</PowerState>
      <HostName>dns-name-of-service</HostName>
      <RemoteAccessCertificateThumbprint>cert-thumbprint-for-remote-access</RemoteAccessCertificateThumbprint>
    </RoleInstance>
  </RoleInstanceList>
  <UpgradeStatus>
    <UpgradeType>auto|manual</UpgradeType>
    <CurrentUpgradeDomainState>before|during</CurrentUpgradeDomainState>
    <CurrentUpgradeDomain>n</CurrentUpgradeDomain>
  </UpgradeStatus>
  <UpgradeDomainCount>number-of-upgrade-domains-in-deployment</UpgradeDomainCount>
  <RoleList>
    <Role>
      <RoleName>name-of-role</RoleName>
      <OsVersion>operating-system-version</OsVersion>
      <ConfigurationSets>
        <ConfigurationSet>
          <ConfigurationSetType>NetworkConfiguration</ConfigurationSetType>
          <InputEndpoints>
            <InputEndpoint>
              <Port>port-number-of-input-endpoint-in-network</Port>
              <Protocol>protocol-of-input-endpoint-in-network</Protocol>
              <Vip>virtual-ip-address-of-input-endpoint-in-network</Vip>
            </InputEndpoint>
          </InputEndpoints>
        </NetworkConfigurationSet>
      </ConfigurationSets>
    </Role>
    <Role>
      <RoleName>name-of-role</RoleName>
      <OsVersion>operating-system-version</OsVersion>
      <RoleType>PersistentVMRole</RoleType>
      <ConfigurationSets>
        <ConfigurationSet>
          <ConfigurationSetType>NetworkConfiguration</ConfigurationSetType>
          <InputEndpoints>
            <InputEndpoint>
              <LoadBalancedEndpointSetName>name-of-load-balanced-endpoint-set</LoadBalancedEndpointSetName>
              <LocalPort>internal-facing-port-of-input-endpoint</LocalPort>
              <Name>name-of-input-endpoint</Name>
              <Port>external-facing-port-of-input-endpoint</Port>
              <LoadBalancerProbe>
                <Path>path-of-probe</Path>
                <Port>port-assigned-to-probe</Port>
                <Protocol>protocol-of-probe-port</Protocol>
              </LoadBalancerProbe>
              <Protocol>protocol-of-input-endpoint</Protocol>
              <Vip>virtual-ip-address-of-input-endpoint</Vip>
            </InputEndpoint>
          <InputEndpoints>
          <SubnetNames>
            <SubnetName>name-of-subnet</SubnetName>
          </SubnetNames>
        </ConfigurationSet>
      </ConfigurationSets>
      <AvailabilitySetName>name-of-availability-set</AvailabilitySetName>
      <DataVirtualHardDisks>
        <DataVirtualHardDisk>
          <HostCaching>host-caching-mode-of-data-disk</HostCaching>
          <DiskName>name-of-data-disk</DiskName>
          <Lun>logical-unit-number-of-data-disk</Lun>
          <LogicalDiskSizeInGB>size-of-data-disk</LogicalDiskSizeInGB>
          <MediaLink>path-to-vhd</MediaLink>
        </DataVirtualHardDisk>
      </DataVirtualHardDisks>
      <OSVirtualHardDisk>
        <HostCaching>host-caching-mode-of-os-disk</HostCaching>
        <DiskName>name-of-os-disk</DiskName>
        <MediaLink>path-to-vhd</MediaLink>
        <SourceImageName>image-used-to-create-os-disk</SourceImageName>
        <OS>operating-system-on-os-disk</OS>
      </OSVirtualHardDisk>
      <RoleSize>size-of-instance</RoleSize>
    </Role>
  </RoleList>
  <SdkVersion>sdk-version-used-to-create-package</SdkVersion>
  <Locked>status-of-deployment-write-allowed</Locked>
  <RollbackAllowed>rollback-operation-allowed</RollbackAllowed>
  <VirtualNetworkName>name-of-virtual-network</VirtualNetworkName>
  <Dns>
    <DnsServers>
      <DnsServer>
        <Name>name-of-dns-server</Name>
        <Address>address-of-dns-server</Address>
      </DnsServer>
    </DnsServers>
  </Dns>
  <ExtendedProperties>
    <ExtendedProperty>
      <Name>name-of-property</Name>
      <Value>value-of-property</Value>
    </ExtendedProperty>
  </ExtendedProperties>
  <PersistentVMDowntime>
    <StartTime>start-of-downtime</StartTime>
    <EndTime>end-of-downtime</EndTime>
    <Status>status-of-downtime</Status>
  </PersistentVMDowntime>
  <VirtualIPs>
    <VirtualIP>
      <Address>virtual-ip-address-of-deployment</Address>
    </VirtualIP>
  </VirtualIPs>
  <ExtensionConfiguration>
    <AllRoles>
      <Extension>
        <Id>identifier-of-extension</Id>
      </Extension>
      ...
    </AllRoles>
    <NamedRoles>
      <Role>
        <RoleName>role_name1</RoleName>
        <Extensions>
          <Extension>
            <Id>identifier-of-extension</Id>
          </Extension>
          ...
        </Extensions>
      </Role>
    </NamedRoles>
  </ExtensionConfiguration>
</Deployment>

The following table describes the key elements in the response body:

Element name	Description
Name	The user-supplied name for this deployment.
DeploymentSlot	The environment to which the cloud service is deployed, either staging or production.
PrivateID	A unique identifier generated internally by Windows Azure for this deployment.
Status	The status of the deployment. Possible values are: `Running` `Suspended` `RunningTransitioning` `SuspendedTransitioning` `Starting` `Suspending` `Deploying` `Deleting`
Label	The user-supplied name of the deployment returned as a base-64 encoded string. This name can be used to identify the deployment for your tracking purposes.
Url	The URL used to access the cloud service. For example, if the service name is MyService you could access the access the service by calling: http:// MyService.cloudapp.net
Configuration	The base-64 encoded configuration file of the deployment.
RoleInstanceList	The list of role instances in the deployment.
UpgradeStatus	Specifies how the deployment is upgraded.
UpgradeDomainCount	An integer that represents the total number of upgrade domains for the deployment. The UpgradeDomainCount element is only available using version 2011-06-01 or higher.
RoleList	The list of roles in the deployment.
SdkVersion	The version of the SDK that was used to generate the .cspkg file for the deployment. The SdkVersion element is only available using version 2011-06-01 or higher.
Locked	True to prevent a new write operation on the deployment while it is being updated; otherwise false. The Locked element is only available using version 2011-06-01 or higher.
RollbackAllowed	True if the RollbackDeploymentUpdateOrUpgrade operation is allowed on the deployment; otherwise false. The RollbackAllowed element is only available using version 2011-06-01 or higher.
CreatedTime	The time that the deployment was created.
LastModifiedTime	The last time that the deployment was modified.
VirtualNetworkName	The name of the Virtual Network that the virtual machine connects to. The VirtualNetworkName element is only available using version 2012-03-01 or higher.
Dns	The custom DNS settings that are specified for deployment. The Dns element is only available using version 2012-03-01 or higher.
ExtendedProperties	The properties that are used to provide more information about a deployment.
PersistentVMDowntime	Specifies information about when the virtual machine has been started and stopped. The PersistentVMDowntime element is only available using version 2012-03-01 or higher.
VirtualIPs	The virtual IP addresses that are specified for the deployment. The VirtualIPs element is only available using version 2012-03-01 or higher.
ExtensionConfiguration	Represents an extension that is added to the cloud service. In Windows Azure, a process can run as an extension of a cloud service. For example, Remote Desktop Access or the Windows Azure Diagnostics Agent can run as extensions to the cloud service. You can add an extension to a cloud service by using Add Extension and you can add the extension to the deployment by using Upgrade Deployment or Change Deployment Configuration. The ExtensionConfiguration element is only available using version 2013-03-01 or higher.

RoleInstanceList

Contains a collection of objects that provide role instance details.

Element name Description

RoleName

The name of the role.

InstanceName

The name of the specific role instance, if an instance of the role is running.

InstanceStatus

The current status of this instance. If x-ms-version header is set to version 2011-10-01 or later, the returned state will be one of the following values:

Status Message	Description
`RoleStateUnknown`	The role state is currently unknown. The state should automatically be resolved once the role state is detected, so no action is required.
`CreatingVM`	The host agent is currently creating resources for the Virtual Machine.
`StartingVM`	The host agent is starting the Virtual Machine.
`CreatingRole`	Windows Azure is creating resources for the role.
`StartingRole`	Windows Azure is starting the role.
`ReadyRole`	The role instance has started and is ready to be used.
`BusyRole`	The role instance is unavailable for requests. This state is usually generated while the role is being created or stopped.
`StoppingRole`	Windows Azure is stopping the role.
`StoppingVM`	The host agent is stopping the Virtual Machine. This status also indicates that the role has already been stopped.
`DeletingVM`	The Virtual Machine is being deleted by the host agent.
`StoppedVM`	The Virtual Machine is not running. This is the final state of the shutdown process, and no other status messages should be received after `StoppedVM`.
`RestartingRole`	The role has unexpectedly stopped or has failed to start. This status indicates that there is a problem with the role that is causing it to crash or preventing it from starting, and must be corrected before the role can be started. The `InstanceStateDetails` and `InstanceErrorCode` fields can hold information about the role error that caused this state, which may be useful for identifying and debugging the problem.
`CyclingRole`	The role has continually crashed after being started by Windows Azure. This status indicates that there is a problem with the role that prevents it from starting, and may be generated after the `StartingRole` even `ReadyRole` statuses are received. The problem in the role must be found and corrected before the role can be started. The `InstanceStateDetails` and `InstanceErrorCode` fields can hold information about the role error that caused this state, which may be useful for identifying and debugging the problem.
`FailedStartingRole`	The role has continually failed to start. This status indicates that there is a problem with the role that prevents it from starting, and may be generated after the process returns `StartingRole`. The problem in the role must be found and corrected before the role can be started. The `InstanceStateDetails` and `InstanceErrorCode` fields can hold information about the role error that caused this state, which may be useful for identifying and debugging the problem.
`FailedStartingVM`	A Windows Azure or container error is preventing the Virtual Machine from starting. This status is generated by Windows Azure, and does not indicate an error with the role. It may be generated after the `StartingRole` state.
`UnresponsiveRole`	The role has timed out before receiving a status message and is not responding to requests.

InstanceUpgradeDomain

The upgrade domain that this role instance belongs to. During an upgrade deployment, all roles in the same upgrade domain are upgraded at the same time.

The InstanceUpgradeDomain element is only available using version 2011-06-01 or higher.

InstanceFaultDomain

The fault domain that this role instance belongs to. Role instances in the same fault domain may be vulnerable to the failure of a single piece of hardware.

The InstanceFaultDomain element is only available using version 2011-06-01 or higher.

InstanceSize

The size of the role instance.

The InstanceSize element is only available using version 2011-06-01 or higher.

InstanceStateDetails

The instance state is returned as a string that, when present, provides a snapshot of the state of the virtual machine at the time the operation was called.

The InstanceStateDetails element is only available using version 2011-10-01 or higher.

InstanceErrorCode

The error code of the latest role start.

For Virtual Machines the error codes are:

WaitTimeout - The virtual machine did not communicate back to Azure infrastructure within 25 minutes. Typically this indicates that the virtual machine did not start or that the guest agent is not installed.
VhdTooLarge - The VHD image selected was too large for the virtual machine hosting the role.
AzureInternalError – An internal error has occurred that has caused to virtual machine to fail to start. Contact support for additional assistance.

For web and worker roles this field returns an error code that can be provided to Windows Azure support to assist in resolution of errors. Typically this field will be empty.

The InstanceErrorCode element is only available using version 2011-10-01 or higher.

IpAddress

The IP address of the virtual machine (DIP).

The IpAddress element is only available using version 2012-03-01 or higher.

InstanceEndpoints

The list of instance endpoints for the role.

PowerState

The running state of the virtual machine.

The following are possible values:

Starting
Started
Stopping
Stopped
Unknown

HostName

The DNS hostname of the virtual machine.

RemoteAccessCertificateThumbprint

The thumbprint of the RDP server certificate (in Windows) or SSH server certificate (in Linux). The thumbprint only for used for virtual machines that have been created from an image.

The RemoteAccessCertificateThumbprint element is only available using version 2012-08-01 or higher.

InstanceEndpoints

Contains a collection of InstanceEndpoint objects.

Element name	Description
Name	The name for the endpoint.
Vip	The virtual IP address for the endpoint. The Vip element is only available using version 2011-06-01 or higher.
PublicPort	The external port used by the endpoint.
LocalPort	The internal port used by the endpoint.
Protocol	The protocol specified for the endpoint.

UpgradeStatus

Element name	Description
UpgradeType	The upgrade type designated for the deployment. Possible values are Auto and Manual.
CurrentUpgradeDomainState	The state of the current upgrade domain. Possible values are Before and During.
CurrentUpgradeDomain	An integer value that identifies the current upgrade domain. Upgrade domains are identified with a zero-based index: the first upgrade domain has an ID of 0, the second has an ID of 1, and so on.

Contains a collection of objects that provide role details.

Element name	Description
RoleName	The name of the role.
OsVersion	The version of the operating system on which the role instances are running.
RoleType	Specifies the type of the role. This element is only listed for Virtual Machine deployments and by default is PersistentVMRole.
ConfigurationSets	A collection of values that represents system or application configuration settings.
AvailabilitySetName	Represents the logical group name of a collection of virtual machines.
DataVirtualHardDisks	Contains the parameters Windows Azure uses to create a data disk for a virtual machine.
OSVirtualHardDisk	Contains the parameters Windows Azure uses to create the operating system disk for the virtual machine.
RoleSize	The size of the role instance.

Contains a collection of objects that provide system or application data.

Element name	Description
ConfigurationSetType	Specifies the configuration type for the configuration set. This is currently always set to NetworkConfigurationSet.
InputEndpoints	Contains a collection of external endpoints for the virtual machine.
SubnetNames	The list of Virtual Network subnet names that the deployment belongs to.

Contains a collection of objects that provide input endpoint details.

Element name	Description
LoadBalancedEndpointSetName	Specifies a name for a set of load-balanced endpoints. Specifying this name in multiple endpoints adds them all to the set. This element is only listed for Virtual Machine deployments.
LocalPort	Specifies the internal port on which the virtual machine is listening to serve the endpoint. This element is only listed for Virtual Machine deployments.
Name	Specifies the name for the external endpoint. This element is only listed for Virtual Machine deployments.
Port	Specifies the external port to use for the endpoint.
LoadBalancerProbe	Contains properties that specify the endpoint settings which the Windows Azure load balancer uses to monitor the availability of this virtual machine before forwarding traffic to the endpoint.
Protocol	Specifies the transport protocol for the endpoint. Possible Values are: TCP UDP
Vip	The virtual IP address for the endpoint.

Contains properties that specify the endpoint settings which the Windows Azure load balancer uses to monitor the availability of this virtual machine before forwarding traffic to the endpoint.

Element name	Description
Path	Specifies the relative path name to inspect to determine the virtual machine availability status. If Protocol is set to TCP, this value must be NULL. Example: path The probe will use https://example.com/path to perform the probe.
Port	Specifies the port to use to inspect the virtual machine availability status.
Protocol	Specifies the protocol to use to inspect the virtual machine availability status. Possible values are: HTTP TCP

Element name

Description

Path

Specifies the relative path name to inspect to determine the virtual machine availability status. If Protocol is set to TCP, this value must be NULL.

Example:

path

The probe will use https://example.com/path to perform the probe.

Port

Specifies the port to use to inspect the virtual machine availability status.

Protocol

Specifies the protocol to use to inspect the virtual machine availability status.

Possible values are:

HTTP
TCP

Contains a collection of objects that define the DNS server settings.

Element name	Description
Name	The name of the DNS server.
Address	The IP address of the DNS server.

Contains a collection of objects that provide additional information about a deployment.

Element name	Description
Name	Represents the name of a property that is associated with the deployment. Each extended property must have both a defined name and value. You can have a maximum of 50 extended property name and value pairs. The maximum length of the Name element is 64 characters, only alphanumeric characters and underscores are valid in the Name, and the name must start with a letter. Attempting to use other characters, starting the Name with a non-letter character, or entering a name that is identical to that of another extended property owned by the same deployment, will result in a status code 400 (Bad Request) error.
Value	Represents the value of a property that is associated with the deployment. Each extended property must have both a defined name and value. You can have a maximum of 50 extended property name and value pairs, and each extended property value has a maximum length of 255 characters.

Element name

Description

Name

Represents the name of a property that is associated with the deployment. Each extended property must have both a defined name and value. You can have a maximum of 50 extended property name and value pairs.

The maximum length of the Name element is 64 characters, only alphanumeric characters and underscores are valid in the Name, and the name must start with a letter. Attempting to use other characters, starting the Name with a non-letter character, or entering a name that is identical to that of another extended property owned by the same deployment, will result in a status code 400 (Bad Request) error.

Value

Represents the value of a property that is associated with the deployment. Each extended property must have both a defined name and value. You can have a maximum of 50 extended property name and value pairs, and each extended property value has a maximum length of 255 characters.

Contains information about when the virtual machine has been started and stopped.

Element name	Description
StartTime	The time that the virtual machine was started.
EndTime	The time that the virtual machine was stopped.
Status	The status of the virtual machine.

Contains a collection of objects that specify the virtual IP address of the deployment.

Element name	Description
Address	The virtual IP address of the deployment.

Contains a collection of objects that are used to create a data disk for a virtual machine.

Element name	Description
HostCaching	Specifies the platform caching behavior of the data disk blob for read/write efficiency. The default vault is ReadOnly. Possible values are: None ReadOnly ReadWrite
DiskName	Specifies the name of the VHD to use to create the data disk for the virtual machine.
Lun	Specifies the Logical Unit Number (LUN) for the data disk. The LUN specifies the slot in which the data drive appears when mounted for usage by the virtual machine. This element is only listed when more than one data disk is attached to a virtual machine.
LogicalDiskSizeInGB	Specifies the size, in GB, of an empty VHD to be attached to the virtual machine. The VHD can be created as part of disk attach or create virtual machine call by specifying the value for this property. Windows Azure creates the empty VHD based on size preference and attaches the newly created VHD to the virtual machine.
MediaLink	Specifies the location of the disk in Windows Azure storage. Example: http://example.blob.core.windows.net/disks/mydatadisk.vhd

Contains the parameters Windows Azure uses to create the operating system disk for the virtual machine.

Element name	Description
HostCaching	Specifies the platform caching behavior of the operating system disk blob for read/write efficiency. Possible values are: ReadOnly ReadWrite
DiskName	Specifies the name an operating system image in the image repository.
MediaLink	Specifies the location of the operating system disk in Windows Azure storage.
SourceImageName	Specifies the name of the source image that was used to provision the virtual machine.
OS	The operating system running in the virtual machine.

Represents an extension that is added to the cloud service.

Element name	Description
AllRoles	Specifies a list of extensions that are applied to all roles in a deployment.
Extension	Represents an extension that is to be deployed to a role in a cloud service.
NamedRoles	Specifies a list of extensions that are applied to specific roles in a deployment.

Represents an extension that is to be deployed to a role in a cloud service.

Element name	Description
Id	The identifier of the extension. The identifier is created when the extension is added to the cloud service. You can find the Id of an extension that was added to a cloud service by using List Extensions.

Specifies a list of extensions that are applied to specific roles in a deployment.

Element name	Description
Role	Represents a specific role to which the extension is added.
RoleName	Specifies the name of the role.
Extension	Represents an extension that is to be deployed to a role in a cloud service.

Any management certificate associated with the subscription specified by <subscription-id> can be used to authenticate this operation. For additional details, see Authenticating Service Management Requests.

By default, a service is deployed with five update domains, which are updated one at a time during an in-place update. For information on modifying the number of update domains in the service definition file, see Windows Azure Service Definition Schema (.csdef File).

To determine the update domain in which a particular instance is running in Windows Azure, use the UpdateDomain property of the RoleInstance class. See the Windows Azure Managed Library Reference for more information.

You can call Get Deployment to determine whether an update is in progress or has completed. If an update is currently in progress, the response body for the Get Deployment operation returns the UpgradeStatus element and its child elements. If no upgrade is in progress, the UpgradeStatus element is not returned in the response.

Get Deployment

Request

URI Parameters

Request Headers

Request Body

Response

Status Code

Response Headers

Response Body

RoleInstanceList

InstanceEndpoints

UpgradeStatus

RoleList

ConfigurationSets

InputEndpoints

LoadBalancerProbe

Dns

ExtendedProperties

PersistentVMDowntime

VirtualIPs

DataVirtualHardDisks

OSVirtualHardDisk

ExtensionConfiguration

Extension

NamedRoles

Authorization

Remarks