website: Import Vagrant Enterprise docs
This commit is contained in:
Justin Campbell
parent
20b4766dd7
commit
4eacb3d492
|
|
@ -0,0 +1,46 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Discovering Vagrant Boxes"
|
||||
sidebar_current: "vagrant-cloud-boxes-catalog"
|
||||
---
|
||||
|
||||
# Discovering Vagrant Boxes
|
||||
|
||||
Atlas serves a public, searchable index of Vagrant boxes. It's easy to find
|
||||
boxes you can use with Vagrant that contain the technologies you need
|
||||
for a Vagrant environment.
|
||||
|
||||
You don't need an Atlas account to use public boxes.
|
||||
|
||||
1. Go to the [Box search page](https://vagrantcloud.com/boxes/search)
|
||||
|
||||
1. Once you find a box, click its name to learn more about it.
|
||||
|
||||
1. When you're ready to use it, copy the name, such as "hashicorp/precise64"
|
||||
and initialize your Vagrant project with `vagrant init hashicorp/precise64`.
|
||||
Or, if you already have a Vagrant project created, modify the Vagrantfile
|
||||
to use the box: `config.vm.box = "hashicorp/precise64"`
|
||||
|
||||
## Provider Support
|
||||
|
||||
Not all boxes are available for all providers. You may need
|
||||
to sort by a provider that you have on your local system
|
||||
to narrow down your search.
|
||||
|
||||
## Choosing the Right Box
|
||||
|
||||
As with all software and configuration used from a public source,
|
||||
it's important to keep in mind whose box you're using. Here
|
||||
are some things to note when you're choosing a box:
|
||||
|
||||
- __The username of the user__. If it's `bento` or `canonical`, you can likely
|
||||
trust the box more than an anonymous user
|
||||
- __The number of downloads of the box__. Heavily downloaded boxes
|
||||
are likely vetted more often by other members of the community. Hashicorp
|
||||
responds to reports of malicious software distributed via Atlas
|
||||
and takes down boxes
|
||||
- __The latest release date__. More up-to-date boxes contain up-to-date
|
||||
software
|
||||
- __Availability of the box download__. Atlas periodically checks if box
|
||||
has is publicly accessible. You can see this information on the box
|
||||
page next to the provider
|
||||
|
|
@ -0,0 +1,29 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Create a New Box Version"
|
||||
sidebar_current: "vagrant-cloud-boxes-create-version"
|
||||
---
|
||||
|
||||
# Create a New Box Version
|
||||
|
||||
To release a new version of a box to the public or to your team:
|
||||
|
||||
1. Click on the name of the box you want to release a new version for.
|
||||
|
||||
2. To the right of the box name, there is a dropdown of all the available
|
||||
versions. Click this, and click "Create a New Version"
|
||||
|
||||
3. Enter details for your new version and click "Create Version." Note that
|
||||
after clicking create version, the version is not yet _released_.
|
||||
|
||||
4. Click "Create new provider" on this next page to add at least one
|
||||
provider to the version. Specify the name of the provider (this is the
|
||||
same value you specify to `--provider` when using Vagrant). Then
|
||||
enter the URL to a self-hosted box file or upload a box to us.
|
||||
|
||||
5. Once the provider is created, you now have the option to release the
|
||||
version by clicking "Release now," or you can add more providers.
|
||||
|
||||
Once you click "Release now," that version will be available for installation
|
||||
with Vagrant. Before clicking this, Vagrant does not know the version even
|
||||
exists.
|
||||
|
|
@ -0,0 +1,80 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Creating a New Vagrant Box"
|
||||
sidebar_current: "vagrant-cloud-boxes-create-x"
|
||||
---
|
||||
|
||||
# Creating a New Vagrant Box
|
||||
|
||||
This page will cover creating a new box in Atlas and how to distribute
|
||||
it to users. Boxes can be distributed without Atlas, but
|
||||
miss out on several [important features](/help/vagrant/boxes).
|
||||
|
||||
There are __three ways to create and upload Vagrant Boxes to Atlas__. All
|
||||
three options are outlined below.
|
||||
|
||||
We recommend using Packer, as is it is fully repeatable and keeps a strong
|
||||
history of changes within Atlas. However, for some situations, including
|
||||
legacy workflows, the Web UI or API will work well.
|
||||
|
||||
All three options require you [sign up for Atlas](/account/new).
|
||||
|
||||
## Creating Boxes with Packer
|
||||
|
||||
Using Packer requires more up front effort, but the repeatable and
|
||||
automated builds will end any manual management of boxes. Additionally,
|
||||
all boxes will be stored and served from Atlas, keeping a history along
|
||||
the way.
|
||||
|
||||
## Creating Boxes via the Atlas Web Interface
|
||||
|
||||
You'll first need to create a box file. This can be done via
|
||||
the [vagrant `package` command](http://docs.vagrantup.com/v2/boxes/base.html)
|
||||
or with Packer locally.
|
||||
|
||||
After you've created the `.box` file, this guide can be followed.
|
||||
|
||||
1. Go to the [Create Box](/boxes/new) page.
|
||||
|
||||
1. Name the box and give it a simple description
|
||||
|
||||
1. Create your first version for the box. This version
|
||||
must match the format `[0-9].[0-9].[0-9]`
|
||||
|
||||
1. Create a provider for the box, matching the provider you need
|
||||
locally in Vagrant. `virtualbox` is the most common provider.
|
||||
|
||||
1. Upload the `.box` file for each provider, or use a url to the `.box`
|
||||
file that is publicly accessible
|
||||
|
||||
You can find all of your boxes in the [Vagrant section](/vagrant) of Atlas.
|
||||
|
||||
Once you've created and released a box, you can release new versions of
|
||||
the box by clicking "Create New Version" under the versions sidebar on
|
||||
a box page. For more information on the release lifecycle of boxes, see
|
||||
the [help page dedicated to box lifecycle](/help/boxes/lifecycle).
|
||||
|
||||
## Creating Boxes with the API
|
||||
|
||||
This example uses the [Boxes API](/docs) to upload boxes with `curl`. To
|
||||
get started, you'll need to get an [access token](/settings/tokens).
|
||||
|
||||
Then, prepare the upload:
|
||||
|
||||
$ curl 'https://atlas.hashicorp.com/api/v1/box/USERNAME/BOX_NAME/version/VERSION/provider/PROVIDER_NAME/upload?access_token=ACCESS_TOKEN'
|
||||
|
||||
This should return something like this:
|
||||
|
||||
{
|
||||
"upload_path": "https://archivist.hashicorp.com/v1/object/630e42d9-2364-2412-4121-18266770468e"
|
||||
}
|
||||
|
||||
Then, upload your box with the following command, with the filename in this case being `foo.box`:
|
||||
|
||||
$ curl -X PUT --upload-file foo.box https://archivist.hashicorp.com/v1/object/630e42d9-2364-2412-4121-18266770468e
|
||||
|
||||
When the upload finishes, you can verify it worked by making this request and matching the `hosted_token` it returns to the previously retrieved upload token.
|
||||
|
||||
$ curl 'https://atlas.hashicorp.com/api/v1/box/USERNAME/BOX_NAME/version/VERSION_NUMBER/provider/PROVIDER_NAME?access_token=ACCESS_TOKEN'
|
||||
|
||||
Your box should then be available for download.
|
||||
|
|
@ -0,0 +1,59 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Distributing Boxes"
|
||||
sidebar_current: "vagrant-cloud-boxes-distributing"
|
||||
---
|
||||
|
||||
## Distributing Boxes
|
||||
|
||||
To distribute the box to your team, update your Vagrantfile to reference the
|
||||
box on Atlas.
|
||||
|
||||
Vagrant.configure(2) do |config|
|
||||
config.vm.box = "ATLAS_USERNAME_HERE/example-box"
|
||||
end
|
||||
|
||||
Now when a team member runs `vagrant up`, the box will be downloaded from Atlas.
|
||||
If the box is private, the team member will be prompted to authorize access. Users
|
||||
are granted access to private resources by logging in with an Atlas username and
|
||||
password or by using a shared Atlas token.
|
||||
[Learn more about authorization options here](/help/user-accounts/authentication).
|
||||
|
||||
## Private Boxes
|
||||
|
||||
If you create a private box, only you (the owner) and collaborators
|
||||
will be able to access it. This is valuable if you
|
||||
have information, data or provisioning in your box
|
||||
that cannot be public.
|
||||
|
||||
Private boxes will be excluded from the box catalog.
|
||||
|
||||
### Collaborators
|
||||
|
||||
Collaborators can be both teams in
|
||||
organizations or individual users.
|
||||
|
||||
To add a collaborator:
|
||||
|
||||
1. Go to the "Access" page of a box via the sidebar
|
||||
2. Enter the username or team name and submit the form
|
||||
3. You'll now see an the user or team in the list of collaborators,
|
||||
and if necessary a collaborator can be removed
|
||||
|
||||
### Vagrant Login
|
||||
|
||||
In order to access these private boxes from Vagrant, you'll need to first
|
||||
authenticate with your Atlas account.
|
||||
|
||||
1. Run `vagrant login` (with [the latest version of Vagrant](/help/intro/updating-tools))
|
||||
2. Enter your credentials
|
||||
|
||||
You should now be logged in. We use these credentials to request
|
||||
a unique authentication token that is stored locally by Vagrant. Your
|
||||
username or password is never stored on your machine.
|
||||
|
||||
### 404 Not Found
|
||||
|
||||
If you don't authenticate, you will likely receive a `404 Not Found`
|
||||
error in Vagrant. We return a 404 for security reasons, so a potential
|
||||
attacker could not verify if a private box exists.
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "About Vagrant Boxes"
|
||||
sidebar_current: "vagrant-cloud-boxes"
|
||||
---
|
||||
|
||||
# About Vagrant Boxes
|
||||
|
||||
Boxes are the package format for [Vagrant](https://vagrantup.com) environments.
|
||||
A box can be used on any Vagrant-supported platform to bring up an identical
|
||||
working environment across a development team.
|
||||
|
||||
## Vagrant Box Creation and Versioning
|
||||
|
||||
Boxes support versioning so that members of your team using Vagrant can update
|
||||
the underlying box easily, and the people who create boxes can push fixes and
|
||||
communicate these fixes efficiently.
|
||||
|
||||
Atlas makes it easy to manage the versioning of boxes. Versioning boxes in
|
||||
Atlas allows for easy updates, transparent fixes, and clear communication in
|
||||
changes made. Learn more about the [box release lifecycle
|
||||
here](/docs/vagrant-cloud/boxes/lifecycle.html).
|
||||
|
||||
## Vagrant Box Catalog and Discovery
|
||||
|
||||
Atlas hosts a catalog of publically available Vagrant Boxes. These are boxes
|
||||
created by both HashiCorp and community contributions. You can find an owner of
|
||||
a box by selecting their username in the URL or on the box page.
|
||||
|
||||
Public Vagrant boxes let you get up-and-running quickly in unfamiliar
|
||||
environments. This is a popular way to set a base development environment
|
||||
launchable in a single command within an organization or community.
|
||||
|
|
@ -0,0 +1,47 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Box Versioning and Lifecycle"
|
||||
sidebar_current: "vagrant-cloud-boxes-lifecycle"
|
||||
---
|
||||
|
||||
# Box Versioning and Lifecycle
|
||||
|
||||
Boxes support versioning so that members of your team using Vagrant can
|
||||
update the underlying box easily, and the people who create boxes can
|
||||
push fixes and communicate these fixes efficiently.
|
||||
|
||||
There are multiple components of a box:
|
||||
|
||||
- The box itself, comprised of the box name and description.
|
||||
- One or more box versions.
|
||||
- One or more providers for each box version.
|
||||
|
||||
## Vagrant Messaging
|
||||
|
||||
Upon `vagrant up` or `vagrant box outdated`, an out-of-date box
|
||||
user will see the following message in Vagrant:
|
||||
|
||||
Bringing machine 'default' up with 'virtualbox' provider...
|
||||
==> default: Checking if box 'hashicorp/example' is up to date...
|
||||
==> default: A newer version of the box 'hashicorp/example' is available! You currently
|
||||
==> default: have version '0.0.5'. The latest is version '0.0.6'. Run
|
||||
==> default: `vagrant box update` to update.
|
||||
...
|
||||
|
||||
## Box Version Release States
|
||||
|
||||
Atlas lets you create new versions of boxes without
|
||||
releasing them or without Vagrant seeing the update. This lets you prepare
|
||||
a box for release slowly. Box versions have three states:
|
||||
|
||||
- `unreleased`: Vagrant cannot see this version yet, so it needs
|
||||
to be released. Versions can be released by editing them and clicking
|
||||
the release button at the top of the page
|
||||
- `active`: Vagrant is able to add and use this box version
|
||||
- `revoked`: Vagrant cannot see this version, and it cannot be re-released.
|
||||
You must create the version again
|
||||
|
||||
### Release Requirements
|
||||
|
||||
A box can only be released if it has at least one of each component: a
|
||||
box, a version, and a provider.
|
||||
|
|
@ -0,0 +1,44 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Private Boxes"
|
||||
sidebar_current: "vagrant-cloud-boxes-private"
|
||||
---
|
||||
|
||||
# Private Boxes
|
||||
|
||||
If you create a private box, only you (the owner) and collaborators
|
||||
will be able to access it.
|
||||
|
||||
## Collaborators
|
||||
|
||||
To add a collaborator:
|
||||
|
||||
1. Click the gear setting beside the boxes name in order to edit it.
|
||||
2. Under the "Add Collaborator" section, enter their username and
|
||||
submit the form.
|
||||
3. You'll now see a list of collaborators, and if necessary a collaborator
|
||||
can be removed.
|
||||
|
||||
Collaborators can edit the box, versions and providers. The only
|
||||
things they cannot do are:
|
||||
|
||||
- Add another collaborator
|
||||
- Delete the box
|
||||
|
||||
## Vagrant Login
|
||||
|
||||
In order to access these boxes from Vagrant, you'll need to first
|
||||
authenticate with your Atlas account.
|
||||
|
||||
1. Run `vagrant login`
|
||||
2. Enter your credentials
|
||||
|
||||
You should now be logged in. We use these credentials to request
|
||||
a unique authentication token that is stored locally by Vagrant. Your
|
||||
username or password is never stored on your machine.
|
||||
|
||||
## 404 Not Found
|
||||
|
||||
If you don't authenticate, you will likely receive a `404 Not Found`
|
||||
error in Vagrant. We return a 404 for security reasons, so a potential
|
||||
attacker could not verify if a private box exists.
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "API Release Workflow"
|
||||
sidebar_current: "vagrant-cloud-boxes-release-workflow"
|
||||
---
|
||||
|
||||
# API Release Workflow
|
||||
|
||||
Creating new boxes through their [release lifecycle](/help/boxes/lifecycle)
|
||||
is possible through the Atlas website, but you can also automate
|
||||
the task via the Atlas API.
|
||||
|
||||
1. Create box, or locate a boxes `tag`, like `hashicorp/precise64`
|
||||
2. After some event, like the end of a CI build, you may want to
|
||||
release a new version of the box. To do this, first use the API to
|
||||
create a new version with a version number and a short description
|
||||
of the changes
|
||||
3. Then, create any providers associated with the version, like
|
||||
`virtualbox`
|
||||
4. Once your system has made the necessary requests to the API and the
|
||||
version is ready, make a request to the `release` endpoint on the version
|
||||
5. The version should now be available to users of the box via
|
||||
the command `vagrant box outdated` or via the automated checks on
|
||||
`vagrant up`
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Finding and Using Boxes"
|
||||
sidebar_current: "vagrant-cloud-boxes-using"
|
||||
---
|
||||
|
||||
# Finding and Using Boxes
|
||||
|
||||
A primary use case of Atlas by HashiCorp is to be able to easily find
|
||||
boxes you can use with Vagrant that contain the technologies you need
|
||||
for a Vagrant environment. We've made it extremely easy to do that:
|
||||
|
||||
1. Go to the [Discover page](/discover)
|
||||
|
||||
2. Search for any box you want, or use the navigation on the left
|
||||
to see [featured](/discover/featured) boxes.
|
||||
|
||||
3. Once you find a box, click its name to learn more about it.
|
||||
|
||||
4. When you're ready to use it, copy the name, such as "hashicorp/precise64"
|
||||
and initialize your Vagrant project with `vagrant init hashicorp/precise64`.
|
||||
Or, if you already have a Vagrant project created, modify the Vagrantfile
|
||||
to use the box: `config.vm.box = "hashicorp/precise64"`
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Vagrant Enterprise"
|
||||
sidebar_current: "vagrant-cloud"
|
||||
---
|
||||
|
||||
# Vagrant Enterprise
|
||||
|
||||
Vagrant Enterprise provides the following features for Vagrant:
|
||||
|
||||
- [Vagrant Box Catalog](/docs/vagrant-cloud/boxes/catalog.html)
|
||||
- [Vagrant Box Creation](/docs/vagrant-cloud/boxes/create.html)
|
||||
- [Vagrant Box Versioning](/docs/vagrant-cloud/boxes/lifecycle.html)
|
||||
|
|
@ -214,6 +214,27 @@
|
|||
<li<%= sidebar_current("other-wsl") %>><a href="/docs/other/wsl.html">WSL</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
|
||||
<hr />
|
||||
|
||||
<li<%= sidebar_current("vagrant-cloud") %>>
|
||||
<a href="/docs/vagrant-cloud/">Vagrant Enterprise</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("vagrant-cloud-boxes") %>>
|
||||
<a href="/docs/vagrant-cloud/boxes/index.html">Boxes</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("vagrant-cloud-boxes-catalog") %>><a href="/docs/vagrant-cloud/boxes/catalog.html">Catalog</a></li>
|
||||
<li<%= sidebar_current("vagrant-cloud-boxes-create-x") %>><a href="/docs/vagrant-cloud/boxes/create.html">Creating a New Box</a></li>
|
||||
<li<%= sidebar_current("vagrant-cloud-boxes-create-version") %>><a href="/docs/vagrant-cloud/boxes/create-version.html">Creating a New Version</a></li>
|
||||
<li<%= sidebar_current("vagrant-cloud-boxes-distributing") %>><a href="/docs/vagrant-cloud/boxes/distributing.html">Distributing</a></li>
|
||||
<li<%= sidebar_current("vagrant-cloud-boxes-lifecycle") %>><a href="/docs/vagrant-cloud/boxes/lifecycle.html">Lifecycle</a></li>
|
||||
<li<%= sidebar_current("vagrant-cloud-boxes-private") %>><a href="/docs/vagrant-cloud/boxes/private.html">Private Boxes</a></li>
|
||||
<li<%= sidebar_current("vagrant-cloud-boxes-release-workflow") %>><a href="/docs/vagrant-cloud/boxes/release-workflow.html">Release Workflow</a></li>
|
||||
<li<%= sidebar_current("vagrant-cloud-boxes-using") %>><a href="/docs/vagrant-cloud/boxes/using.html">Finding & Using Boxes</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
<% end %>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue