Exercise - Set up your Azure DevOps environment

Completed

In this section, you make sure that your Azure DevOps organization is set up to complete the rest of this module. You also create the Azure App Service environments that you'll deploy to.

To accomplish these goals, you:

  • Add a user to ensure Azure DevOps can connect to your Azure subscription.
  • Set up an Azure DevOps project for this module.
  • On Azure Boards, move the work item for this module to the Doing column.
  • Make sure your project is set up locally so that you can push changes to the pipeline.
  • Create the Azure App Service environments by using the Azure CLI in Azure Cloud Shell.
  • Create pipeline variables that define the names of your App Service environments.
  • Create a service connection that enables Azure Pipelines to securely access your Azure subscription.

Add a user to Azure DevOps

To complete this module, you need your own Azure subscription. You can get started with Azure for free.

You don't need an Azure subscription to work with Azure DevOps, but here you'll use Azure DevOps to deploy to Azure resources that exist in your Azure subscription. To simplify the process, use the same Microsoft account to sign in to both your Azure subscription and your Azure DevOps organization.

If you use different Microsoft accounts to sign in to Azure and Azure DevOps, add a user to your DevOps organization under the Microsoft account that you use to sign in to Azure. For more information, see Add users to your organization or project. When you add the user, select the Basic access level.

Next, sign out of Azure DevOps and sign in. Use the Microsoft account that you use to sign in to your Azure subscription.

Get the Azure DevOps project

Here, you make sure that your Azure DevOps organization is set up to complete the rest of this module. To do so, you run a template that creates a project in Azure DevOps.

The modules in this learning path form a progression. You follow the Tailspin web team through their DevOps journey. For learning purposes, each module has its own Azure DevOps project.

Run the template

Run a template that sets up your Azure DevOps organization:

From the Azure DevOps Demo Generator site, to run the template, follow these steps.

  1. Select Sign In, and accept the usage terms.

  2. On the Create New Project page, select your Azure DevOps organization. Enter a project name, such as Space Game - web - Multistage.

    A screenshot of the Azure DevOps Demo Generator showing the process for creating the project.

  3. Select Yes, I want to fork this repository > Authorize.

    If a window appears, authorize access to your GitHub account.

    Important

    You need to select this option so the template will connect to your GitHub repository. Select it even if you've already forked the Space Game website project. The template uses your existing fork.

  4. Select Create Project.

    The template takes a few moments to run.

  5. To go to your project in Azure DevOps, select Navigate to project.

Important

In this module, the Clean up your Azure DevOps environment page contains important cleanup steps. Cleaning up helps ensure that you don't run out of free build minutes. Even if you don't complete this module, be sure to follow the cleanup steps.

Set your project's visibility

Your fork of the Space Game repository on GitHub is initially public. The Azure DevOps template creates a project that's initially private.

A public GitHub repository is accessible to everyone, whereas a private repository is accessible to you and the people you share it with. In both cases, only collaborators can commit changes to a GitHub repository.

A project on Azure DevOps works the same way. Users who aren't signed in to the service have read-only access to public projects. Private projects require users to be granted access to the project and signed in to access the services.

For learning purposes, you don't need to change any of these settings right now. But for your own projects, you need to decide what visibility and access you want to provide to others. For example, if your project is open source, you might make both your GitHub repository and your Azure DevOps project public. If your project is closed source, you would likely make both your GitHub repository and your Azure DevOps project private.

Later, you can use these resources to help you decide which option is best for your project:

Move the work item to Doing

Here, you assign a work item to yourself on Azure Boards. You also move the work item to the Doing state. In practice, you and your team would create work items at the start of each sprint, or work iteration.

This work assignment gives you a checklist to work from. It gives other team members visibility into what you're working on and how much work is left. The work item also helps enforce work-in-progress (WIP) limits, so that the team doesn't take on too much work at one time.

Recall that the team settled on the following top issues for the current sprint.

A screenshot of Azure Boards showing the five tasks for this sprint.

Note

Within an Azure DevOps organization, work items are numbered sequentially. In your project, the number for each work item might not match what you see here.

