Skip to content

Commit

Permalink
Update docs to match running builtins as plugins (#5727)
Browse files Browse the repository at this point in the history
  • Loading branch information
Becca Petrin authored Nov 14, 2018
1 parent e81948d commit c17ec38
Show file tree
Hide file tree
Showing 15 changed files with 134 additions and 77 deletions.
10 changes: 0 additions & 10 deletions website/source/api/system/auth.html.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,9 +84,6 @@ For example, enable the "foo" auth method will make it accessible at
- `max_lease_ttl` `(string: "")` - The maximum lease duration, specified as a
string duration like "5s" or "30m".

- `plugin_name` `(string: "")` - The name of the plugin in the plugin catalog
to use.

- `audit_non_hmac_request_keys` `(array: [])` - Comma-separated list of keys
that will not be HMAC'd by audit devices in the request data object.

Expand All @@ -99,13 +96,6 @@ For example, enable the "foo" auth method will make it accessible at
- `passthrough_request_headers` `(array: [])` - Comma-separated list of headers
to whitelist and pass from the request to the backend.

The plugin_name can be provided in the config map or as a top-level option,
with the former taking precedence.

- `plugin_name` `(string: "")` – Specifies the name of the auth plugin to
use based from the name in the plugin catalog. Applies only to plugin
methods.

Additionally, the following options are allowed in Vault open-source, but
relevant functionality is only supported in Vault Enterprise:

Expand Down
17 changes: 3 additions & 14 deletions website/source/api/system/mounts.html.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,6 @@ $ curl \
"default_lease_ttl": 0,
"max_lease_ttl": 0,
"force_no_cache": false,
"plugin_name": "",
"seal_wrap": false
}
},
Expand All @@ -49,7 +48,6 @@ $ curl \
"default_lease_ttl": 0,
"max_lease_ttl": 0,
"force_no_cache": false,
"plugin_name": "",
"seal_wrap": false
}
}
Expand Down Expand Up @@ -89,9 +87,6 @@ This endpoint enables a new secrets engine at the given path.

- `force_no_cache` `(bool: false)` - Disable caching.

- `plugin_name` `(string: "")` - The name of the plugin in the plugin catalog
to use.

- `audit_non_hmac_request_keys` `(array: [])` - Comma-separated list of keys
that will not be HMAC'd by audit devices in the request data object.

Expand All @@ -105,11 +100,9 @@ This endpoint enables a new secrets engine at the given path.
- `passthrough_request_headers` `(array: [])` - Comma-separated list of headers
to whitelist and pass from the request to the backend.

These control the default and maximum lease time-to-live, force
disabling backend caching, and option plugin name for plugin backends
respectively. The first three options override the global defaults if
set on a specific mount. The plugin_name can be provided in the config
map or as a top-level option, with the former taking precedence.
These control the default and maximum lease time-to-live, and the force
disabling backend caching. They override the global defaults if
set on a specific mount.

When used with supported seals (`pkcs11`, `awskms`, etc.), `seal_wrap`
causes key material for supporting mounts to be wrapped by the seal's
Expand All @@ -123,10 +116,6 @@ This endpoint enables a new secrets engine at the given path.
- `version` `(string: "1")` - The version of the KV to mount. Set to "2" for mount
KV v2.

- `plugin_name` `(string: "")` – Specifies the name of the plugin to
use based from the name in the plugin catalog. Applies only to plugin
backends.

Additionally, the following options are allowed in Vault open-source, but
relevant functionality is only supported in Vault Enterprise:

Expand Down
88 changes: 72 additions & 16 deletions website/source/api/system/plugins-catalog.html.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,24 +9,23 @@ description: |-

# `/sys/plugins/catalog`

The `/sys/plugins/catalog` endpoint is used to list, register, update, and
The `/sys/plugins/catalog` endpoint is used to read, register, update, and
remove plugins in Vault's catalog. Plugins must be registered before use, and
once registered backends can use the plugin by querying the catalog.

## List Plugins
## LIST Plugins

This endpoint lists the plugins in the catalog.
This endpoint lists the plugins in the catalog by type.

| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/sys/plugins/catalog` | `200 application/json` |
| `GET` | `/sys/plugins/catalog` | `200 application/json` |

### Sample Request

```
$ curl \
--header "X-Vault-Token: ..." \
--request LIST
http://127.0.0.1:8200/v1/sys/plugins/catalog
```

Expand All @@ -35,11 +34,59 @@ $ curl \
```javascript
{
"data": {
"keys": [
"auth": [
"aws",
"azure",
"custom-auth-plugin",
"gcp",
"ldap"
],
"database": [
"cassandra-database-plugin",
"mssql-database-plugin",
"mysql-database-plugin",
"postgresql-database-plugin"
],
"secret": [
"ad",
"aws",
"azure",
"gcp",
"transit"
]
}
}
```
## LIST Plugins

This endpoint lists the plugins in the catalog by type.

| Method | Path | Produces |
| :------- | :-------------------------------- | :--------------------- |
| `LIST` | `/sys/plugins/catalog/auth` | `200 application/json` |
| `LIST` | `/sys/plugins/catalog/database` | `200 application/json` |
| `LIST` | `/sys/plugins/catalog/secret` | `200 application/json` |

### Sample Request

```
$ curl \
--header "X-Vault-Token: ..." \
--request LIST
http://127.0.0.1:8200/v1/sys/plugins/catalog/auth
```

### Sample Response

```javascript
{
"data": {
"keys": [
"aws",
"azure",
"custom-auth-plugin",
"gcp",
"ldap"
]
}
}
Expand All @@ -53,15 +100,18 @@ supplied name.
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
any path-specific capabilities.

| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `PUT` | `/sys/plugins/catalog/:name` | `204 (empty body)` |
| Method | Path | Produces |
| :------- | :--------------------------------- | :--------------------- |
| `PUT` | `/sys/plugins/catalog/:type/:name` | `204 (empty body)` |

### Parameters

- `name` `(string: <required>)` – Specifies the name for this plugin. The name
is what is used to look up plugins in the catalog. This is part of the request
URL.

- `type` `(string: <required>)` – Specifies the type of this plugin. May be
"auth", "database", or "secret".

- `sha256` `(string: <required>)` – This is the SHA256 sum of the plugin's
binary. Before a plugin is run it's SHA will be checked against this value, if
Expand Down Expand Up @@ -94,7 +144,7 @@ $ curl \
--header "X-Vault-Token: ..." \
--request PUT \
--data @payload.json \
http://127.0.0.1:8200/v1/sys/plugins/catalog/example-plugin
http://127.0.0.1:8200/v1/sys/plugins/catalog/secret/example-plugin
```

## Read Plugin
Expand All @@ -104,22 +154,25 @@ This endpoint returns the configuration data for the plugin with the given name.
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
any path-specific capabilities.

| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `GET` | `/sys/plugins/catalog/:name` | `200 application/json` |
| Method | Path | Produces |
| :------- | :--------------------------------- | :--------------------- |
| `GET` | `/sys/plugins/catalog/:type/:name` | `200 application/json` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the plugin to retrieve.
This is part of the request URL.

- `type` `(string: <required>)` – Specifies the type of this plugin. May be
"auth", "database", or "secret".

### Sample Request

```
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/sys/plugins/catalog/example-plugin
http://127.0.0.1:8200/v1/sys/plugins/catalog/secret/example-plugin
```

### Sample Response
Expand All @@ -144,18 +197,21 @@ This endpoint removes the plugin with the given name.

| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `DELETE` | `/sys/plugins/catalog/:name` | `204 (empty body)` |
| `DELETE` | `/sys/plugins/catalog/:type/:name` | `204 (empty body)` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the plugin to delete.
This is part of the request URL.

- `type` `(string: <required>)` – Specifies the type of this plugin. May be
"auth", "database", or "secret".

### Sample Request

```
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/sys/plugins/catalog/example-plugin
http://127.0.0.1:8200/v1/sys/plugins/catalog/secret/example-plugin
```
4 changes: 2 additions & 2 deletions website/source/docs/auth/azure.html.md
Original file line number Diff line number Diff line change
Expand Up @@ -177,15 +177,15 @@ for your server at `path/to/plugins`:
1. Enable the plugin in the catalog:
```text
$ vault write sys/plugins/catalog/azure-auth \
$ vault write sys/plugins/catalog/auth/azure-auth \
command="vault-plugin-auth-azure" \
sha256="..."
```
1. Enable the azure auth method as a plugin:
```text
$ vault auth enable -path=azure -plugin-name=azure-auth plugin
$ vault auth enable -path=azure azure-auth
```
## API
Expand Down
3 changes: 0 additions & 3 deletions website/source/docs/commands/auth/enable.html.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,3 @@ flags](/docs/commands/index.html) included on all commands.
- `-path` `(string: "")` - Place where the auth method will be accessible. This
must be unique across all auth methods. This defaults to the "type" of the
auth method. The auth method will be accessible at `/auth/<path>`.

- `-plugin-name` `(string: "")` - Name of the auth method plugin. This plugin
name must already exist in the Vault server's plugin catalog.
5 changes: 3 additions & 2 deletions website/source/docs/commands/plugin/deregister.html.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,15 @@ description: |-
# plugin deregister

The `plugin deregister` command deregisters an existing plugin from Vault's
plugin catalog. If the plugin does not exist, no error is returned.
plugin catalog. If the plugin does not exist, no error is returned. The plugin's
type of "auth", "database", or "secret" must be included.

## Examples

Deregister a plugin:

```text
$ vault plugin deregister my-custom-plugin
$ vault plugin deregister auth my-custom-plugin
Success! Deregistered plugin (if it was registered): my-custom-plugin
```

Expand Down
3 changes: 2 additions & 1 deletion website/source/docs/commands/plugin/info.html.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,14 @@ description: |-
# plugin info

The `plugin info` displays information about a plugin in the catalog.
The plugin's type of "auth", "database", or "secret" must be included.

## Examples

Display information about a plugin

```text
$ vault plugin info my-custom-plugin
$ vault plugin info auth my-custom-plugin
Key Value
--- -----
Expand Down
7 changes: 7 additions & 0 deletions website/source/docs/commands/plugin/list.html.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ description: |-
# plugin list

The `plugin list` command lists all available plugins in the plugin catalog.
It can be used alone or with a type such as "auth", "database", or "secret".

## Examples

Expand All @@ -22,6 +23,12 @@ Plugins
-------
my-custom-plugin
# ...
$ vault plugin list database
Plugins
-------
cassandra-database-plugin
# ...
```

## Usage
Expand Down
5 changes: 3 additions & 2 deletions website/source/docs/commands/plugin/register.html.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ description: |-
# plugin register

The `plugin register` command registers a new plugin in Vault's plugin catalog.
The plugin's type of "auth", "database", or "secret" must be included.

## Examples

Expand All @@ -19,7 +20,7 @@ Register a plugin:
```text
$ vault plugin register \
-sha256=d3f0a8be02f6c074cf38c9c99d4d04c9c6466249 \
my-custom-plugin
auth my-custom-plugin
Success! Registered plugin: my-custom-plugin
```

Expand All @@ -29,7 +30,7 @@ Register a plugin with custom args:
$ vault plugin register \
-sha256=d3f0a8be02f6c074cf38c9c99d4d04c9c6466249 \
-args=--with-glibc,--with-curl-bindings \
my-custom-plugin
auth my-custom-plugin
```

## Usage
Expand Down
5 changes: 1 addition & 4 deletions website/source/docs/commands/secrets/enable.html.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ $ vault secrets enable -max-lease-ttl=30m database
Enable a custom plugin (after it is registered in the plugin registry):

```text
$ vault secrets enable -path=my-secrets -plugin-name=my-plugin plugin
$ vault secrets enable -path=my-secrets my-plugin
```

For more information on the specific configuration options and paths, please see
Expand Down Expand Up @@ -84,6 +84,3 @@ flags](/docs/commands/index.html) included on all commands.
- `-path` `(string: "")` Place where the secrets engine will be accessible. This
must be unique cross all secrets engines. This defaults to the "type" of the
secrets engine.

- `-plugin-name` `(string: "")` - Name of the secrets engine plugin. This plugin
name must already exist in Vault's plugin catalog.
Loading

0 comments on commit c17ec38

Please sign in to comment.