PartsUnlimited : Continous Delivery with Octopus

This lab will step through integrating Octopus deployments into Azure and as well as your deployment pipelines in Visual Studio Team services (VSTS)

DevOps MPP Course Source

This lab is used in course DevOps200.3x: Continuous Integration and Continuous Deployment - module 5.

Pre-requisites:

a Visual Studio team services (VSTS) account
an Azure Subscription
Visual Studio

Lab Tasks:

In this lab you will Install and Configure Octopus Deploy Server using VSTS and Deploy a Web App to Azure App Service Web App.

Task 1: Install Octopus Deploy on an Azure virtual machine using Azure Portal
Task 2: Install Octopus Deploy extension in VSTS account
Task 3: Configure Octopus Deploy Connected Service as VSTS Service Endpoint
Task 4: Create a Simple Application and push Code to VSTS
Task 5: Configure Octupus Deploy Build Integration Tasks in VSTS
Task 6: Create a Web App and Service Principal in Azure for deployment
Task 7: Create Deployment Environments
Task 8: Create an Octopus Deploy Project and configure variable replacement
Task 9: Create a Release and Deploy

Estimated Lab Time:

approx. 90 minutes

Task 1: Install Octopus Deploy on an Azure virtual machine using Azure Portal

Octopus Deploy can be installed either on premises or the cloud. All that is needed is a Windows Server machine and a Microsoft SQL Server (Express edition supported) or a Microsoft Azure SQL Database.

See Minimum requirements and SQL Server requirements.

We can install everything manually, or we can use an Azure Virtual machine template that installs an Octopus Deploy Server with just a few clicks (including setting up a trial, which after 45 days downgrades automatically to Octopus Deploy community edition).

Log on to Azure Portal and click + Create a Resource and enter Octopus in the search box:
Click on enter, and on the Filter blade, select Octopus Deploy Template and then select Octopus Deploy template:
A new blade will open with the description of the Octopus Deploy template:
Take a few minutes to read the description and follow the links to learn more about Octopus Deploy.
Click on the Create button and configure the settings for the virtual machine:
- Configure the Resource Group (we recommend a group on its own)
- Give the machine a name (it will be accessible on the internet under this name)
- Assign a password to octoadmin user (or choose a new user name). This can be used to remote desktop to the machine
- Select virtual machine size (this will have impact on costs)
- Assign a password for sqladmin user
- Assign Octopus Deploy Administrator password
- Enter your name, your organization name, and your email address (you will be emailed the trial license just in case)
After filling all required fields, validate the entered data and click OK.
Read the terms of use and privacy policy [1] for the virtual machine.
When you are ready to purchase the virtual machine, click on Purchase button [2].
Deployment of the Virtual Machine will start and will take a few minutes.

While the Virtual Machine deploys you can take a few moments to see how to install Octopus Deploy had we not used a Virtual Machine Template.

When deployment finishes, you will see a notification in the portal notification area:
If you access the resource group where you have created the virtual machine, you can see all created resources provisioned by the template (virtual machine, SQL Azure database, public IP, storage account, etc.)
We are now ready to login on Octopus Deploy by opening our favorite browser and pointing to the fully qualified domain name that you have created.

