Add information about Vagrant boxes
Split box format information from box repository information to avoid confusion between the metadata.json in the box and metadata for the a box repository.
This commit is contained in:
sophia
parent
24a830aff0
commit
cbe5ecde4a
68
website/content/docs/boxes/box_repository.mdx
Normal file
68
website/content/docs/boxes/box_repository.mdx
Normal file
@ -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](/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-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](/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-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.
|
||||
@ -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](<https://en.wikipedia.org/wiki/Tar_(computing)>)
|
||||
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](<https://en.wikipedia.org/wiki/Tar_(computing)>)
|
||||
(`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-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.
|
||||
|
||||
@ -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"
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user