diff --git a/website/pages/api-docs/secret/databases/redshift.mdx b/website/pages/api-docs/secret/databases/redshift.mdx new file mode 100644 index 000000000000..ea6404505df5 --- /dev/null +++ b/website/pages/api-docs/secret/databases/redshift.mdx @@ -0,0 +1,117 @@ +--- +layout: api +page_title: Redshift - Database - Secrets Engines - HTTP API +sidebar_title: Redshift +description: >- + The Redshift plugin for Vault's database secrets engine generates database + credentials to access the AWS Redshift service. +--- + +# Redshift Database Plugin HTTP API + +The Redshift 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 Redshift database. + +## Configure Connection + +In addition to the parameters defined by the [Database +Backend](/api/secret/databases#configure-connection), this plugin +has a number of parameters to further configure a connection. + +| Method | Path | +| :----- | :----------------------- | +| `POST` | `/database/config/:name` | + +### Parameters + +- `connection_url` `(string: )` - Specifies the Redshift DSN. This field + can be templated and supports passing the username and password + parameters in the following format {{field_name}}. A templated connection URL is + required when using root credential rotation. + +- `max_open_connections` `(int: 4)` - Specifies the maximum number of open + connections to the database. + +- `max_idle_connections` `(int: 0)` - Specifies the maximum number of idle + connections to the database. A zero uses the value of `max_open_connections` + and a negative value disables idle connections. If larger than + `max_open_connections` it will be reduced to be equal. + +- `max_connection_lifetime` `(string: "0s")` - Specifies the maximum amount of + time a connection may be reused. If <= 0s connections are reused forever. + +- `username` `(string: "")` - The root credential username used in the connection URL. + +- `password` `(string: "")` - The root credential password used in the connection URL. + +### Sample Payload + +```json +{ + "plugin_name": "redshift-database-plugin", + "allowed_roles": "readonly", + "connection_url": "postgresql://{{username}}:{{password}}@localhost:5432/dev", + "max_open_connections": 5, + "max_connection_lifetime": "5s", + "username": "username", + "password": "password" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/database/config/redshift +``` + +## 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 the database + statements executed to create and configure a user. Must be a + semicolon-separated string, a base64-encoded semicolon-separated string, a + serialized JSON string array, or a base64-encoded serialized JSON string + array. The '{{name}}', '{{password}}' and '{{expiration}}' values will be + substituted. The generated password will be a random alphanumeric 20 character + string. + +- `revocation_statements` `(list: [])` – Specifies the database statements to + be executed to revoke a user. Must be a semicolon-separated string, a + base64-encoded semicolon-separated string, a serialized JSON string array, or + a base64-encoded serialized JSON string array. The '{{name}}' value will be + substituted. If not provided defaults to a generic drop user statement. + +- `rollback_statements` `(list: [])` – Specifies the database statements to be + executed rollback a create operation in the event of an error. Not every + plugin type will support this functionality. Must be a semicolon-separated + string, a base64-encoded semicolon-separated string, a serialized JSON string + array, or a base64-encoded serialized JSON string array. The '{{name}}' value + will be substituted. + +- `renew_statements` `(list: [])` – Specifies the database statements to be + executed to renew a user. Not every plugin type will support this + functionality. Must be a semicolon-separated string, a base64-encoded + semicolon-separated string, a serialized JSON string array, or a + base64-encoded serialized JSON string array. The '{{name}}' and + '{{expiration}}' values will be substituted. + +- `rotation_statements` `(list: [])` – Specifies the database statements to be + executed to rotate the password for a given username. Must be a + semicolon-separated string, a base64-encoded semicolon-separated string, a + serialized JSON string array, or a base64-encoded serialized JSON string + array. The '{{name}}' and '{{password}}' values will be substituted. The + generated password will be a random alphanumeric 20 character string. diff --git a/website/pages/docs/secrets/databases/redshift.mdx b/website/pages/docs/secrets/databases/redshift.mdx new file mode 100644 index 000000000000..5876bbd8f910 --- /dev/null +++ b/website/pages/docs/secrets/databases/redshift.mdx @@ -0,0 +1,82 @@ +--- +layout: docs +page_title: Redshift - Database - Secrets Engines +sidebar_title: Redshift +description: |- + Redshift is a supported plugin for the database secrets engine. + This plugin generates database credentials dynamically based on configured + roles for the AWS Redshift database service. +--- + +# Redshift Database Secrets Engine + +Redshift is a supported plugin for the database secrets engine. This +plugin generates database credentials dynamically based on configured roles for +the AWS Redshift database service, and also supports [Static +Roles](/docs/secrets/databases#static-roles). + +See the [database secrets engine](/docs/secrets/databases) docs for +more information about setting up the database secrets engine. + +## Setup + +1. Enable the database secrets engine if it is not already enabled: + + ```text + $ 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 information to access your Redshift database: + + ```text + $ vault write database/config/my-redshift-database \ + plugin_name=redshift-database-plugin \ + allowed_roles="my-role" \ + connection_url="postgresql://{{username}}:{{password}}@localhost:5432/" \ + username="root" \ + password="root" + ``` + +1. Configure a role that maps a name in Vault to a SQL statement to execute which + creates the database credential: + + ```text + $ vault write database/roles/my-role \ + db_name=my-redshift-database \ + creation_statements="CREATE USER \"{{name}}\" WITH PASSWORD '{{password}}' VALID UNTIL '{{expiration}}'; \ + GRANT SELECT ON ALL TABLES IN SCHEMA public TO \"{{name}}\";" \ + default_ttl="1h" \ + max_ttl="24h" + Success! Data written to: database/roles/my-role + ``` + +## Usage + +After the secrets engine is configured and a user/machine has a Vault token with +the proper permission, it can generate credentials. + +1. Generate a new credential by reading from the `/creds` endpoint with the name + of the role: + + ```text + $ vault read database/creds/my-role + Key Value + --- ----- + lease_id database/creds/my-role/2f6a614c-4aa2-7b19-24b9-ad944a8d4de6 + lease_duration 1h + lease_renewable true + password 8cab931c-d62e-a73d-60d3-5ee85139cd66 + username v-root-e2978cd0- + ``` + +## API + +The full list of configurable options can be seen in the [Redshift database +plugin API](/api/secret/databases/redshift) page. + +For more information on the database secrets engine's HTTP API please see the +[Database secrets engine API](/api/secret/databases) page.