If you don’t remember the name you have assigned to your virtual machine, access the VM on Azure portal and check its details:
After entering your fully qualified domain name on the browser (in our case, it is http://octopuswalkthrough.centralus.cloudapp.azure.com), the login page will appear after a few seconds:

Congratulations. You are now ready to start using Octopus Deploy.

If you want, you can log in (admin if you haven’t changed the default username) to take a peek at Octopus Deploy.

Task 2: Install Octopus Deploy extension in VSTS account

Octopus can deploy software in multiple formats: packages NuGet, which can be created using OctoPack, ZIP files, and other formats.

Learn more about packaging applications.

Octopus Deploy supports multiple build automation solutions (Visual Studio Team Services, Jenkins, TeamCity, Bamboo, etc.) or manual builds.

In this exercise, we are going to use Visual Studio Team Service (VSTS) to host the source code and to build the package that Octopus is going to deploy.

We assume you already have a VSTS account (with administration privileges). If you don’t have one, learn how to sign up for a free VSTS account.

Installing the extension

We are now going to set up Octopus Deploy Integration extension from Visual Studio Marketplace to quickly package and push applications from Team Build to Octopus Deploy.

Open Octopus Deploy Integration on your favorite browser and click on the Install button,
Select the account you want to install by clicking on the Continue button and then on Confirm.

The extension is now installed and ready to be used.

Task 3: Configure Octopus Deploy Connected Service as VSTS Service Endpoint

We are now going to set an Octopus Deploy connected service to allow builds to connect to Octopus.

Generate an Octopus Deploy API key

First, we need to login to Octopus and create an API key with all the required permissions for the operations we need to perform.

Login to Octopus Deploy portal and create an API key.
Expand the Admin profile, select the Profile entry,
click on the API keys tab, and click on New API key.
Enter the purpose of this team (e.g., VSTS team build),

and click on Generate new:
Copy the key to a safe place since it cannot be retrieved (you can generate a new one though).

We need an API Key for a user that has sufficient permissions for the tasks we want to perform in our build and release process (e.g., create releases on the projects we want to deploy to). Since we have used the admin user, we are all good.

Generating an API key is described in the Octopus official documentation.

lets configure VSTS Connected Service now. Access the Team project we have created previously in VSTS, hover over the cog [1] and then select the Services entry [2]:
Click on + New Service Endpoint [1] and select Octopus Deploy [2]:
Enter a name, the server URL, and the API key obtained previously and click the OK button [1].

We are now ready to configure the build.
Let’s go back to the team project by clicking on the team project name [1] and then clicking on Team Project Home [2]:

Task 4: Create a Simple Application and push Code to VSTS

We are going to create a simple ASP.NET using Visual Studio 2017; it is enough for our purpose. But first, we are going create a new team project to hold our application.

On the VSTS landing page, we are going to click on the New Project button.
We are going to name it OctopusWalkthrough [1], select Git in Version control [2], and click on the Create button [3].

It will take a moment.
We are now going to create a simple ASP.NET project and then push the source code to the Git repository on VSTS using Visual Studio.
First, make sure we are connected to our Team Project. On Team Menu, select Manage Connections.
On Team Explorer click on Manage Connections and then click on Connect to Project.
A Connect to a Project window will open (enter account and credentials if asked). If you have never connected to the account, click on the Add TFS Server link and enter the URL of your account [2] and click on Add [3]:
Expand your account, select OctopusWalkthrough team project and click Connect:
You are now connected to OctopusWalkthrough. Team Explorer is now giving us the chance to clone the team project Git repository.
If you wish, you can change the path of the local folder [1] where the remote Git repository will be cloned.
We now click on the Clone button and the repository will be cloned in a few seconds.
Select File->New->Project…

and select ASP.NET Web Application (.NET Framework)[1], name the project, and set its location. [2]

Note: Make sure the project location is inside the local folder of the repository we have cloned to [3].

$Screenshot of two windows: On the left, a New Project window displays. Under New Project, a tree-view is expanded as Installed\Templates\Visual C#. In the center pane, ASP.NET Web Application (.NET Framework) is circled, and marked with a 1. At the bottom, the Name and Location fields are circled and marked with a 2. On the right, a Solution Explorer – Folder View window displays. The local folder address is circled and marked with a 3.$
Click on the OK button.
Select an MVC project type and click on OK:
Edit the Web.config file and add a setting with name deployedFrom to the appSettings element.

Edit HomeController.cs file in the Controllers folder and add to the Index method the following code:

ViewData["deployedFrom"] = ConfigurationManager.AppSettings["deployedFrom"];

$Screenshot of the Solution ‘OctopusWalkthrough’ tree view, with Controllers\HomeController.cs circled. On the right, the HomeController.cs file displays, with the previously mentioned line of code circled.$

<h1>ASP.NET</h1>

with

<h1>ASP.NET deployed from @ViewData["deployedFrom"]</h1>

Edit Index.cshtml file in the Views folder and replace

$Screenshot of the Solution ‘OctopusWalkthrough’ tree view, with Views\Home\Index.cshtml circled. On the right, the HomeController.cs file displays, with the previously mentioned line of code circled.$
Open Team Explorer (View->Team Explorer), click on Changes, enter a commit message [1], click on the Commit All drop-down, and then click on Commit All and Push [2].

Task 5: Configure Octupus Deploy Build Integration Tasks in VSTS

Open a browser and navigate to your VSTS account. If the project is not in the list of recent projects, then search for it[1].
Hover over the team project name and click on code to access the code hub [2]:
You can now see the code in the OctopusWalkthrough repository [1] and you can navigate all files, and even edit them online, but we are more interested in automating the build.

We can do this in the Build & Release hub, but since there is yet no build for this repository, we will just click on the Set up build button [2] that is sitting on the top upper left corner:
A new window/tab will open with the build editor and first you will see is the list of build templates.

Hover over the ASP.NET template and click on the Apply button:
Select Hosted in the Default Agent queue dropdown [1]:

Click on the Build Solution task and replace the MSBUild arguments parameter value with the value:

 /p:DeployOnBuild=true /p:WebPublishMethod=Package /p:PackageAsSingleFile=true /p:SkipInvalidConfigurations=true /p:PackageLocation="$(build.artifactstagingdirectory)\\"

Screenshot of the Build solution (Visual Studio Build) task. On the right, the MSBuild Arguments field is highlighted.

Remove Unwanted Tasks byt selecting the Test Assemblies and the Publish symbols paths tasks and remove them from the build definition (right click and then click on Remove selected task(s)):
Click on the + Add Task and add the following tasks (use the add button). Before clicking on the add, make sure you click on the Build solution task, so new tasks are added between Build solution and Publish Artifact task).

