Project

vagrant_cloud

0.03
A long-lived project that still receives updates
vagrant_cloudhashicorp/vagrant_cloudHomepageDocumentationSource CodeBug TrackerMailing List
Ruby library for the HashiCorp Vagrant Cloud API
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Popularity
Downloads
133,460
Stars
16
Forks
16
Watchers
11
 Releases
Current version
3.1.2
Total releases
25
First release
2014-04-03
Latest release
2024-11-11
 Issues
Open Issues
4
Closed Issues
14
Total Issues
18
Issue Closure Rate
77%
 Pull Requests
Open Pull Requests
0
Closed Pull Requests
5
Merged Pull Requests
67
Pull Request Acceptance Rate
93%
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2023-07-21
Reverse Dependencies
3

 Dependencies

Development

rake
~> 12.3
rspec
~> 3.0
webmock
~> 3.0

Runtime

excon
~> 1.0
log4r
~> 1.1
oauth2
~> 2.0
rexml
~> 3.3
 Project Readme

vagrant_cloud

Ruby client for the Vagrant Cloud API.

Gem Version

This library provides the functionality to create, modify, and delete boxes, versions, and providers on Vagrant Cloud.

Usage

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.

Authentication

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_TOKEN environment variable
  • Generated HCP service principal access token when HCP_CLIENT_ID and HCP_CLIENT_SECRET environment variables are set

Direct Client

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"
)

Simple Models

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.release

Development & Contributing

Pull requests are very welcome!

Install dependencies:

bundle install

Run the tests:

bundle exec rspec

Releasing

Release a new version:

  1. Update the version in the version.txt file
  2. Commit the change to master
  3. Create a new version tag in git: git tag vX.X.X
  4. Push the new tag and master to GitHub git push origin main --tags

The new release will be automatically built and published.

History

  • This gem was developed and maintained by Cargo Media from April 2014 until October 2017.
  • The vagrant_cloud CLI tool included in this RubyGem has been deprecated and removed. See vagrant cloud for a replacement.