From 553e1cfb0dc0681f538ab194a1ebeec436b8582b Mon Sep 17 00:00:00 2001
From: Max Coulombe <109547106+maxcoulombe@users.noreply.github.com>
Date: Wed, 18 Jan 2023 15:51:15 -0500
Subject: [PATCH] * added the new redis parameter documentation (#18752)

* added the new redis parameter documentation
* added changelog
---
 changelog/18752.txt                           |  3 ++
 .../secret/databases/rediselasticache.mdx     | 21 +++++++++---
 .../secrets/databases/rediselasticache.mdx    | 34 ++++++++++++++++---
 3 files changed, 48 insertions(+), 10 deletions(-)
 create mode 100644 changelog/18752.txt

diff --git a/changelog/18752.txt b/changelog/18752.txt
new file mode 100644
index 000000000..95346e043
--- /dev/null
+++ b/changelog/18752.txt
@@ -0,0 +1,3 @@
+```release-note:improvement
+**Redis ElastiCache DB Engine**: Renamed configuration parameters for disambiguation; old parameters still supported for compatibility.
+```
\ No newline at end of file
diff --git a/website/content/api-docs/secret/databases/rediselasticache.mdx b/website/content/api-docs/secret/databases/rediselasticache.mdx
index 0fe1739c5..31e741c55 100644
--- a/website/content/api-docs/secret/databases/rediselasticache.mdx
+++ b/website/content/api-docs/secret/databases/rediselasticache.mdx
@@ -25,10 +25,20 @@ has a number of parameters to further configure a connection.
 
 - `url` `(string: <required>)` – Specifies the primary endpoint to connect to.
 
-- `username` `(string)` – Specifies the IAM access_key_id for Vault to use. If omitted, authentication fallbacks on the AWS credentials provider chain and tries to infer authentication from the environment.
+- `access_key_id` `(string)` – Specifies the IAM `access_key_id` for Vault to use. If omitted, authentication falls back on
+the AWS credentials provider chain and tries to infer authentication from the environment.
 
-- `password` `(string)` – Specifies the IAM secret_access_key corresponding to
-the given access_key_id. If omitted, authentication fallbacks on the AWS credentials provider chain and tries to infer authentication from the environment.
+- `secret_access_key` `(string)` – Specifies the IAM `secret_access_key` corresponding to the given `access_key_id`.
+If omitted, authentication falls back on the AWS credentials provider chain and tries to infer authentication from the environment.
+
+- `region` `(string)` – Specifies the AWS region where to ElastiCache cluster is provisioned. If omitted, falls back on
+the context from the environment.
+
+### Deprecated Parameters
+
+- `username` `(string)` – Use `access_key_id` instead, it is strictly equivalent.
+
+- `password` `(string)` – Use `secret_access_key` instead, it is strictly equivalent.
 
 ### Sample Payload
 
@@ -36,8 +46,9 @@ the given access_key_id. If omitted, authentication fallbacks on the AWS credent
 {
   "plugin_name": "redis-elasticache-database-plugin",
   "url": "primary-endpoint.my-cluster.xxx.yyy.cache.amazonaws.com:6379",
-  "username": "AKI***",
-  "password": "ktriNYvULAWLzUmTGb***",
+  "access_key_id": "AKI***",
+  "secret_access_key": "ktriNYvULAWLzUmTGb***",
+  "region": "us-east-1",
   "allowed-roles": "*"
 }
 ```
diff --git a/website/content/docs/secrets/databases/rediselasticache.mdx b/website/content/docs/secrets/databases/rediselasticache.mdx
index 01705c8d1..a6f160f45 100644
--- a/website/content/docs/secrets/databases/rediselasticache.mdx
+++ b/website/content/docs/secrets/databases/rediselasticache.mdx
@@ -38,14 +38,38 @@ more information about setting up the database secrets engine.
   $ vault write database/config/my-redis-elasticache-cluster \
     plugin_name="redis-elasticache-database-plugin" \
     url="primary-endpoint.my-cluster.xxx.yyy.cache.amazonaws.com:6379" \
-    username="AKI***" \
-    password="ktriNYvULAWLzUmTGb***" \
+    access_key_id="AKI***" \
+    secret_access_key="ktriNYvULAWLzUmTGb***" \
+    region=us-east-1 \
     allowed_roles="*"
   ```
 
-~> **Note**: The username and password parameters are optional. If omitted, authentication falls back on the AWS credentials provider chain.
-  Using a [temporary credential](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html) stored in the proper environment
-  variable is the preferred configuration method.
+~> **Note**: The `access_key_id`, `secret_access_key` and `region` parameters are optional. If omitted, authentication falls back
+on the AWS credentials provider chain.
+
+~> **Deprecated**: The `username` & `password` parameters are deprecated but supported for backward compatibility. They are replaced
+by the equivalent `access_key_id` and `secret_access_key` parameters respectively.
+
+The Redis ElastiCache secrets engine must use AWS credentials that have sufficient permissions to manage ElastiCache users.
+This IAM policy sample can be used as an example. Note that &lt;region&gt; and &lt;account-id&gt;
+must correspond to your own environment.
+
+  ```json
+  {
+    "Version": "2012-10-17",
+    "Statement": [
+      {
+        "Sid": "",
+        "Effect": "Allow",
+        "Action": [
+          "elasticache:ModifyUser",
+          "elasticache:DescribeUsers"
+        ],
+        "Resource": "arn:aws:elasticache:<region>:<account-id>:user:*"
+      }
+    ]
+  }
+  ```
 
 ## Usage