Azure Cloud Services

Octopus Deploy supports deployment of Azure Cloud Services. This page will walk you through, step by step, setting up a deployment using the Octopus built-in Deploy an Azure Cloud Service step.

Step 1: Packaging

An Azure cloud service package is normally compiled into a .cspkg file. This file will need to be re-packed into a supported package for Octopus to consume. The easiest way to do this currently is to either create a simple zip file or use the NuGet.exe command line tool. For example, the resulting NuGet package will look like this:

Upload to a NuGet feed

In order to make the NuGet package accessible to Octopus it needs to be uploaded to a package repository. The built-in Octopus package repository is accessible from Library ➜ Packages and is a suitable place to upload your Cloud Service NuGet package:

Step 2: Create an Azure account

If you haven’t already, create an Azure Management Certificate Account to grant Octopus Deploy access to your Azure Subscription.

Step 3: Create the Azure Cloud Service deployment step

Add a new Azure Cloud Service Deployment Step to your project. For information about adding a step to the deployment process, see the add step section.

Step 4: Configure your Azure Cloud Service step

Once an Account is selected, the list of Cloud Services and Storage Accounts available to the Azure subscription associated with the chosen Account will be populated for you to choose from.

Deployment features available to Azure Cloud Service steps

The following features are available when deploying a package to an Azure Cloud Service:

• Custom Scripts
• Configuration Variables
• .NET Configuration Transforms
• Structured configuration variables
• Substitute variables in templates

Please note these features actually run on the Octopus Server prior to deploying the Cloud Service package to Azure. They don’t execute in the Azure Cloud Service instances you are eventually targeting.

Using custom scripts

Custom scripts typically rely on specific tools being available when they execute.

It is best that you control the version of these tools - your scripts will rely on a specific version that they are compatible with to function correctly.

The easiest way to achieve this is to use an execution container for your step.

If this is not an option in your scenario, we recommend that you provision your own tools on your worker.

If the Azure PowerShell module is available, it will be loaded for your convenience, and the subscription from the account associated with the target will be selected. This means you don’t have to worry about loading the Azure PowerShell module nor authenticating with Azure yourself.

You can write very straightforward scripts like the example below:

# Swap the staging slot into production
$ServiceName = $OctopusParameters["Octopus.Action.Azure.CloudServiceName"]
$Deployment = Get-AzureDeployment -Slot "Staging" -ServiceName $ServiceName
if ($Deployment -ne $null -AND $Deployment.DeploymentId  -ne $null) {
  Write-Host ("Current Status of staging slot for {0}" -f $ServiceName)
  $Deployment
  $MoveStatus = Move-AzureDeployment -ServiceName $ServiceName
  Write-Host ("Vip swap of {0} status: {1}" -f $ServiceName, $MoveStatus.OperationStatus)
} else {
  Write-Host ("There is no deployment in staging slot of {0} to swap." -f $ServiceName)
}

See the Azure PowerShell documentation for more information.

Deployment process

Deployment to an Azure Cloud Service proceeds as follows (more details provided below):

1. Download the package from the package repository.
2. Extract the package on the Octopus Server to a temporary location.
3. Extract the Cloud Service package (.cspkg) to a temporary location.
4. Any configured or packaged PreDeploy scripts are executed.
5. Variable substitutions in Cloud Service configuration file (.cscfg).
6. Substitute variables in templates (if configured).
7. .NET XML configuration transformations (if configured) are performed.
8. .NET XML configuration variables (if configured) are replaced.
9. Any configured or package Deploy scripts are executed.
10. Re-package the Cloud Service Package.
11. Upload the Cloud Service Package to Azure Storage.
12. Deploy the Cloud Service Package (see ‘Customizing the deployment process’ section below).
13. Any configured or packaged PostDeploy scripts are executed.

Extract the Cloud Service package

Cloud Service Package files are extracted during deployment, in order to make available features such as .NET Configuration Transforms and Variable Substitution.

To extract the Cloud Service Package, it is first converted to the CTP format (also known as V20120315). This is the format described by Microsoft documentation, but is not used by default by the CSPack utility (passing the /useCtpPackageFormat switch is required for this format to be used). This is just an implementation detail, but the documented archive layout gives a good starting point to understanding the layout of the extracted package.

Setting the Octopus.Action.Azure.LogExtractedCspkg variable to true will cause the layout of the extracted package to be written into the Task Log. This may assist with finding the path to a particular file.

Variable substitutions in Cloud Service configuration file

Octopus will attempt to modify your .cscfg file. For example, take the following configuration:

<ServiceConfiguration serviceName="Humpty" xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceConfiguration" osFamily="2" osVersion="*" schemaVersion="2012-10.1.8">
  <Role name="Humpty.Web">
    <Instances count="1" />
    <ConfigurationSettings>
      <Setting name="Microsoft.WindowsAzure.Plugins.Diagnostics.ConnectionString" value="UseDevelopmentStorage=true" />
      <Setting name="HelloMessage" value="Hello world! This is a web role!" />
    </ConfigurationSettings>
  </Role>
  <Role name="Humpty.Worker">
    <Instances count="1" />
    <ConfigurationSettings>
      <Setting name="Microsoft.WindowsAzure.Plugins.Diagnostics.ConnectionString" value="UseDevelopmentStorage=true" />
      <Setting name="HelloMessage" value="Hello world! This is a worker!" />
    </ConfigurationSettings>
  </Role>
</ServiceConfiguration>

If a variable named HelloMessage is defined in your Octopus project variables, Octopus will automatically update it in the configuration file. You can also name the variable Humpty.Worker/HelloMessage to scope the setting to a specific web/worker role.

Customizing the deployment process

The deployment is performed using the open-source Calamari project. For backwards compatibility, Octopus will look for a PowerShell script called DeployToAzure.ps1. If a file with this name exists within your package, Octopus will invoke it. Otherwise, Octopus will continue to use it’s bundled Sashimi.AzureCloudService library.

Deploying to multiple geographic regions

When your application is deployed to more than one geographic region, you are likely to need per-region configuration settings. You can achieve this result in many different ways, but the two most popular methods we have seen are:

1. Cloud Regions: enable rolling deployments across multiple geographic regions.
2. Environment-per-region: by creating an environment per region you can leverage lifecycles to create a strict release promotion process.

Both methods allow you to modify your deployment process and variables per-region, but have slightly different release promotion paths. Choose the one that suits you best.

Learn more

• Generate an Octopus guide for Azure and the rest of your CI/CD pipeline.

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Sunday, January 1, 2023