Migrate to IBM Cloud Object 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 IBM Cloud Object Storage and referencing them from a Vagrantfile. You will learn to create a service instance using the IBM Cloud command line interface (CLI) and its Cloud Object Storage plugin, add a bucket, upload your boxes to the bucket, and optionally serve your boxes publicly.

Overview

IBM Cloud Object Storage organizes data in a hierarchy. A service instance is the highest level of organization. Each instance can hold many buckets, and each bucket can hold virtually any number of objects, such as your vagrant.box files. In this guide, you create one service instance, add a bucket to it, and upload your boxes as objects.

Cost considerations

IBM Cloud Object Storage is a paid service, though it offers a free lite plan with limited capacity. Review the IBM Cloud Object Storage pricing page to understand the charges you may incur.

Prerequisites

To follow this guide, you need:

The IBM Cloud CLI installed.
An IBM Cloud account. This guide uses a free account, which supports the lite plan.

Download your boxes

You need each box's vagrant.box file on your local machine before you can move it to IBM Cloud Object 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 and target a region

$ ibmcloud login

Select a region either by passing -r REGION to the login command or by setting it afterward with ibmcloud target:

$ ibmcloud login -r REGION

$ ibmcloud target -r REGION

The login command supports many additional options, such as single sign-on and API key authentication. Refer to the IBM Cloud CLI getting started guide for the full list.

Target a resource group

Target the Default resource group:

$ ibmcloud target -g Default

To list the resource groups available to your account, run the following command:

$ ibmcloud resource groups

If you want to use a custom resource group instead of Default, refer to the IBM Cloud resource commands reference.

Install the Cloud Object Storage plugin

The IBM Cloud Object Storage plugin extends the CLI with an API wrapper for working with object storage resources. Install it with the following command:

$ ibmcloud plugin install cloud-object-storage

For more information, refer to the IBM Cloud Object Storage CLI documentation.

Create a Cloud Object Storage service instance

Create a service instance to hold your buckets:

$ ibmcloud resource service-instance-create INSTANCE_NAME cloud-object-storage PLAN global

To list the available plans, run the following command:

$ ibmcloud catalog service cloud-object-storage

A free account supports the lite plan. Other options include standard and onerate.

Create a bucket

Create a bucket in the service instance:

$ ibmcloud cos bucket-create --bucket BUCKET_NAME [--class CLASS_NAME] [--ibm-service-instance-id ID] [--region REGION] [--output FORMAT]

When you use IAM authentication, you must pass --ibm-service-instance-id. Retrieve the Cloud Resource Name (CRN) of the instance you created to use as this ID:

$ ibmcloud resource service-instance INSTANCE_NAME --crn

For more information, refer to Create a new bucket in the IBM Cloud documentation.

Upload a box

Upload a box to the bucket:

$ ibmcloud cos upload --bucket BUCKET_NAME --key PATH_WITHIN_BUCKET --file PATH_TO_BOX_ON_LOCAL_MACHINE

We recommend using a --key 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 Upload objects by using s3manager in the IBM Cloud documentation.

Make the bucket public

Buckets are private by default. To let Vagrant download boxes without authentication, make the bucket public by granting the Content Reader role to the public access group:

$ ibmcloud iam access-group-policy-create "Public Access" --roles "Content Reader" --service-name cloud-object-storage --service-instance INSTANCE_ID --resource-type bucket --resource BUCKET_NAME

For more information, refer to ibmcloud iam access-group-policy-create in the IBM Cloud documentation.

Warning

A public bucket allows anyone to download its objects. Only make a bucket 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 bucket

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

Vagrant.configure("2") do |config|
  config.vm.box = "BOX_NAME"
  config.vm.box_url = "https://BUCKET_NAME.s3.REGION.cloud-object-storage.appdomain.cloud/KEY"
end

Reference a box from a private bucket

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

Download the box object from the bucket, passing the object's --key and the local file name to save it as:

$ ibmcloud cos object-get --bucket BUCKET_NAME --key KEY LOCAL_FILE

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