Migrate to Azure Blob Storage

Note

HCP Vagrant is being deprecated. Customers using Vagrant boxes hosted on the HCP Vagrant registry must find a new provider and re-host their boxes. As of October 1, 2026, new boxes can no longer be created in HCP Vagrant. Existing box deployments will continue to operate until the end of operations date of December 31, 2026. After that time, all deployments will be decommissioned.

This guide describes the process of moving your Vagrant boxes from HCP Vagrant Registry to Azure Blob Storage and referencing them from a Vagrantfile. You will learn to create a storage account using the Microsoft Azure command line interface (CLI), add a container, upload your boxes to the container, and optionally serve your boxes publicly.

Overview

Azure Blob Storage organizes data in a hierarchy. At the top sits a storage account, which can hold many containers. Each container, in turn, can hold virtually any number of blobs, such as your vagrant.box files. In this guide, you create a single storage account, add one container to it, and upload your boxes into that container as blobs.

Cost considerations

Azure Blob Storage is a paid service. Review the Azure Blob Storage pricing page to understand the charges you may incur. To estimate your costs, use the Azure pricing calculator.

Prerequisites

To follow this guide, you need:

The Azure CLI installed.
An Azure account.

Download your boxes

You need each box's vagrant.box file on your local machine before you can move it to Azure Blob Storage. A box stores a separate file for each version, provider, and architecture, so download each one you want to migrate.

Download from the registry UI

You can download boxes from the HCP Vagrant Registry web UI. Public boxes are on the Discover page. Private boxes are in your registry in the HCP portal.

Open a box, then click the download button for each provider and architecture to save its vagrant.box file.

Download from the command line

You can download boxes using the command line. The process is the same for public and private boxes, except that a private box requires an HCP access token.

Request a box's download URL from the HCP Vagrant Registry API. Replace each path segment with your registry, box, version, provider, and architecture:

$ curl "https://api.cloud.hashicorp.com/vagrant/2022-09-30/registry/REGISTRY/box/BOX_NAME/version/VERSION/provider/PROVIDER/architecture/ARCHITECTURE/download"

For a private box, generate an HCP access token from a service principal's client ID and secret by following the steps in Generate an HCP access token, then pass it as a bearer token:

$ curl --header "Authorization: Bearer $(hcp auth print-access-token)" \
    "https://api.cloud.hashicorp.com/vagrant/2022-09-30/registry/REGISTRY/box/BOX_NAME/version/VERSION/provider/PROVIDER/architecture/ARCHITECTURE/download"

The request returns a url field. Download the box from that URL:

$ curl -L -o vagrant.box "DOWNLOAD_URL"

Log in

$ az login

The login command supports many additional options, such as service principal and managed identity authentication. Refer to the az login reference for the full list.

Create a resource group

A storage account needs a resource group to live in, so create one first. Set the --location value to a region near you or your users, such as eastus:

$ az group create --name GROUP_NAME --location LOCATION

To see the regions available to your account, list them first:

$ az account list-locations --output table

Create a storage account

Create a storage account inside the resource group:

$ az storage account create --name ACCOUNT_NAME --resource-group GROUP_NAME --location LOCATION --sku Standard_LRS

Storage account names must be globally unique across all of Azure and can contain only lowercase letters and numbers. The --sku value sets the redundancy option; for instance, Standard_LRS maintains three copies of the data within a single region. For more information, refer to az storage account create in the Azure documentation.

Create a container

Create a container in your storage account to hold the boxes:

$ az storage container create --name CONTAINER_NAME --account-name ACCOUNT_NAME

For more information, refer to az storage container create in the Azure documentation.

Upload a box

Upload a box to the container:

$ az storage blob upload --account-name ACCOUNT_NAME --container-name CONTAINER_NAME --name PATH_WITHIN_CONTAINER --file PATH_TO_BOX_ON_LOCAL_MACHINE

We recommend using a --name that follows the format BOX_NAME/VERSION/PROVIDER/ARCHITECTURE/vagrant.box to keep your boxes organized by version, provider, and architecture.

For more information, refer to az storage blob upload in the Azure documentation.

Make the container public

Containers are private by default. To let Vagrant download boxes without authentication, you need to open up public access at two levels: on the storage account, and then on the container within it.

Allow public access at the storage account level:

$ az storage account update --name ACCOUNT_NAME --resource-group GROUP_NAME --allow-blob-public-access true

Set the container's public access level to blob. The blob level grants public read access to individual blobs while keeping the container listing private:

$ az storage container set-permission --name CONTAINER_NAME --account-name ACCOUNT_NAME --public-access blob

For more information, refer to az storage container set-permission in the Azure documentation.

Warning

A public container allows anyone to download its blobs. Only make a container public if everything it contains is safe to distribute publicly. Every public download also incurs data transfer charges on your account, so a widely shared or high-traffic box can lead to unexpected costs.

Reference a box from a public container

For a public container, reference the blob URL in your Vagrantfile with config.vm.box_url:

Vagrant.configure("2") do |config|
  config.vm.box = "BOX_NAME"
  config.vm.box_url = "https://STORAGE_ACCOUNT_NAME.blob.core.windows.net/CONTAINER_NAME/NAME"
end

Reference a box from a private container

Vagrant cannot download boxes from a private container. To use a box stored in a private container, download it, then add the locally stored box to Vagrant.

Download the box blob from the container, passing the blob's --name and the local file name to save it as:

$ az storage blob download --account-name ACCOUNT_NAME --container-name CONTAINER_NAME --name NAME --file LOCAL_FILE

For more information, refer to az storage blob download in the Azure documentation.

Add the downloaded box to Vagrant under a name of your choice:

$ vagrant box add BOX_NAME LOCATION

LOCATION is the path to the box file you downloaded. For more options, refer to vagrant box add.

After you add the box, reference it directly in your Vagrantfile by name:

Vagrant.configure("2") do |config|
  config.vm.box = "BOX_NAME"
end