Architecture for Vagrant boxes
Providers for Vagrant boxes, in Vagrant version 2.4.0 and newer, can include multiple architecture options. This allows you to have multiple instances of one specific provider. The specific provider shares a common name for artifacts of different architectures.
For example, the hashicorp/precise32 and hashicorp/precise64 boxes each
include a provider for virtualbox.
The addition of architecture now allows these to be combined into a single
box. Instead of having a hashicorp/precise32 box for a 32-bit guest, and
a hashicorp/precise64 box for a 64-bit guest, a single hashicorp/precise
box can provide both.
The Vagrant CLI will automatically match the provider architecture using the detected local host architecture. If the Vagrant CLI cannot find a matching architecture, it will attempt a special case match.
Default architecture
Vagrant Cloud allows you to optionally specify one architecture as the "default architecture" for a provider. This enables the box owner to control which architecture for the provider the Vagrant CLI uses when architecture filtering is not available. By default, the first provider in the configuration for a box version is the default architecture.
Note, this functionality enables backwards compatiblity with previous versions of the Vagrant CLI that do not support architecture filtering when matching an appropriate provider.
For example, the 2.0.0 version of the hashicorp/precise box is created and
a new virtualbox provider is created with amd64 architecture.
Adding another virtualbox provider with i386 architecture.
When the Vagrant CLI, prior to version 2.4.0, requests the hashicorp/precise
box with the virtualbox provider, it will receive the information from
the virtualbox provider with the amd64 architecture because it is flagged
as being the default architecture. If, instead, the provider with i386
architecture should be returned, the virtualbox provider for the i386
architecture can be updated to be the default architecture.
Now the provider with the i386 architecture will be returned.
Special cases
There are two cases where Vagrant CLI versions with architecture support will use the default architecture flag.
User requested
If the user sets the config.vm.box_architecture
option in their Vagrantfile to nil, the Vagrant CLI will use the
provider which has been flagged as the default architecture.
Unknown architecture
The architecture value unknown combined with the default architecture
flag provides a special matching case for the Vagrant CLI. If the
config.vm.box_architecture
option in the local Vagrantfile is configured with the default :auto
value, and no architecture matching the host platform can be found
for the desired provider, the Vagrant CLI will check for a matching
provider that is flagged as the default architecture and has an
architecture value of unknown. If that match is found, the Vagrant
CLI will use that provider.
This special case matching was included so the Vagrant CLI would be
able to use boxes published to Vagrant Cloud prior to the introduction
of architecture metadata. All previously existing providers have a
default architecture value of unknown and are flagged as the default
architecture since they are the only provider to exist for a given name.