Microsoft Azure Cloud Shell Image

Azure Cloud Shell is an interactive, authenticated, browser-accessible shell for managing Azure resources. As a web-based environment, Cloud Shell provides immediate management access to any device with a network connection. Azure Cloud Shell provides a host of tools, including Azure CLI, Azure PowerShell, Ansible, Terraform, kubectl, and many more.

For more details, check out Overview of Azure Cloud Shell.

Roadmap of planned development

Azure Cloud Shell is continually working with customers to improve Azure resource management by focusing on the experience and tools most needed by our customers. We invite everyone to view and provide feedback to our roadmap and future investigations. The Azure Cloud Shell team respects and enjoys engaging with our customers, please share our roadmap and provide feedback here in Discussions or Issues.

About this repository

When you connect to Azure Cloud Shell, we start a container hosting a wide variety of tools, and connect your browser to a shell process running inside that container. This repository contains the Docker files used to build that container image. It does not contain the code used for the rest of the Azure Cloud Shell service. The code in this repository may not match exactly to what is running in the Cloud Shell service at any given time. The service is updated periodically and changes are gradually rolled out to different regions over time. There may be a lag of up to 3-4 weeks for changes made here to be reflected in all Cloud Shell regions.

This repository has several uses:

1. Running the Cloud Shell image locally. If you want a curated set of up-to-date command-line tools suitable for managing an Azure environment, but you want to run the tools locally on your own computer instead of in Cloud Shell, you can build the image and run it yourself.

2. Contributing to Cloud Shell. If you would like to propose a new tool for inclusion in Cloud Shell, you can create an issue or submit a Pull Request to request the tool be added. Please ensure that the PR actually builds within GitHub Actions.

The repository does not provide an out-of-the-box replacement for the Azure Cloud Shell service. Azure Cloud Shell provide a user interface integrated into the Azure portal, a web service that manages the infrastructure on which the containers run, and some additional code used inside the container to connect the shell process to the user interface via a websocket.

Running the Cloud Shell image locally

Differences between running locally and in Cloud Shell

1. No identity endpoint. In Cloud Shell, we provide a way to automatically obtain tokens for the user connected to the shell. We can't provide this when you run locally, so you have to authenticate explicitly before you can access Azure resources. When using AZ CLI, run az login; for PowerShell, run Connect-AzAccount.

2. No cloud drive. We don't mount the Cloud Drive from your Azure Cloud Shell, so you won't have access to files stored there.

3. Root instead of cloud shell user. In Azure Cloud Shell you always run as a regular user. When running the image locally, you run as root.

Understanding the base.Dockerfile and tools.Dockerfile

The repository contains two Docker configuration files: base and tools. Normally you just have one Dockerfile and rely on the container registry to cache the layers that haven't changed. However, we need to cache the base image explicitly to ensure a fast startup time. Tools is built on top of the base file and starts from an internal repository where the base image is cached, so that we know when we need to update the base.

When building or using the image locally, you don't need to worry about that. Just build using the instructions below, and be aware that changes to the base layer will take longer to release than changes to the tools.

Layer	Job
Base	Contains large, infrequently changing packages. Changes every 3-4 months.
Tools	Contains frequently changing packages. Changes every 2-3 weeks

Building and Testing the image

Building the images

Required software:

• Docker
• Bash terminal / Powershell

Building base.Dockerfile image from the root repository

docker build \
   -t base_cloudshell \
   -f linux/base.Dockerfile .

Building tools.Dockerfile image

docker build \
   -t tools_cloudshell \
   --build-arg IMAGE_LOCATION=base_cloudshell \
   -f linux/tools.Dockerfile .

Testing the images

Running bash in the tools.Dockerfile based image:

docker run -it tools_cloudshell /bin/bash

Running pwsh in the tools.Dockerfile based image:

docker run -it tools_cloudshell /usr/bin/pwsh

Testing the Cloud Shell image:

docker run \
   --volume $(pwd)/tests:/tests \
   -it tools_cloudshell \
   /tests/test.sh

For more information about bind mounts, please see the Docker documentation. We do expect all test cases to pass if you want your changes to be merged.

Contribution Guidelines

Types of issues

Issue Type	Action
Package is out of date	Create a Pull Request or Issue
Add a package to my Cloud Shell	Follow Cloud Shell package addition
Add a package to everyone's Cloud Shell	Follow Package Inclusion Guide
New desired Cloud Shell feature	Create an Discussion
Issue with one of the packages*	Talk to package owner & create a PR on their repo.
Issue with how package interacts with Cloud Shell	Create a Pull Request OR GitHub Issue
Security bug	See https://www.microsoft.com/en-us/msrc/faqs-report-an-issue
Issue with Cloud Shell in Azure Portal (can't log in, for example)	Open a support ticket

For example, if you have an issue within Azure CLI, don't open up an issue in the Cloud Shell repo, open an issue within the Azure CLI repo.

• Azure PowerShell issues
• Azure CLI issues

Cloud Shell Documentation

The Cloud Shell documentation can be found at https://learn.microsoft.com/azure/cloud-shell/overview. If you wish to contribute to The Cloud Shell documentation, see the Microsoft Learn Contributors Guide.

Legal

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, see https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.