diff --git a/docs/Documentation.md b/docs/Documentation.md index 3e68db2a1..51f4f710a 100644 --- a/docs/Documentation.md +++ b/docs/Documentation.md @@ -13,6 +13,7 @@ - [Aurora Initial Connection Strategy Plugin](./using-the-jdbc-driver/using-plugins/UsingTheAuroraInitialConnectionStrategyPlugin.md) - [AWS Secrets Manager Plugin](./using-the-jdbc-driver/using-plugins/UsingTheAwsSecretsManagerPlugin.md) - [Blue/Green Deployment Plugin](./using-the-jdbc-driver/using-plugins/UsingTheBlueGreenPlugin.md) + - [Using Roles in MySQL 8.0 to Grant Privileges to mysql.rds_topology](./using-the-jdbc-driver/using-plugins/GrantingPermissionsToNonAdminUserInMySQL.md) - [Driver Metadata Connection Plugin](./using-the-jdbc-driver/using-plugins/UsingTheDriverMetadataConnectionPlugin.md) - [Failover Plugin](./using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md) - [Failover Configuration Guide](./using-the-jdbc-driver/FailoverConfigurationGuide.md) diff --git a/docs/using-the-jdbc-driver/using-plugins/GrantingPermissionsToNonAdminUserInMySQL.md b/docs/using-the-jdbc-driver/using-plugins/GrantingPermissionsToNonAdminUserInMySQL.md new file mode 100644 index 000000000..f3ac966f2 --- /dev/null +++ b/docs/using-the-jdbc-driver/using-plugins/GrantingPermissionsToNonAdminUserInMySQL.md @@ -0,0 +1,164 @@ +# Using Roles in MySQL 8.0 to Grant Privileges to mysql.rds_topology + +For customers using the [Blue/Green plugin](UsingTheBlueGreenPlugin.md) for their planned [Blue/Green Deployment](https://docs.aws.amazon.com/whitepapers/latest/blue-green-deployments/introduction.html), every user account on the DB instance/cluster needs to be granted SELECT privileges to the `mysql.rds_topology` metadata table. This creates an extra operational overhead for customers to adopt fast switchovers. + +This document uses [MySQL roles](https://dev.mysql.com/doc/refman/8.0/en/roles.html) to reduce complexity for multi-user grant to read from `mysql.rds_topology`. + +## Prerequisites + +1. First we need to create a role that grants `SELECT` privilege to `mysql.rds_topology`. + ```bash + mysql> CREATE ROLE 'rds_topology_role'; + Query OK, 0 rows affected (0.06 sec) + + mysql> GRANT SELECT ON mysql.rds_topology TO 'rds_topology_role'; + Query OK, 0 rows affected (0.06 sec) + ``` +2. Then create our test application users. + ```bash + mysql> CREATE USER 'app1'@'%' IDENTIFIED BY 'Amaz0n1an_'; + Query OK, 0 rows affected (0.06 sec) + + mysql> CREATE USER 'app2'@'%' IDENTIFIED BY 'Amaz0n1an_'; + Query OK, 0 rows affected (0.07 sec) + + mysql> SHOW GRANTS FOR 'app1'@'%'; + +----------------------------------+ + | Grants for app1@% | + +----------------------------------+ + | GRANT USAGE ON *.* TO `app1`@`%` | + +----------------------------------+ + 1 row in set (0.06 sec) + + mysql> SHOW GRANTS FOR 'app2'@'%'; + +----------------------------------+ + | Grants for app2@% | + +----------------------------------+ + | GRANT USAGE ON *.* TO `app2`@`%` | + +----------------------------------+ + 1 row in set (0.07 sec) + ``` + +## Activate the Role + +### Option 1: [mandatory_roles](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_mandatory_roles) with [SET DEFAULT ROLE](https://dev.mysql.com/doc/refman/8.0/en/set-default-role.html) + +This is recommended if there is only a small and static set of user accounts that require the privileges. + +| Pros | Cons | +|-------------------------------------------------------------------------------|---------------------------------------------------------------------------------------| +| Assign roles to ALL user accounts by default, activate only for select users. | The list of user accounts to revoke/activate the role becomes a maintenance overhead. | + +First modify the cluster parameter group to add the role `rds_topology_role` we created as a global mandatory role. + +```bash +mysql> select @@global.mandatory_roles; ++--------------------------+ +| @@global.mandatory_roles | ++--------------------------+ +| rds_topology_role | ++--------------------------+ +1 row in set (0.06 sec) + +``` + +When the application users connect, they will see that the role will be granted but not active. + +```bash +mysql> SELECT CURRENT_USER(); ++----------------+ +| CURRENT_USER() | ++----------------+ +| app1@% | ++----------------+ +1 row in set (0.07 sec) + +mysql> SHOW GRANTS \G +*************************** 1. row *************************** +Grants for app1@%: GRANT USAGE ON *.* TO `app1`@`%` +*************************** 2. row *************************** +Grants for app1@%: GRANT `rds_topology_role`@`%` TO `app1`@`%` +2 rows in set (0.06 sec) + +mysql> SELECT * FROM mysql.rds_topology; +ERROR 1142 (42000): SELECT command denied to user 'app1'@'172.44.75.29' +for table 'rds_topology' +``` + +To activate the role, we can use `SET DEFAULT ROLE` via the customer admin account, then we should be able to query the +metadata table. + +```bash +mysql> SET DEFAULT ROLE 'rds_topology_role' TO 'app1'@'%', 'app2'@'%'; +Query OK, 0 rows affected (0.07 sec) +``` + +The application users should be able to query the topology metadata at this time. + +```bash +mysql> SHOW GRANTS \G +*************************** 1. row *************************** +Grants for app1@%: GRANT USAGE ON *.* TO `app1`@`%` +*************************** 2. row *************************** +Grants for app1@%: GRANT SELECT ON `mysql`.`rds_topology` TO `app1`@`%` +*************************** 3. row *************************** +Grants for app1@%: GRANT `rds_topology_role`@`%` TO `app1`@`%` +3 rows in set (0.06 sec) + +mysql> SELECT * FROM mysql.rds_topology; ++------------+----------------------------------------------------------------------------+------+------------------------------+-----------+---------+ +| id | endpoint | port | role | status | version | ++------------+----------------------------------------------------------------------------+------+------------------------------+-----------+---------+ +| 1116047085 | bgd113287-green-adbzs8.cluster-cyfc0ofzobmh.us-east-1-qa.rds.amazonaws.com | 3306 | +BLUE_GREEN_DEPLOYMENT_TARGET | AVAILABLE | 1.0 | +| 1125403360 | bgd113287.cluster-cyfc0ofzobmh.us-east-1-qa.rds.amazonaws.com | 3306 | BLUE_GREEN_DEPLOYMENT_SOURCE | +AVAILABLE | 1.0 | ++------------+----------------------------------------------------------------------------+------+------------------------------+-----------+---------+ +2 rows in set (0.06 sec) + +``` + +### Option 2: [mandatory_roles](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_mandatory_roles) with [activate_all_roles_on_login](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_activate_all_roles_on_login) + +This is recommended if the list of user accounts that require access to the topology metadata table is dynamic. + +| Pros | Cons | +|-------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Assign and activate the role at the same time to ALL users. | Existing users may have assigned but deactivated roles. `activate_all_roles_on_login` will override this behavior and also activate all roles assigned to existing users aside from `rds_topology_role`. | + +First modify the cluster parameter group to add the role `rds_topology_role` we created as a global mandatory role and +enable `activate_all_roles_on_login`. + +```bash +mysql> SELECT @@global.activate_all_roles_on_login, @@global.mandatory_roles; ++--------------------------------------+--------------------------+ +| @@global.activate_all_roles_on_login | @@global.mandatory_roles | ++--------------------------------------+--------------------------+ +| 1 | rds_topology_role | ++--------------------------------------+--------------------------+ +1 row in set (0.06 sec) +``` + +After these changes, ALL users will be assigned the new role and it will also be active. + +```bash +mysql> SHOW GRANTS \G +*************************** 1. row *************************** +Grants for app1@%: GRANT USAGE ON *.* TO `app1`@`%` +*************************** 2. row *************************** +Grants for app1@%: GRANT SELECT ON `mysql`.`rds_topology` TO `app1`@`%` +*************************** 3. row *************************** +Grants for app1@%: GRANT `rds_topology_role`@`%` TO `app1`@`%` +3 rows in set (0.06 sec) + +mysql> SELECT * FROM mysql.rds_topology; ++------------+----------------------------------------------------------------------------+------+------------------------------+-----------+---------+ +| id | endpoint | port | role | status | version | ++------------+----------------------------------------------------------------------------+------+------------------------------+-----------+---------+ +| 1116047085 | bgd113287-green-adbzs8.cluster-cyfc0ofzobmh.us-east-1-qa.rds.amazonaws.com | 3306 | +BLUE_GREEN_DEPLOYMENT_TARGET | AVAILABLE | 1.0 | +| 1125403360 | bgd113287.cluster-cyfc0ofzobmh.us-east-1-qa.rds.amazonaws.com | 3306 | BLUE_GREEN_DEPLOYMENT_SOURCE | +AVAILABLE | 1.0 | ++------------+----------------------------------------------------------------------------+------+------------------------------+-----------+---------+ +2 rows in set (0.06 sec)Ò +``` diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheBlueGreenPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheBlueGreenPlugin.md index c19de65b3..78337b9bc 100644 --- a/docs/using-the-jdbc-driver/using-plugins/UsingTheBlueGreenPlugin.md +++ b/docs/using-the-jdbc-driver/using-plugins/UsingTheBlueGreenPlugin.md @@ -7,6 +7,9 @@ The [Blue/Green Deployment](https://docs.aws.amazon.com/whitepapers/latest/blue- The AWS Advanced JDBC 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. ## Prerequisites +- AWS cluster and instance endpoints must be directly accessible from the client side +- :warning: Extra permissions are required for non-admin users so that the blue/green metadata table/function can be properly queried. If the permissions are not granted, the metadata table/function will not be visible and blue/green plugin functionality will not work properly. Please see the [Connecting with non-admin users](#connecting-with-non-admin-users) section below. + > [!WARNING]\ > Currently Supported Database Deployments: > - Aurora MySQL and PostgreSQL clusters @@ -17,8 +20,6 @@ The AWS Advanced JDBC Wrapper leverages the Blue/Green Deployment approach by in > - Aurora Global Database for MySQL and PostgreSQL > > Additional Requirements: -> - AWS cluster and instance endpoints must be directly accessible from the client side -> - :warning: If connecting with non-admin users, permissions must be granted to the users so that the blue/green metadata table/function can be properly queried. If the permissions are not granted, the metadata table/function will not be visible and blue/green plugin functionality will not work properly. Please see the [Connecting with non-admin users](#connecting-with-non-admin-users) section below. > - Connecting to database nodes using CNAME aliases is not supported > > **Blue/Green Support Behaviour and Version Compatibility:** @@ -90,11 +91,12 @@ properties.setProperty("blue-green-monitoring-socketTimeout", "10000"); > [!WARNING]\ > **Always ensure you provide a non-zero socket timeout value or a connect timeout value to the Blue/Green Deployment Plugin** -> ## Connecting with non-admin users + > [!WARNING]\ -> If connecting with non-admin users, permissions must be granted to the users so that the blue/green metadata table/function can be properly queried. If the permissions are not granted, the metadata table/function will not be visible and blue/green plugin functionality will not work properly. +> The following permissions are **required** for every non-admin user account connecting to the DB instance/cluster. +> If the permissions are not granted, the metadata table/function will not be visible and blue/green plugin functionality will not work properly. | Environment | Required permission statements | |-------------------|-----------------------------------------------------------------------------------------------------------------------| @@ -103,6 +105,9 @@ properties.setProperty("blue-green-monitoring-socketTimeout", "10000"); | Aurora MySQL | `GRANT SELECT ON mysql.rds_topology TO 'your_user'@'%';`
`FLUSH PRIVILEGES;` | | RDS MySQL | `GRANT SELECT ON mysql.rds_topology TO 'your_user'@'%';`
`FLUSH PRIVILEGES;` | +In MySQL, you can leverage MySQL Role to grant the required permissions to multiple users at once to reduce operational overhead before switchover. +See instructions in [Using Roles in MySQL 8.0 to Grant Privileges to mysql.rds_topology](./GrantingPermissionsToNonAdminUserInMySQL.md). + ## Plan your Blue/Green switchover in advance To optimize Blue/Green switchover support with the AWS Advanced JDBC Wrapper, advance planning is essential. Please follow these recommended steps: