AWS aurora-dsql documentation change
Summary
Updated prerequisites to require 'iam:CreateServiceLinkedRole', added details about authentication token expiration behavior, restructured cluster creation steps with security-related options (KMS encryption, deletion protection), and revised multi-Region cluster setup documentation.
Security assessment
The changes document security-related configurations like IAM permissions, temporary authentication tokens with expiration, encryption settings using KMS, and deletion protection. However, there is no evidence these changes address a specific security vulnerability or incident.
Diff
diff --git a/aurora-dsql/latest/userguide/getting-started.md b/aurora-dsql/latest/userguide/getting-started.md index 5363fb709..75460bad7 100644 --- a//aurora-dsql/latest/userguide/getting-started.md +++ b//aurora-dsql/latest/userguide/getting-started.md @@ -7,2 +6,0 @@ PrerequisitesAccessing Aurora DSQLCreate a single-Region clusterConnect to a clu -Amazon Aurora DSQL is provided as a Preview service. To learn more, see [Betas and Previews ](https://aws.amazon.com/service-terms/) in the AWS Service Terms. - @@ -11 +9 @@ Amazon Aurora DSQL is provided as a Preview service. To learn more, see [Betas a -In the following sections, you’ll learn how to create single-Region and multi-Region Aurora DSQL clusters, connect to them, and create and load a sample schema. You will access clusters with the AWS Management Console and interact with your database using the psql utility. +Amazon Aurora DSQL is a serverless, distributed relational database optimized for transactional workloads. In the following sections, you’ll learn how to create single-Region and multi-Region Aurora DSQL clusters, connect to them, and create and load a sample schema. You will access clusters with the AWS Management Console and interact with your database using the `psql` utility. By the end, you’ll have a working Aurora DSQL cluster set up and ready to use for test or production workloads. @@ -25 +23 @@ In the following sections, you’ll learn how to create single-Region and multi- - * Step 4: Create a multi-Region peered cluster + * Step 4: Create a multi-Region cluster @@ -40 +38 @@ Before you can begin using Aurora DSQL, make sure you meet the following prerequ - * The ability to get access to the following IAM policy action: `dsql:*` + * The IAM permission `iam:CreateServiceLinkedRole` and the ability to get access to the IAM policy action `dsql:*` @@ -42 +40 @@ Before you can begin using Aurora DSQL, make sure you meet the following prerequ - * If you use the AWS CLI in a Unix-like environment, make sure that Python v3.8+ and psql v14+ are installed. To check your application versions, run the following commands. + * If you use the AWS CLI in a Unix-like environment, make sure that Python version 3.8+ and `psql` version 14+ are installed. To check your application versions, run the following commands. @@ -47 +45 @@ Before you can begin using Aurora DSQL, make sure you meet the following prerequ -If you use the AWS CLI in a different environment, make sure that you manually set up Python v3.8+ and psql v14+. +If you use the AWS CLI in a different environment, make sure that you manually set up Python version 3.8+ and `psql` version 14+. @@ -49 +47 @@ If you use the AWS CLI in a different environment, make sure that you manually s - * If you intend to access Aurora DSQL using AWS CloudShell, Python v3.8+ and psql v14+ are provided with no extra setup. For more information about AWS CloudShell, see [What is AWS CloudShell?](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html). + * If you intend to access Aurora DSQL using AWS CloudShell, Python version 3.8+ and `psql` version 14+ are provided with no extra setup. For more information about AWS CloudShell, see [What is AWS CloudShell?](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html). @@ -73,21 +71 @@ You can access Aurora DSQL through the following techniques. To learn how to use -You can access the AWS Management Console for Aurora DSQL at [https://console.aws.amazon.com/dsql](https://console.aws.amazon.com/dsql). You can perform the following actions in the console: - -**Create a cluster** - - -You can create either a single-Region or a multi-Region cluster. - -**Connect to a cluster** - - -Choose an authentication option that aligns with the policy attached to your IAM identity. Copy the authentication token and provide it as the password when you connect to your cluster. When you connect as an administrator, the console creates the token with the IAM action `dsql:DbConnectAdmin`. When you connect using a custom database role, the console creates a token with the IAM action `dsql:DbConnect`. - -**Modify a cluster** - - -You can enable or disable deletion protection. You can't delete a cluster when deletion protection is enabled. - -**Delete a cluster** - - -You can't undo this action and you won't be able to retrieve any data. +You can access the AWS Management Console for Aurora DSQL at [https://console.aws.amazon.com/dsql](https://console.aws.amazon.com/dsql). @@ -148 +126 @@ DBeaver is an open-source, GUI-based database tool. You can use it to connect to - 1. **Host** \- Use your cluster endpoint. + 1. **Host** – Use your cluster endpoint. @@ -150 +128 @@ DBeaver is an open-source, GUI-based database tool. You can use it to connect to -**Database** \- Enter `postgres` +**Database** – Enter `postgres` @@ -152 +130 @@ DBeaver is an open-source, GUI-based database tool. You can use it to connect to -**Authentication** \- Choose `Database Native` +**Authentication** – Choose `Database Native` @@ -154 +132 @@ DBeaver is an open-source, GUI-based database tool. You can use it to connect to -**Username** \- Enter `admin` +**Username** – Enter `admin` @@ -156 +134 @@ DBeaver is an open-source, GUI-based database tool. You can use it to connect to -**Password** \- Generate an [ authentication token](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/SECTION_authentication-token.html). Copy the generated token and use it as your password. +**Password** – Generate an [ authentication token](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/SECTION_authentication-token.html). Copy the generated token and use it as your password. @@ -173 +151 @@ The administrative features provided by DBeaver for the PostgreSQL databases (su -**Authentication credentials expiry** +**Authentication credentials expiry for DBeaver** @@ -175 +153 @@ The administrative features provided by DBeaver for the PostgreSQL databases (su -Established sessions will remain authenticated for a maximum of 1 hour or until an explicit disconnect or a client-side timeout takes place. If new connections need to be established, a valid Authentication token must be provided in the **Password** field of the **Connection settings**. Trying to open a new session (for example, to list new tables, or a new SQL console) will force a new authentication attempt. If the authentication token configured in the **Connection settings** is no longer valid, that new session will fail and all the previously opened sessions will get invalidated at that point in time too. Have this in mind when choosing the duration of your IAM authentication token with the `expires-in` option. +Established sessions remain authenticated for a maximum of 1 hour or until DBeaver disconnects or times out. To establish new connections, provide a valid authentication token in the **Password** field of **Connection settings**. Trying to open a new session (for example, to list new tables, or a new SQL console) forces a new authentication attempt. If the authentication token configured in the **Connection settings** is no longer valid, the new session fails, and DBeaver invalidates all previously opened sessions. Keep this in mind when choosing the duration of your IAM authentication token with the `expires-in` option. @@ -187 +165 @@ JetBrains DataGrip is a cross-platform IDE for working with SQL and databases, i - 1. **Host** \- Use your cluster endpoint. + 1. **Host** – Use your cluster endpoint. @@ -189 +167 @@ JetBrains DataGrip is a cross-platform IDE for working with SQL and databases, i -**Port** \- Aurora DSQL uses the PostgreSQL default: `5432` +**Port** – Aurora DSQL uses the PostgreSQL default: `5432` @@ -191 +169 @@ JetBrains DataGrip is a cross-platform IDE for working with SQL and databases, i -**Database** \- Aurora DSQL uses the PostgreSQL default of `postgres` +**Database** – Aurora DSQL uses the PostgreSQL default of `postgres` @@ -193 +171 @@ JetBrains DataGrip is a cross-platform IDE for working with SQL and databases, i -**Authentication** \- Choose `User & Password `. +**Authentication** – Choose `User & Password `. @@ -195 +173 @@ JetBrains DataGrip is a cross-platform IDE for working with SQL and databases, i -**Username** \- Enter `admin`. +**Username** – Enter `admin`. @@ -197 +175 @@ JetBrains DataGrip is a cross-platform IDE for working with SQL and databases, i -**Password** \- [ Generate a token](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/SECTION_authentication-token.html) and paste it into this field. +**Password** – [ Generate a token](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/SECTION_authentication-token.html) and paste it into this field. @@ -199 +177 @@ JetBrains DataGrip is a cross-platform IDE for working with SQL and databases, i -**URL** \- Don't modify this field. It will be auto-populated based on the other fields. +**URL** – Don't modify this field. It will be auto-populated based on the other fields. @@ -201 +179 @@ JetBrains DataGrip is a cross-platform IDE for working with SQL and databases, i - 3. **Password** \- Provide this by generating an authentication token. Copy the resulting output of the token generator and paste it into the password field. + 3. **Password** – Provide this by generating an authentication token. Copy the resulting output of the token generator and paste it into the password field. @@ -226 +204 @@ PostgreSQL | Aurora DSQL | Notes -Role (also known as User or Group) | Database Role | Aurora DSQL creates a role for you named `admin`. If you create custom database roles, you must use the admin role to associate them with IAM roles for authenticating when connecting to your cluster. For more information, see [Configure custom database roles](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/using-database-and-iam-roles.html). +Role (also known as User or Group) | Database Role | Aurora DSQL creates a role for you named `admin`. When you create custom database roles, you must use the `admin` role to associate them with IAM roles for authenticating when connecting to your cluster. For more information, see [Configure custom database roles](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/using-database-and-iam-roles.html). @@ -228 +206 @@ Host (also known as hostname or hostspec) | Cluster Endpoint | Aurora DSQL singl -Port | N/A - use default `5432` | This is the PostgreSQL default. +Port | N/A – use default `5432` | This is the PostgreSQL default. @@ -235 +213 @@ Password | Authentication Token | Aurora DSQL requires temporary authentication -The basic unit of Aurora DSQL is the cluster, which is where you store your data. In this task, you create a cluster in a single Region. +The basic unit of Aurora DSQL is the cluster, which is where you store your data. In this task, you create a cluster in a single AWS Region. @@ -237 +215 @@ The basic unit of Aurora DSQL is the cluster, which is where you store your data -###### To create a new cluster in Aurora DSQL +###### To create a single-Region cluster in Aurora DSQL @@ -241 +219,3 @@ The basic unit of Aurora DSQL is the cluster, which is where you store your data - 2. Choose **Create cluster**. + 2. Choose **Create cluster** and then **Single-Region**. + + 3. (Optional) In **Cluster settings** , select any of the following options: @@ -243 +223 @@ The basic unit of Aurora DSQL is the cluster, which is where you store your data - 3. Configure any settings that you want, such as deletion protection or tags. + * Select **Customize encryption settings (advanced)** to choose or create an AWS KMS key. @@ -245 +225,5 @@ The basic unit of Aurora DSQL is the cluster, which is where you store your data - 4. Choose **Create cluster**. + * Select **Enable deletion protection** to prevent a delete operation from removing your cluster. By default, deletion protection is selected. + + 4. (Optional) In **Tags** , choose or enter a tag for this cluster. + + 5. Choose **Create cluster**. @@ -252 +236,3 @@ The basic unit of Aurora DSQL is the cluster, which is where you store your data -Authentication is managed using IAM so you don't need to store credentials in the database. An authentication token is a unique string of characters that is generated dynamically. The token is only used for authentication and doesn't affect the connection after it is established. Before attempting to connect, make sure that your IAM identity has the `dsql:DbConnectAdmin` permission, as described in Prerequisites. +A _cluster endpoint_ is automatically generated when you create an Aurora DSQL cluster based on its cluster ID and Region. The naming format is ``clusterid`.dsql.`region`.on.aws`. A client uses the endpoint to create a network connection to your cluster. + +Authentication is managed using IAM so you don't need to store credentials in the database. An _authentication token_ is a unique string of characters that is generated dynamically. The token is only used for authentication and doesn't affect the connection after it is established. Before attempting to connect, make sure that your IAM identity has the `dsql:DbConnectAdmin` permission, as described in Prerequisites. @@ -254 +240 @@ Authentication is managed using IAM so you don't need to store credentials in th -###### To connect to the cluster with an authentication token +###### To connect to your cluster with an authentication token @@ -266 +252 @@ Authentication is managed using IAM so you don't need to store credentials in th - 6. On the command line, use the following command to start psql and connect to your cluster. Replace ``your_cluster_endpoint`` with the cluster endpoint that you copied previously. + 6. On the operating system command line, use the following command to start `psql` and connect to your cluster. Replace ``your_cluster_endpoint`` with the cluster endpoint that you copied previously. @@ -273 +259 @@ Authentication is managed using IAM so you don't need to store credentials in th -When prompted for a password, enter the authentication token that you copied previously. If you try to re-connect using an expired token, the connection request is denied. For more information, see [Generating an authentication token in Amazon Aurora DSQL](./SECTION_authentication-token.html). +When prompted for a password, enter the authentication token that you copied previously. If you try to reconnect using an expired token, the connection request is denied. For more information, see [Generating an authentication token in Amazon Aurora DSQL](./SECTION_authentication-token.html). @@ -343 +329 @@ The following sample output shows that Department Three has the most sales. -## Step 4: Create a multi-Region peered cluster +## Step 4: Create a multi-Region cluster @@ -345 +331 @@ The following sample output shows that Department Three has the most sales. -When you create a multi-Region peered cluster, you specify the following Regions: +When you create a multi-Region cluster, you specify the following Regions: @@ -347 +333 @@ When you create a multi-Region peered cluster, you specify the following Regions - * The peered cluster Region +**Remote Region** @@ -349 +334,0 @@ When you create a multi-Region peered cluster, you specify the following Regions -This is a separate Region in which you create a second cluster. Aurora DSQL replicates all writes on the original cluster to the peered cluster. You can read and write on any peered cluster. @@ -351 +336 @@ This is a separate Region in which you create a second cluster. Aurora DSQL repl - * The witness Region +This is the Region in which you create a second cluster. You create a second cluster in this Region and peer it to your initial cluster. Aurora DSQL replicates all writes on the initial cluster to the remote cluster. You can read and write on any cluster. @@ -353 +338 @@ This is a separate Region in which you create a second cluster. Aurora DSQL repl -This Region receives all data that is written to peered clusters, but you can't write to it. The witness Region stores a limited window of encrypted transaction logs. Aurora DSQL uses these capabilities to provide multi-Region durability and availability. +**Witness Region** @@ -355,0 +341 @@ This Region receives all data that is written to peered clusters, but you can't +This Region receives all data that is written to the multi-Region cluster. However, witness Regions don't host client endpoints and don't provide user data access. A limited window of the encrypted transaction log is maintained in witness Regions. This log facilitates recovery and supports transactional quorum if a Region becomes unavailable. @@ -356,0 +343 @@ This Region receives all data that is written to peered clusters, but you can't +The following example shows how to create an initial cluster, create a second cluster in a different Region, and then peer the two clusters to create a multi-Region cluster. It also demonstrates cross-Region write replication and consistent reads from both Regional endpoints. @@ -358 +345 @@ This Region receives all data that is written to peered clusters, but you can't -The following example demonstrates cross-Region write replication and consistent reads from both Regional endpoints. +###### To create a multi-Region cluster @@ -360 +347 @@ The following example demonstrates cross-Region write replication and consistent -###### To create a new cluster and connect in multiple Regions + 1. Sign in to the AWS Management Console and open the Aurora DSQL console at [https://console.aws.amazon.com/dsql](https://console.aws.amazon.com/dsql). @@ -362 +349 @@ The following example demonstrates cross-Region write replication and consistent - 1. In the Aurora DSQL console, go to the **Clusters** page. + 2. In the navigation pane, choose **Clusters**. @@ -364 +351 @@ The following example demonstrates cross-Region write replication and consistent - 2. Choose **Create cluster**. + 3. Choose **Create cluster** and then **Multi-Region**. @@ -366 +353 @@ The following example demonstrates cross-Region write replication and consistent - 3. Choose **Add peered Regions**. + 4. (Optional) In **Cluster settings** , select any of the following options for your initial cluster: @@ -368 +355 @@ The following example demonstrates cross-Region write replication and consistent - 4. Choose a Region for your peered cluster from **Peered cluster Region**. + * Select **Customize encryption settings (advanced)** to choose or create an AWS KMS key. @@ -370 +357 @@ The following example demonstrates cross-Region write replication and consistent - 5. Choose **us-west-2** as the witness Region. + * Select **Enable deletion protection** to prevent a delete operation from removing your cluster. By default, deletion protection is selected. @@ -372 +359 @@ The following example demonstrates cross-Region write replication and consistent -###### Note + 5. In **Multi-Region settings** , choose the following options for your initial cluster: @@ -374 +361 @@ The following example demonstrates cross-Region write replication and consistent -Witness Regions don't host client endpoints and don't provide user data access. A limited window of the encrypted transaction log is maintained in witness Regions. This facilitates recovery and supports transactional quorum in the event of Region unavailability. + * In **Witness Region** , choose a Region. Currently, only US-based Regions are supported for witness Regions in multi-Region clusters. @@ -376 +363 @@ Witness Regions don't host client endpoints and don't provide user data access. - 6. Choose any additional settings, such as deletion protection or tags. + * (Optional) In **Remote Region cluster ARN** , enter an ARN for an existing cluster in another Region. If no cluster exists to serve as the second cluster in your multi-Region cluster, complete setup after you create the initial cluster. @@ -378 +365 @@ Witness Regions don't host client endpoints and don't provide user data access. - 7. Choose **Create cluster**. + 6. (Optional) Choose tags for your initial cluster. @@ -380 +367 @@ Witness Regions don't host client endpoints and don't provide user data access. - 8. Open the AWS CloudShell console at [https://console.aws.amazon.com/cloudshell](https://console.aws.amazon.com/cloudshell) in two browser tabs. Open one environment in us-east-1 and another in us-east-2. + 7. Choose **Create cluster** to create your initial cluster. If you didn't enter an ARN in the previous step, the console shows the **Cluster setup pending** notification. @@ -382 +369 @@ Witness Regions don't host client endpoints and don't provide user data access. - 9. In the Aurora DSQL console, choose the peered cluster that you created. + 8. In the **Cluster setup pending** notification, choose **Complete multi-Region cluster setup**. This action initiates creation of a second cluster in another Region. @@ -384 +371 @@ Witness Regions don't host client endpoints and don't provide user data access. - 10. Choose the peer in the **Peered Regions** column. + 9. Choose one of the following options for your second cluster: @@ -386 +373 @@ Witness Regions don't host client endpoints and don't provide user data access. - 11. Copy the endpoint to your peered cluster. + * **Add remote Region cluster ARN** – Choose this option if a cluster exists, and you want it to be the second cluster in your multi-Region cluster.