You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Azure Cloud Shell is a browser-based shell environment which enables Azure customers to manage and configure their Azure services. It provides a [host of tools](https://docs.microsoft.com/azure/cloud-shell/features), including Azure CLI, Azure PowerShell, Ansible, Terraform, Puppet Bolt, kubectl, and many more.
4
+
Azure Cloud Shell is an interactive, authenticated, browser-accessible shell for managing Azure
5
+
resources. As a web-based environment, Cloud Shell provides immediate management access to any
6
+
device with a network connection. Azure Cloud Shell provides a
7
+
[host of tools](https://docs.microsoft.com/azure/cloud-shell/features), including Azure CLI, Azure
8
+
PowerShell, Ansible, Terraform, Puppet Bolt, kubectl, and many more.
5
9
6
-
For more details, check out [Overview of Azure Cloud Shell](https://docs.microsoft.com/azure/cloud-shell/overview#:~:text=Features%201%20Browser-based%20shell%20experience.%20...%202%20Choice,7%20Connect%20your%20Microsoft%20Azure%20Files%20storage.%20).
10
+
For more details, check out
11
+
[Overview of Azure Cloud Shell](https://docs.microsoft.com/azure/cloud-shell/overview).
7
12
13
+
## Roadmap of planned development
8
14
9
-
# About this repository
15
+
Azure Cloud Shell is continually working with customers to improve Azure resource management by
16
+
focusing on the experience and tools most needed by our customers. We invite everyone to view and
17
+
provide feedback to our [roadmap](./roadmap/cs-roadmap-2023.md) and future investigations. The Azure
18
+
Cloud Shell team respects and enjoys engaging with our customers, please share our
19
+
[roadmap](./roadmap/cs-roadmap-2023.md) and provide feedback here in
20
+
[Discussions](https://github.com/Azure/CloudShell/discussions) or
When you connect to Azure Cloud Shell, we start a container containing a wide variety of tools, and connect your
12
-
browser to a shell process running inside that container. This repository contains the Docker files used to build that image.
13
-
It does _not_ contain all of the code used for the rest of the Azure Cloud Shell service. The code in this repository may not
14
-
match exactly to what is running in the Cloud Shell service at any given time. The service is updated periodically and changes
15
-
are gradually rolled out to different regions over time, so there may be a lag of up to 3-4 weeks between a change being made
16
-
here and being reflected in all Cloud Shell regions.
23
+
## About this repository
24
+
25
+
When you connect to Azure Cloud Shell, we start a container hosting a wide variety of tools, and
26
+
27
+
connect your browser to a shell process running inside that container. This repository contains the
28
+
Docker files used to build that container image. It does _not_ contain the code used for the rest of
29
+
30
+
the Azure Cloud Shell service. The code in this repository may not match exactly to what is running
31
+
in the Cloud Shell service at any given time. The service is updated periodically and changes are
32
+
gradually rolled out to different regions over time.
33
+
There may be a lag of up to 3-4 weeks
34
+
for changes made here to be reflected in all Cloud Shell regions.
17
35
18
36
This repository has several uses:
19
37
20
-
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.
38
+
1.**Running the Cloud Shell image locally**. If you want a curated set of up-to-date command-line
39
+
tools suitable for managing an Azure environment, but you want to run the tools locally on your
40
+
own computer instead of in Cloud Shell, you can build the image and run it yourself.
21
41
22
-
1.**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.
42
+
1.**Contributing to Cloud Shell.** If you would like to propose a new tool for inclusion in Cloud
43
+
Shell, you can create an issue or submit a Pull Request to request the tool be added. Please
44
+
ensure that the PR actually builds within GitHub Actions.
23
45
24
-
The repository does *not* provide an out-of-the-box replacement for the Cloud Shell service. In addition to the container image here, Azure Cloud Shell consists of a user interface integrated into the portal, a web service which 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 websocket.
46
+
The repository does _not_ provide an out-of-the-box replacement for the Azure Cloud Shell service.
47
+
Azure Cloud Shell provide a user interface integrated into the Azure portal, a web service that
48
+
manages the infrastructure on which the containers run, and some additional code used inside the
49
+
container to connect the shell process to the user interface via a websocket.
25
50
26
51
## Running the Cloud Shell image locally
27
52
28
53
### Differences between running locally and in Cloud Shell
29
54
30
-
1.**No identity endpoint**. In Cloud Shell, we provide a way to automatically obtain tokens for the user connected to the shell.
31
-
We can't provide this when you run locally, so you have to authenticate explicitly before you can access Azure resources.
32
-
When using AZ CLI, run `az login`; for PowerShell, run `Connect-AzAccount`.
33
-
34
-
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.
35
-
36
-
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.
55
+
1.**No identity endpoint**. In Cloud Shell, we provide a way to automatically obtain tokens for the
56
+
user connected to the shell. We can't provide this when you run locally, so you have to
57
+
authenticate explicitly before you can access Azure resources. When using AZ CLI, run `az login`;
58
+
for PowerShell, run `Connect-AzAccount`.
37
59
38
-
# Contributing to Cloud Shell
60
+
1.**No cloud drive**. We don't mount the Cloud Drive from your Azure Cloud Shell, so you won't have
61
+
access to files stored there.
39
62
63
+
1.**Root instead of cloud shell user**. In Azure Cloud Shell you always run as a regular user. When
64
+
running the image locally, you run as root.
40
65
41
-
## Understanding the base.Dockerfile and tools.Dockerfile
66
+
###Understanding the base.Dockerfile and tools.Dockerfile
42
67
43
-
The repository contains two Dockerfile, 'base' and 'tools'. Tools is built on top of the base file, so normally you would
44
-
just have one Dockerfile and rely on the container registry to cache all the layers that haven't changed. However we need
45
-
to cache the base image explicitly to ensure fast startup time. So the image is split into these two files, and the tools
46
-
layer starts FROM an internal repository where the base image is cached, so that we know when we need to update the base.
68
+
The repository contains two Docker configuration files: `base` and `tools`. Normally you just have
69
+
one Dockerfile and rely on the container registry to cache the layers that haven't changed.
70
+
However, we need to cache the base image explicitly to ensure a fast startup time. Tools is built
71
+
on top of the base file and starts from an internal repository where the base image is cached, so
72
+
that we know when we need to update the base.
47
73
48
-
When building or using the image locally, you don't need to worry about that. Just build using the instructions below, and be
49
-
aware that changes the the base layer will take longer to release than changes to the tools.
74
+
When building or using the image locally, you don't need to worry about that. Just build using the
75
+
instructions below, and be aware that changes to the base layer will take longer to release than
76
+
changes to the tools.
50
77
51
78
| Layer | Job |
52
79
| ---|---|
@@ -55,41 +82,48 @@ aware that changes the the base layer will take longer to release than changes t
55
82
56
83
## Building and Testing the image
57
84
58
-
### Required software
85
+
Required software
59
86
60
-
* Docker
61
-
* Bash terminal / Powershell
87
+
- Docker
88
+
- Bash terminal / Powershell
89
+
90
+
Building base.Dockerfile image from the root repository
docker run --volume /path/to/CloudShell/folder/tests:/tests -it tools_cloudshell /tests/test.sh
86
118
```
87
119
88
-
For more information about bind mounts, please go onto the [Docker documentation](https://docs.docker.com/storage/bind-mounts/). We do expect all the test cases to pass if you would like your changes to be merged.
120
+
For more information about bind mounts, please see the
121
+
[Docker documentation](https://docs.docker.com/storage/bind-mounts/). We do expect all test cases
122
+
to pass if you want your changes to be merged.
89
123
90
-
# Contribution Guidelines
124
+
##Contribution Guidelines
91
125
92
-
## Types of issues
126
+
###Types of issues
93
127
94
128
| Issue Type | Action |
95
129
| ---|---|
@@ -99,16 +133,21 @@ For more information about bind mounts, please go onto the [Docker documentation
99
133
| Issue with one of the packages*| Talk to package owner & create a PR on their repo. |
100
134
| Issue with how package interacts with Cloud Shell | Create a Pull Request OR GitHub Issue |
101
135
| Security bug | See https://www.microsoft.com/en-us/msrc/faqs-report-an-issue|
102
-
| Issue with Cloud Shell in Azure Portal (can't log in, for example) | Open a [support ticket](https://docs.microsoft.com/azure/active-directory/fundamentals/active-directory-troubleshooting-support-howto#:~:text=How%20to%20open%20a%20support%20ticket%20for%20Azure,Troubleshooting%20%2B%20Support%20and%20select%20New%20support%20request.)|
136
+
| Issue with Cloud Shell in Azure Portal (can't log in, for example) | Open a [support ticket](https://learn.microsoft.com/azure/active-directory/fundamentals/how-to-get-support)|
103
137
104
-
\* For example, if you have an issue within Azure CLI, don't open up an issue with the Cloud Shell repo, open an issue within the Azure CLI repo.
105
-
Azure PowerShell is [here](https://github.com/Azure/azure-powershell/issues) and Azure CLI is [here](https://github.com/Azure/azure-cli/issues)
106
138
107
-
## Types of tools
139
+
<sup>*</sup> For example, if you have an issue within Azure CLI, don't open up an issue in the Cloud Shell
140
+
repo, open an issue within the Azure CLI repo.
108
141
109
-
Cloud Shell aims to provide a core set of tools for Azure and Microsoft 365 devops scenarios, but we can't include everything.
110
-
If you just want to use a tool yourself, you can install most utilities into your own home directory inside Cloud Shell.
111
-
You only need to update the image if you want _every_ Cloud Shell admin to have the tool available.
Cloud Shell aims to provide a core set of tools for Azure and Microsoft 365 devops scenarios, but we
148
+
can't include everything. If you just want to use a tool yourself, you can install most utilities
149
+
into your own home directory inside Cloud Shell. You only need to update the image if you want
150
+
_every_ Cloud Shell admin to have the tool available.
112
151
113
152
For a tool to be included in Cloud Shell, it has to be:
114
153
@@ -118,37 +157,47 @@ For a tool to be included in Cloud Shell, it has to be:
118
157
- lightweight in terms of CPU requirements, size on disk, and memory
119
158
120
159
Please:
160
+
121
161
- support fetching tokens from Managed Identity if a tool authenticates to Azure services
122
162
- add basic tests to the test suite run by GitHub Actions
123
163
- consume the tools from the [Mariner package repo](https://packages.microsoft.com/cbl-mariner/2.0/)
124
164
125
165
In general we avoid:
126
-
- alpha, beta, preview or unstable versions of software.
127
-
- tools primarily useful for extensive software development, as opposed to DevOps. Consider [Visual Studio Codespaces](https://visualstudio.microsoft.com/services/visual-studio-codespaces/) for that.
166
+
167
+
- alpha, beta, preview or unstable versions of software.
168
+
- tools primarily useful for extensive software development, as opposed to DevOps. Consider
169
+
[Visual Studio Codespaces](https://visualstudio.microsoft.com/services/visual-studio-codespaces/)
170
+
for that.
128
171
129
172
## Cloud Shell Documentation
130
173
131
-
Please see the [Microsoft Azure Documentation](https://github.com/MicrosoftDocs/azure-docs) for a guide to add to the Azure docs repo.
132
-
The Cloud Shell documentation can be found [here](https://github.com/MicrosoftDocs/azure-docs/tree/master/articles/cloud-shell).
0 commit comments