Couchbase database plugin documentation (#9764)
This commit is contained in:
Tom Proctor
GitHub
parent
4d00aca0d8
commit
ba9d1b6fbf
|
|
@ -23,6 +23,7 @@ export default [
|
|||
category: 'databases',
|
||||
content: [
|
||||
'cassandra',
|
||||
'couchbase',
|
||||
'elasticdb',
|
||||
'influxdb',
|
||||
'hanadb',
|
||||
|
|
|
|||
|
|
@ -221,6 +221,7 @@ export default [
|
|||
category: 'databases',
|
||||
content: [
|
||||
'cassandra',
|
||||
'couchbase',
|
||||
'elasticdb',
|
||||
'hanadb',
|
||||
'influxdb',
|
||||
|
|
|
|||
|
|
@ -0,0 +1,86 @@
|
|||
---
|
||||
layout: api
|
||||
page_title: Couchbase - Database - Secrets Engines - HTTP API
|
||||
sidebar_title: Couchbase
|
||||
description: >-
|
||||
The Couchbase plugin for Vault's database secrets engine generates database
|
||||
credentials to access Couchbase servers.
|
||||
---
|
||||
|
||||
# Couchbase Database Plugin HTTP API
|
||||
|
||||
The Couchbase database plugin is one of the supported plugins for the database
|
||||
secrets engine. This plugin generates database credentials dynamically based on
|
||||
configured roles for the Couchbase database.
|
||||
|
||||
## Configure Connection
|
||||
|
||||
In addition to the parameters defined by the [Database
|
||||
Secrets Engine](/api-docs/secret/databases#configure-connection), this plugin
|
||||
has a number of parameters to further configure a connection.
|
||||
|
||||
| Method | Path |
|
||||
| :----- | :----------------------- |
|
||||
| `POST` | `/database/config/:name` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `hosts` `(string: <required>)` – Specifies a set of comma-delimited Couchbase
|
||||
hosts to connect to. Must use `couchbases://` scheme if `tls` is `true`.
|
||||
|
||||
- `username` `(string: <required>)` – Specifies the username for Vault to use.
|
||||
|
||||
- `password` `(string: <required>)` – Specifies the password corresponding to
|
||||
the given username.
|
||||
|
||||
- `tls` `(bool: false)` – Specifies whether to use TLS when connecting to
|
||||
Couchbase.
|
||||
|
||||
- `insecure_tls` `(bool: false)` – Specifies whether to skip verification of the
|
||||
server certificate when using TLS.
|
||||
|
||||
- `base64pem` `(string: "")` – Required if `tls` is `true`. Specifies the
|
||||
certificate authority of the Couchbase server, as a PEM certificate that has
|
||||
been base64 encoded.
|
||||
|
||||
- `bucket_name` `(string: "")` - Required for Couchbase versions prior to 6.5.0. This
|
||||
is only used to verify vault's connection to the server.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"plugin_name": "couchbase-database-plugin",
|
||||
"hosts": "couchbases://127.0.0.1",
|
||||
"username": "user",
|
||||
"password": "pass",
|
||||
"allowed-roles": "my-*-role"
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```bash
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
http://127.0.0.1:8200/v1/database/config/couchbase
|
||||
```
|
||||
|
||||
## Statements
|
||||
|
||||
Statements are configured during role creation and are used by the plugin to
|
||||
determine what is sent to the database on user creation, renewing, and
|
||||
revocation. For more information on configuring roles see the [Role
|
||||
API](/api/secret/databases#create-role) in the database secrets engine docs.
|
||||
|
||||
### Parameters
|
||||
|
||||
The following are the statements used by this plugin. If not mentioned in this
|
||||
list the plugin does not support that statement type.
|
||||
|
||||
- `creation_statements` `(list: [])` – Specifies a JSON string containing
|
||||
Couchbase RBAC roles to assign to created users. Any groups specified must
|
||||
already exist. Must be a single JSON string. If not provided, defaults to
|
||||
read-only admin.
|
||||
|
|
@ -0,0 +1,141 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Couchbase - Database - Secrets Engines
|
||||
sidebar_title: Couchbase
|
||||
description: |-
|
||||
Couchbase is one of the supported plugins for the database secrets engine.
|
||||
This plugin generates database credentials dynamically based on configured
|
||||
roles for the Couchbase database.
|
||||
---
|
||||
|
||||
# Couchbase Database Secrets Engine
|
||||
|
||||
Couchbase is one of the supported plugins for the database secrets engine. This
|
||||
plugin generates database credentials dynamically based on configured roles for
|
||||
the Couchbase database.
|
||||
|
||||
See the [database secrets engine](/docs/secrets/databases) docs for
|
||||
more information about setting up the database secrets engine.
|
||||
|
||||
## Capabilities
|
||||
| Plugin Name | Root Credential Rotation | Dynamic Roles | Static Roles |
|
||||
| --- | --- | --- | --- |
|
||||
| `couchbase-database-plugin` | Yes | Yes | Yes |
|
||||
|
||||
## Setup
|
||||
|
||||
1. Enable the database secrets engine if it is not already enabled:
|
||||
|
||||
```bash
|
||||
$ vault secrets enable database
|
||||
Success! Enabled the database secrets engine at: database/
|
||||
```
|
||||
|
||||
By default, the secrets engine will enable at the name of the engine. To
|
||||
enable the secrets engine at a different path, use the `-path` argument.
|
||||
|
||||
1. Configure Vault with the proper plugin and connection configuration:
|
||||
|
||||
```bash
|
||||
$ vault write database/config/my-couchbase-database \
|
||||
plugin_name="couchbase-database-plugin" \
|
||||
hosts="couchbases://127.0.0.1" \
|
||||
tls=true \
|
||||
base64pem="${BASE64PEM}" \
|
||||
username="vaultuser" \
|
||||
password="vaultpass" \
|
||||
allowed_roles="my-*-role"
|
||||
```
|
||||
|
||||
Where `${BASE64PEM}` is the server's root certificate authority in PEM
|
||||
format, encoded as a base64 string with no new lines.
|
||||
|
||||
To connect to clusters prior to version 6.5.0, a `bucket_name` must also
|
||||
be configured:
|
||||
|
||||
```bash
|
||||
$ vault write database/config/my-couchbase-database \
|
||||
plugin_name="couchbase-database-plugin" \
|
||||
hosts="couchbases://127.0.0.1" \
|
||||
tls=true \
|
||||
base64pem="${BASE64PEM}" \
|
||||
username="vaultuser" \
|
||||
password="vaultpass" \
|
||||
allowed_roles="my-*-role" \
|
||||
bucket_name="travel-sample"
|
||||
```
|
||||
|
||||
1. You should consider rotating the admin password. Note that if you do, the
|
||||
new password will never be made available through Vault, so you should
|
||||
create a Vault-specific database admin user for this.
|
||||
|
||||
```bash
|
||||
vault write -force database/rotate-root/my-couchbase-database
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
After the secrets engine is configured, configure dynamic and static roles
|
||||
to enable generating credentials.
|
||||
|
||||
### Dynamic roles
|
||||
|
||||
1. Configure a dynamic role that maps a name in Vault to a JSON string
|
||||
specifying a Couchbase RBAC role. The default value for
|
||||
`creation_statements` is a read-only admin role:
|
||||
`{"Roles": [{"role":"ro_admin"}]}`.
|
||||
|
||||
```bash
|
||||
$ vault write database/roles/my-dynamic-role \
|
||||
db_name="my-couchbase-database" \
|
||||
creation_statements='{"Roles": [{"role":"ro_admin"}]}' \
|
||||
default_ttl="5m" \
|
||||
max_ttl="1h"
|
||||
```
|
||||
|
||||
Note that any groups specified in the creation statement must already exist.
|
||||
|
||||
1. Generate a new credential by reading from the `/creds` endpoint with the name
|
||||
of the role:
|
||||
|
||||
```bash
|
||||
$ vault read database/creds/my-dynamic-role
|
||||
Key Value
|
||||
--- -----
|
||||
lease_id database/creds/my-dynamic-role/wiLNQjtcvCOT1VnN3qnUJnBz
|
||||
lease_duration 5m
|
||||
lease_renewable true
|
||||
password A1a-HjmYpYpN8xsHkXPM
|
||||
username v-root-my-dynamic-role-eXnVr4gm55dpM1EVgTYz-1596815027
|
||||
```
|
||||
|
||||
### Static roles
|
||||
|
||||
1. Configure a static role that maps a name in Vault to an existing couchbase
|
||||
user.
|
||||
|
||||
```bash
|
||||
$ vault write database/static-roles/my-static-role \
|
||||
db_name="my-couchbase-database" \
|
||||
username="my-existing-couchbase-user" \
|
||||
rotation_period=5m
|
||||
```
|
||||
|
||||
1. Retrieve the credentials from the `/static-creds` endpoint:
|
||||
|
||||
```bash
|
||||
$ vault read database/static-creds/my-static-role
|
||||
Key Value
|
||||
--- -----
|
||||
last_vault_rotation 2020-08-07T16:50:48.393354+01:00
|
||||
password A1a-NI9M2XMSYhqYG98b
|
||||
rotation_period 5m
|
||||
ttl 4m39s
|
||||
username my-existing-couchbase-user
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
The full list of configurable options can be seen in the [Couchbase database plugin API](/api-docs/secret/databases/couchbase) page.
|
||||
|
||||
For more information on the database secrets engine's HTTP API please see the [Database secret secrets engine API](/api-docs/secret/databases) page.
|
||||
|
|
@ -132,6 +132,7 @@ the proper permission, it can generate credentials.
|
|||
| Database | Root Credential Rotation | Dynamic Roles | Static Roles |
|
||||
| --- | --- | --- | --- |
|
||||
| [Cassandra](/docs/secrets/databases/cassandra) | Yes | Yes | No |
|
||||
| [Couchbase](/docs/secrets/databases/couchbase) | Yes | Yes | Yes |
|
||||
| [Elasticsearch](/docs/secrets/databases/elasticdb) | Yes | Yes | No |
|
||||
| [HanaDB](/docs/secrets/databases/hanadb) | No | Yes | No |
|
||||
| [InfluxDB](/docs/secrets/databases/influxdb) | Yes | Yes | No |
|
||||
|
|
|
|||
Loading…
Reference in New Issue