Here you move the first item, Create a multistage pipeline, to the Doing column. Then you assign yourself to the work item. Create a multistage pipeline relates to defining each stage of deploying the Space Game website.

To set up the work item:

  1. From Azure DevOps, navigate to Boards. Then, from the menu, select Boards.

    A screenshot of Azure DevOps showing the location of the Boards menu.

  2. In the Create a multistage pipeline work item, at the bottom of the card, select the down arrow. Then, assign the work item to yourself.

    Azure Boards showing the location of the down arrow.

  3. Move the work item from the To Do column to the Doing column.

    A screenshot of Azure Boards showing the card in the Doing column.

At the end of this module, you'll move the card to the Done column, after you complete the task.

Set up the project locally

Here you load the Space Game project in Visual Studio Code, configure Git, clone your repository locally, and set the upstream remote so that you can download starter code.

Note

If you're already set up with the mslearn-tailspin-spacegame-web-deploy project locally, you can move to the next section.

Open the integrated terminal

Visual Studio Code comes with an integrated terminal. Here you can both edit files and work from the command line.

  1. Start Visual Studio Code.

  2. On the View menu, select Terminal.

  3. In the drop-down list, select bash. If you're familiar with another Unix shell that you prefer to use, such as Zsh, select that shell instead.

    A screenshot of Visual Studio Code showing the location of the Bash shell.

    In the terminal window, you can choose any shell that's installed on your system. For example, you can choose Bash, Zsh, or PowerShell.

    Here you'll use Bash. Git for Windows provides Git Bash, which makes it easy to run Git commands.

    Note

    On Windows, if you don't see bash listed as an option, make sure you've installed Git and then restart Visual Studio Code.

    If you still don't see the bash option, see Integrated Terminal to manually configure your terminal settings.

  4. Run the cd command to navigate to the directory where you want to work. Choose your home directory (~) or a different directory if you want.

    cd ~
    

Configure Git

If you're new to Git and GitHub, first run a few commands to associate your identity with Git and authenticate with GitHub. For more information, see Set up Git.

At a minimum, you need to complete the following steps. Run the commands from the integrated terminal.

  1. Set your username.
  2. Set your commit email address.
  3. Cache your GitHub password.

Note

If you already use two-factor authentication with GitHub, create a personal access token. When you're prompted, use your token in place of your password.

Treat your access token like a password. Keep it in a safe place.

Set up your project in Visual Studio Code

In the Build applications with Azure DevOps learning path, you forked and then cloned a Git repository. The repository contains the source code for the Space Game website. Your fork was connected to your projects in Azure DevOps so that the build runs when you push changes to GitHub.

Important

In this learning path, we switch to a different Git repository, mslearn-tailspin-spacegame-web-deploy. When you ran the template to set up your Azure DevOps project, the process forked the repository automatically for you.

In this part, you clone your fork locally so that you can change and build out your pipeline configuration.

Clone your fork locally

You now have a copy of the Space Game web project in your GitHub account. Now you'll download, or clone, a copy to your computer so you can work with it.

A clone, just like a fork, is a copy of a repository. When you clone a repository, you can make changes, verify that they work as you expect, and then upload those changes to GitHub. You can also synchronize your local copy with changes that other authenticated users have made to the GitHub copy of your repository.

To clone the Space Game web project to your computer:

  1. Go to your fork of the Space Game web project (mslearn-tailspin-spacegame-web-deploy) on GitHub.

  2. Select Code. Then, from the HTTPS tab, select the button next to the URL that's shown to copy the URL to your clipboard.

    Locating the URL and copy button from the GitHub repository.

  3. In Visual Studio Code, go to the terminal window.

  4. In the terminal, move to the directory where you want to work. Choose your home directory (~) or a different directory if you want.

    cd ~
    
  5. Run the git clone command. Replace the URL that's shown here with the contents of your clipboard:

    git clone https://github.com/your-name/mslearn-tailspin-spacegame-web-deploy.git
    
  6. Move to the mslearn-tailspin-spacegame-web-deploy directory. This is the root directory of your repository.

    cd mslearn-tailspin-spacegame-web-deploy
    

