beckermj/vaguerent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add architecture page to vagrant cloud docs

Browse Source
This commit is contained in:
Chris Roberts 2023-09-28 16:58:49 -07:00
parent 4faf740059
commit 3d1fc711a3
1 changed files with 117 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

117
website/content/vagrant-cloud/boxes/architecture.mdx Normal file
View File

@ -0,0 +1,117 @@
---
layout: vagrant-cloud
page_title: Vagrant Box Architecture
description: "Vagrant box architecture and default architecture"
---
# Architecture For Vagrant Boxes
This page provides information on the architecture option available when
creating a provider for a box on Vagrant Cloud. The architecture option
allows a box to provide multiple instances of a provider with a specific
name. Each of these providers that share a common name can provide an
artifact for a different architecture.
Using the `hashicorp/precise32` and `hashicorp/precise64` boxes as an example,
each of these boxes include a provider for `virtualbox`. This looks like:
```
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
a `hashicorp/precise64` box for a 64-bit guest, a single `hashicorp/precise`
box can provider both. The new box would look like:
```
hashicorp/precise
v1.0.0
provider: virtualbox, architecture: amd64
provider: virtualbox, architecture: i386
```
The Vagrant CLI (starting with version 2.4.0) 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/vagrant-cloud/boxes/architecture#special-case-unknown-architecture).
# Default Architecture
Vagrant Cloud allows a single architecture to be flagged as the "default
architecture" for a provider. The flag is used for backwards compatiblity
with previous versions of the Vagrant CLI that do not support architecture
filtering when matching an appropriate provider. Using this flag allows
the box owner to control which architecture for a specific provider is
used by the Vagrant CLI when architecture filtering is not available.
By default, the first provider for a specific name uploaded in a box version
will be flagged as the default architecture. For example, after creating
the `2.0.0` version of the `hashicorp/precise` box and creating a new
provider for `virtualbox` with `amd64` architecture it would look like:
```
hashicorp/precise
v2.0.0
provider: virtualbox, architecture: amd64, default_architecture: true
```
If another `virtualbox` provider is created with `i386` architecture it would
then look like:
```
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 `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 provider can be updated to look like:
```
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.
## 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](/vagrant/docs/vagrantfile/machine_settings#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](/vagrant/docs/vagrantfile/machine_settings#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.