From acf6d8d9c11251976fe982db97b5db464f1be0f2 Mon Sep 17 00:00:00 2001
From: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com>
Date: Fri, 6 Dec 2024 10:41:34 +0100
Subject: [PATCH] docs(datasource/aws-rds): improve readme (#29870)
Co-authored-by: Rhys Arkins <rhys@arkins.net>
---
lib/modules/datasource/aws-rds/readme.md | 50 +++++++++++++++++++-----
1 file changed, 40 insertions(+), 10 deletions(-)
diff --git a/lib/modules/datasource/aws-rds/readme.md b/lib/modules/datasource/aws-rds/readme.md
index be47f3644d..c82ff7c8b6 100644
--- a/lib/modules/datasource/aws-rds/readme.md
+++ b/lib/modules/datasource/aws-rds/readme.md
@@ -1,9 +1,16 @@
This datasource returns the database engine versions available for use on [AWS RDS](https://aws.amazon.com/rds/) via the AWS API.
+
Generally speaking, all publicly released database versions are available for use on RDS.
However, new versions may not be available on RDS for a few weeks or months after their release while AWS tests them.
In addition, AWS may pull existing versions if serious problems arise during their use.
-**AWS API configuration**
+<!-- prettier-ignore -->
+!!! warning
+ The default versioning of the `aws-rds` datasource is _not_ compatible with [AWS Aurora](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/CHAP_AuroraOverview.html)!
+ If you use AWS Aurora, you must set your own custom versioning.
+ Scroll down to see an example.
+
+### AWS API configuration
Since the datasource uses the AWS SDK for JavaScript, you can configure it like other AWS Tools.
You can use common AWS configuration options, for example:
@@ -14,9 +21,7 @@ You can use common AWS configuration options, for example:
Read the [AWS Developer Guide - Configuring the SDK for JavaScript](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/configuring-the-jssdk.html) for more information on these configuration options.
-The minimal IAM privileges required for this datasource are:
-
-```json
+```json title="Minimal IAM privileges needed for this datasource"
{
"Sid": "AllowDBEngineVersionLookup",
"Effect": "Allow",
@@ -27,7 +32,7 @@ The minimal IAM privileges required for this datasource are:
Read the [AWS RDS IAM reference](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonrds.html) for more information.
-**Usage**
+### Usage
Because Renovate has no manager for the AWS RDS datasource, you need to help Renovate by configuring the custom manager to identify the RDS dependencies you want updated.
@@ -53,16 +58,14 @@ For example:
[{"Name":"engine","Values":["mysql"]},{"Name":"engine-version","Values":["5.7"]}]
```
-Here's an example of using the custom manager to configure this datasource:
-
-```json
+```json title="Using a custom manager to configure this datasource"
{
"customManagers": [
{
"customType": "regex",
"fileMatch": ["\\.yaml$"],
"matchStrings": [
- ".*amiFilter=(?<lookupName>.+?)[ ]*\n[ ]*(?<depName>[a-zA-Z0-9-_:]*)[ ]*?:[ ]*?[\"|']?(?<currentValue>[.\\d]+)[\"|']?.*"
+ ".*rdsFilter=(?<lookupName>.+?)[ ]*\n[ ]*(?<depName>[a-zA-Z0-9-_:]*)[ ]*?:[ ]*?[\"|']?(?<currentValue>[.\\d]+)[\"|']?.*"
],
"datasourceTemplate": "aws-rds"
}
@@ -74,6 +77,33 @@ The configuration above matches every YAML file, and recognizes these lines:
```yaml
spec:
- # amiFilter=[{"Name":"engine","Values":["mysql"]},{"Name":"engine-version","Values":["5.7"]}]
+ # rdsFilter=[{"Name":"engine","Values":["mysql"]},{"Name":"engine-version","Values":["5.7"]}]
engineVersion: 5.7.34
```
+
+#### Using Terraform, `aws-rds` datasource and Aurora MySQL
+
+Here is the Renovate configuration to use Terraform, `aws-rds` and Aurora MySQL:
+
+```json
+{
+ "customManagers": [
+ {
+ "description": "Update RDS",
+ "customType": "regex",
+ "fileMatch": [".+\\.tf$"],
+ "matchStrings": [
+ "\\s*#\\s*renovate:\\s*rdsFilter=(?<lookupName>.+?) depName=(?<depName>.*) versioning=(?<versioning>.*)\\s*.*_version\\s*=\\s*\"(?<currentValue>.*)\""
+ ],
+ "datasourceTemplate": "aws-rds"
+ }
+ ]
+}
+```
+
+The above configuration is an example of updating an AWS RDS version inside a Terraform file, using a custom manager.
+
+```
+# renovate:rdsFilter=[{"Name":"engine","Values":["aurora-mysql"]},{"Name":"engine-version","Values":["8.0"]}] depName=aurora-mysql versioning=loose
+engine_version = "8.0.mysql_aurora.3.05.2"
+```
--
GitLab