Vagrant 手册之 box - box 的文件格式

原文地址

过去，box 只是 VirtualBox 导出的 tar 文件。因为 Vagrant 如今支持多个 provider 和版本控制，box 文件稍微复杂一些。

用于 Vagrant 1.0.x 的 Box 文件（VirtualBox 导出的 tar 文件）能够继续与新版本的 Vagrant 一块儿使用。当 Vagrant 遇到旧 box 时，会自动将其更新为新格式。

今天，有三个不一样的组件：

• Box 文件：这是个特定于某个 provider 的压缩文件（tar、tar.gz、zip），能够包含任何东西。Vagrant 内核并不会使用这个文件的内容。相反，文件内容会被传输给 provider。所以，用于 VirtualBox 的 box 文件跟用于 VMware 的 box 文件内容是不一样的。
• Box 目录元数据（Catalog Metadata）：JSON 文档（一般用于跟 HashiCorp 的 Vagrant Cloud 交互），指定了 box 的名字、描述、可用版本、可用 provider 以及 指向不一样 provider 和不一样版本的真实 box 文件的 URL。若是目录元数据不存在，也能够直接添加 box 文件，可是不支持版本控制且没法更新。
• Box 信息：JSON 文档，在用户运行 vagrant box list -i 时提供关于 box 的额外信息。更多信息参考 这里。

1. Box 文件

真实的 box 文件是 Vagrant 的必需部分。建议始终在使用 box 文件时使用元数据文件，但因为历史遗留问题，在 Vagrant 中能够直接使用 box 文件。

Box 文件使用 tar，tar.gz 或 zip 进行压缩。文档中能够放特定于 provider 的任何东西。Vagrant 核心只会解压缩 box。

在文档中，Vagrant 期待一个文件：metadata.json。这是一个与上面的 box 目录元数据组件彻底无关的 JSON 文件; 每一个 box 文件（box 文件内）只有一个metadata.json，而一个目录元数据 JSON 文档能够描述同一个 box 的多个版本，可能跨越多个 provider。

metadata.json 必须至少包含 provider 的“provider”关键字。Vagrant 用这个来验证 box 的 provider。例如，若是 box 是用于 VirtualBox 的，则 metadata.json 将以下所示：

{
  "provider": "virtualbox" }

若是没有 metadata.json 文件或文件不包含有效的且至少有一个“provider”键的 JSON 文件，则添加该 box 时，Vagrant 将会出错，由于它没法验证 provider。

其余的键/值对也能够被添加到元数据。元数据文件的值被不透明地传递给 Vagrant，插件也可使用。此时，Vagrant 内核不会在此文件中使用任何其余键。

2. Box 元数据

元数据是一个 box 的可选组件（但强烈推荐），支持从一个文件进行版本控制、更新、多个 provider 等。

不须要手动建立元数据。若是你有 HashiCorp 的 Vagrant Cloud 帐户，能够在那里建立 box，而 HashiCorp 的 Vagrant Cloud 会自动建立元数据。格式仍然记录在这里。

box 元数据是 JSON 文档，组织以下：

{
  "name": "hashicorp/precise64",
  "description": "This box contains Ubuntu 12.04 LTS 64-bit.",
  "versions": [ { "version": "0.1.0", "providers": [ { "name": "virtualbox", "url": "http://somewhere.com/precise64_010_virtualbox.box", "checksum_type": "sha1", "checksum": "foo" } ] } ] }

如上所示，JSON 文档能够描述多个版本的 box，多个 provider，而且能够添加/删除不一样版本的 provider。

这个 JSON 文件可使用本地文件系统的文件路径或经过 URL 直接传递到 vagrant box add，Vagrant 将安装正确版本的 box。这种状况下，JSON 中的 url 键值也能够是文件路径。若是有多个 provider 可用，Vagrant 会询问要使用哪一个provider。