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/precise64 boxes each
include a provider for
hashicorp/precise32 v1.0.0 provider: virtualbox hashicorp/precise64 v1.0.0 provider: 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
hashicorp/precise64 box for a 64-bit guest, a single
box can provide both.
hashicorp/precise v1.0.0 provider: virtualbox, architecture: amd64 provider: virtualbox, architecture: i386
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.
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
virtualbox provider is created with
hashicorp/precise v2.0.0 provider: virtualbox, architecture: amd64, default_architecture: true
virtualbox provider with
hashicorp/precise v2.0.0 provider: virtualbox, architecture: amd64, default_architecture: true provider: virtualbox, architecture: i386, default_architecture: false
When the Vagrant CLI, prior to version 2.4.0, requests the
box with the
virtualbox provider, it will receive the information from
virtualbox provider with the
amd64 architecture because it is flagged
as being the default architecture. If, instead, the provider with
architecture should be returned, the
virtualbox provider for the
architecture can be updated to be the default architecture.
hashicorp/precise v2.0.0 provider: virtualbox, architecture: amd64, default_architecture: false provider: virtualbox, architecture: i386, default_architecture: true
Now the provider with the
i386 architecture will be returned.
There are two cases where Vagrant CLI versions with architecture support will use the default architecture flag.
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.
The architecture value
unknown combined with the default architecture
flag provides a special matching case for the Vagrant CLI. If the
option in the local Vagrantfile is configured with the default
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.