Skip to content

Commit b5543df

Browse files
sergiyvamzkarenc-bq
sergiyvamz
and
karenc-bq
authored
feat: add support of Blue/Green Deployment (#1355)
Co-authored-by: Karen <[email protected]>
1 parent a1d8080 commit b5543df

File tree

82 files changed

+7336
-383
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

82 files changed

+7336
-383
lines changed

‎.github/workflows/code_quality.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,3 +39,4 @@ jobs:
3939
uses: JetBrains/[email protected]
4040
with:
4141
use-caches: false
42+
upload-result: true

‎README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,18 @@ The current limitations are:
126126

127127
The development team is aware of these limitations and is working to improve the wrapper's awareness and handling of Blue/Green switchovers. In the meantime, users can consider utilizing the `enableGreenNodeReplacement` configuration parameter, which allows the driver to override incorrect topology metadata and try to connect to available new Blue endpoints.
128128

129+
> [!WARNING]\
130+
> **Blue/Green Support Behaviour and Version Compatibility**
131+
>
132+
> The AWS Advanced JDBC Wrapper now includes enhanced full support for Blue/Green Deployments. This support requires a minimum database version, for RDS and Aurora PostgreSQL, that includes a specific metadata table. This constraint **does not** apply to RDS MySQL and Aurora MySQL.
133+
>
134+
> If your database version does **not** support this table, the driver will automatically detect its absence and fallback to its previous behaviour. In this fallback mode, Blue/Green handling is subject to the same limitations listed above.
135+
>
136+
> **No action is required** if your database does not include the new metadata table -- the driver will continue to operate as before. If you have questions or encounter issues, please open an issue in this repository.
137+
>
138+
> Supported RDS PostgreSQL Versions: `rds_tools v1.7 (17.1, 16.5, 15.9, 14.14, 13.17, 12.21)`.<br>
139+
> Supported Aurora PostgreSQL Versions: Engine Release `17.5, 16.9, 15.13, 14.18, 13.21`.
140+
129141
[^1]: Aurora MySQL requires v3.07 or later.
130142

131143
#### Amazon Aurora Global Databases

‎docs/using-the-jdbc-driver/UsingTheJdbcDriver.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -209,12 +209,12 @@ The AWS JDBC Driver has several built-in plugins that are available to use. Plea
209209
| [Aurora Initial Connection Strategy](./using-plugins/UsingTheAuroraInitialConnectionStrategyPlugin.md) | `initialConnection` | Aurora | Allows users to configure their initial connection strategy to reader cluster endpoints. | None |
210210
| [Limitless Connection Plugin](./using-plugins/UsingTheLimitlessConnectionPlugin.md) | `limitless` | Aurora | Enables client-side load-balancing of Transaction Routers on Amazon Aurora Limitless Databases . | None |
211211
| Fastest Response Strategy Plugin | `fastestResponseStrategy` | Aurora | When read-write splitting is enabled, this plugin selects the reader to switch to based on the host with the fastest response time. The plugin achieves this by periodically monitoring the hosts' response times and storing the fastest host in a cache. **Note:** the `readerHostSelectorStrategy` parameter must be set to `fastestResponse` in the user-defined connection properties in order to enable this plugin. See [reader selection strategies](./ReaderSelectionStrategies.md). | None |
212-
212+
| [Blue/Green Deployment Plugin](./using-plugins/UsingTheBlueGreenPlugin.md) | `bg` | Aurora, <br>RDS Instance | Enables client-side Blue/Green Deployment support. | None |
213213
[^1]: [RDS Multi-AZ DB Clusters do not support IAM](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.Limitations.html).
214214
[^2]: Federated Identity and Okta rely on IAM. Due to [^1], RDS Multi-AZ Clusters are not supported.
215215

216-
:exclamation:**NOTE**: To see information logged by plugins such as `DataCacheConnectionPlugin` and `LogQueryConnectionPlugin`,
217-
> see the [Logging](#logging) section.
216+
> [!NOTE]\
217+
> To see information logged by plugins such as `DataCacheConnectionPlugin` and `LogQueryConnectionPlugin`, see the [Logging](#logging) section.
218218

219219
In addition to the built-in plugins, you can also create custom plugins more suitable for your needs.
220220
For more information, see [Custom Plugins](../development-guide/LoadablePlugins.md#using-custom-plugins).

‎docs/using-the-jdbc-driver/using-plugins/UsingTheBlueGreenPlugin.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Blue/Green Deployment Plugin
2+
3+
## What is Blue/Green Deployment?
4+
5+
The [Blue/Green Deployment](https://docs.aws.amazon.com/whitepapers/latest/blue-green-deployments/introduction.html) technique enables organizations to release applications by seamlessly shifting traffic between two identical environments running different versions of the application. This strategy effectively mitigates common risks associated with software deployment, such as downtime and limited rollback capability.
6+
7+
The AWS JDBC Driver 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+
9+
10+
## Prerequisites
11+
> [!WARNING]\
12+
> Currently Supported Database Deployments:
13+
> - Aurora MySQL and PostgreSQL clusters
14+
> - RDS MySQL and PostgreSQL instances
15+
>
16+
> Unsupported Database Deployments and Configurations:
17+
> - RDS MySQL and PostgreSQL Multi-AZ clusters
18+
> - Aurora Global Database for MySQL and PostgreSQL
19+
>
20+
> Additional Requirements:
21+
> - AWS cluster and instance endpoints must be directly accessible from the client side
22+
> - Connecting to database nodes using CNAME aliases is not supported
23+
>
24+
25+
26+
## What is Blue/Green Deployment Plugin?
27+
28+
During a [Blue/Green switchover](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/blue-green-deployments-switching.html), several significant changes occur to your database configuration:
29+
- Connections to blue nodes terminate at a specific point during the transition
30+
- Node connectivity may be temporarily impacted due to reconfigurations and potential node restarts
31+
- Cluster and instance endpoints are redirected to different database nodes
32+
- Internal database node names undergo changes
33+
- Internal security certificates are regenerated to accommodate the new node names
34+
35+
36+
All factors mentioned above may cause application disruption. The AWS Advanced JDBC Driver aims to minimize the application disruption during Blue/Green switchover by performing the following actions:
37+
- Actively monitors Blue/Green switchover status and implements appropriate measures to suspend, pass-through, or re-route database traffic
38+
- Prior to Blue/Green switchover initiation, compiles a comprehensive inventory of cluster and instance endpoints for both blue and green nodes along with their corresponding IP addresses
39+
- During the active switchover phase, temporarily suspends execution of JDBC calls to blue nodes, which helps unload database nodes and reduces transaction lag for green nodes, thereby enhancing overall switchover performance
40+
- Substitutes provided hostnames with corresponding IP addresses when establishing new blue connections, effectively eliminating stale DNS data and ensuring connections to current blue nodes
41+
- During the brief post-switchover period, continuously monitors DNS entries, confirms that blue endpoints have been reconfigured, and discontinues hostname-to-IP address substitution as it becomes unnecessary
42+
- Automatically rejects new connection requests to green nodes when the switchover is completed but DNS entries for green nodes remain temporarily available
43+
- Intelligently detects switchover failures and rollbacks to the original state, implementing appropriate connection handling measures to maintain application stability
44+
45+
46+
## How do I use Blue/Green Deployment Plugin with the AWS JDBC Driver?
47+
48+
To enable the Blue/Green Deployment functionality, add the plugin code `bg` to the [`wrapperPlugins`](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters) parameter value.
49+
The Blue/Green Deployment Plugin supports the following configuration parameters:
50+
51+
| Parameter | Value | Required | Description | Example Value |
52+
|-------------------------------|:-------:|:--------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------|
53+
| `bgdId` | String | If using multiple Blue/Green Deployments, yes; otherwise, no | This parameter is optional and defaults to `1`. When supporting multiple Blue/Green Deployments (BGDs), this parameter becomes mandatory. Each connection string must include the `bgdId` parameter with a value that can be any number or string. However, all connection strings associated with the same Blue/Green Deployment must use identical `bgdId` values, while connection strings belonging to different BGDs must specify distinct values. | `1234`, `abc-1`, `abc-2` |
54+
| `bgConnectTimeoutMs` | Integer | No | Maximum waiting time (in milliseconds) for establishing new connections during a Blue/Green switchover when blue and green traffic is temporarily suspended. | `30000` |
55+
| `bgBaselineMs` | Integer | No | The baseline interval (ms) for checking Blue/Green Deployment status. | `60000` |
56+
| `bgIncreasedMs` | Integer | No | The increased interval (ms) for checking Blue/Green Deployment status. | `1000` |
57+
| `bgHighMs` | Integer | No | The high-frequency interval (ms) for checking Blue/Green Deployment status. | `100` |
58+
| `bgSwitchoverTimeoutMs` | Integer | No | Maximum duration (in milliseconds) allowed for switchover completion. If the switchover process stalls or exceeds this timeframe, the driver will automatically assume completion and resume normal operations. | `180000` |
59+
| `bgSuspendNewBlueConnections` | Boolean | No | Enables Blue/Green Deployment switchover to suspend new blue connection requests while the switchover process is in progress. | `false` |
60+
61+
The plugin establishes dedicated monitoring connections to track Blue/Green Deployment status. To apply specific configurations to these monitoring connections, add the `blue-green-monitoring-` prefix to any configuration parameter, as shown in the following example:
62+
63+
```java
64+
final Properties properties = new Properties();
65+
// Configure the timeout values for all, non-monitoring connections.
66+
properties.setProperty("connectTimeout", "30000");
67+
properties.setProperty("socketTimeout", "30000");
68+
// Configure different timeout values for the Blue/Green monitoring connections.
69+
properties.setProperty("blue-green-monitoring-connectTimeout", "10000");
70+
properties.setProperty("blue-green-monitoring-socketTimeout", "10000");
71+
```
72+
73+
> [!WARNING]\
74+
> **Always ensure you provide a non-zero socket timeout value or a connect timeout value to the Blue/Green Deployment Plugin**
75+
>
76+
77+
78+
## Plan your Blue/Green switchover in advance
79+
80+
To optimize Blue/Green switchover support with the AWS JDBC Driver, advance planning is essential. Please follow these recommended steps:
81+
82+
1. Create a Blue/Green Deployment for your database.
83+
2. Configure your application by incorporating the `bg` plugin along with any additional parameters of your choice, then deploy your application to the corresponding environment.
84+
3. The order of steps 1 and 2 is flexible and can be performed in either sequence.
85+
4. Allow sufficient time for the deployed application with the active Blue/Green plugin to collect deployment status information. This process typically requires several minutes.
86+
5. Initiate the Blue/Green Deployment switchover through the AWS Console, CLI, or RDS API.
87+
6. Monitor the process until the switchover completes successfully or rolls back. This may take several minutes.
88+
7. Review the switchover summary in the application logs. This requires setting the log level to `FINE` for either the entire package `software.amazon.jdbc.plugin.bluegreen` or specifically for the class `software.amazon.jdbc.plugin.bluegreen.BlueGreenStatusProvider`.
89+
8. Update your application by deactivating the `bg` plugin through its removal from your application configuration. Redeploy your application afterward. Note that an active Blue/Green plugin produces no adverse effects once the switchover has been completed.
90+
9. Delete the Blue/Green Deployment through the appropriate AWS interface.
91+
10. The sequence of steps 8 and 9 is flexible and can be executed in either order based on your preference.
92+
93+
Here's an example of a switchover summary. Time zero corresponds to the beginning of the active switchover phase. Time offsets indicate the start time of each specific switchover phase.
94+
```
95+
[2025-04-23 17:42:26.537] [FINE ] [pool-30-thread-1] [software.amazon.jdbc.plugin.bluegreen.BlueGreenStatusProvider logSwitchoverFinalSummary] :
96+
----------------------------------------------------------------------------
97+
timestamp time offset (ms) event
98+
----------------------------------------------------------------------------
99+
2025-04-23T17:39:23.529507Z -46468 ms NOT_CREATED
100+
2025-04-23T17:39:23.795213Z -46202 ms CREATED
101+
2025-04-23T17:40:07.411020Z -2585 ms PREPARATION
102+
2025-04-23T17:40:09.996344Z 0 ms IN_PROGRESS
103+
2025-04-23T17:40:17.429581Z 7434 ms POST
104+
2025-04-23T17:40:35.853160Z 25857 ms Green topology changed
105+
2025-04-23T17:40:48.537135Z 38543 ms Blue DNS updated
106+
2025-04-23T17:42:23.163572Z 133174 ms Green DNS removed
107+
2025-04-23T17:42:26.536226Z 136547 ms COMPLETED
108+
----------------------------------------------------------------------------
109+
```
110+

0 commit comments

Comments
 (0)