Skip to content

Commit d8526be

Browse files
aaron-congoaaron-congo
authored
docs: Blue/Green plugin (#921)
1 parent 2caf143 commit d8526be

File tree

3 files changed

+159
-14
lines changed

3 files changed

+159
-14
lines changed

‎README.md

Lines changed: 29 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -146,9 +146,35 @@ To find all the documentation and concrete examples on how to use the AWS Advanc
146146

147147
#### Amazon RDS Blue/Green Deployments
148148

149-
This driver currently does not support switchover in Amazon RDS Blue/Green Deployments. In order to execute a Blue/Green deployment with the driver,
150-
please ensure your application is coded to retry the database connection. Retry will allow the driver to re-establish a connection to an available
151-
database instance. Without a retry, the driver will not be able to identify an available database instance after blue/green switchover has occurred.
149+
Although the AWS Advanced Python Wrapper is not compatible with [AWS Blue/Green Deployments](https://docs.aws.amazon.com/whitepapers/latest/overview-deployment-options/bluegreen-deployments.html) and does not officially support them, the combination of the AWS Advanced Python Wrapper and the Failover Plugin has been validated for use with clusters that employ Blue/Green Deployments. While general basic connectivity to both Blue and Green clusters is always in place, some failover cases are not fully supported.
150+
The current limitations are:
151+
- 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.
152+
- The specific database version requirements for different database deployments may vary, as the internal systems used by the wrapper can differ.
153+
154+
The development team is aware of these limitations and is working to improve the wrapper's awareness and handling of Blue/Green switchovers.
155+
156+
> [!WARNING]\
157+
> The AWS Advanced Python Wrapper now includes support for Blue/Green Deployments according to the description below:
158+
>
159+
> Currently Supported Database Deployments:
160+
> - Aurora MySQL and PostgreSQL clusters
161+
> - RDS MySQL and PostgreSQL instances
162+
>
163+
> Unsupported Database Deployments and Configurations:
164+
> - RDS MySQL and PostgreSQL Multi-AZ clusters
165+
> - Aurora Global Database for MySQL and PostgreSQL
166+
>
167+
> Supported RDS PostgreSQL Versions: `rds_tools v1.7 (17.1, 16.5, 15.9, 14.14, 13.17, 12.21)`.<br>
168+
> Supported Aurora PostgreSQL Versions: Engine Release `17.5, 16.9, 15.13, 14.18, 13.21`.<br>
169+
> Supported Aurora MySQL Versions: Engine Release `3.07` and above.
170+
>
171+
> For RDS Postgres, you will also need to manually install the `rds_tools` extension using the following DDL so that the metadata required by the driver is available:
172+
>
173+
> ```sql
174+
> CREATE EXTENSION rds_tools;
175+
> ```
176+
>
177+
> If your database version does **not** match the supported versions listed above, the driver will automatically fallback to its previous behaviour. In this fallback mode, Blue/Green handling is subject to the same limitations listed above. If you have questions or encounter issues, please open an issue in this repository.
152178
153179
#### MySQL Connector/Python C Extension
154180

‎docs/using-the-python-driver/UsingThePythonDriver.md

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -61,17 +61,18 @@ Plugins are loaded and managed through the Connection Plugin Manager and may be
6161

6262
The AWS Advanced Python Driver has several built-in plugins that are available to use. Please visit the individual plugin page for more details.
6363

64-
| Plugin name | Plugin Code | Database Compatibility | Description | Additional Required Dependencies |
65-
|--------------------------------------------------------------------------------------------------------|-----------------------------|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------|
66-
| [Failover Connection Plugin](./using-plugins/UsingTheFailoverPlugin.md) | `failover` | Aurora | Enables the failover functionality supported by Amazon Aurora clusters. Prevents opening a wrong connection to an old writer host dues to stale DNS after failover event. This plugin is enabled by default. | None |
67-
| [Host Monitoring Connection Plugin](./using-plugins/UsingTheHostMonitoringPlugin.md) | `host_monitoring` | Aurora | Enables enhanced host connection failure monitoring, allowing faster failure detection rates. This plugin is enabled by default. | None |
68-
| [IAM Authentication Connection Plugin](./using-plugins/UsingTheIamAuthenticationPlugin.md) | `iam` | Any database | Enables users to connect to their Amazon Aurora clusters using AWS Identity and Access Management (IAM). | [Boto3 - AWS SDK for Python](https://aws.amazon.com/sdk-for-python/) |
69-
| [AWS Secrets Manager Connection Plugin](./using-plugins/UsingTheAwsSecretsManagerPlugin.md) | `aws_secrets_manager` | Any database | Enables fetching database credentials from the AWS Secrets Manager service. | [Boto3 - AWS SDK for Python](https://aws.amazon.com/sdk-for-python/) |
70-
| [Federated Authentication Connection Plugin](./using-plugins/UsingTheFederatedAuthenticationPlugin.md) | `federated_auth` | Any database | Enables users to authenticate via Federated Identity and then database access via IAM. | [Boto3 - AWS SDK for Python](https://aws.amazon.com/sdk-for-python/) |
71-
| Aurora Stale DNS Plugin | `stale_dns` | Aurora | Prevents incorrectly opening a new connection to an old writer host when DNS records have not yet updated after a recent failover event. <br><br> :warning:**Note:** Contrary to `failover` plugin, `stale_dns` plugin doesn't implement failover support itself. It helps to eliminate opening wrong connections to an old writer host after cluster failover is completed. <br><br> :warning:**Note:** This logic is already included in `failover` plugin so you can omit using both plugins at the same time. | None |
72-
| [Aurora Connection Tracker Plugin](./using-plugins/UsingTheAuroraConnectionTrackerPlugin.md) | `aurora_connection_tracker` | Aurora | Tracks all the opened connections. In the event of a cluster failover, the plugin will close all the impacted connections to the host. This plugin is enabled by default. | None |
73-
| [Read Write Splitting Plugin](./using-plugins/UsingTheReadWriteSplittingPlugin.md) | `read_write_splitting` | Aurora | Enables read write splitting functionality where users can switch between database reader and writer instances. | None |
74-
| [Fastest Response Strategy Plugin](./using-plugins/UsingTheFastestResponseStrategyPlugin.md) | `fastest_response_strategy` | Aurora | A host selection strategy plugin that uses a host monitoring service to monitor each reader host's response time and choose the host with the fastest response. | None |
64+
| Plugin name | Plugin Code | Database Compatibility | Description | Additional Required Dependencies |
65+
|--------------------------------------------------------------------------------------------------------|-----------------------------|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------|
66+
| [Failover Connection Plugin](./using-plugins/UsingTheFailoverPlugin.md) | `failover` | Aurora | Enables the failover functionality supported by Amazon Aurora clusters. Prevents opening a wrong connection to an old writer host dues to stale DNS after failover event. This plugin is enabled by default. | None |
67+
| [Host Monitoring Connection Plugin](./using-plugins/UsingTheHostMonitoringPlugin.md) | `host_monitoring` | Aurora | Enables enhanced host connection failure monitoring, allowing faster failure detection rates. This plugin is enabled by default. | None |
68+
| [IAM Authentication Connection Plugin](./using-plugins/UsingTheIamAuthenticationPlugin.md) | `iam` | Any database | Enables users to connect to their Amazon Aurora clusters using AWS Identity and Access Management (IAM). | [Boto3 - AWS SDK for Python](https://aws.amazon.com/sdk-for-python/) |
69+
| [AWS Secrets Manager Connection Plugin](./using-plugins/UsingTheAwsSecretsManagerPlugin.md) | `aws_secrets_manager` | Any database | Enables fetching database credentials from the AWS Secrets Manager service. | [Boto3 - AWS SDK for Python](https://aws.amazon.com/sdk-for-python/) |
70+
| [Federated Authentication Connection Plugin](./using-plugins/UsingTheFederatedAuthenticationPlugin.md) | `federated_auth` | Any database | Enables users to authenticate via Federated Identity and then database access via IAM. | [Boto3 - AWS SDK for Python](https://aws.amazon.com/sdk-for-python/) |
71+
| Aurora Stale DNS Plugin | `stale_dns` | Aurora | Prevents incorrectly opening a new connection to an old writer host when DNS records have not yet updated after a recent failover event. <br><br> :warning:**Note:** Contrary to `failover` plugin, `stale_dns` plugin doesn't implement failover support itself. It helps to eliminate opening wrong connections to an old writer host after cluster failover is completed. <br><br> :warning:**Note:** This logic is already included in `failover` plugin so you can omit using both plugins at the same time. | None |
72+
| [Aurora Connection Tracker Plugin](./using-plugins/UsingTheAuroraConnectionTrackerPlugin.md) | `aurora_connection_tracker` | Aurora | Tracks all the opened connections. In the event of a cluster failover, the plugin will close all the impacted connections to the host. This plugin is enabled by default. | None |
73+
| [Read Write Splitting Plugin](./using-plugins/UsingTheReadWriteSplittingPlugin.md) | `read_write_splitting` | Aurora | Enables read write splitting functionality where users can switch between database reader and writer instances. | None |
74+
| [Fastest Response Strategy Plugin](./using-plugins/UsingTheFastestResponseStrategyPlugin.md) | `fastest_response_strategy` | Aurora | A host selection strategy plugin that uses a host monitoring service to monitor each reader host's response time and choose the host with the fastest response. | None |
75+
| [Blue/Green Deployment Plugin](./using-plugins/UsingTheBlueGreenPlugin.md) | `bg` | Aurora, <br>RDS Instance | Enables client-side Blue/Green Deployment support. | None |
7576

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

0 commit comments

Comments
 (0)