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。