Set the upstream remote

A remote is a Git repository where team members collaborate (like a repository on GitHub). Here you list your remotes and add a remote that points to Microsoft's copy of the repository so that you can get the latest sample code.

  1. Run this git remote command to list your remotes:

    git remote -v
    

    You see that you have both fetch (download) and push (upload) access to your repository:

    origin  https://github.com/username/mslearn-tailspin-spacegame-web-deploy.git (fetch)
    origin  https://github.com/username/mslearn-tailspin-spacegame-web-deploy.git (push)
    

    Origin specifies your repository on GitHub. When you fork code from another repository, the original remote (the one you forked from) is often named upstream.

  2. Run this git remote add command to create a remote named upstream that points to the Microsoft repository:

    git remote add upstream https://github.com/MicrosoftDocs/mslearn-tailspin-spacegame-web-deploy.git
    
  3. Run git remote again to see the changes:

    git remote -v
    

    You see that you still have both fetch (download) access and push (upload) access to your repository. You also now have fetch access to the Microsoft repository:

    origin  https://github.com/username/mslearn-tailspin-spacegame-web-deploy.git (fetch)
    origin  https://github.com/username/mslearn-tailspin-spacegame-web-deploy.git (push)
    upstream        https://github.com/MicrosoftDocs/mslearn-tailspin-spacegame-web-deploy.git (fetch)
    

Open the project in the file explorer

In Visual Studio Code, your terminal window points to the root directory of the Space Game web project. To view its structure and work with files, from the file explorer, you'll now open the project.

  1. The easiest way to open the project is to reopen Visual Studio Code in the current directory. To do so, run the following command from the integrated terminal:

    code -r .
    

    You see the directory and file tree in the file explorer.

  2. Reopen the integrated terminal. The terminal places you at the root of your web project.

If the code command fails, you need to add Visual Studio Code to your system PATH. To do so:

  1. In Visual Studio Code, select F1 or select View > Command Palette to access the command palette.
  2. In the command palette, enter Shell Command: Install 'code' command in PATH.
  3. Repeat the previous procedure to open the project in the file explorer.

You're now set up to work with the Space Game source code and your Azure Pipelines configuration from your local development environment.

Create the Azure App Service environments

Here, you create the environments that define the pipeline stages. You create one App Service instance for each stage: Dev, Test, and Staging.

In Create a release pipeline with Azure Pipelines, you brought up App Service through the Azure portal. Although the portal is a great way to explore what's available on Azure or to do basic tasks, bringing up components such as App Service can be tedious.

In this module, you use the Azure CLI to bring up three App Service instances. You can access the Azure CLI from a terminal or through Visual Studio Code. Here, you access the Azure CLI from Azure Cloud Shell. This browser-based shell experience is hosted in the cloud. In Cloud Shell, the Azure CLI is configured for use with your Azure subscription.

Important

To complete the exercises in this module, you need your own Azure subscription.

Bring up Cloud Shell through the Azure portal

  1. Go to the Azure portal, and sign in.

  2. From the menu, select Cloud Shell. When prompted, select the Bash experience.

    A screenshot of the Azure portal showing the location of the Cloud Shell menu item.

    Note

    Cloud Shell requires an Azure storage resource to persist any files that you create in the Cloud Shell. When you first open the Cloud Shell, you're prompted to create a resource group, storage account, and Azure Files share. This setup is automatically used for all future Cloud Shell sessions.

Select an Azure region

A region is one or more Azure datacenters within a geographic location. East US, West US, and North Europe are examples of regions. Every Azure resource, including an App Service instance, is assigned a region.

