209 lines
7.5 KiB
Plaintext
209 lines
7.5 KiB
Plaintext
---
|
||
layout: docs
|
||
page_title: Vagrant Experimental Vagrant Go
|
||
description: Introduction to Vagrant Go
|
||
---
|
||
|
||
# Vagrant Go
|
||
|
||
Vagrant-go is Vagrant implemented in Go. This version of Vagrant is compatible
|
||
with Ruby based Vagrant plugins as well as Vagrantfiles. However, there are
|
||
some significant changes to how Vagrant-go works which make it NOT interchangeable
|
||
with Vagrant (Ruby).
|
||
|
||
~> **Warning!** Vagrant-go is in alpha and should be expected to be unstable.
|
||
Users are not recommended to use Vagrant-go for normal day to day operations.
|
||
|
||
## Anatomy of Vagrant-go
|
||
|
||
Vagrant-go has made significant changes in where data is stored. As a result,
|
||
machines managed with Vagrant (Ruby) can not be managed by Vagrant-go and vice versa.
|
||
|
||
### Vagrant-go binary
|
||
|
||
The Vagrant-go binary is shipped with the Vagrant installer. In order to run the Vagrant-go
|
||
binary do:
|
||
|
||
```
|
||
$ vagrant-go global-status
|
||
```
|
||
|
||
### Vagrant Ruby
|
||
|
||
Vagrant-go still depends on Vagrant-ruby being available in order to run Ruby plugins
|
||
and for parsing Vagrantfiles. So, Vagrant-go runs Vagrant-ruby as a server in a subprocess,
|
||
providing it access to all the Ruby functionality.
|
||
|
||
### Scopes
|
||
|
||
Vagrant-go has a notion of an information hierarchy. There are three main components:
|
||
|
||
**Target**: A target is the most specific component in the information hierarchy. It
|
||
represents the guest that Vagrant may manipulate. It is similar to the notion of a
|
||
Vagrant Machine.
|
||
|
||
**Project**: A project is similar to the concept of an Environment. It represents
|
||
a group of targets. A project may have plugins installed that are not available
|
||
to other projects. A project directory is any directory that has a Vagrantfile.
|
||
|
||
**Basis**: The basis is the most general component. It represents the root of the Vagrant
|
||
execution environment and may contain multiple projects. A user may define multiple basis'
|
||
for their installation. Plugins installed into the basis will be available to all projects
|
||
within the basis. Vagrantfiles setup in the basis will be applied to all projects.
|
||
|
||
### Data directories
|
||
|
||
The default Vagrant-go data directory and config directory have changed to meet the
|
||
[XDG specification](https://pkg.go.dev/github.com/adrg/xdg).
|
||
The data directory is now at the XDG data home. The config directory is now at the
|
||
XDG config home. In addition, project level information is no longer available in
|
||
`PROJECT_DIR/.vagrant`. Instead, this information is available with the data and config dirs.
|
||
|
||
The form of these directories is as follows:
|
||
|
||
```
|
||
|- $XDG_CONFIG_DIR
|
||
\- default # basis name
|
||
|- Vagrantfile # a basis level Vagrantfile will be applied to all machines in the basis
|
||
\- project
|
||
\- project_one # project name
|
||
\- target
|
||
|- target_one # target name
|
||
|- target_two
|
||
\- project_two
|
||
\- target
|
||
|- a
|
||
|- b
|
||
```
|
||
|
||
```
|
||
|- $XDG_DATA_DIR
|
||
|- data.db # Vagrant database
|
||
\- default # basis name
|
||
|- insecure_private_key
|
||
\- boxes # box directory
|
||
\- hashicorp-VAGRANTSLASH-bionic64 # box name
|
||
\- 1.0.282 # box version
|
||
\- virtualbox # box provider
|
||
|- Vagrantfile
|
||
|- box.ovf
|
||
|- metadata.json
|
||
|- ubuntu-18.04-amd64-disk001.vmdk
|
||
\- project
|
||
\- project_one # project name
|
||
\- target
|
||
|- target_one # target name
|
||
|- target_two
|
||
\- project_two
|
||
|- vbox_symlink_create_warning
|
||
\- target
|
||
|- a
|
||
|- b
|
||
|
||
|
||
```
|
||
|
||
Vagrant-go does not have knowledge of the Vagrant-ruby data directories so does not
|
||
have access to that data and vice versa. Both Vagrant-go and Vagrant-ruby
|
||
respect the [Vagrant environment variables](/vagrant/docs/other/environmental-variables/) for
|
||
setting data directory paths. However, the layout and content of these directories
|
||
are different for Vagrant-go and Vagrant-ruby.
|
||
|
||
~> **Warning!** Vagrant-go users should not attempt to use an existing `VAGRANT_HOME`
|
||
directory as it may corrupt it.
|
||
|
||
|
||
#### Boxes
|
||
|
||
Boxes still exist within the data directory. As mentioned above, the data directory is now
|
||
at `$XDG_DATA_DIR`. The ramifications of this are:
|
||
- Boxes will be duplicated between Vagrant-go and Vagrant-ruby
|
||
- Users can still import local boxes in both Vagrant-go and Vagrant-ruby using the
|
||
`box add` command. So, users don't need to download boxes multiple times.
|
||
|
||
#### Machine index
|
||
|
||
The machine index for Vagrant-go is backed by the `data.db` in the data directory.
|
||
The ramifications of this are:
|
||
- Vagrant-go and Vagrant-ruby do not share a machine index. They have no knowledge of
|
||
each other, so machines you bring up in one will not be available in the other. There is
|
||
currently no way to “import” or “export” a machine index entry
|
||
|
||
## Installing Go Vagrant plugins
|
||
|
||
Vagrant-go can load external plugins that are packaged as executables. Plugins can be
|
||
launched from the basis (`VAGRANT_CONFIG_DIR/plugins`) or the project directory
|
||
(`VAGRANT_PROJECT/.vagrant/plugins`).
|
||
|
||
These executables will be executed without any options or flags provided.
|
||
To install a new plugin, drop the plugin executable in one of these paths.
|
||
|
||
## Known Issues
|
||
|
||
For all Vagrant-Go issues see the public [GitHub issues](https://github.com/hashicorp/vagrant/labels/vagrant-go)
|
||
|
||
### Vagrant ssh command does not work interactively
|
||
|
||
The `-c` argument does work to specify a single command to run. For example:
|
||
```
|
||
# Run a command on the guest machine
|
||
vagrant ssh -c "echo hello world"
|
||
```
|
||
|
||
Users may still access the Vagrant machine over SSH by running the ssh command. For example:
|
||
```
|
||
# Get the SSH configuration for the target machine
|
||
vagrant ssh-config <target>
|
||
|
||
# Use the info provided to SSH into the target machine using the ssh command
|
||
ssh vagrant@<ip> -p <port> -i <path to key>
|
||
```
|
||
|
||
### `vagrant plugin` command only manipulates Ruby plugins
|
||
|
||
The Vagrant plugin command uses bundler to manage Ruby based plugins. To install/uninstall
|
||
go based plugins, users must manually add the plugin binary to the plugins path.
|
||
Uninstalling Ruby Vagrant plugins does not currently work.
|
||
|
||
### Vagrant does not work on Windows
|
||
|
||
The go plugin setup currently is built on Unix sockets. So, Vagrant-go is not expected to
|
||
work on Windows. This will be addressed in a future release.
|
||
|
||
### Concurrent Vagrant runs don’t work
|
||
|
||
Only one Vagrant-go process may run at a time.
|
||
|
||
### Puppet and Chef provisioners do not work
|
||
|
||
These provisioners require Vagrant to modify synced folders on the fly during a Vagrant run.
|
||
This capability will not be implemented for 2.3.0, so, these provisioners will not work as
|
||
expected.
|
||
|
||
### Each machine must specify their own SSH port for multi machine environments
|
||
|
||
Currently, Vagrant-go does not check for port collisions when forwarding ports. Instead, it
|
||
will allow for multiple forwarded ports to be defined on the same host port. This results in
|
||
the SSH ports for machines to all be assigned to the same default port if none is specified.
|
||
This causes Vagrant to time out when connecting to a machine in multimachine environments. To
|
||
avoid this issue you may specify the SSH port for the machines, for example:
|
||
```
|
||
Vagrant.configure("2") do |config|
|
||
config.vm.define "one" do |c|
|
||
c.vm.hostname = "one"
|
||
c.vm.network "forwarded_port", guest: 22, host: 2223
|
||
c.ssh.port = 2223
|
||
c.vm.box = "hashicorp/bionic64"
|
||
c.vm.synced_folder ".", "vagrant", disabled: true
|
||
end
|
||
|
||
config.vm.define "two" do |c|
|
||
c.vm.hostname = "two"
|
||
c.vm.network "forwarded_port", guest: 22, host: 2224
|
||
c.ssh.port = 2224
|
||
c.vm.box = "hashicorp/bionic64"
|
||
c.vm.synced_folder ".", "vagrant", disabled: true
|
||
end
|
||
end
|
||
```
|