diff --git a/website/content/docs/boxes/box_repository.mdx b/website/content/docs/boxes/box_repository.mdx new file mode 100644 index 000000000..bdd57662d --- /dev/null +++ b/website/content/docs/boxes/box_repository.mdx @@ -0,0 +1,68 @@ +--- +layout: docs +page_title: Box Repository +description: |- + Vagrant can download boxes from a Box Repository. [Vagrantcloud](https://vagrantcloud.com/) + is the HashiCorp maintained Box Repository. +--- + +# Box Repository + +A Vagrant Box Repository provides Vagrant with some boxes and information +on how to get the boxes. This can exist on a local filesystem or a service +like Vagrantcloud. + +There are two components that make up a Box Repository: + +- Vagrant Boxes - These are Vagrant `.box` files. See the + [box documentation](/vagrant/docs/boxes) for more information on Vagrant boxes. + +- Box Catalog Metadata - This is a JSON document (typically exchanged + during interactions with [HashiCorp's Vagrant Cloud](/vagrant/vagrant-cloud)) + that specifies the name of the box, a description, available + versions, available providers, and URLs to the actual box files + (next component) for each provider and version. If this catalog + metadata does not exist, a box file can still be added directly, but + it will not support versioning and updating. + +## Box Catalog Metadata + +The metadata is an optional component for a box (but highly recommended) +that enables [versioning](/vagrant//docs/boxes/versioning), updating, multiple +providers from a single file, and more. + +-> **You do not need to manually make the metadata.** If you +have an account with [HashiCorp's Vagrant Cloud](/vagrant/vagrant-cloud), you +can create boxes there, and HashiCorp's Vagrant Cloud automatically creates +the metadata for you. The format is still documented here. + +It is a JSON document, structured in the following way: + +```json +{ + "name": "hashicorp/bionic64", + "description": "This box contains Ubuntu 18.04 LTS 64-bit.", + "versions": [ + { + "version": "0.1.0", + "providers": [ + { + "name": "virtualbox", + "url": "http://example.com/bionic64_010_virtualbox.box", + "checksum_type": "sha1", + "checksum": "foo" + } + ] + } + ] +} +``` + +As you can see, the JSON document can describe multiple versions of a box, +multiple providers, and can add/remove providers in different versions. + +This JSON file can be passed directly to `vagrant box add` from the +local filesystem using a file path or via a URL, and Vagrant will +install the proper version of the box. In this case, the value for the +`url` key in the JSON can also be a file path. If multiple providers +are available, Vagrant will ask what provider you want to use. diff --git a/website/content/docs/boxes/format.mdx b/website/content/docs/boxes/format.mdx index f38bf0019..d51285995 100644 --- a/website/content/docs/boxes/format.mdx +++ b/website/content/docs/boxes/format.mdx @@ -2,61 +2,47 @@ layout: docs page_title: Box File Format description: |- - The box file format for Vagrant has changed from only supporting VirtualBox to - supporting a number different providers and box formats. + The box file format for Vagrant supports a number different providers. --- # Box File Format -In the past, boxes were just [tar files]() -of VirtualBox exports. With Vagrant supporting multiple -[providers](/vagrant/docs/providers/) and [versioning](/vagrant/docs/boxes/versioning) -now, box files are slightly more complicated. +A Vagrant `.box` file is a [tarball]() +(`tar`, `tar.gz`, `zip`) that contains all the information for a provider +to launch a Vagrant machine. -Box files made for Vagrant 1.0.x (the VirtualBox export `tar` files) continue -to work with Vagrant today. When Vagrant encounters one of these old boxes, -it automatically updates it internally to the new format. +There are four different components that make up a box: -Today, there are three different components: +- VM artifacts (required) - This is the VM image and other artifacts + in the format accepted by the provider the box is intended for. + For example, a box targeting the VirtualBox provider might have a `.ofv` + file and some `.vmdk` files. -- Box File - This is a compressed (`tar`, `tar.gz`, `zip`) file that is specific - to a single provider and can contain anything. Vagrant core does not ever - use the contents of this file. Instead, they are passed to the provider. - Therefore, a VirtualBox box file has different contents from a VMware - box file and so on. +- metadata.json (required) - Contains a map with information about the box. + Most importantly the target provider. -- Box Catalog Metadata - This is a JSON document (typically exchanged - during interactions with [HashiCorp's Vagrant Cloud](/vagrant/vagrant-cloud)) - that specifies the name of the box, a description, available - versions, available providers, and URLs to the actual box files - (next component) for each provider and version. If this catalog - metadata does not exist, a box file can still be added directly, but - it will not support versioning and updating. - -- Box Information - This is a JSON document that can provide additional +- info.json - This is a JSON document that can provide additional information about the box that displays when a user runs `vagrant box list -i`. More information is provided [here](/vagrant/docs/boxes/info). -The first two components are covered in more detail below. +- Vagrantfile - The Vagrantfile embedded in the Vagrant box will provide + some defaults for users of the box. For more information on how + Vagrant merges Vagrantfiles including ones sourced within the + box file see the [Vagrantfile docs](/vagrant/vagrant-cloud) -## Box File +So, if you extract a box and look at it's contents it will look like: +``` +# contents of the hashicorp/bionic64 box +# ref: https://app.vagrantup.com/hashicorp/boxes/bionic64 +$ ls hashicorp_bionic_box +Vagrantfile metadata.json +box.ovf ubuntu-18.04-amd64-disk001.vmdk +``` -The actual box file is the required portion for Vagrant. It is recommended -you always use a metadata file alongside a box file, but direct box files -are supported for legacy reasons in Vagrant. - -Box files are compressed using `tar`, `tar.gz`, or `zip`. The contents of the -archive can be anything, and is specific to each -[provider](/vagrant/docs/providers/). Vagrant core itself only unpacks -the boxes for use later. +## Box metadata.json Within the archive, Vagrant does expect a single file: -`metadata.json`. This is a JSON file that is completely unrelated to -the above box catalog metadata component; there is only one -`metadata.json` per box file (inside the box file), whereas one -catalog metadata JSON document can describe multiple versions of the -same box, potentially spanning multiple providers. - +`metadata.json`. There is only one `metadata.json` per box file. `metadata.json` must contain at least the "provider" key with the provider the box is for. Vagrant uses this to verify the provider of the box. For example, if your box was for VirtualBox, the @@ -76,45 +62,3 @@ Other keys/values may be added to the metadata without issue. The value of the metadata file is passed opaquely into Vagrant and plugins can make use of it. At this point, Vagrant core does not use any other keys in this file. - -## Box Metadata - -The metadata is an optional component for a box (but highly recommended) -that enables [versioning](/vagrant/docs/boxes/versioning), updating, multiple -providers from a single file, and more. - --> **You do not need to manually make the metadata.** If you -have an account with [HashiCorp's Vagrant Cloud](/vagrant/vagrant-cloud), you -can create boxes there, and HashiCorp's Vagrant Cloud automatically creates -the metadata for you. The format is still documented here. - -It is a JSON document, structured in the following way: - -```json -{ - "name": "hashicorp/bionic64", - "description": "This box contains Ubuntu 18.04 LTS 64-bit.", - "versions": [ - { - "version": "0.1.0", - "providers": [ - { - "name": "virtualbox", - "url": "http://example.com/bionic64_010_virtualbox.box", - "checksum_type": "sha1", - "checksum": "foo" - } - ] - } - ] -} -``` - -As you can see, the JSON document can describe multiple versions of a box, -multiple providers, and can add/remove providers in different versions. - -This JSON file can be passed directly to `vagrant box add` from the -local filesystem using a file path or via a URL, and Vagrant will -install the proper version of the box. In this case, the value for the -`url` key in the JSON can also be a file path. If multiple providers -are available, Vagrant will ask what provider you want to use. diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 6839608e7..75d24d407 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -266,6 +266,10 @@ "title": "Box File Format", "path": "boxes/format" }, + { + "title": "Box Repository", + "path": "boxes/box_repository" + }, { "title": "Box Info Format", "path": "boxes/info"