Edit

Persist files in Azure Cloud Shell

The first time you start Cloud Shell, you're prompted to select your storage options. If you want store files that can be used every time you use Cloud Shell, you must create new or choose existing storage resources. Cloud Shell uses a Microsoft Azure Files share to persist files across sessions.

How Cloud Shell storage works

Cloud Shell persists files through both of the following methods:

  • Creates a disk image to contain the contents of your $HOME directory. The disk image is saved to https://storageaccountname.file.core.windows.net/filesharename/.cloudconsole/acc_user.img. Cloud Shell automatically syncs changes to this disk image.
  • Mounts the file share as clouddrive in your $HOME directory. /home/<User>/clouddrive path is mapped to storageaccountname.file.core.windows.net/filesharename.

Note

All files in your $HOME directory, such as SSH keys, are persisted in your user disk image, which is stored in the mounted file share. Use best practices to secure the information in your $HOME directory and mounted file share.

Supported storage regions

Cloud Shell runs session machines in a set of primary regions. You can store persistent files in a storage account located in a primary region or a supported secondary region, as listed in the following table.

Your session generally runs in the primary region associated with your storage account. If you use a secondary storage region or use ephemeral sessions, Cloud Shell selects the primary region nearest to you. Placement depends on available capacity, so a specific region isn't guaranteed.

Files remain at rest in your storage account's region but are processed in the primary region where your session runs. For example, files stored in Canada East remain at rest in Canada but are processed in the United States if your session runs in a US primary region.

Choose a primary region for your storage account unless you need to store your data at rest in a different region. Using a secondary storage region can make file access and Cloud Shell startup slower.

To find the region of your current Cloud Shell machine, run echo "$ACC_LOCATION" in Bash or $env:ACC_LOCATION in PowerShell.

Primary regions

Area Regions
US East US 2, South Central US, West Central US, West US 2
Europe France Central, Germany West Central, Sweden Central, West Europe
Asia Pacific Australia East, Australia Southeast, Central India, East Asia, South India, Southeast Asia

Secondary storage regions

Area Regions
Americas Brazil South, Canada Central, Canada East, Central US, East US, Mexico Central, North Central US, West US, West US 3
Europe North Europe, Norway East, Spain Central, Switzerland North, UK South, UK West
Asia Pacific Australia Central, Japan East, Japan West, Jio India West, Korea Central, Korea South, West India
Middle East and Africa Qatar Central, South Africa North, UAE North

Securing storage access

For security, each user should create their own storage account. For Azure role-based access control (RBAC), users must have contributor access or higher at the storage account level.

Cloud Shell uses an Azure file share in a storage account, inside a specified subscription. Due to inherited permissions, users with sufficient access rights in the subscription can access the storage accounts and file shares contained in the subscription.

Users should lock down access to their files by setting the permissions at the storage account or the subscription level.

The Cloud Shell storage account contains files created by the Cloud Shell user in their home directory, which might include sensitive information including access tokens or credentials.

Restrict resource creation with an Azure resource policy

Storage accounts that are created in Cloud Shell are tagged with ms-resource-usage:azure-cloud-shell. If you want to disallow users from creating storage accounts in Cloud Shell, create an Azure resource policy that's triggered by this specific tag.

Managing Cloud Shell storage

Mount a new clouddrive

If you have previously selected to use ephemeral sessions for Cloud Shell, then you must reset your preferences by selecting Settings > Reset User Settings in Cloud Shell. Follow the steps to mount an existing storage account or a new storage account.

Note

If you're mounting a new share, a new user image is created for your $HOME directory. Your previous $HOME image is kept in the previous file share.

Unmount clouddrive

You can unmount a Cloud Shell file share at any time. Since Cloud Shell requires a mounted file share to be used, Cloud Shell prompts you to create and mount another file share on the next session.

  1. Run clouddrive unmount.
  2. Acknowledge and confirm prompts.

The unmounted file share continues to exist until you manually delete it. After unmounting, Cloud Shell no longer searches for this file share in subsequent sessions. For more information, run clouddrive unmount -h,

Command
  clouddrive unmount: Unmount an Azure file share from Cloud Shell.

    Unmount enables unmounting and disassociating a file share from Cloud Shell.
    All current sessions will be terminated. Machine state and non-persisted files will be lost.
    You will be prompted to create and mount a new file share on your next session.
    Your previously mounted file share will continue to exist.

    Note: This command does not unmount storage if the session is Ephemeral.

Arguments
  None

Warning

Although running this command doesn't delete any resources, manually deleting a resource group, storage account, or file share that's mapped to Cloud Shell erases your $HOME directory disk image and any files in your file share. This action can't be undone.

Use PowerShell commands

Get information about the current file share

Use the Get-CloudDrive command in PowerShell to get information about the resources that back the file share.

PS /home/user> Get-CloudDrive

FileShareName      : cs-user-microsoft-com-xxxxxxxxxxxxxxx
FileSharePath      : //cs7xxxxxxxxxxxxxxx.file.core.windows.net/cs-user-microsoft-com-xxxxxxxxxxxxxxx
MountPoint         : /home/user/clouddrive
Name               : cs7xxxxxxxxxxxxxxx
ResourceGroupName  : cloud-shell-storage-southcentralus
StorageAccountName : cs7xxxxxxxxxxxxxxx
SubscriptionId     : aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e

Unmount the file share

You can unmount a Cloud Shell file share at any time using the Dismount-CloudDrive cmdlet. Dismounting the clouddrive terminates the current session.

Dismount-CloudDrive

Do you want to continue
Dismounting clouddrive will terminate your current session. You will be prompted to create and
mount a new file share on your next session
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"):

Next steps

  • Last updated on