mirror of
https://github.com/hashicorp/vault.git
synced 2026-05-28 04:10:44 -04:00
Elaborate the correlation between CLI and API (#15056)
* Add command help info * Explain CLI and API correlation * Update the heading level * Updated the command example with more description * Update website/content/docs/commands/index.mdx Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * Update website/content/docs/commands/index.mdx Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * Update website/content/docs/commands/index.mdx Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * Incorporate review feedback Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com>
This commit is contained in:
Yoko Hyakuna
GitHub
parent
57edc4ff81
commit
19bbcc29ff
5 changed files with 263 additions and 137 deletions
|
|
@ -10,8 +10,8 @@ description: |-
|
|||
# delete
|
||||
|
||||
The `delete` command deletes secrets and configuration from Vault at the given
|
||||
path. The behavior of "delete" is delegated to the backend corresponding to the
|
||||
given path.
|
||||
path (wrapper command for HTTP DELETE). The behavior of "delete" is delegated to
|
||||
the backend corresponding to the given path.
|
||||
|
||||
## Examples
|
||||
|
||||
|
|
|
|||
|
|
@ -10,54 +10,39 @@ description: |-
|
|||
|
||||
# Vault Commands (CLI)
|
||||
|
||||
~> **Note:** The Vault CLI interface was changed substantially in 0.9.2+ and may cause
|
||||
confusion while using older versions of Vault with this documentation. Read our
|
||||
[upgrade guide](/docs/upgrading/upgrade-to-0.9.2#backwards-compatible-cli-changes) for more information.
|
||||
~> **Note:** The Vault command-line interface (CLI) changed substantially in
|
||||
0.9.2+ and may cause confusion while using older versions of Vault with this
|
||||
documentation. Read our [upgrade
|
||||
guide](/docs/upgrading/upgrade-to-0.9.2#backwards-compatible-cli-changes) for
|
||||
more information.
|
||||
|
||||
In addition to a verbose [HTTP API](/api), Vault features a
|
||||
command-line interface that wraps common functionality and formats output. The
|
||||
Vault CLI is a single static binary. It is a thin wrapper around the HTTP API.
|
||||
Every CLI command maps directly to the HTTP API internally.
|
||||
|
||||
Each command is represented as a command or subcommand. Please see the sidebar
|
||||
for more information about a particular command. This documentation corresponds
|
||||
to the latest version of Vault. If you are running an older version, commands
|
||||
may behave differently. Run `vault -h` or `vault <command> -h` to see the help
|
||||
output which corresponds to your version.
|
||||
|
||||
To get help, run:
|
||||
|
||||
```shell-session
|
||||
$ vault -h
|
||||
```
|
||||
|
||||
To get help for a subcommand, run:
|
||||
|
||||
```shell-session
|
||||
$ vault <subcommand> -h
|
||||
```
|
||||
|
||||
To see the equivalent API call required to perform the same operation, use the `-output-curl-string` flag after the subcommand.
|
||||
```shell-session
|
||||
vault auth enable -output-curl-string approle
|
||||
```
|
||||
In addition to a verbose [HTTP API](/api-docs), Vault features a command-line
|
||||
interface (CLI) that wraps common functionality and formats output. The Vault
|
||||
CLI is a single static binary. It is a thin wrapper around the HTTP API. Every
|
||||
CLI command maps directly to the HTTP API internally.
|
||||
|
||||
## CLI Command Structure
|
||||
|
||||
There are a number of command and subcommand options available: HTTP options,
|
||||
output options, and command specific options.
|
||||
Each command is represented as a command or subcommand, and there are a number
|
||||
of command and subcommand options available: HTTP options, output options, and
|
||||
command-specific options.
|
||||
|
||||
Construct your Vault CLI command such that the command options precede its path
|
||||
and arguments if any:
|
||||
|
||||
<CodeBlockConfig hideClipboard>
|
||||
|
||||
```text
|
||||
vault <command> [options] [path] [args]
|
||||
```
|
||||
|
||||
</CodeBlockConfig>
|
||||
|
||||
- `options` - [Flags](/docs/commands#flags) to specify additional settings
|
||||
- `args` - API arguments specific to the operation
|
||||
|
||||
-> **NOTE:** Run `vault path-help <path>` to see the list of args (parameters).
|
||||
-> **NOTE:** Use the [command help](#command-help) to display available options
|
||||
and arguments.
|
||||
|
||||
#### Examples:
|
||||
|
||||
|
|
@ -83,6 +68,144 @@ $ vault write -address="http://127.0.0.1:8200" -namespace="my-organization" \
|
|||
The options (flags) come after the command (or subcommand) preceding the path,
|
||||
and the args always follow the path to set API parameter values.
|
||||
|
||||
The four most common operations in Vault are [read](/docs/commands/read),
|
||||
[write](/docs/commands/write), [delete](/docs/commands/delete), and
|
||||
[list](/docs/commands/list). These operations work on most paths in Vault. Some
|
||||
paths will contain secrets while other paths may contain configuration. Whatever it
|
||||
is, the primary interface for reading and writing data to Vault is similar.
|
||||
|
||||
### Print cURL Command
|
||||
|
||||
To see the equivalent API call to perform the same operation, use the
|
||||
`-output-curl-string` flag after the subcommand.
|
||||
|
||||
```shell-session
|
||||
$ vault write -output-curl-string auth/userpass/users/bob password="long-password"
|
||||
|
||||
curl -X PUT -H "X-Vault-Request: true" -H "X-Vault-Token: $(vault print token)" -d '{"password":"long-password"}' http://127.0.0.1:8200/v1/auth/userpass/users/bob
|
||||
```
|
||||
|
||||
## Command Help
|
||||
|
||||
There are two primary ways to get help in Vault: [CLI help (`help`)](#cli-help)
|
||||
and [API help (`path-help`)](#api-help).
|
||||
|
||||
### CLI Help
|
||||
|
||||
Use `help` (or `-h` for shorthand) to see the CLI help output which corresponds
|
||||
to your Vault version.
|
||||
|
||||
To get CLI help:
|
||||
|
||||
```shell-session
|
||||
$ vault help
|
||||
```
|
||||
|
||||
**Example:** To get help on the `kv` command.
|
||||
|
||||
```shell-session
|
||||
$ vault kv help
|
||||
```
|
||||
|
||||
The help output displays available subcommands, parameters, and command flags.
|
||||
|
||||
### API Help
|
||||
|
||||
To invoke the Vault API paths, you can use the [read](/docs/commands/read) (for
|
||||
HTTP GET), [write](/docs/commands/write) (for HTTP PUT or POST),
|
||||
[delete](/docs/commands/delete) (for HTTP DELETE), and
|
||||
[list](/docs/commands/list) (for HTTP LIST) commands.
|
||||
|
||||
Use `path-help` to get Vault API help:
|
||||
|
||||
```shell-session
|
||||
$ vault path-help -h
|
||||
```
|
||||
|
||||
The `path-help` retrieves API help on any API paths. Vault API paths provide
|
||||
built-in help in markdown format. This includes system paths, secret engines,
|
||||
and auth methods.
|
||||
|
||||
**Example:** API help on the [`sys/mounts/`](/api-docs/system/mounts) path.
|
||||
|
||||
```shell-session
|
||||
$ vault path-help sys/mounts
|
||||
Request: mounts
|
||||
Matching Route: ^mounts$
|
||||
|
||||
List the currently mounted backends.
|
||||
|
||||
## DESCRIPTION
|
||||
|
||||
This path responds to the following HTTP methods.
|
||||
|
||||
GET /
|
||||
Lists all the mounted secret backends.
|
||||
|
||||
GET /<mount point>
|
||||
Get information about the mount at the specified path.
|
||||
|
||||
POST /<mount point>
|
||||
Mount a new secret backend to the mount point in the URL.
|
||||
|
||||
POST /<mount point>/tune
|
||||
Tune configuration parameters for the given mount point.
|
||||
|
||||
DELETE /<mount point>
|
||||
Unmount the specified mount point.
|
||||
```
|
||||
|
||||
The help output displays supported child-paths and available parameters if there
|
||||
are any.
|
||||
|
||||
## Command Input
|
||||
|
||||
To write data to Vault, the input can be a part of the command in key-value
|
||||
format.
|
||||
|
||||
```shell-session
|
||||
$ vault kv put secret/password value=itsasecret
|
||||
```
|
||||
|
||||
However, some Vault API require more advanced structures such as maps. You can
|
||||
use stdin or file input instead.
|
||||
|
||||
### stdin
|
||||
|
||||
Some commands in Vault can read data from stdin using `-` as the value. If `-`
|
||||
is the entire argument, Vault expects to read a JSON object from stdin:
|
||||
|
||||
```shell-session
|
||||
$ echo -n '{"value":"itsasecret"}' | vault kv put secret/password -
|
||||
```
|
||||
|
||||
In addition to reading full JSON objects, Vault can read just a value from
|
||||
stdin:
|
||||
|
||||
```shell-session
|
||||
$ echo -n "itsasecret" | vault kv put secret/password value=-
|
||||
```
|
||||
|
||||
### Files
|
||||
|
||||
Some commands can also read data from a file on disk. The usage is similar to
|
||||
stdin as documented above. If an argument starts with `@`, Vault will read it as
|
||||
a file:
|
||||
|
||||
```shell-session
|
||||
$ vault kv put secret/password @data.json
|
||||
```
|
||||
|
||||
Or specify the contents of a file as a value:
|
||||
|
||||
```shell-session
|
||||
$ vault kv put secret/password value=@data.txt
|
||||
```
|
||||
|
||||
Note that if an argument is supplied in a @key=value format, Vault will treat that as a
|
||||
kv pair with the key being `@key`, not a file called `key=value`. This also means that Vault
|
||||
does not support filenames with `=` in them.
|
||||
|
||||
## Exit Codes
|
||||
|
||||
The Vault CLI aims to be consistent and well-behaved unless documented
|
||||
|
|
@ -116,83 +239,6 @@ list of available completions. Type `-<tab>` to show available flag completions.
|
|||
If the `VAULT_*` environment variables are set, the autocompletion will
|
||||
automatically query the Vault server and return helpful argument suggestions.
|
||||
|
||||
## Reading and Writing Data
|
||||
|
||||
The four most common operations in Vault are `read`, `write`, `delete`, and
|
||||
`list`. These operations work on most paths in Vault. Some paths will
|
||||
contain secrets, other paths might contain configuration. Whatever it is, the
|
||||
primary interface for reading and writing data to Vault is similar.
|
||||
|
||||
To demonstrate basic read and write operations, the built-in key/value (K/V)
|
||||
secrets engine will be used. This engine is automatically mounted and has no
|
||||
external dependencies, making it practical for this introduction. Note that
|
||||
K/V uses slightly different commands for reading and writing: `kv get`
|
||||
and `kv put`, respectively.
|
||||
|
||||
~> The original version of K/V used the common `read` and `write` operations.
|
||||
A more advanced K/V Version 2 engine was released in Vault 0.10 and introduced
|
||||
the `kv get` and `kv put` commands.
|
||||
|
||||
### Writing Data
|
||||
|
||||
To write data to Vault, use the `vault kv put` command:
|
||||
|
||||
```shell-session
|
||||
$ vault kv put secret/password value=itsasecret
|
||||
```
|
||||
|
||||
For some secrets engines, the key/value pairs are arbitrary. For others, they
|
||||
are generally more strict. Vault's built-in help will guide you to these
|
||||
restrictions where appropriate.
|
||||
|
||||
#### stdin
|
||||
|
||||
Some commands in Vault can read data from stdin using `-` as the value. If `-`
|
||||
is the entire argument, Vault expects to read a JSON object from stdin:
|
||||
|
||||
```shell-session
|
||||
$ echo -n '{"value":"itsasecret"}' | vault kv put secret/password -
|
||||
```
|
||||
|
||||
In addition to reading full JSON objects, Vault can read just a value from
|
||||
stdin:
|
||||
|
||||
```shell-session
|
||||
$ echo -n "itsasecret" | vault kv put secret/password value=-
|
||||
```
|
||||
|
||||
#### Files
|
||||
|
||||
Some commands can also read data from a file on disk. The usage is similar to
|
||||
stdin as documented above. If an argument starts with `@`, Vault will read it as
|
||||
a file:
|
||||
|
||||
```shell-session
|
||||
$ vault kv put secret/password @data.json
|
||||
```
|
||||
|
||||
Or specify the contents of a file as a value:
|
||||
|
||||
```shell-session
|
||||
$ vault kv put secret/password value=@data.txt
|
||||
```
|
||||
|
||||
Note that if an argument is supplied in a @key=value format, Vault will treat that as a
|
||||
kv pair with the key being `@key`, not a file called `key=value`. This also means that Vault
|
||||
does not support filenames with `=` in them.
|
||||
|
||||
### Reading Data
|
||||
|
||||
After data is persisted, read it back using `vault kv get`:
|
||||
|
||||
```shell-session
|
||||
$ vault kv get secret/password
|
||||
Key Value
|
||||
--- -----
|
||||
refresh_interval 768h0m0s
|
||||
value itsasecret
|
||||
```
|
||||
|
||||
## Token Helper
|
||||
|
||||
By default, the Vault CLI uses a "token helper" to cache the token after
|
||||
|
|
@ -257,7 +303,7 @@ Provide Vault output (read/status/write) in the specified format. Valid formats
|
|||
|
||||
### `VAULT_LICENSE`
|
||||
|
||||
[Enterprise, Server only] Specify a license to use for this node. This takes
|
||||
[Enterprise, Server only] Specify a license to use for this node. This takes
|
||||
precedence over [#VAULT_LICENSE_PATH](#vault_license_path) and
|
||||
[license_path in config](/docs/configuration#license_path).
|
||||
|
||||
|
|
|
|||
|
|
@ -8,15 +8,15 @@ description: |-
|
|||
|
||||
# list
|
||||
|
||||
The `list` command lists data from Vault at the given path. This can be used to
|
||||
list keys in a given secrets engine.
|
||||
The `list` command lists data from Vault at the given path (wrapper command for
|
||||
HTTP LIST). This can be used to list keys in a given secrets engine.
|
||||
|
||||
## Examples
|
||||
|
||||
List values under the "my-app" folder of the KV secrets engine:
|
||||
List available entities by their identifiers:
|
||||
|
||||
```shell-session
|
||||
$ vault list secret/my-app/
|
||||
$ vault list identity/entity/id
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
|
|
|||
|
|
@ -9,24 +9,55 @@ description: |-
|
|||
|
||||
# read
|
||||
|
||||
The `read` command reads data from Vault at the given path. This can be used to
|
||||
read secrets, generate dynamic credentials, get configuration details, and more.
|
||||
|
||||
For a full list of examples and paths, please see the documentation that
|
||||
corresponds to the secrets engine in use.
|
||||
The `read` command reads data from Vault at the given path (wrapper command for
|
||||
HTTP GET). You can use the command to read secrets, generate dynamic
|
||||
credentials, get configuration details, and more.
|
||||
|
||||
## Examples
|
||||
|
||||
Read a secret from the static secrets engine:
|
||||
Read entity details of a given ID:
|
||||
|
||||
```shell-session
|
||||
$ vault read secret/my-secret
|
||||
Key Value
|
||||
--- -----
|
||||
refresh_interval 768h
|
||||
foo bar
|
||||
$ vault read identity/entity/id/2f09126d-d161-abb8-2241-555886491d97
|
||||
```
|
||||
|
||||
Generate dynamic AWS credentials for a `my-role`:
|
||||
|
||||
```shell-session
|
||||
$ vault read aws/creds/my-role
|
||||
```
|
||||
|
||||
### API versus CLI
|
||||
|
||||
Assuming that you have K/V version 2 (`kv-v2`) secrets engine enabled at
|
||||
`secret/`, the following command reads secrets at the `secret/data/customers`
|
||||
API path:
|
||||
|
||||
```shell-session
|
||||
$ vault read secret/data/customers
|
||||
```
|
||||
|
||||
This is equivalent to:
|
||||
|
||||
```shell-session
|
||||
$ curl --request GET --header "X-Vault-Token: $VAULT_TOKEN" \
|
||||
$VAULT_ADDR/v1/secret/data/customers
|
||||
```
|
||||
|
||||
Since K/V secrets engine is a commonly used feature, Vault CLI provides the
|
||||
[`kv`](/docs/commands/kv) command. Read secrets from the `secret/data/customers`
|
||||
path using the `kv` CLI command:
|
||||
|
||||
```shell-session
|
||||
$ vault kv get secret/customers
|
||||
```
|
||||
|
||||
-> **Comparison:** All three commands retrieve the same data, but display the
|
||||
output in a different format. By default, `vault read` prints output in
|
||||
key-value format. The `curl` command prints the response in JSON. Since the
|
||||
`kv` command is designed to handle operations associated with K/V secrets
|
||||
engine, it prints the output in more structured format that is easy to read.
|
||||
|
||||
## Usage
|
||||
|
||||
The following flags are available in addition to the [standard set of
|
||||
|
|
@ -41,3 +72,6 @@ flags](/docs/commands) included on all commands.
|
|||
- `-format` `(string: "table")` - Print the output in the given format. Valid
|
||||
formats are "table", "json", or "yaml". This can also be specified via the
|
||||
`VAULT_FORMAT` environment variable.
|
||||
|
||||
For a full list of examples and paths, please see the documentation that
|
||||
corresponds to the secrets engine in use.
|
||||
|
|
|
|||
|
|
@ -9,12 +9,13 @@ description: |-
|
|||
|
||||
# write
|
||||
|
||||
The `write` command writes data to Vault at the given path. The data can be
|
||||
credentials, secrets, configuration, or arbitrary data. The specific behavior of
|
||||
this command is determined at the thing mounted at the path.
|
||||
The `write` command writes data to Vault at the given path (wrapper command for
|
||||
HTTP PUT or POST). The data can be credentials, secrets, configuration, or
|
||||
arbitrary data. The specific behavior of the `write` command is determined at
|
||||
the thing mounted at the path.
|
||||
|
||||
Data is specified as "key=value" pairs on the command line. If the value begins
|
||||
with an "@", then it is loaded from a file. If the value for a key is "-", Vault
|
||||
Data is specified as "**key=value**" pairs on the command line. If the value begins
|
||||
with an "**@**", then it is loaded from a file. If the value for a key is "**-**", Vault
|
||||
will read the value from stdin rather than the command line.
|
||||
|
||||
Some API fields require more advanced structures such as maps. These cannot
|
||||
|
|
@ -29,18 +30,21 @@ corresponds to the secrets engines in use.
|
|||
|
||||
## Examples
|
||||
|
||||
Persist data in the KV secrets engine:
|
||||
Store an arbitrary secrets in the token's cubbyhole.
|
||||
|
||||
```shell-session
|
||||
$ vault write secret/my-secret foo=bar
|
||||
$ vault write cubbyhole/git-credentials username="student01" password="p@$$w0rd"
|
||||
```
|
||||
|
||||
Create a new encryption key in the transit secrets engine:
|
||||
|
||||
```shell-session
|
||||
$ vault write -f transit/keys/my-key
|
||||
$ vault write -force transit/keys/my-key
|
||||
```
|
||||
|
||||
The `-force` flag allows the write operation without input data. (See [command
|
||||
options](#command-options).)
|
||||
|
||||
Upload an AWS IAM policy from a file on disk:
|
||||
|
||||
```shell-session
|
||||
|
|
@ -53,6 +57,48 @@ Configure access to Consul by providing an access token:
|
|||
$ echo $MY_TOKEN | vault write consul/config/access token=-
|
||||
```
|
||||
|
||||
### API versus CLI
|
||||
|
||||
Create a token with TTL set to 8 hours, limited to 3 uses, and attach `admin`
|
||||
and `secops` policies.
|
||||
|
||||
```shell-session
|
||||
$ vault write auth/token/create policies="admin" policies="secops" ttl=8h num_uses=3
|
||||
```
|
||||
|
||||
Equivalent cURL command for this operation:
|
||||
|
||||
```shell-session
|
||||
$ tee request_payload.json -<<EOF
|
||||
{
|
||||
"policies": ["admin", "secops"],
|
||||
"ttl": "8h",
|
||||
"num_uses": 3
|
||||
}
|
||||
EOF
|
||||
|
||||
$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
|
||||
--request POST \
|
||||
--data @request_payload.json \
|
||||
$VAULT_ADDR/v1/auth/token/create
|
||||
```
|
||||
|
||||
The `vault write` command simplifies the API call.
|
||||
|
||||
Since token management is a common task, Vault CLI provides a
|
||||
[`token`](/docs/commands/token) command with
|
||||
[`create`](/docs/commands/token/create) subcommand. The CLI command simplifies
|
||||
the token creation. Use the `vault create` command with options to set the token
|
||||
TTL, policies, and use limit.
|
||||
|
||||
```shell-session
|
||||
$ vault token create -policy=admin -policy=secops -ttl=8h -use-limit=3
|
||||
```
|
||||
|
||||
-> **Syntax:** The command options start with `-` (e.g. `-ttl`) while API path
|
||||
parameters do not (e.g. `ttl`). You always set the API parameters after the path
|
||||
you are invoking.
|
||||
|
||||
## Usage
|
||||
|
||||
The following flags are available in addition to the [standard set of
|
||||
|
|
@ -72,4 +118,4 @@ flags](/docs/commands) included on all commands.
|
|||
|
||||
- `-force` `(bool: false)` - Allow the operation to continue with no key=value
|
||||
pairs. This allows writing to keys that do not need or expect data. This is
|
||||
aliased as "-f".
|
||||
aliased as `-f`.
|
||||
|
|
|
|||
Loading…
Reference in a new issue