To make commands easier to run, start by selecting a default region. After you specify the default region, later commands use that region unless you specify a different region.

  1. From the Cloud Shell, to list the regions that are available from your Azure subscription, run the following az account list-locations command.

    az account list-locations \
      --query "[].{Name: name, DisplayName: displayName}" \
      --output table
    
  2. From the Name column in the output, select a region that's close to you. For example, choose eastasia or westus2.

  3. Run az configure to set your default region. Replace <REGION> with the name of the region you selected.

    az configure --defaults location=<REGION>
    

    This example sets westus2 as the default region:

    az configure --defaults location=westus2
    

Create the App Service instances

Here, you create the App Service instances for the three stages you'll deploy to: Dev, Test, and Staging. Here's a brief overview of the process you'll follow:

  1. Generate a random number that makes your web app's domain name unique.

    This step is for learning purposes. In practice, you would choose a domain name that matches the name of your app or service.

  2. Create a resource group that contains all of your App Service instances.

    For learning purposes, here you create one resource group that contains all of your App Service instances. In practice, you might create a separate resource group for each App Service instance so that you can better control the life cycle of each instance.

  3. Create an App Service plan.

    An App Service plan defines the CPU, memory, and storage resources for your web app. Here, you use the B1 Basic plan. This plan is intended for apps that have low traffic requirements. The Standard and Premium plans are for production workloads. These plans run on dedicated virtual machine instances.

  4. For each of the Dev, Test, and Staging environments, create an App Service instance.

  5. Get the host name for each environment.

  6. Verify that each environment is running, and that the home page is accessible.

    Note

    For learning purposes, here, you use the default network settings. These settings make your site accessible from the internet. In practice, you could configure an Azure virtual network that places your website in a network that's not internet routable, and that only you and your team can access. Later, you could reconfigure your network to make the website available to your users.

To create your App Service instances, follow these steps:

  1. From the Cloud Shell, generate a random number that makes your web app's domain name unique.

    webappsuffix=$RANDOM
    
  2. To create a resource group that's named tailspin-space-game-rg, run the following az group create command.

    az group create --name tailspin-space-game-rg
    
  3. To create an App Service plan that's named tailspin-space-game-asp, run the following az appservice plan create command.

    az appservice plan create \
      --name tailspin-space-game-asp \
      --resource-group tailspin-space-game-rg \
      --sku B1 \
      --is-linux
    

    The --sku argument specifies the B1 plan. This plan runs on the Basic tier. The --is-linux argument specifies to use Linux workers.

    Important

    If the B1 SKU isn't available in your Azure subscription, select a different plan, such as S1 (Standard).

  4. To create the three App Service instances, one for each environment (Dev, Test, and Staging), run the following az webapp create commands.

    az webapp create \
      --name tailspin-space-game-web-dev-$webappsuffix \
      --resource-group tailspin-space-game-rg \
      --plan tailspin-space-game-asp \
      --runtime "DOTNET|5.0"
    
    az webapp create \
      --name tailspin-space-game-web-test-$webappsuffix \
      --resource-group tailspin-space-game-rg \
      --plan tailspin-space-game-asp \
      --runtime "DOTNET|5.0"
    
    az webapp create \
      --name tailspin-space-game-web-staging-$webappsuffix \
      --resource-group tailspin-space-game-rg \
      --plan tailspin-space-game-asp \
      --runtime "DOTNET|5.0"
    

    For learning purposes, here, you apply the same App Service plan, B1 Basic, to each App Service instance. In practice, you would assign a plan that matches your expected workload.

    For example, for the environments that map to the Dev and Test stages, B1 Basic might be appropriate because you want only your team to access the environments.

    For the Staging environment, you would select a plan that matches your production environment. That plan would likely provide greater CPU, memory, and storage resources. Under the plan, you can run performance tests, like load tests, in an environment that resembles your production environment. You can run the tests without affecting live traffic to your site.

  5. To list the host name and state of each App Service instance, run the following az webapp list command.

    az webapp list \
      --resource-group tailspin-space-game-rg \
      --query "[].{hostName: defaultHostName, state: state}" \
      --output table
    

    Note the host name for each running service. You'll need the host names later when you verify your work. Here's an example:

    HostName                                                 State
    -------------------------------------------------------  -------
    tailspin-space-game-web-dev-21017.azurewebsites.net      Running
    tailspin-space-game-web-test-21017.azurewebsites.net     Running
    tailspin-space-game-web-staging-21017.azurewebsites.net  Running
    
  6. As an optional step, go to one or more of the host names. Verify that they're running, and that the default home page appears.

    Here's what you see:

    A screenshot of a web browser showing the default home page on Azure App Service.

