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。