You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+16-12Lines changed: 16 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -57,26 +57,30 @@ To find all the documentation and concrete examples on how to use the AWS Advanc
57
57
58
58
#### Amazon RDS Blue/Green Deployments
59
59
60
-
The AWS Advanced NodeJS Wrapper **versions 1.3.0 and above** now include enhanced full support for Blue/Green Deployments. This support requires a minimum database version that includes a specific metadata table. This constraint **does not** apply to RDS MySQL.
60
+
**Important: Service Dependency**
61
61
62
-
**No action is required** if your database does not include the new metadata table -- the driver will continue to operate as before with no special blue/green functionality. If you have questions or encounter issues, please open an issue in this repository.
62
+
Support for Blue/Green deployments using the AWS Advanced NodeJS Wrapper requires specific metadata tables that are **not available in the current RDS and Aurora service**. Please contact your AWS account team for metadata release timelines.
Supported Aurora MySQL Versions: Engine Release `3.07` and above.
64
+
**Limitations:**
67
65
68
-
If your database version does **not** support this table, the driver will automatically detect its absence and fallback to its previous behaviour in wrapper versions <1.3.0. In this fallback mode, Blue/Green handling is subject to the same limitations listed below.
66
+
-**Post-switchover failures:** After a Blue/Green switchover, the wrapper may not properly detect the new cluster topology, leading to failed failover attempts.
67
+
-**Metadata inconsistencies:** Discrepancies between topology metadata and actual available endpoints prevent reliable operation.
68
+
-**Version-specific issues:** Requirements vary between Aurora MySQL and Aurora PostgreSQL due to different internal systems.
69
69
70
-
AWS Advanced NodeJS Wrapper **versions earlier than 1.3.0** are not compatible with [AWS Blue/Green Deployments](https://docs.aws.amazon.com/whitepapers/latest/overview-deployment-options/bluegreen-deployments.html) and do not officially support them. However, the combination of the AWS Advanced NodeJS Wrapper and the Failover Plugin has been validated for use with clusters that employ Blue/Green Deployments for these versions. While general basic connectivity to both Blue and Green clusters is always in place, some failover cases are not fully supported.
70
+
**If You Must Use Blue/Green (Not Recommended for Production):**
71
71
72
-
The limitations for versions earlier than 1.3.0 are:
72
+
1. Enable the `enableGreenNodeReplacement` configuration parameter.
73
+
2. Thoroughly test in non-production environments.
73
74
74
-
- After a Blue/Green switchover, the wrapper may not be able to properly detect the new topology and handle failover, as there are discrepancies between the metadata and the available endpoints.
75
-
- The specific version requirements for Aurora MySQL versus Aurora PostgreSQL may vary, as the internal systems used by the wrapper can differ[^1].
75
+
**Recommendation:**
76
76
77
-
For these earlier versions, users can consider utilizing the `enableGreenHostReplacement` configuration parameter, which allows the driver to override incorrect topology metadata and try to connect to available new Blue endpoints.
77
+
We advise waiting for the RDS service update before enabling the Blue/Green Deployments plugin. If the metadata table does not exist, your application will continue to work; however, errors will be logged stating that relevant Blue/Green metadata cannot be found.
78
78
79
-
[^1]: Aurora MySQL requires v3.07 or later.
79
+
When the RDS service update is released, the following service versions will provide support for Blue/Green Deployments:
Copy file name to clipboardExpand all lines: docs/development-guide/IntegrationTests.md
+17-13Lines changed: 17 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -39,7 +39,8 @@ PostgreSQL and MySQL tests are currently supported.
39
39
40
40
> [!TIP]
41
41
> If you are not running against an existing cluster (`REUSE_RDS_DB` is `false`), the test will automatically create and
42
-
> delete the test resources. However, if the tests fail, the test resources may not be fully cleaned up. After running the
42
+
> delete the test resources. However, if the tests fail, the test resources may not be fully cleaned up. After running
43
+
> the
43
44
> integration tests, ensure all test resources are cleaned up.
44
45
45
46
#### Environment Variables
@@ -53,7 +54,8 @@ variable listed in the tables below is not provided by the user, it may use a de
53
54
54
55
> [!NOTE]
55
56
> If you are running tests against an existing cluster, the tests will only run against the Aurora database engine of
56
-
> that cluster. For example, if you specify a MySQL cluster using the environment variables, only the MySQL tests will be
57
+
> that cluster. For example, if you specify a MySQL cluster using the environment variables, only the MySQL tests will
58
+
> be
57
59
> run even if you pick test-all-aurora as the task. To run against Postgres instead, you will need to change your
58
60
> environment variables.
59
61
@@ -75,7 +77,7 @@ variable listed in the tables below is not provided by the user, it may use a de
75
77
|`DB_USERNAME`| The username to access the database. |`admin`|`test_user`|
76
78
|`DB_PASSWORD`| The database cluster password. |`password`|`secret_password`|
77
79
|`DB_DATABASE_NAME`| Name of the database that will be used by the tests. The default database name is test. |`test_db_name`|`test_database`|
78
-
|`RDS_CLUSTER_NAME`| The database identifier for your Aurora or RDS cluster. Must be a unique value to avoid conflicting with existing clusters. |`db-identifier`|
80
+
|`RDS_DB_NAME`| The database identifier for your Aurora or RDS cluster. Must be a unique value to avoid conflicting with existing clusters. |`db-identifier`|
79
81
|`IAM_USER`| User within the database that is identified with AWSAuthenticationPlugin. This is used for AWS IAM Authentication and is optional. |`example_user_name`|`jane_doe`|
80
82
|`NUM_INSTANCES`| The number of database instances in the cluster to test with. This value must be one of the following: `1`, `2`, `3`, `5`. |`5`| Integration tests will be run several times, against `1`, `2`, and `5` instances. |
81
83
@@ -86,8 +88,8 @@ variable listed in the tables below is not provided by the user, it may use a de
86
88
|`DB_USERNAME`| The database username to access the specified cluster. |`admin`|`test_user`|
87
89
|`DB_PASSWORD`| The database password to access the specified cluster. |`password`|`secret_password`|
88
90
|`DB_DATABASE_NAME`| Name of the database that will be used by the tests. |`test_db_name`|`test_database`|
89
-
|`RDS_CLUSTER_NAME`| The database identifier for your Aurora or RDS cluster. Must be a unique value to avoid conflicting with existing clusters. |`db-identifier`|
90
-
|`RDS_CLUSTER_DOMAIN`| The database connection suffix of the existing cluster.[^1]|`XYZ.us-east-2.rds.amazonaws.com`|
91
+
|`RDS_DB_NAME`| The database identifier for your Aurora or RDS cluster. Must be a unique value to avoid conflicting with existing clusters. |`db-identifier`|
92
+
|`RDS_DB_DOMAIN`| The database connection suffix of the existing cluster.[^1]|`XYZ.us-east-2.rds.amazonaws.com`|
91
93
|`IAM_USER`| User within the database that is identified with AWSAuthenticationPlugin. This is used for AWS IAM Authentication and is optional. |`example_user_name`|`jane_doe`|
92
94
|`AWS_ACCESS_KEY_ID`| An AWS access key associated with an IAM user or role with RDS permissions. |`ASIAIOSFODNN7EXAMPLE`|
93
95
|`AWS_SECRET_ACCESS_KEY`| The secret key associated with the provided AWS_ACCESS_KEY_ID. |`wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`|
@@ -97,9 +99,10 @@ variable listed in the tables below is not provided by the user, it may use a de
|`NUM_INSTANCES`| The number of database instances in the cluster to test with. This value must be one of the following: `1`, `2`, `3`, `5`. |`5`| Integration tests will be run several times, against `1`, `2`, and `5` instances. |
102
+
| Environment Variable Name | Description | Example Value | Default Value (If available) |
|`NUM_INSTANCES`| The number of database instances in the cluster to test with. This value must be one of the following: `1`, `2`, `3`, `5`. |`5`| Integration tests will be run several times, against `1`, `2`, and `5` instances. |
105
+
|`RDS_ENDPOINT`| The RDS service endpoint URL for AWS API calls. This is relevant if you are testing against non-prod environments. |`https://rds-int.amazon.com`| None |
103
106
104
107
### Standard Integration Tests
105
108
@@ -159,8 +162,9 @@ Linux:
159
162
Test results can be found in `tests/integration/host/build/test-results/test-all-environments/`.
160
163
161
164
[^1]:
162
-
The cluster domain suffix can be determined by checking the endpoint of an existing cluster in the desired region,
163
-
or by temporarily creating a database to check the endpoint. For example, given the database endpoint
164
-
`db-identifier.cluster-XYZ.us-east-2.rds.amazonaws.com`, the domain suffix would be `XYZ.us-east-2.rds.amazonaws.com`.
165
-
See [here](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/Aurora.Endpoints.Cluster.html) for more
166
-
information on Amazon Aurora cluster endpoints.
165
+
166
+
The cluster domain suffix can be determined by checking the endpoint of an existing cluster in the desired region,
167
+
or by temporarily creating a database to check the endpoint. For example, given the database endpoint
168
+
`db-identifier.cluster-XYZ.us-east-2.rds.amazonaws.com`, the domain suffix would be `XYZ.us-east-2.rds.amazonaws.com`.
169
+
See [here](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/Aurora.Endpoints.Cluster.html) for more
Copy file name to clipboardExpand all lines: docs/using-the-nodejs-wrapper/SupportForRDSMultiAzDBCluster.md
+4Lines changed: 4 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -22,6 +22,10 @@ CREATE EXTENSION rds_tools;
22
22
23
23
To prepare a connection with PostgreSQL in a Multi-AZ Cluster, please refer to [this example](../../examples/aws_driver_example/aws_simple_connection_postgresql_example.ts).
24
24
25
+
### Connections with the IAM Authentication Plugin
26
+
27
+
Additional permissions for the IAM user are required when connecting to a Multi-AZ Cluster. See [Connecting with Multi-AZ or Blue/Green Deployments](./using-plugins/UsingTheIamAuthenticationPlugin.md#connecting-with-multi-az-or-bluegreen-deployments) for specifics.
28
+
25
29
## Optimizing Switchover Time
26
30
27
31
Amazon RDS Multi-AZ with two readable standbys supports minor version upgrades with 1 second of downtime.
Copy file name to clipboardExpand all lines: docs/using-the-nodejs-wrapper/using-plugins/UsingTheBlueGreenPlugin.md
+9Lines changed: 9 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,6 +6,10 @@ The [Blue/Green Deployment](https://docs.aws.amazon.com/whitepapers/latest/blue-
6
6
7
7
The AWS Advanced NodeJS Wrapper leverages the Blue/Green Deployment approach by intelligently managing traffic distribution between blue and green nodes, minimizing the impact of stale DNS data and connectivity disruptions on user applications.
8
8
9
+
**Important: Service Dependency**
10
+
11
+
Support for Blue/Green deployments using the AWS Advanced Go Wrapper requires specific metadata tables that are **not available in the current RDS and Aurora service**. Please contact your AWS account team for metadata release timelines.
12
+
9
13
## Prerequisites
10
14
11
15
> [!WARNING]\
@@ -87,6 +91,11 @@ await client.connect();
87
91
> [!WARNING]\
88
92
> **Always ensure you provide a non-zero network timeout value to the Blue/Green Deployment Plugin**
89
93
94
+
### Connections with the IAM Authentication Plugin
95
+
96
+
When connecting with the IAM Authentication Plugin, additional permissions for the IAM user may be required.
97
+
See [Connecting with Multi-AZ or Blue/Green Deployments](UsingTheIamAuthenticationPlugin.md#connecting-with-multi-az-or-bluegreen-deployments) for specifics.
98
+
90
99
## Plan your Blue/Green switchover in advance
91
100
92
101
To optimize Blue/Green switchover support with the AWS Advanced NodeJS Wrapper, advance planning is essential. Please follow these recommended steps:
Copy file name to clipboardExpand all lines: docs/using-the-nodejs-wrapper/using-plugins/UsingTheIamAuthenticationPlugin.md
+11-1Lines changed: 11 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -27,7 +27,8 @@ The AWS Advanced NodeJS Wrapper supports Amazon AWS Identity and Access Manageme
27
27
`CREATE USER example_user_name IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';`
28
28
2. For a PostgreSQL database, use the following command to create a new user:<br>
29
29
`CREATE USER db_userx; GRANT rds_iam TO db_userx;`
30
-
4. Add the plugin code `iam` to the [`plugins`](../UsingTheNodejsWrapper.md#connection-plugin-manager-parameters) connection parameter.
30
+
4. If connecting to a Multi-AZ deployment or using the Blue/Green plugin with a Blue/Green deployment, ensure the IAM user has access to required tables. See [Connecting with Multi-AZ or Blue/Green Deployments](UsingTheIamAuthenticationPlugin.md#connecting-with-multi-az-or-bluegreen-deployments) for specifics.
31
+
5. Add the plugin code `iam` to the [`plugins`](../UsingTheNodejsWrapper.md#connection-plugin-manager-parameters) connection parameter.
31
32
32
33
| Parameter | Value | Required | Description | Default Value | Example Value |
@@ -38,6 +39,15 @@ The AWS Advanced NodeJS Wrapper supports Amazon AWS Identity and Access Manageme
38
39
39
40
This plugin requires a valid set of AWS credentials to retrieve the database credentials from AWS Secrets Manager. The AWS credentials must be located in [one of these locations](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromNodeProviderChain) supported by the AWS SDK's default credentials provider. See also at [AWS Credentials Configuration](../custom-configuration/AwsCredentialsConfiguration.md)
40
41
42
+
### Connecting with Multi-AZ or Blue/Green Deployments
43
+
44
+
The following additional permissions are required when connecting to a Multi-AZ deployment or using the Blue/Green plugin with a Blue/Green deployment.
| mysql | Multi-AZ or Blue/Green |`GRANT SELECT ON mysql.* TO '" + dbUser + "'@'%'`|
49
+
| pg | Multi-AZ |`CREATE EXTENSION rds_tools`<br>`GRANT USAGE ON SCHEMA rds_tools TO " + dbUser`<br>`GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA rds_tools TO " + dbUser`|
50
+
41
51
## Using the IAM Authentication Plugin with Custom Endpoints
42
52
43
53
When using AWS IAM database authentication with a custom domain or an IP address, in addition to the `clusterInstanceHostPattern` variable, the `iamHost` must be specified and must point to a valid Amazon endpoint, i.e. `db-identifier.cluster-XYZ.us-east-2.rds.amazonaws.com`.
0 commit comments