From 83818f9321cbf0b9853677205a295f4f16a46fac Mon Sep 17 00:00:00 2001
From: Jonathan Foster <jonathan@jonathanfoster.io>
Date: Fri, 27 Sep 2024 12:37:37 -0400
Subject: [PATCH] Document supported KV stores and reference notation (#6563)

---
 docs/kv.md | 91 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)
 create mode 100644 docs/kv.md

diff --git a/docs/kv.md b/docs/kv.md
new file mode 100644
index 00000000000..39414f64ba4
--- /dev/null
+++ b/docs/kv.md
@@ -0,0 +1,91 @@
+# External Key-Value Storage
+
+Tyk Gateway supports storing configuration data in key-value (KV) stores such as AWS Secrets Manager, Consul, and Vault
+and then referencing these values the gateway configuration or API definitions deployed on the gateway.
+
+## Supported KV Stores
+
+Tyk Gateway supports the following KV stores:
+
+- [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/)
+- [Consul](https://www.consul.io/)
+- [Vault](https://www.vaultproject.io/)
+- Tyk Config Secrets
+- Environment Variables
+
+## Accessing KV Store Data
+
+You can configure Tyk Gateway to retrieve values from KV stores in the following places:
+
+- Tyk Gateway configuration file (tyk.conf)
+- API definitions
+- Transform Middleware
+
+### Gateway Configuration
+
+You can retrieve values from KV stores for the following fields Tyk Gateway configuration fields:
+
+- `secret`
+- `node_secret`
+- `storage.password`
+- `cache_storage.password`
+- `security.private_certificate_encoding_secret`
+- `db_app_conf_options.connection_string`
+- `policies.policy_connection_string`
+
+Use the following notation to reference KV store values in the gateway configuration file:
+
+| Store                       | Notation                                                    |
+|-----------------------------|-------------------------------------------------------------|
+| AWS Secrets Manager \[1\]   | `secretsmanager://{key}` or `secretsmanager://{path}.{key}` |
+| Consul                      | `consul://{key}`                                            |
+| Vault  \[1\]                | `vault://{path}.{key}`                                      |
+| Tyk config secrets          | `secrets://{key}`                                           |
+| Environment variables \[2\] | `env://{key}`                                               |
+
+\[1\] Path key value must be a JSON document to support `{path}.{key}` references (e.g., `{"key": "value"}`).\
+\[2\] Gateway configuration environment variable names must be prefixed with `TYK_SECRETS_{KEY}` (e.g.,
+`TYK_SECRETS_MY_API_SECRET` is referenced as `env://MY_API_SECRET`).
+
+### API Definition
+
+Use the following notation to reference KV store values in API definition fields:
+
+| Store                       | Notation                 |
+|-----------------------------|--------------------------|
+| AWS Secrets Manager \[1\]   | `secretsmanager://{key}` |
+| Consul \[1\]                | `consul://{key}`         |
+| Vault \[1\]                 | `vault://{key}`          |
+| Tyk config secrets          | `secrets://{key}`        |
+| Environment variables \[2\] | `env://{key}`            |
+
+\[1\] External API definition secrets must be stored in a JSON document in the KV store with the key `tyk-apis`.
+In this case, `{key}` refers to the JSON document key (e.g., `{"key": "value"}`).\
+\[2\] API definition environment variables can be any name (e.g. `MY_API_SECRET` is referenced as
+`env://MY_API_SECRET`). They **do not** require the prefix `TYK_SECRETS_{KEY}`.
+
+### Transform Middleware
+
+You can retrieve values from KV stores for the following transform middleware:
+
+- Authentication Token (signature secret)
+- Persist GraphQL Operation (request path)
+- Rate Limiting (rate limit pattern)
+- Request Body
+- Request Headers
+- Response Headers
+- URL Rewrite
+
+Use the following notation to reference KV store values in transform middleware:
+
+| Store                       | Notation                                                    |
+|-----------------------------|-------------------------------------------------------------|
+| AWS Secrets Manager \[1\]   | `secretsmanager://{key}` or `secretsmanager://{path}.{key}` |
+| Consul                      | `consul://{key}`                                            |
+| Vault  \[1\]                | `vault://{path}.{key}`                                      |
+| Tyk config secrets          | `secrets://{key}`                                           |
+| Environment variables \[2\] | `env://{key}`                                               |
+
+\[1\] Path key value must be a JSON document to support `{path}.{key}` references (e.g., `{"key": "value"}`).\
+\[2\] Transform middleware environment variable names must be prefixed with `TYK_SECRETS_{KEY}` (e.g.,
+`TYK_SECRETS_MY_API_SECRET` is referenced as `env://MY_API_SECRET`).