From 19bbcc29ff076f323c7e345a5c8484f89f339c00 Mon Sep 17 00:00:00 2001 From: Yoko Hyakuna Date: Thu, 21 Apr 2022 09:17:24 -0700 Subject: [PATCH] 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> --- website/content/docs/commands/delete.mdx | 4 +- website/content/docs/commands/index.mdx | 268 +++++++++++++---------- website/content/docs/commands/list.mdx | 8 +- website/content/docs/commands/read.mdx | 56 ++++- website/content/docs/commands/write.mdx | 64 +++++- 5 files changed, 263 insertions(+), 137 deletions(-) diff --git a/website/content/docs/commands/delete.mdx b/website/content/docs/commands/delete.mdx index c40d30e3c7..75bebffe3a 100644 --- a/website/content/docs/commands/delete.mdx +++ b/website/content/docs/commands/delete.mdx @@ -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 diff --git a/website/content/docs/commands/index.mdx b/website/content/docs/commands/index.mdx index 22d76a8c11..14df297707 100644 --- a/website/content/docs/commands/index.mdx +++ b/website/content/docs/commands/index.mdx @@ -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 -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 -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: + + ```text vault [options] [path] [args] ``` + + - `options` - [Flags](/docs/commands#flags) to specify additional settings - `args` - API arguments specific to the operation - -> **NOTE:** Run `vault path-help ` 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 / + Get information about the mount at the specified path. + + POST / + Mount a new secret backend to the mount point in the URL. + + POST //tune + Tune configuration parameters for the given mount point. + + DELETE / + 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 `-` 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). diff --git a/website/content/docs/commands/list.mdx b/website/content/docs/commands/list.mdx index 3f8c5ac5cb..dce32d7b5d 100644 --- a/website/content/docs/commands/list.mdx +++ b/website/content/docs/commands/list.mdx @@ -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 diff --git a/website/content/docs/commands/read.mdx b/website/content/docs/commands/read.mdx index 4089739655..5d72cdb735 100644 --- a/website/content/docs/commands/read.mdx +++ b/website/content/docs/commands/read.mdx @@ -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. diff --git a/website/content/docs/commands/write.mdx b/website/content/docs/commands/write.mdx index 9296de7bed..6ced095210 100644 --- a/website/content/docs/commands/write.mdx +++ b/website/content/docs/commands/write.mdx @@ -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 -< **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`.