Vagrant Box S3

Use Vagrant boxes stored in Amazon S3 private buckets.

• vagrant (2.4.x)
• aws-sdk-s3 (1.x)

This plugin works using the authenticate_box_url hook to replace S3 URLs with presigned URLs and monkey patching Vagrant::Util::Downloader, extending the core Downloader class in Vagrant to override the head method used when fetching box metadata URLs from S3.

Via Vagrantfile, using config.vagrant.plugins:

Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
  config.vagrant.plugins = ['vagrant-box-s3', 'other-plugin']
  ...
end

Or via plugin install command:

vagrant plugin install vagrant-box-s3

The plugin will automatically sign requests to AWS S3 URLs with your AWS credentials, allowing storage of private boxes on S3 with your own bucket policies in place.

AWS credentials are read from the standard environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

You can also use your credentials file to create a profile. Select the appropriate profile using the AWS_PROFILE environment variable. For example:

[vagrant-box-s3]
aws_access_key_id = AKIA...
aws_secret_access_key = ...

ENV.delete_if { |name| name.start_with?('AWS_') }  # Filter out rogue env vars.
ENV['AWS_PROFILE'] = 'vagrant-box-s3'

Vagrant.configure("2") { |config| ... }

You can use any valid HTTP(S) URL for your box URL:

Virtual-hosted-style URLs use the bucket name as a subdomain. This is the recommended and most commonly used format.

Specify the bucket name in the path of the URL. AWS has deprecated path-style URLs, but they might still be seen or used in legacy systems.

IAM accounts will need at least the following policy, replacing BUCKET with your bucket name.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::BUCKET/*"
        },
        {
            "Effect": "Allow",
            "Action": ["s3:GetBucketLocation", "s3:ListBucket"],
            "Resource": "arn:aws:s3:::BUCKET"
        }
    ]
}

• Ruby (3.2.x)

A specific version of ruby can be installed on macOS via rbenv:

brew install rbenv

echo 'eval "$(rbenv init -)"' >> ~/.zshrc

rbenv install 3.2.2

cd /path/to/vagrant-box-s3

rbenv local 3.2.2

ruby -v

If bundled packages / dependencies have changed, run bundle install:

bundle install --path vendor/bundle

Update the current version in lib/vagrant-box-s3/version.rb.

To build the plugin, use rake build, this will create a file with the current version number, e.g. pkg/vagrant-box-s3-{VERSION}.gem.

Remove the old version:

vagrant plugin uninstall vagrant-box-s3 --local

Testing the plugin requires installing into vagrant from the build:

vagrant plugin install ../vagrant-box-s3/pkg/vagrant-box-s3-{VERSION}.gem

Then running a command that will trigger box URL related actions, such as vagrant up, vagrant box update etc. with the --debug flag.

To release a new version to RubyGems.org, you must be authenticated.

If you have not previously authenticated, sign in:

gem signin

This will store and use credentials in ~/.gem/credentials.

Ensure the new version number is correctly set in lib/vagrant-box-s3/version.rb.

Then you can build and push the release:

rake release

Bug reports and pull requests are welcome on GitHub at https://github.com/memiah/vagrant-box-s3. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

The gem is available as open source under the terms of the MIT License.