If the tasks are not added before the Publish Artifact task, don’t worry—you can reorder them by dragging and dropping in the right order).
- Package Application [1]
- Push Package(s) to Octopus [2]
Note: use the search box to find the tasks faster (enter package for example):
Now, configure the task’s parameters:
Click on Package task and enter the following values:
- OctopusWalkthrough for Package ID field
- select NuPkg for the Package Format dropdown
- 1.0.$(Build.BuildId) for Package Version (notice the 1.0 version is hardcoded. We could use a variable for readability and easier maintenance.)
- $(Build.ArtifactStagingDirectory) for Source Path
- $(Build.ArtifactStagingDirectory)\packages for Output Path
Note: Octopus requires the semver versioning format for the build number. If you intend to build from multiple branches, you can use the 1.0.$(BuildID)-$(SourceBranchName).

We only configured the version for the OctoPack package version. Octopus uses this version; it is recommended that we use a similar version number for the build itself for easier correlation between builds and releases in Octopus.
Click on Push Packages to Octopus task and enter the following values:
- The connected service name we configured previously in the Octopus Deploy Server drop-down
- $(Build.ArtifactStagingDirectory)\packages\*.nupkg for Package
We are now ready to save and queue our first build.
Click on Save & queue,
accept the default parameters, and then click on Queue button:
The build is queued and will start as soon as there is an available agent. Click on the build number:
We are now going to check the results of our build execution.

Navigate to Octopus Deploy portal and log in. We now have a check mark on the Application Package set. It means we have successfully uploaded our first package to the Octopus Deploy repository[1]. Click on the Library menu [2].
We can see we now have one package [1] in the repository. The OctopusWalkthrough package is visible [2] on the list of Available packages:

With our package in Octopus Deploy Repository, we are now ready to deploy it.

Task 6: Create a Web App and Service Principal in Azure for deployment

