Vagrant の Box 作成時に適用した Vagrantfile と、Vagrant up 時の Vagrantfile で、設定の優先度はどうなっているの？

TL;DR（概要）

Vagrantfiles は以下の順序でロードされます。各ステップで Vagrantfile が見つからなかった場合、Vagrant は次のステップに進み、Vagrantfile が見つかった場合は、その値をマージしていきます。

対象仮想マシンの Box に内包された Vagrantfile。

Vagrant のホームディレクトリにある Vagrantfile（デフォルトは ~/.vagrant.d）。

プロジェクトのディレクトリにある Vagrantfile。

Multi-machine がある場合は、それらの設定。

プロバイダ¹固有のオーバーライドある場合、それらの設定。

ほとんどの場合、Vagrant ファイルの変更はステップ 3 を指します。適用の優先度の仕組みは、profile .bash_profile .bashrc のような bash の設定が適用される優先度がイメージとして近いかもしれません。

TS;DR（詳細）

`--vagrantfile` オプションの使い道がわからない

Vagrant² のコマンド・ツールには Vagrant の Box³ アーカイブを作成するための package というコマンドがあります。その、package コマンドに --vagrantfile というオプションがあります。

ヘルプの翻訳（一部）

$ vagrant --help | grep package
     package         現行の Vagrant 環境を Box にパッケージングします。

$ vagrant package --help
Usage: vagrant package [オプション] [パッケージ名|パッケージ id]

オプション:

        --base NAME                  Box にパッケージングしたい VirtualBox の仮想マシン名。
                                    （VirtualBox 限定オプション。仮想マシンの設定にある "Name"）
        --output NAME                Name of the file to output
        --include FILE,FILE..        Box のパッケージングの際に追加するファイル。コンマ区切り。
        --vagrantfile FILE           Box のパッケージングの際に同梱する Vagrantfile。　　←これ
    -h, --help                       このヘルプ

しかし、そもそも Vagrantfile から呼び出されるのが作成された Box ファイルであるため、このオプションの使い道がいまいちピンと来ないのです。

公式のドキュメントを読むと注釈に簡単な違いが書いてありました。

A common misconception is that the --vagrantfile option will package a Vagrantfile that is used when vagrant init is used with this box. This is not the case. Instead, a Vagrantfile is loaded and read as part of the Vagrant load process when the box is used. For more information, read about the Vagrantfile load order.
（「Options の注釈 | Package | Docs」@ Vagrant 公式より）

（筆者訳）
よくある誤解は、--vagrantfile オプションで Box にパッケージ化された Vagrantfile は、vagrant init 時に使われると勘違いされることです。違います。この、パッケージに含まれた Vagrant ファイルは、Box の使用時の Vagrant のロード・プロセスの一部として読み込まれます。詳しくは、Vagrantfile のロード順序をお読みください。

なるほど、よくある誤解だったようです。とほほ。

そこで、詳しく知りたかったので、公式の「Load Order and Merging」を訳してみました。

▼ 以下翻訳（この記事は原文と同じ MIT ライセンスとします）

Vagrantfile のロード順とマージ

Vagrant が、どのように Vagrantfiles をロードする（読み込まれる）か概念を理解することが重要です。

実際には、Vagrant は一連の Vagrantfiles をロードし、設定をマージして行きます。これにより、さまざまなレベルの特定の Vagrantfiles が以前の設定を上書きすることができます。

Vagrantfiles は以下の順序でロードされます。各ステップで Vagrant ファイルが見つからなかった場合、Vagrant は次のステップに進むことに注意してください。

各段階で設定された項目は、それ以前の値とマージされます。どのようにマージされるかは設定によって異なります。ほとんどの設定では、新しい設定が古い設定を上書きします。一方、ネットワークの定義などの場合は上書きでなく追加されていきます。デフォルトで設定は互いに優先しあう（上書きしあう）と仮定する必要があります。動作が異なる場合は、関連するドキュメントに記載されています。

各 Vagrantfile 内では、複数の Vagrant.configure ブロック（構成）を指定できます。すべての構成は、定義されている順序で単一の Vagrant ファイルにマージされます。

▲ 翻訳ここまで

つまり、Box に内包された Vagrantfile は vagrant init でなく vagrant up 時に影響がある設定ということのようです。どうやら、提供する Box のデフォルト値を変更したい時に --vagrantfile オプションを活用するのが主な目的のようです。

Vagrant Cloud から macOS の Vagrant box をダウンロードして単純に vagrant up すると以下のような「Vagrant is not able to mount VirtualBox shared folders」エラーが出る場合に、デフォルトで共有フォルダを無効にしておくなどに活用できそうです。

Vagrant is not able to mount VirtualBox shared folders on BSD-based
guests. BSD-based guests do not support the VirtualBox filesystem at
this time.

To change the type of the default synced folder, specify the type as
rsync or nfs:

    config.vm.synced_folder ".", "/vagrant", type: "nfs" # or "rsync"

Alternatively, if you do not need to mount the default synced folder,
you can also disable it entirely:

    config.vm.synced_folder ".", "/vagrant", disabled: true

You can read more about Vagrant's synced folder types and the various
configuration options on the Vagrant website.

This is not a bug in Vagrant.

【プロバイダーとは】Vagrant におけるプロバイダーとは、仮想環境を提供しているアプリおよび Box が必要な仮想環境のこと。VirtualBox、VMware、Docker などを指す。 ↩ ↩²
【Vagrant とは】VirtualBOX / VMware / Docker などの仮想マシン系のアプリの挙動を、コマンドで操作するためのツールのこと。例えば、VirtualBOX の仮想マシンとゲスト OS の入手と起動、必要なアプリのインストール、OS のスナップショット、シェルコマンドの実行、スナップを戻すといったバッチ処理的なことができる。これにより、テスト環境の構築とテストの実行や、特定環境でのビルドを自動化することができる。このように指揮をとるイメージから、オーケストレーション・ツールと呼ばれるものの１つ。CI などに使われる。「Vagrant (ソフトウェア)」@ Wikipedia ↩
【Box とは】Vagrant における Box は、".box" の拡張子が付いたパッケージ・ファイルのこと。作成した仮想マシンとゲスト OS（仮想マシン上で動かす OS）を異なる Vagrant 環境で動かすために必要なファイルをアーカイブして１つのファイルにしたもの。基本的に含まれる内容は「Raw Contents | Boxes」@ Vagrant 公式を参照。 ↩