Ruby client for the Vagrant Cloud API.
This library provides the functionality to create, modify, and delete boxes, versions, and providers on Vagrant Cloud.
The Vagrant Cloud library provides two methods for interacting with the Vagrant Cloud API. The
first is direct interaction using a VagrantCloud::Client instance. The second is a basic
model based approach using a VagrantCloud::Account instance.
The access token that is used for authenticated requests can be set in one of three ways:
- Static access token set directly in the client
- Static access token extracted from the
VAGRANT_CLOUD_TOKENenvironment variable - Generated HCP service principal access token when
HCP_CLIENT_IDandHCP_CLIENT_SECRETenvironment variables are set
The VagrantCloud::Client class contains all the underlying functionality which with
vagrant_cloud library uses for communicating with Vagrant Cloud. It can be used directly
for quickly and easily sending requests to Vagrant Cloud. The VagrantCloud::Client
class will automatically handle any configured authentication, request parameter
structuring, and response validation. All API related methods in the VagrantCloud::Client
class will return Hash results.
Example usage (display box details):
require "vagrant_cloud"
client = VagrantCloud::Client.new(access_token: "MY_TOKEN")
box = client.box_get(username: "hashicorp", name: "bionic64")
puts "Box: #{box[:tag]} Description: #{box[:description]}"Example usage (creating box and releasing a new version):
require "vagrant_cloud"
require "net/http"
# Create a new client
client = VagrantCloud::Client.new(access_token: "MY_TOKEN")
# Create a new box
client.box_create(
username: "hashicorp",
name: "test-bionic64",
short_description: "Test Box",
long_description: "Testing box for an example",
is_private: false
)
# Create a new version
client.box_version_create(
username: "hashicorp",
name: "test-bionic64",
version: "1.0.0",
description: "Version 1.0.0 release"
)
# Create a new provider
client.box_version_provider_create(
username: "hashicorp",
name: "test-bionic64",
version: "1.0.0",
provider: "virtualbox"
)
# Request box upload URL
upload_url = client.box_version_provider_upload(
username: "hashicorp",
name: "test-bionic64",
version: "1.0.0",
provider: "virtualbox"
)
# Upload box asset
uri = URI.parse(upload_url[:upload_path])
request = Net::HTTP::Post.new(uri)
box = File.open(BOX_PATH, "rb")
request.set_form([["file", box]], "multipart/form-data")
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme.eql?("https")) do |http|
http.request(request)
end
# Release the version
client.box_version_release(
username: "hashicorp",
name: "test-bionic64",
version: "1.0.0"
)The VagrantCloud::Account class is the entry point for using simple models to
interact with Vagrant Cloud.
Example usage (display box details):
require "vagrant_cloud"
account = VagrantCloud::Account.new(access_token: "MY_TOKEN")
org = account.organization(name: "hashicorp")
box = org.boxes.detect { |b| b.name == "bionic64" }
puts "Box: #{box[:tag]} Description: #{box[:description]}"Example usage (creating box and releasing a new version):
require "vagrant_cloud"
# Load our account
account = VagrantCloud::Account.new(access_token: "MY_TOKEN")
# Load organization
org = account.organization(name: "hashicorp")
# Create a new box
box = org.add_box("test-bionic64")
box.description = "Testing box for an example"
box.short_description = "Test Box"
# Create a new version
version = box.add_version("1.0.0")
version.description = "Version 1.0.0 release"
# Create a new provider
provider = version.add_provider("virtualbox")
# Save the box, version, and provider
box.save
# Upload box asset
provider.upload(path: BOX_PATH)
# Release the version
version.releasePull requests are very welcome!
Install dependencies:
bundle install
Run the tests:
bundle exec rspec
Release a new version:
- Update the version in the
version.txtfile - Commit the change to master
- Create a new version tag in git:
git tag vX.X.X - Push the new tag and master to GitHub
git push origin main --tags
The new release will be automatically built and published.
- This gem was developed and maintained by Cargo Media from April 2014 until October 2017.
- The
vagrant_cloudCLI tool included in this RubyGem has been deprecated and removed. Seevagrant cloudfor a replacement.