Zum Inhalt springen
1337skills 1337skills - Referenzen

Vagrant Cloud Cheat Sheet

Overview

Vagrant Cloud (now part of the HashiCorp Cloud Platform) is a registry and collaboration platform for Vagrant boxes—pre-built virtual machine images used to create reproducible development environments. It hosts publicly available boxes from the community (like hashicorp/bionic64, ubuntu/jammy64, and generic/rhel9) and supports private boxes for organizations. Vagrant Cloud handles box versioning, provider-specific variants (VirtualBox, VMware, Hyper-V, libvirt), and checksum verification.

Vagrant Cloud integrates directly with the vagrant CLI. When you specify a box name in a Vagrantfile, Vagrant automatically downloads it from Vagrant Cloud. Teams can publish custom boxes with their specific tooling pre-installed, maintain version histories, and control access. The platform supports box catalogs for organizations, allowing standardized base images across development teams. Vagrant Cloud also provides APIs for automation and CI/CD integration.

Installation

Install Vagrant

# macOS
brew install hashicorp/tap/vagrant

# Ubuntu/Debian
wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install vagrant

# RHEL/CentOS
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo
sudo yum install vagrant

# Verify
vagrant --version

Core Commands

CommandDescription
vagrant cloud auth loginAuthenticate with Vagrant Cloud
vagrant cloud auth whoamiShow current user
vagrant cloud box show <user/box>Show box details
vagrant cloud search <query>Search for boxes
vagrant cloud publishPublish a box version
vagrant cloud box createCreate a new box entry
vagrant cloud box updateUpdate box metadata
vagrant cloud box deleteDelete a box
vagrant box add <user/box>Download a box locally
vagrant box listList locally installed boxes
vagrant box updateUpdate box to latest version
vagrant box remove <user/box>Remove local box

Authentication

# Login to Vagrant Cloud
vagrant cloud auth login
# Enter username and password, or use token

# Login with token
vagrant cloud auth login --token YOUR_TOKEN

# Check authentication
vagrant cloud auth whoami

# Set token via environment variable
export VAGRANT_CLOUD_TOKEN=your-api-token

Searching and Using Boxes

# Search for boxes
vagrant cloud search ubuntu --provider virtualbox --sort downloads

# Show box information
vagrant cloud box show ubuntu/jammy64

# Initialize project with a box
vagrant init ubuntu/jammy64

# Add a box locally
vagrant box add generic/rhel9

# List local boxes
vagrant box list

# Update to latest version
vagrant box update --box ubuntu/jammy64

Vagrantfile with Cloud Boxes

Vagrant.configure("2") do |config|
  # Use a cloud box
  config.vm.box = "ubuntu/jammy64"
  config.vm.box_version = ">= 20230901.0.0"
  config.vm.box_check_update = true

  # Provider-specific settings
  config.vm.provider "virtualbox" do |vb|
    vb.memory = "2048"
    vb.cpus = 2
    vb.name = "dev-server"
  end

  # Network
  config.vm.network "private_network", ip: "192.168.56.10"
  config.vm.network "forwarded_port", guest: 8080, host: 8080

  # Provisioning
  config.vm.provision "shell", inline: <<-SHELL
    apt-get update
    apt-get install -y docker.io nginx
  SHELL
end

Multi-Machine Environment

Vagrant.configure("2") do |config|
  config.vm.define "web" do |web|
    web.vm.box = "ubuntu/jammy64"
    web.vm.hostname = "web-server"
    web.vm.network "private_network", ip: "192.168.56.10"
    web.vm.provider "virtualbox" do |vb|
      vb.memory = "1024"
    end
  end

  config.vm.define "db" do |db|
    db.vm.box = "ubuntu/jammy64"
    db.vm.hostname = "db-server"
    db.vm.network "private_network", ip: "192.168.56.11"
    db.vm.provider "virtualbox" do |vb|
      vb.memory = "2048"
    end
  end
end

Publishing Boxes

Create and Publish a Box

# Create box entry on Vagrant Cloud
vagrant cloud box create myorg/mybox --description "Custom dev box"

# Package current VM as a box
vagrant package --output mybox.box

# Publish a version
vagrant cloud publish myorg/mybox 1.0.0 virtualbox mybox.box \
  --description "Initial release" \
  --version-description "Ubuntu 22.04 with dev tools" \
  --release \
  --force

# Publish without releasing (draft)
vagrant cloud publish myorg/mybox 1.1.0 virtualbox mybox.box \
  --no-release

Building Boxes with Packer

{
  "builders": [{
    "type": "virtualbox-iso",
    "iso_url": "https://releases.ubuntu.com/22.04/ubuntu-22.04.3-live-server-amd64.iso",
    "iso_checksum": "sha256:abcdef123456",
    "ssh_username": "vagrant",
    "ssh_password": "vagrant",
    "shutdown_command": "sudo shutdown -P now"
  }],
  "post-processors": [
    [{
      "type": "vagrant",
      "output": "builds/{{.Provider}}-ubuntu2204.box"
    },
    {
      "type": "vagrant-cloud",
      "box_tag": "myorg/ubuntu2204",
      "version": "{{user `version`}}"
    }]
  ]
}

Configuration

Vagrant Cloud API

# List boxes for a user
curl -s "https://app.vagrantup.com/api/v2/user/myorg" \
  -H "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" | jq '.boxes[].tag'

# Get box details
curl -s "https://app.vagrantup.com/api/v2/box/myorg/mybox" \
  -H "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" | jq

# Create box via API
curl -X POST "https://app.vagrantup.com/api/v2/boxes" \
  -H "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"box":{"username":"myorg","name":"mybox","is_private":true}}'

Advanced Usage

Box Versioning Strategy

# Release new version
vagrant cloud publish myorg/mybox 2.0.0 virtualbox mybox-v2.box --release

# Revoke a version (keeps it but marks unavailable)
vagrant cloud version revoke myorg/mybox 1.0.0

# Delete a version permanently
vagrant cloud version delete myorg/mybox 1.0.0

Private Box Hosting (Self-Hosted)

{
  "name": "myorg/mybox",
  "versions": [{
    "version": "1.0.0",
    "providers": [{
      "name": "virtualbox",
      "url": "https://internal.example.com/boxes/mybox-1.0.0.box",
      "checksum_type": "sha256",
      "checksum": "abc123def456..."
    }]
  }]
}
# Vagrantfile pointing to self-hosted catalog
config.vm.box = "myorg/mybox"
config.vm.box_url = "https://internal.example.com/boxes/mybox.json"

Troubleshooting

IssueSolution
Authentication token not foundRun vagrant cloud auth login or set VAGRANT_CLOUD_TOKEN
Box download failsCheck network connectivity; try vagrant box add --clean <box>
Version conflictUse vagrant box update or specify exact version in Vagrantfile
Provider mismatchEnsure the box has a provider matching your hypervisor
Box not foundVerify the box name format is username/boxname
Upload timeout for large boxesUse the API with chunked upload or host the box externally
Checksum verification failsRe-download the box with --force flag