Login to Azure portal and click on the + sign [1], click on Web + Mobile [2], and finally, click on Web App[3].
A new blade will open. Fill in the details to create a Web Application:
- Enter a name [1]
- Assign a resource group (create a new one or use the one used previously, for example) [2]
- Select the Service plan [3]. If you do not have any service plan on the selected subscription [4], then create a new one.
Click on the Create button [5]; in a few seconds, the web app is provisioned.
Before being able to deploy to Azure, we need to provide Octopus Deploy with the means to authenticate itself against Azure to perform the necessary operations.
Open Octopus Deploy dashboard and click on Environments [1] and then Select Accounts [2]:
Click on Add account in the Azure Subscriptions section.

Octopus Deploy supports two kinds of Azure Authentication:
- Certificate which can be used to interact with Azure Web Apps. This implies creating a certificate and uploading it to the portal.
- A Service Principal, which is required if you want to use Azure Resource Management.
We will go with service principal authentication. If you have a service principal created already you can re-use that.

There are three ways of creating a service principal:
After creating a service principal using your preferred method, you will be ready to configure the Account on Octopus Deploy.

Note: Don’t forget to grant permissions to the service principal (at least to the resource group you created for the Web Application).
Enter the account settings for the service principal data:
Next, click on the Save and test button [1].

If the data verifies successfully, a green checkmark appears:

Task 7: Create Deployment Environments

We need to create an environment so we can deploy to one or more targets. An environment represents a group of deployment targets that we can deploy to at the same time.

It is common to have a set of environments, for example, development, testing, and production.

On Octopus Deploy portal, click on environment [1] and then click on Add environment button [2]:
Enter Development on the environment name and give it a description of Octopus Walkthrough Development Environment and click on the Save button.

We now have an environment to deploy to; now, we need to define what we are going to deploy by creating a project.

Task 8: Create an Octopus Deploy Project and configure variable replacement

On Octopus Deploy portal, click on Projects drop down [1] and then click on All[2]. When the project screen loads, click on the Add project button [3].
Give the project a name, Octopus Walkthrough, and description, and then click on the Save button.

We will be routed to the project details page:
We are now ready to start defining the deploy process. Click on the Process tab [1]:
Then, click on the Add your first step button [1].
The list of step templates appears:
Click on Deploy an Azure Web App and configure the step details:

Step Name Deploy to Web App
Package
- Run on Octopus Server
- Package ID OctopusWalkthrough (the id of package we packaged and published previously using VSTS Team Build)
Azure
- Account Select the Azure Account name you created previously
- Web App Select from the dropdown the name of the Web App created previously:

The Web App value is hard coded to the web application name. If we want to deploy to multiple web applications (representing different environments) we should use an expression and a variable to deploy to multiple environments.

Click on Configure features [1], select the Configuration Variables check box [2], and then click on the Apply button [3]:
Click on the Save button and then click on the Variables tab.
Click on the first row of the Project Variables and enter deployedFrom as the variable name and Octopus Deploy as the value:
The star is an indicator the variables are unsaved. Click on the Save button on right top of the screen.

Learn more about Configuration Variables.

Task 9: Create a Release and Deploy

On the project details click on the Create release button [1] or the Create a release link [2], or click on the Releases tab and then on the Create your first release button:
Give the release a version number and select the OctopusWalkthrough package version (there should be only one unless you have built the code multiple times) and click on the Save button:

We could automate creation of a release from VSTS build. This way, we could have a continuous deployment scenario by setting up VSTS in continuous integration mode and deploy it using Octopus Deploy every time someone pushed a change to VSTS.

We are now ready to deploy. Click on the Deploy to Development button [1] (or click on the Deploy to link [2] for more advanced scenarios):
After clicking on Deploy to Development, click on the Deploy now button [1]:
Deployment will start, and you can see in real time the status of the deployment:
After deployment is complete, on the front of the release, you can now see a green check mark [1] signaling the deploy was successful.
On the task progress [2], you can see the status of all tasks.
On the history zone [3], you can see all changes that this release has suffered.
Since this is our first deployment, you can also see a congratulation banner [4].
If we navigate to the Azure Web Site we have deployed to, we can now see the application we have created previously is now deployed:

As the message says, “ASP.NET deployed from Octopus Deploy,” which means we have used the configuration variables to make a change unique to our process.