AWS AmazonRDS documentation change
Summary
Updated documentation structure by replacing inline content with hyperlinks to dedicated pages for Data API topics (region availability, limitations, comparisons, authorization, etc.). Added 'Amazon' branding to RDS Data API references and fixed markdown formatting.
Security assessment
Changes are organizational/structural improvements rather than security fixes. While authorization and Secrets Manager permissions are mentioned, these updates only link to existing security documentation rather than introducing new security controls or addressing vulnerabilities.
Diff
diff --git a/AmazonRDS/latest/AuroraUserGuide/data-api.md b/AmazonRDS/latest/AuroraUserGuide/data-api.md index 15d857525..12b840c84 100644 --- a//AmazonRDS/latest/AuroraUserGuide/data-api.md +++ b//AmazonRDS/latest/AuroraUserGuide/data-api.md @@ -5,3 +5 @@ -Region and version availabilityLimitationsComparison with Serverless v2 and provisioned, and Aurora Serverless v1Authorizing accessEnabling RDS Data APICreating an Amazon VPC endpointCalling RDS Data APIUsing the Java client libraryProcessing RDS Data API query results in JSON formatTroubleshooting Data API issues - -# Using RDS Data API +# Using the Amazon RDS Data API @@ -11 +9 @@ By using RDS Data API (Data API), you can work with a web-services interface to -Users don't need to pass credentials with calls to Data API, because Data API uses database credentials stored in AWS Secrets Manager. To store credentials in Secrets Manager, users must be granted the appropriate permissions to use Secrets Manager, and also Data API. For more information about authorizing users, see Authorizing access to RDS Data API. +Users don't need to pass credentials with calls to Data API, because Data API uses database credentials stored in AWS Secrets Manager. To store credentials in Secrets Manager, users must be granted the appropriate permissions to use Secrets Manager, and also Data API. For more information about authorizing users, see [Authorizing access to the Amazon RDS Data API](./data-api.access.html). @@ -15 +13 @@ You can also use Data API to integrate Amazon Aurora with other AWS applications -You can enable Data API when you create the Aurora DB cluster. You can also modify the configuration later. For more information, see Enabling RDS Data API. +You can enable Data API when you create the Aurora DB cluster. You can also modify the configuration later. For more information, see [Enabling the Amazon RDS Data API](./data-api.enabling.html). @@ -21 +19 @@ After you enable Data API, you can also use the query editor to run ad hoc queri - * Region and version availability + * [Region and version availability for the Amazon RDS Data API](./data-api.regions.html) @@ -23 +21 @@ After you enable Data API, you can also use the query editor to run ad hoc queri - * Limitations with RDS Data API + * [Limitations for the Amazon RDS Data API](./data-api.limitations.html) @@ -25 +23 @@ After you enable Data API, you can also use the query editor to run ad hoc queri - * Comparison of RDS Data API with Serverless v2 and provisioned, and Aurora Serverless v1 + * [Comparing Amazon RDS Data API behaviors for Aurora Serverless v2 and provisioned clusters with Aurora Serverless v1 clusters](./data-api.differences.html) @@ -27 +25 @@ After you enable Data API, you can also use the query editor to run ad hoc queri - * Authorizing access to RDS Data API + * [Authorizing access to the Amazon RDS Data API](./data-api.access.html) @@ -29 +27 @@ After you enable Data API, you can also use the query editor to run ad hoc queri - * Enabling RDS Data API + * [Enabling the Amazon RDS Data API](./data-api.enabling.html) @@ -31 +29 @@ After you enable Data API, you can also use the query editor to run ad hoc queri - * Creating an Amazon VPC endpoint for RDS Data API (AWS PrivateLink) + * [Creating an Amazon VPC endpoint for the Amazon RDS Data API (AWS PrivateLink)](./data-api.vpc-endpoint.html) @@ -33 +31 @@ After you enable Data API, you can also use the query editor to run ad hoc queri - * Calling RDS Data API + * [Calling the Amazon RDS Data API](./data-api.calling.html) @@ -35 +33 @@ After you enable Data API, you can also use the query editor to run ad hoc queri - * Using the Java client library for RDS Data API + * [Using the Java client library for RDS Data API](./data-api.java-client-library.html) @@ -37 +35 @@ After you enable Data API, you can also use the query editor to run ad hoc queri - * Processing RDS Data API query results in JSON format + * [Processing Amazon RDS Data API query results in JSON format](./data-api-json.html) @@ -39 +37 @@ After you enable Data API, you can also use the query editor to run ad hoc queri - * Troubleshooting RDS Data API issues + * [Troubleshooting Amazon RDS Data API](./data-api.troubleshooting.html) @@ -41 +39 @@ After you enable Data API, you can also use the query editor to run ad hoc queri - * [Logging RDS Data API calls with AWS CloudTrail](./logging-using-cloudtrail-data-api.html) + * [Logging Amazon RDS Data API calls with AWS CloudTrail](./logging-using-cloudtrail-data-api.html) @@ -48,1740 +45,0 @@ After you enable Data API, you can also use the query editor to run ad hoc queri -## Region and version availability - -For information about the Regions and engine versions available for Data API, see the following sections. - -Cluster type | Region and version availability ----|--- -Aurora PostgreSQL provisioned and Serverless v2 | [Data API with Aurora PostgreSQL Serverless v2 and provisioned](./Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.html#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.apg) -Aurora MySQL provisioned and Serverless v2 | [Data API with Aurora MySQL Serverless v2 and provisioned](./Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.html#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.ams) -Aurora PostgreSQL Serverless v1 | [Data API with Aurora PostgreSQL Serverless v1](./Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.html#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.apg-sv1) -Aurora MySQL Serverless v1 | [Data API with Aurora MySQL Serverless v1](./Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.html#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.amy) - -If you require cryptographic modules validated by FIPS 140-2 when accessing Data API through a command line interface or an API, use a FIPS endpoint. For more information about the available FIPS endpoints, see [Federal Information Processing Standard (FIPS) 140-2](https://aws.amazon.com/compliance/fips/). - -## Limitations with RDS Data API - -RDS Data API has the following limitations: - - * You can only execute Data API queries on writer instances in a DB cluster. However, writer instances can accept both write and read queries. - - * With Aurora global databases, you can enable Data API on both the primary and secondary DB clusters. However, a secondary cluster doesn't have a writer instance until it's promoted to be the primary. Data API requires access to the writer instance for query processing, even for read queries. As a result, read and write queries sent to the secondary cluster fail while it lacks a writer instance. Once a secondary cluster is promoted and has a writer instance available, Data API queries on that DB instance succeed. - - * Data API isn't supported on T DB instance classes. - - * For Aurora Serverless v2 and provisioned DB clusters, RDS Data API doesn't support some data types. For the list of supported types, see Comparison of RDS Data API with Serverless v2 and provisioned, and Aurora Serverless v1. - - * For Aurora PostgreSQL version 14 and higher databases, Data API only supports `scram-sha-256` for password encryption. - - * The response size limit is 1 MiB. If the call returns more than 1 MiB of response data, the call is terminated. - - * For Aurora Serverless v1, the maximum number of requests per second is 1,000. For all other supported databases, there is no limit. - - * The Data API size limit is 64 KB per row in the result set returned by the database. Make sure that each row in a result set is 64 KB or less. - - - - -## Comparison of RDS Data API with Serverless v2 and provisioned, and Aurora Serverless v1 - -The most recent enhancements to RDS Data API make it available for clusters that use recent versions of the PostgreSQL or MySQL engines. Those clusters could be configured to use Aurora Serverless v2, or provisioned instance classes such as `db.r6g` or `db.r6i`. - -The following table describes differences between RDS Data API (Data API) with Aurora Serverless v2 and provisioned DB clusters, and Aurora Serverless v1 DB clusters. Aurora Serverless v1 DB clusters use the `serverless` engine mode. Provisioned DB clusters use the `provisioned` engine mode. An Aurora Serverless v2 DB cluster also uses the `provisioned` engine mode, and contains one or more Aurora Serverless v2 DB instances with the `db.serverless` instance class. - -Difference | Aurora Serverless v2 and provisioned | Aurora Serverless v1 ----|---|--- -Maximum number of requests per second | Unlimited | 1,000 -Enabling or disabling Data API on an existing database by using the RDS API or AWS CLI | - - * RDS API – Use the `EnableHttpEndpoint` and `DisableHttpEndpoint` operations. - * AWS CLI – Use the `enable-http-endpoint` and `disable-http-endpoint` operations. - -| - - * RDS API – Use the `ModifyDBCluster` operation, and specify `true` or `false`, as applicable, for the `EnableHttpEndpoint` parameter. - * AWS CLI – Use the `modify-db-cluster` operation with the `--enable-http-endpoint` or `--no-enable-http-endpoint` option, as applicable. - - -CloudTrail events | Events from Data API calls are data events. These events are automatically excluded in a trail by default. For more information, see [Including Data API events in an AWS CloudTrail trail](./logging-using-cloudtrail-data-api.html#logging-using-cloudtrail-data-api.including-cloudtrail-events). | Events from Data API calls are management events. These events are automatically included in a trail by default. For more information, see [Excluding Data API events from an AWS CloudTrail trail (Aurora Serverless v1 only)](./logging-using-cloudtrail-data-api.html#logging-using-cloudtrail-data-api.excluding-cloudtrail-events). -Multistatement support | Multistatements aren't supported. In this case, Data API throws `ValidationException: Multistatements aren't supported`. | For Aurora PostgreSQL, multistatements return only the first query response. For Aurora MySQL, multistatements aren't supported. -Concurrent requests for the same transaction ID | Data API throws the error `DatabaseErrorException: Transaction is still running a query`. Wait and retry the request. | Subsequent requests wait until the current request finishes. Your application needs to handle timeout errors if the waiting period is too long. -[BatchExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html) | In Aurora MySQL, the generated fields object in the update result includes inserted values. In Aurora PostgreSQL, the generated fields object is empty. | The generated fields object in the update result includes inserted values. -[ExecuteSQL](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteSQL.html) | Not supported | Deprecated -[ExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html) | `ExecuteStatement` doesn't support retrieving multidimentional array columns. In this case, Data API throws `UnsupportedResultException`. Data API doesn't support some data types, such as geometric and monetary types. In this case, Data API throws `UnsupportedResultException: The result contains the unsupported data type `data_type``. For a list of the data types that RDS Data API supports from each Aurora database engine, see Data API operations reference . | `ExecuteStatement` supports retrieving multidimentional array columns and all advanced data types. - -## Authorizing access to RDS Data API - -Users can invoke RDS Data API (Data API) operations only if they are authorized to do so. You can give a user permission to use Data API by attaching an AWS Identity and Access Management (IAM) policy that defines their privileges. You can also attach the policy to a role if you're using IAM roles. An AWS managed policy, `AmazonRDSDataFullAccess`, includes permissions for Data API. - -The `AmazonRDSDataFullAccess` policy also includes permissions for the user to get the value of a secret from AWS Secrets Manager. Users need to use Secrets Manager to store secrets that they can use in their calls to Data API. Using secrets means that users don't need to include database credentials for the resources that they target in their calls to Data API. Data API transparently calls Secrets Manager, which allows (or denies) the user's request for the secret. For information about setting up secrets to use with Data API, see Storing database credentials in AWS Secrets Manager. - -The `AmazonRDSDataFullAccess` policy provides complete access (through Data API) to resources. You can narrow the scope by defining your own policies that specify the Amazon Resource Name (ARN) of a resource. - -For example, the following policy shows an example of the minimum required permissions for a user to access Data API for the DB cluster identified by its ARN. The policy includes the needed permissions to access Secrets Manager and get authorization to the DB instance for the user. - - - { - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "SecretsManagerDbCredentialsAccess", - "Effect": "Allow", - "Action": [ - "secretsmanager:GetSecretValue" - ], - "Resource": "arn:aws:secretsmanager:*:*:secret:rds-db-credentials/*" - }, - { - "Sid": "RDSDataServiceAccess", - "Effect": "Allow", - "Action": [ - "rds-data:BatchExecuteStatement", - "rds-data:BeginTransaction", - "rds-data:CommitTransaction", - "rds-data:ExecuteStatement", - "rds-data:RollbackTransaction" - ], - "Resource": "arn:aws:rds:us-east-2:111122223333:cluster:prod" - } - ] - } - -We recommend that you use a specific ARN for the "Resources" element in your policy statements (as shown in the example) rather than a wildcard (*). - -### Working with tag-based authorization - -RDS Data API (Data API) and Secrets Manager both support tag-based authorization. _Tags_ are key-value pairs that label a resource, such as an RDS cluster, with an additional string value, for example: - - * `environment:production` - - * `environment:development` - - - - -You can apply tags to your resources for cost allocation, operations support, access control, and many other reasons. (If you don't already have tags on your resources and you want to apply them, you can learn more at [Tagging Amazon RDS resources](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_Tagging.html).) You can use the tags in your policy statements to limit access to the RDS clusters that are labeled with these tags. As an example, an Aurora DB cluster might have tags that identify its environment as either production or development. - -The following example shows how you can use tags in your policy statements. This statement requires that both the cluster and the secret passed in the Data API request have an `environment:production` tag. - -Here's how the policy is applied: When a user makes a call using Data API, the request is sent to the service. Data API first verifies that the cluster ARN passed in the request is tagged with `environment:production`. It then calls Secrets Manager to retrieve the value of the user's secret in the request. Secrets Manager also verifies that the user's secret is tagged with `environment:production`. If so, Data API then uses the retrieved value for the user's DB password. Finally, if that's also correct, the Data API request is invoked successfully for the user. - - - { - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "SecretsManagerDbCredentialsAccess", - "Effect": "Allow", - "Action": [ - "secretsmanager:GetSecretValue" - ], - "Resource": "arn:aws:secretsmanager:*:*:secret:rds-db-credentials/*", - "Condition": { - "StringEquals": { - "aws:ResourceTag/environment": [ - "production" - ] - } - } - }, - { - "Sid": "RDSDataServiceAccess", - "Effect": "Allow", - "Action": [ - "rds-data:*" - ], - "Resource": "arn:aws:rds:us-east-2:111122223333:cluster:*", - "Condition": { - "StringEquals": { - "aws:ResourceTag/environment": [ - "production" - ] - }