From 3603ef94cd0b66e5be60c8dab231d6b06d30a306 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Thu, 9 Apr 2015 22:52:02 -0700 Subject: [PATCH] website: lots more docs --- .../source/docs/commands/apply.html.markdown | 53 --------- .../docs/commands/destroy.html.markdown | 23 ---- .../source/docs/commands/get.html.markdown | 28 ----- website/source/docs/commands/index.html.md | 22 ++++ website/source/docs/http/index.html.md | 98 +++++++++++++++++ website/source/layouts/docs.erb | 57 +++------- website/source/layouts/http.erb | 103 ++++++++++++++++++ 7 files changed, 240 insertions(+), 144 deletions(-) delete mode 100644 website/source/docs/commands/apply.html.markdown delete mode 100644 website/source/docs/commands/destroy.html.markdown delete mode 100644 website/source/docs/commands/get.html.markdown create mode 100644 website/source/docs/commands/index.html.md create mode 100644 website/source/docs/http/index.html.md create mode 100644 website/source/layouts/http.erb diff --git a/website/source/docs/commands/apply.html.markdown b/website/source/docs/commands/apply.html.markdown deleted file mode 100644 index dc2cf1a033..0000000000 --- a/website/source/docs/commands/apply.html.markdown +++ /dev/null @@ -1,53 +0,0 @@ ---- -layout: "docs" -page_title: "Command: apply" -sidebar_current: "docs-commands-apply" -description: |- - The `vault apply` command is used to apply the changes required to reach the desired state of the configuration, or the pre-determined set of actions generated by a `vault plan` execution plan. ---- - -# Command: apply - -The `vault apply` command is used to apply the changes required -to reach the desired state of the configuration, or the pre-determined -set of actions generated by a `vault plan` execution plan. - -## Usage - -Usage: `vault apply [options] [dir]` - -By default, `apply` scans the current directory for the configuration -and applies the changes appropriately. However, a path to another configuration -or an execution plan can be provided. Execution plans can be used to only -execute a pre-determined set of actions. - -The `dir` argument can also be a [module source](/docs/modules/index.html). -In this case, `apply` behaves as though `init` were called with that -argument followed by an `apply` in the current directory. This is meant -as a shortcut for getting started. - -The command-line flags are all optional. The list of available flags are: - -* `-backup=path` - Path to the backup file. Defaults to `-state-out` with - the ".backup" extension. Disabled by setting to "-". - -* `-input=true` - Ask for input for variables if not directly set. - -* `-no-color` - Disables output with coloring. - -* `-refresh=true` - Update the state for each resource prior to planning - and applying. This has no effect if a plan file is given directly to - apply. - -* `-state=path` - Path to the state file. Defaults to "vault.tfstate". - -* `-state-out=path` - Path to write updated state file. By default, the - `-state` path will be used. - -* `-var 'foo=bar'` - Set a variable in the Vault configuration. This - flag can be set multiple times. - -* `-var-file=foo` - Set variables in the Vault configuration from - a file. If "vault.tfvars" is present, it will be automatically - loaded if this flag is not specified. - diff --git a/website/source/docs/commands/destroy.html.markdown b/website/source/docs/commands/destroy.html.markdown deleted file mode 100644 index 9b02c532ba..0000000000 --- a/website/source/docs/commands/destroy.html.markdown +++ /dev/null @@ -1,23 +0,0 @@ ---- -layout: "docs" -page_title: "Command: destroy" -sidebar_current: "docs-commands-destroy" -description: |- - The `vault destroy` command is used to destroy the Vault-managed infrastructure. ---- - -# Command: destroy - -The `vault destroy` command is used to destroy the Vault-managed -infrastructure. - -## Usage - -Usage: `vault destroy [options] [dir]` - -Infrastructure managed by Vault will be destroyed. This will ask for -confirmation before destroying. - -This command accepts all the flags that the -[apply command](/docs/commands/apply.html) accepts. If `-force` is -set, then the destroy confirmation will not be shown. diff --git a/website/source/docs/commands/get.html.markdown b/website/source/docs/commands/get.html.markdown deleted file mode 100644 index 31cb79fc9f..0000000000 --- a/website/source/docs/commands/get.html.markdown +++ /dev/null @@ -1,28 +0,0 @@ ---- -layout: "docs" -page_title: "Command: get" -sidebar_current: "docs-commands-get" -description: |- - The `vault get` command is used to download and update modules. ---- - -# Command: get - -The `vault get` command is used to download and update -[modules](/docs/modules/index.html). - -## Usage - -Usage: `vault get [options] [dir]` - -The modules are downloaded into a local `.vault` folder. This -folder should not be committed to version control. - -If a module is already downloaded and the `-update` flag is _not_ set, -Vault will do nothing. As a result, it is safe (and fast) to run this -command multiple times. - -The command-line flags are all optional. The list of available flags are: - -* `-update` - If specified, modules that are already downloaded will be - checked for updates and the updates will be downloaded if present. diff --git a/website/source/docs/commands/index.html.md b/website/source/docs/commands/index.html.md new file mode 100644 index 0000000000..2a2e534752 --- /dev/null +++ b/website/source/docs/commands/index.html.md @@ -0,0 +1,22 @@ +--- +layout: "docs" +page_title: "Commands (CLI)" +sidebar_current: "docs-commands" +description: |- + Vault can be controlled via a command-line interface. This page documents all the commands Vault accepts. +--- + +# Vault Commands (CLI) + +Vault is controlled via a very easy to use command-line interface (CLI). +Vault is only a single command-line application: `vault`. This application +then takes a subcommand such as "read" or "write". The complete list of +subcommands is in the navigation to the left. + +The Vault CLI is a well-behaved command line application. In erroneous cases, +a non-zero exit status will be returned. It also responds to `-h` and `--help` +as you'd most likely expect. + +To view a list of the available commands at any time, just run Vault +with no arguments. To get help for any specific subcommand, run the subcommand +with the `-h` argument. diff --git a/website/source/docs/http/index.html.md b/website/source/docs/http/index.html.md new file mode 100644 index 0000000000..629363e773 --- /dev/null +++ b/website/source/docs/http/index.html.md @@ -0,0 +1,98 @@ +--- +layout: "http" +page_title: "HTTP API" +sidebar_current: "docs-http" +description: |- + Vault has an HTTP API that can be used to control every aspect of Vault. +--- + +# HTTP API + +The Vault HTTP API gives you full access to Vault via HTTP. Every +aspect of Vault can be controlled via this API. The Vault CLI uses +the HTTP API to access Vault. + +## Version Prefix + +All API routes are prefixed with `/v1/`. + +This documentation is only for the v1 API. + +~> **Backwards compatibility:** At the current version, Vault does +not yet promise backwards compatibility even with the v1 prefix. We'll +remove this warning when this policy changes. We expect we'll reach API +stability by Vault 0.3. + +## Transport + +The API is expected to be accessed over a TLS connection at +all times, with a valid certificate that is verified by a well +behaved client. It is possible to disable TLS verification for +listeners, however, so API clients should expect to have to do both +depending on user settings. + +## Authentication + +Once the Vault is unsealed, every other operation requires +a _client token_. A user may have a client token explicitly. +The client token must be sent as the `token` cookie. + +Otherwise, a client token can be retrieved via +[authentication backends](#). + +Each authentication backend will have one or more unauthenticated +login endpoints. These endpoints can be reached without any authentication, +and are used for authentication itself. These endpoints are specific +to each authentication backend. + +Login endpoints for authentication backends that generate an identity +will be sent down with a `Set-Cookie` header. If you are using a +well-behaved HTTP client, then authentication information will +automatically be saved and sent to the Vault API. + +## Help + +To retrieve the help for any API within Vault, including mounted +backends, credential providers, etc. then append `?help=1` to any +URL. If you have valid permission to access the path, then the help text +will be returned with the following structure: + + { + "help": "help text" + } + +## Error Response + +A common JSON structure is always returned to return errors: + + { + "errors": [ + "message", + "another message" + ] + } + +This structure will be sent down for any HTTP status greater than +or equal to 400. + +## HTTP Status Codes + +The following HTTP status codes are used throughout the API. + +- `200` - Success with data. +- `204` - Success, no data returned. +- `400` - Invalid request, missing or invalid data. See the + "validation" section for more details on the error response. +- `401` - Unauthorized, your authentication details are either + incorrect or you don't have access to this feature. +- `404` - Invalid path. This can both mean that the path truly + doesn't exist or that you don't have permission to view a + specific path. We use 404 in some cases to avoid state leakage. +- `429` - Rate limit exceeded. Try again after waiting some period + of time. +- `500` - Internal server error. An internal error has occurred, + try again later. If the error persists, report a bug. +- `503` - Vault is down for maintenance or is currently sealed. + Try again later. + + diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 6809dffab9..56c4a08547 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -22,48 +22,25 @@ > Commands (CLI) + + + > + HTTP API + + + > + Secret Backends + diff --git a/website/source/layouts/http.erb b/website/source/layouts/http.erb new file mode 100644 index 0000000000..a83d4186c6 --- /dev/null +++ b/website/source/layouts/http.erb @@ -0,0 +1,103 @@ +<% wrap_layout :inner do %> + <% content_for :sidebar do %> + + <% end %> + + <%= yield %> +<% end %>