Important

The Clean up your Azure DevOps environment page in this module contains important cleanup steps. Cleaning up helps ensure that you're not charged for Azure resources after you complete this module. Be sure to perform the cleanup steps even if you don't complete this module.

Create pipeline variables in Azure Pipelines

In Create a release pipeline with Azure Pipelines, you added a variable to your pipeline that stores the name of your web app in App Service. Here you do the same. But this time, you add one variable for each App Service instance that corresponds to a Dev, Test, or Staging stage in your pipeline.

You could hard-code these names in your pipeline configuration, but if you define them as variables, your configuration will be more reusable. Additionally, if the names of your App Service instances change, you can update the variables and trigger your pipeline without modifying your configuration.

To add the variables:

  1. In Azure DevOps, go to your Space Game - web - Multistage project.

  2. Under Pipelines, select Library.

    A screenshot of Azure Pipelines showing the location of the Library menu option.

  3. Select + Variable group.

  4. Under Properties, enter Release for the variable group name.

  5. Under Variables, select + Add.

  6. For the name of your variable, enter WebAppNameDev. For the value, enter the name of the App Service instance that corresponds to your Dev environment, such as tailspin-space-game-web-dev-1234.

  7. Repeat the previous two steps twice more to create variables for your Test and Staging environments. Here are examples:

    Variable name Example value
    WebAppNameTest tailspin-space-game-web-test-1234
    WebAppNameStaging tailspin-space-game-web-staging-1234

    Be sure to replace each example value with the App Service instance that corresponds to your environment.

    Important

    Set the name of the App Service instance, not its host name. In this example, you would enter tailspin-space-game-web-dev-1234 and not tailspin-space-game-web-dev-1234.azurewebsites.net.

  8. Near the top of the page, to save your variable to the pipeline, select Save.

    Your variable group resembles this one:

    A screenshot of Azure Pipelines showing the variable group. The group contains three variables.

Create the dev and test environments

In Create a release pipeline with Azure Pipelines, you created an environment for the dev environment. Here, you'll repeat the process for both the dev and test environments. Later, you'll set up the staging environment, which includes additional criteria.

To create the dev and test environments:

  1. From Azure Pipelines, select Environments.

    A screenshot of Azure Pipelines showing the location of the Environments menu option.

  2. To create the dev environment:

    1. Select Create environment.
    2. Under Name, enter dev.
    3. Leave the remaining fields at their default values.
    4. Select Create.
  3. To create the test environment:

    1. Return to the Environments page.
    2. Select New environment.
    3. Under Name, enter test.
    4. Select Create.

Create a service connection

Here, you create a service connection that enables Azure Pipelines to access your Azure subscription. Azure Pipelines uses this service connection to deploy the website to App Service. You created a similar service connection in the previous module.

Important

Make sure that you're signed in to both the Azure portal and Azure DevOps under the same Microsoft account.

  1. In Azure DevOps, go to your Space Game - web - Multistage project.

  2. From the bottom corner of the page, select Project settings.

  3. Under Pipelines, select Service connections.

  4. Select New service connection, then select Azure Resource Manager, and then select Next.

  5. Near the top of the page, Service principal (automatic). Then, select Next.

  6. Fill in these fields:

    Field Value
    Scope level Subscription
    Subscription Your Azure subscription
    Resource Group tailspin-space-game-rg
    Service connection name Resource Manager - Tailspin - Space Game

    During the process, you might be prompted to sign in to your Microsoft account.

  7. Ensure you have selected Grant access permission to all pipelines.

  8. Select Save.

    To verify that it can connect to your Azure subscription, Azure DevOps performs a test connection. If Azure DevOps can't connect, you have the chance to sign in a second time.