Running Azure Cloud Shell locally using Docker

/ Harm Veenstra

Azure Cloud Shell is a tool I use often and is easy to access from the Admin pages in Azure and 365. You can also use those tools in a local container and connect to it using the command line or Visual Studio Code. In this blog post, I will show you how to install everything and connect and use it locally.

Table Of Contents
show

What is Azure Cloud Shell?

“Azure Cloud Shell is an interactive, authenticated, browser-accessible terminal for managing Azure resources. It provides the flexibility of choosing the shell experience that best suits the way you work, either Bash or PowerShell.”

Source: https://learn.microsoft.com/en-us/azure/cloud-shell/overview

It’s an instance that contains all the tools that you need to manage your environment. The complete list of features and tools can be found here.

Running Azure Cloud Shell locally

Why?

Why not 🙂 No, seriously… There are pros and cons:

Pros:

  • It is easy to have all the tools available, like those listed in the link here, and you can reuse the container you build on another system.
  • Microsoft maintains and updates it; you don’t have to find, install, and update all the tools locally.

Cons:

  • It’s a Linux container. While this doesn’t have to be an issue, it might be when you use cmdlets that are only available on Windows (I’m thinking about building a Windows Server Core Docker container for that in the future)

Prerequisites

To run it locally, you need to install the following things mentioned below (I’m running Windows 11 on my system, but on Mac or Linux, you might need other installation steps, and you can skip the WSL installation)

Windows Subsystem for Linux

The Docker installation will use WSL2, which must be installed on your system. To install it, you can use this command in an Admin command prompt: (This might need a reboot of your system afterward)

wsl --install

(More information about installing WSL can be found here.)

Docker

The container for Azure Cloud Shell will run on your local system in Docker. To install Docker on your system, you can follow these steps:

  • Download the Docker Desktop installer here
  • Start the installation and make sure “Use WSL 2 instead of Hyper-V (recommended)” is selected
  • Select “Close and restart“

After restarting, the ‘Docker Subscription Service Agreement‘ will appear, and select Accept. It will also ask to use recommended settings (Requires administrator password), select that, and select Finish to complete the installation. Afterward, it will prompt you to sign in to Docker desktop or sign up; you can either do that or select Continue without signing in. Complete the survey or choose Skip survey. (The survey has only two questions. I have seen longer ones 😉 )

You will now see the Docker desktop application; if there is an update to the installation, it will show that in the bottom right. (Select the notification and select Download update to update and follow the steps)

Note:

A Windows Subsystem for Linux prompt might ask you to update to the latest version. Press any key to start the update if that’s the case. (Requires Elevation)

Git

To create the Docker container, you need to clone a repository to your system. The easiest way to do that is to use Git. You can install the Git command-line tools using the following steps:

  • Download the installer here
  • Start the installation
  • Select Next
  • Select Next (Or change the installation folder using Browse)
  • Select Next to keep the default component options, or select more if needed.
  • Select Next to create a Git folder in your Start Menu, or ‘Don’t create a Start Menu folder.’
  • Select Next to keep VIM as the default editor, or select one from the dropdown list.
  • Select Next to Let Git decide the name of the initial branch in new repositories or override the name if needed.
  • Select Next to use Git from the command line and also from 3rd-party software (Recommended)
  • Select Next to use the OpenSSL library or the native Windows Secure Channel library if needed.
  • Select Next to use Checkout Windows-Style, or select Checkout as-is or Checkout as-is/commit as-is.
  • Select Next to use MinTTY or Use the Windows’default console window.
  • Select Next to use Fast-forward or merge, or Rebabase or Only ever fast-forward if needed.
  • Select Next to use Git Credential Manager of None if needed
  • Select Next to use file system caching and Enable symbolic links if needed
  • Select Install to complete the wizard, Enable experimental support for pseudo consoles, or Enable experimental built-in file system monitor if needed.
  • Select Finish to close the installation, and the Release Notes will be shown afterward.

Docker container

Downloading the container

You can download the latest version of the container by running docker pull mcr.microsoft.com/azure-cloudshell in a command prompt. (This will take a while, depending on your internet speed)

Building the container yourself

To build the docker container, you must first clone the https://github.com/Azure/CloudShell repository to your system. You can follow these steps to do that:

  • Start an Administrative command prompt.
  • Change the directory to where you want to clone the repository; in this example, I will clone it to my c:\users\HarmVeenstra folder.
  • Run “git clone https://github.com/Azure/CloudShell.git”

From the same command prompt you started in the chapter above, use the following steps:

  • Run ‘cd CloudShell” to change the directory to the cloned Repository.
  • Run ‘docker build -t base_cloudshell -f linux/base.Dockerfile .‘ to start building the base image, it will take some time to run all the 25 steps. On my test system, it took 13 minutes (8vCPU/32Gb Cloud PC 🙂 )

Now that the base container is done, which is updated every 3 or 4 months, we can build the tools image, which is updated more frequently (Every 2 or 3 weeks). You can do that by following these steps:

  • Run ‘docker build -t tools_cloudshell –build-arg IMAGE_LOCATION=base_cloudshell -f linux/tools.Dockerfile .‘ to start the build. This build is faster, but it still took 6 minutes on my system.

Using the Docker container

Command-Line

Like Azure Cloud Shell, you can connect to the container using Docker in Bash or PowerShell mode.

To use the Bash prompt, you can run this from a command prompt:

docker run -it tools_cloudshell /bin/bash

To use the PowerShell prompt, you can run this from a command prompt:

docker run -it tools_cloudshell /usr/bin/pwsh

You can use the same commands, cmdlets, tools, etc, as in your Azure Cloud Shell session. Replace tools_cloudshell with mcr.microsoft.com/azure-cloudshell if you downloaded the Docker container.

Visual Studio Code

You can connect the Docker container from within Visual Studio Code. To do that, you should install the Docker extension. You can find it in the Extensions pane on the left. Search for Docker and select Install.

After installation, you can select the Docker Extension on the left. You should see both your images (Base and Tools) if you have build the images yourself or the azure-cloudshell container if you downloaded it:

Right-click the tools_cloudshell image, for example, and select Run to start it or Run Interactive to attach a terminal process. In this example, I chose Run to start it in the background.

The container will be started and shown in the upper pane. Right-click it and select Attach Visual Studio Code:

A new Visual Studio Code screen will be opened, and you will see the Starting Dev Container at the bottom right.

You can now select Open Folder or Clone Repository. In this example, I chose Open Folder, but you can use Clone Repository to download your files from a GitHub repository in the docker container. The container was opened as Root and will show its home folder, like the screenshot below, as default. Select OK to open that folder or Show Local to show the contents of your local drive. (I chose OK and opened the Root home folder.)

After opening that folder, you can select the left + icon to create a file.

I created a test.ps1 file and it will prompt you to install the PowerShell extension for that in the bottom right:

After installing that, you can open, edit, and run scripts using the Azure Cloud Shell tools and modules in your local Docker container.

You can run commands from the Terminal tab, too, of course, and things like the AZ commands will work there just like in Azure Cloud Shell:

Wrapping up

I showed you how to install the required software components, build the images, run the container interactively from a terminal, and use it in Visual Studio Code. I’m no expert in Docker yet, but I see the benefits of using this as a coding solution where you don’t have to find and install everything yourself. (It’s an excellent starter kit 🙂 )