From 6af2dd635f7e6f4103276df16d5c274a91ebf25e Mon Sep 17 00:00:00 2001 From: Favian Samatha Date: Mon, 29 Sep 2025 14:53:29 -0700 Subject: [PATCH] docs: update bg sections on README and UsingTheBlueGreenPlugin.md --- README.md | 23 ++++++------- .../using-plugins/UsingTheBlueGreenPlugin.md | 32 ++++++++++++------- 2 files changed, 29 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 20be2fe4..eeb8c3d7 100644 --- a/README.md +++ b/README.md @@ -146,23 +146,18 @@ To find all the documentation and concrete examples on how to use the AWS Advanc #### Amazon RDS Blue/Green Deployments -The AWS Advanced Python 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. +Support for Blue/Green deployments using the AWS Advanced Python Driver requires specific metadata tables. The following service versions provide support for Blue/Green Deployments: -**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. +- Supported RDS PostgreSQL Versions: `rds_tools v1.7 (17.1, 16.5, 15.9, 14.14, 13.17, 12.21)` and above. +- Supported Aurora PostgreSQL Versions: Engine Release `17.5, 16.9, 15.13, 14.18, 13.21` and above. +- Supported Aurora MySQL Versions: Engine Release `3.07` and above. -Supported RDS PostgreSQL Versions: `rds_tools v1.7 (17.1, 16.5, 15.9, 14.14, 13.17, 12.21)` and above.
-Supported Aurora PostgreSQL Versions: Engine Release `17.5, 16.9, 15.13, 14.18, 13.21` and above.
-Supported Aurora MySQL Versions: Engine Release `3.07` and above. +Please note that Aurora Global Database and RDS Multi-AZ clusters with Blue/Green deployments is currently not supported. For detailed information on supported database versions, refer to the [Blue/Green Deployment Plugin Documentation](./docs/using-the-python-driver/using-plugins/UsingTheBlueGreenPlugin.md). -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. - -AWS Advanced Python 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 Python 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. - -The limitations for versions earlier than 1.3.0 are: -- 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. -- The specific version requirements for Aurora MySQL versus Aurora PostgreSQL may vary, as the internal systems used by the wrapper can differ[^1]. - -[^1]: Aurora MySQL requires v3.07 or later. +In addition: +- **Post-switchover failures:** After a Blue/Green switchover, the wrapper may not properly detect the new cluster topology, leading to failed failover attempts. +- **Metadata inconsistencies:** Discrepancies between topology metadata and actual available endpoints prevent reliable operation. +- **Version-specific issues:** Requirements vary between Aurora MySQL and Aurora PostgreSQL due to different internal systems. #### MySQL Connector/Python C Extension diff --git a/docs/using-the-python-driver/using-plugins/UsingTheBlueGreenPlugin.md b/docs/using-the-python-driver/using-plugins/UsingTheBlueGreenPlugin.md index a61bf90a..4375719d 100644 --- a/docs/using-the-python-driver/using-plugins/UsingTheBlueGreenPlugin.md +++ b/docs/using-the-python-driver/using-plugins/UsingTheBlueGreenPlugin.md @@ -8,32 +8,40 @@ The AWS Python Driver leverages the Blue/Green Deployment approach by intelligen ## Prerequisites + > [!WARNING]\ -> **Blue/Green Support Behaviour and Version Compatibility** -> > Currently Supported Database Deployments: +> > - Aurora MySQL and PostgreSQL clusters > - RDS MySQL and PostgreSQL instances > > Unsupported Database Deployments and Configurations: +> > - RDS MySQL and PostgreSQL Multi-AZ clusters > - Aurora Global Database for MySQL and PostgreSQL -> -> Supported RDS PostgreSQL Versions: `rds_tools v1.7 (17.1, 16.5, 15.9, 14.14, 13.17, 12.21)`.
-> Supported Aurora PostgreSQL Versions: Engine Release `17.5, 16.9, 15.13, 14.18, 13.21`.
-> Supported Aurora MySQL Versions: Engine Release `3.07` and above. -> +> +> Additional Requirements: +> +> - AWS cluster and instance endpoints must be directly accessible from the client side +> - Connecting to database nodes using CNAME aliases is not supported +> +> **Blue/Green Support Behaviour and Version Compatibility:** +> +> The AWS Advanced Python Driver now includes enhanced full support for Blue/Green Deployments. This support requires a minimum database version that includes a specific metadata table. The metadata will be accessible provided the green deployment satisfies the minimum version compatibility requirements. This constraint **does not** apply to RDS MySQL. +> > 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 wrapper is available: > > ```sql > CREATE EXTENSION rds_tools; > ``` > -> If your database version does **not** match the supported versions listed above, the wrapper will automatically fallback to its previous behaviour. In this fallback mode, Blue/Green handling is subject to the limitations listed below: -> - 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. -> - The specific database version requirements for different database deployments may vary, as the internal systems used by the wrapper can differ. -> -> If you have questions or encounter issues, please open an issue in this repository. +> 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. +> +> **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. +> +> Supported RDS PostgreSQL Versions: `rds_tools v1.7 (17.1, 16.5, 15.9, 14.14, 13.17, 12.21)` and above.
+> Supported Aurora PostgreSQL Versions: Engine Release `17.5, 16.9, 15.13, 14.18, 13.21` and above.
+> Supported Aurora MySQL Versions: Engine Release `3.07` and above. ## What is the Blue/Green Deployment Plugin?