AWS amazondynamodb documentation change
Summary
Restructured and expanded documentation about DynamoDB global tables with new sections on consistency modes (MREC/MRSC), fault injection testing, settings synchronization, and management considerations. Added detailed technical explanations of replication behaviors, conflict resolution, and operational characteristics.
Security assessment
The changes document that Server-Side Encryption (SSE) type is synchronized across global table replicas, which is a security-related configuration. However, there is no evidence of addressing a specific security vulnerability or incident.
Diff
diff --git a/amazondynamodb/latest/developerguide/V2globaltables_HowItWorks.md b/amazondynamodb/latest/developerguide/V2globaltables_HowItWorks.md index e788fe914..1be73ca5e 100644 --- a//amazondynamodb/latest/developerguide/V2globaltables_HowItWorks.md +++ b//amazondynamodb/latest/developerguide/V2globaltables_HowItWorks.md @@ -5 +5 @@ -Global table conceptsCommon tasksMonitoring global tablesTime To Live (TTL)Streams and transactions with global tablesRead and write throughputConsistency and conflict resolutionAvailability and durability +ConceptsVersionsAvailabilityConsistency modesChoosing a consistency modeMonitoringFault injection testingTime To Live (TTL)StreamsTransactionsRead and write throughputSettings synchronizationDAXConsiderations for managing global tables @@ -7 +7 @@ Global table conceptsCommon tasksMonitoring global tablesTime To Live (TTL)Strea -# DynamoDB global tables: How it works +# How DynamoDB global tables work @@ -11 +11 @@ The following sections describe the concepts and behaviors of global tables in A -## Global table concepts +## Concepts @@ -13 +13 @@ The following sections describe the concepts and behaviors of global tables in A -A _global table_ is a collection of one or more replica tables, all owned by a single AWS account. +_Global tables_ is a DynamoDB feature that replicates table data across AWS Regions. @@ -15 +15 @@ A _global table_ is a collection of one or more replica tables, all owned by a s -A _replica table_ (or _replica_ , for short) is a single DynamoDB table that functions as a part of a global table. Each replica stores the same set of data items. Any given global table can only have one replica table per AWS Region. For more information about how to get started with global tables, see [Tutorial: Creating a global table](./V2globaltables.tutorial.html). +A _replica table_ (or replica) is a DynamoDB table that functions as part of a global table. A global table consists of two or more replica tables across different AWS Regions. Each global table can have only one replica per AWS Region. All replicas in a global table share the same table name, primary key schema, and item data. @@ -17 +17 @@ A _replica table_ (or _replica_ , for short) is a single DynamoDB table that fun -When you create a DynamoDB global table, it consists of multiple replica tables (one per Region) that DynamoDB treats as a single unit. Every replica has the same table name and the same primary key schema. When an application writes data to a replica table in one Region, DynamoDB propagates the write to the other replica tables in the other AWS Regions automatically. +When an application writes data to a replica in one Region, DynamoDB automatically replicates the write to all other replicas in the global table. For more information about how to get started with global tables, see [Tutorials: Creating global tables](./V2globaltables.tutorial.html). @@ -19 +19 @@ When you create a DynamoDB global table, it consists of multiple replica tables -You can add replica tables to the global table so that it can be available in additional Regions. +## Versions @@ -21 +21 @@ You can add replica tables to the global table so that it can be available in ad -With Version 2019.11.21 (Current), when you create a Global Secondary Index in one Region it is automatically replicated to the other Region(s) as well as automatically backfilled. +There are two versions of DynamoDB global tables available: Version 2019.11.21 (Current) and [Version 2017.11.29 (Legacy)](./globaltables.V1.html). You should use Version 2019.11.21 (Current) whenever possible. The information in this documentation section is for Version 2019.11.21 (Current). For more information, see [Determining the version of a global table](./V2globaltables_versions.html#globaltables.DetermineVersion). @@ -23 +23 @@ With Version 2019.11.21 (Current), when you create a Global Secondary Index in o -## Common tasks +## Availability @@ -25 +25 @@ With Version 2019.11.21 (Current), when you create a Global Secondary Index in o -Common tasks for global tables work as follows. +Global tables help improve your business continuity by making it easier to implement a multi-Region high availability architecture. If a workload in a single AWS Region becomes impaired, you can shift application traffic to a different Region and perform reads and writes to a different replica table in the same global table. @@ -27 +27 @@ Common tasks for global tables work as follows. -You can delete a global table’s replica table the same as a regular table. This will stop replication to that Region and delete the table copy kept in that Region. You can't sever the replication and have copies of the table exist as independent entities. You can copy the global table to a local table in that Region, and then delete the global replica for that Region. +Each replica table in a global table provides the same durability and availability as a single-Region DynamoDB table. Global tables offer a 99.999% availability [Service Level Agreement (SLA)](https://aws.amazon.com/dynamodb/sla/), compared to 99.99% for single-Region tables. @@ -29 +29 @@ You can delete a global table’s replica table the same as a regular table. Thi -###### Note +## Consistency modes @@ -31 +31 @@ You can delete a global table’s replica table the same as a regular table. Thi -You won’t be able to delete a source table until at least 24 hours after it’s used to initiate a new Region. If you try to delete it too soon you will receive an error. +When you create a global table, you can configure its consistency mode. Global tables support two consistency modes: multi-Region eventual consistency (MREC), and multi-Region strong consistency (MRSC). @@ -33 +33 @@ You won’t be able to delete a source table until at least 24 hours after it’ -Conflicts can arise if applications update the same item in different Regions at about the same time. To help ensure eventual consistency, DynamoDB global tables use a “last writer wins” method to reconcile between concurrent updates. All the replicas will agree on the latest update and converge toward a state in which they all have identical data. +If you do not specify a consistency mode when creating a global table, the global table defaults to multi-Region eventual consistency (MREC). A global table cannot contain replicas configured with different consistency modes. You cannot change a global table's consistency mode after creation. @@ -35 +35,35 @@ Conflicts can arise if applications update the same item in different Regions at -###### Note +### Multi-Region eventual consistency (MREC) + +Multi-Region eventual consistency (MREC) is the default consistency mode for global tables. Item changes in an MREC global table replica are asynchronously replicated to all other replicas, typically within a second or less. In the unlikely event a replica in a MREC global table becomes isolated or impaired, any data not yet replicated to other Regions will be replicated when the replica becomes healthy. + +If the same item is modified in multiple Regions simultaneously, DynamoDB will resolve the conflict by using the modification with the latest internal timestamp on a per-item basis, referred to as a "last writer wins" conflict resolution method. An item will eventually converge in all replicas to the version created by the last write. + +[Strongly consistent read operations](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html#DDB-GetItem-request-ConsistentRead) return the latest version of an item if that item was last updated in the Region where the read occurred, but may return stale data if the item was last updated in a different Region. Conditional writes evaluate the condition expression against the version of the item in the Region. + +You create a MREC global table by adding a replica to an existing DynamoDB table. Adding a replica has no performance impact on existing single-Region DynamoDB tables or global table replicas. You can add replicas to a MREC global table to expand the number of Regions where data is replicated, or remove replicas from an MREC global table if they are no longer needed. An MREC global table can have a replica in any Region where DynamoDB is available, and can have as many replicas as there are Regions in the [AWS partition.](https://docs.aws.amazon.com/whitepapers/latest/aws-fault-isolation-boundaries/partitions.html) + +### Multi-Region strong consistency (MRSC) + +You can configure multi-Region strong consistency (MRSC) mode when you create a global table. Item changes in an MRSC global table replica are synchronously replicated to at least one other Region before the write operation returns a successful response. + +Strongly consistent read operations on any MRSC replica always returns the latest version of an item. Conditional writes always evaluate the condition expression against the latest version of an item. + +A write operation fails with a `ReplicatedWriteConflictException` when it attempts to modify an item that is already being modified in another Region. Writes that fail with the `ReplicatedWriteConflictException` can be retried, and will succeed if the item is no longer being modified in another Region. + +You can configure a MRSC global table with three replicas, or with two replicas and one witness. A witness is a component of a MRSC global table that contains data written to global table replicas, and provides an optional alternative to a full replica while supporting MRSC's availability architecture. You cannot perform read or write operations on a witness. A witness is located in a different Region than the two replicas. + +When creating a MRSC global table, you choose the Regions for both your replicas and the witness deployment at MRSC table creation time. You can determine whether and in which Region a MRSC global table has a witness configured from the output of the [`DescribeTable`](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html) API. The witness is owned and managed by DynamoDB, and the witness will not appear in your AWS account in the Region where it is configured. + +A MRSC global table must be deployed in exactly three Regions. You create a MRSC global table by adding one replica and a witness or two replicas to an existing DynamoDB table that contains no data. You cannot add additional replicas to an existing MRSC global table. You cannot delete a single replica or a witness from a MRSC global table. You can delete two replicas or delete one replica and a witness from a MRSC global table, converting the remaining replica to a single-Region DynamoDB table. + +The following considerations apply to MRSC global tables: + + * MRSC global tables are available in the following Region sets: + + * US Region set: US East (N. Virginia), US East (Ohio), US West (Oregon) + + * EU Region set: Europe (Ireland), Europe (London), Europe (Paris), Europe (Frankfurt) + + * AP Region set: Asia Pacific (Tokyo), Asia Pacific (Seoul), and Asia Pacific (Osaka). + + * MRSC global tables cannot span Region sets (e.g. a MRSC global table cannot contain replicas from both US and EU Region sets). @@ -37 +71 @@ Conflicts can arise if applications update the same item in different Regions at -There are several ways to avoid conflicts, including: + * Time to Live (TTL) is not supported for MRSC global tables. @@ -39 +73 @@ There are several ways to avoid conflicts, including: - * Only allowing writes to the table in one Region. + * Local secondary indexes (LSIs) are not supported for MRSC global tables. @@ -41 +75 @@ There are several ways to avoid conflicts, including: - * Routing user traffic to different Regions according to your write policies, to ensure there are no conflicts. + * CloudWatch Contributor Insights information is only reported for the Region in which an operation occurred. @@ -43 +76,0 @@ There are several ways to avoid conflicts, including: - * Avoiding the use of non-idempotent updates such as Bookmark = Bookmark + 1, in favor of static updates such as Bookmark=25. @@ -45 +78,28 @@ There are several ways to avoid conflicts, including: - * Keeping in mind that when you route writes or reads to one Region, it’s up to your application to ensure that flow is enforced. + + +## Choosing a consistency mode + +The key criteria for choosing a multi-Region consistency mode is whether your application prioritizes lower latency writes and strongly consistent reads, or prioritizes global strong consistency. + +MREC global tables will have lower write and strongly consistent read latencies compared to MRSC global tables. MREC global tables can support a Recovery Point Objective (RPO) equal to the replication delay between replicas, usually a few seconds depending on the replica Regions. + +You should use the MREC mode when: + + * Your application can tolerate stale data returned from strongly consistent read operations if that data was updated in another Region. + + * You prioritize lower write and strongly consistent read latencies over multi-Region read consistency. + + * Your multi-Region high availability strategy can tolerate an RPO greater than zero. + + + + +MRSC global tables will have higher write and strongly consistent read latencies compared to MREC global tables. MRSC global tables support a Recovery Point Objective (RPO) of zero. + +You should use the MRSC mode when: + + * You need strongly consistent reads across multiple Regions. + + * You prioritize global read consistency over lower write latency. + + * Your multi-Region high availability strategy requires an RPO of zero. @@ -52 +112 @@ There are several ways to avoid conflicts, including: -You can use CloudWatch to observe the metric `ReplicationLatency`. This tracks the elapsed time between when an item is written to a replica table, and when that item appears in another replica in the global table. It’s expressed in milliseconds and is emitted for every source-Region and destination-Region pair. This metric is kept at the source Region. This is the only CloudWatch metric provided by Global Tables v2. +Global tables configured for multi-Region eventual consistency (MREC) publish the [ReplicationLatency](./metrics-dimensions.html#ReplicationLatency) metric to CloudWatch. This metric tracks the elapsed time between when an item is written to a replica table, and when that item appears in another replica in the global table. `ReplicationLatency` is expressed in milliseconds and is emitted for every source and destination Region pair in a global table. @@ -54 +114 @@ You can use CloudWatch to observe the metric `ReplicationLatency`. This tracks t -The replication latency you will experience depends on the distance between your chosen AWS Regions, as well as other variables. If your original table was in the US West (N. California) (us-west-1) Region, a replica in a closer Region, such as the US West (Oregon) (us-west-2) Region, would have lower replication latency compared to a replica in a Region which is much further away, such as the Africa (Cape Town) (af-south-1) Region. +Typical `ReplicationLatency` values depends on the distance between your chosen AWS Regions, as well as other variables like workload type and throughput. For example, a source replica in the US West (N. California) (us-west-1) Region has lower `ReplicationLatency` to the US West (Oregon) (us-west-2) Region compared to the Africa (Cape Town) (af-south-1) Region. @@ -56 +116,3 @@ The replication latency you will experience depends on the distance between your -###### Note +An increasing value for `ReplicationLatency` could indicate that updates from one replica are not propagating to other replica tables in a timely manner. In this case, you can temporarily redirect your application's read and write activity to a different AWS Region. + +Global tables configured for multi-Region strong consistency (MRSC) do not publish a `ReplicationLatency` metric. @@ -58 +120,3 @@ The replication latency you will experience depends on the distance between your -Replication latency doesn't effect API latency. If you have a client and table in Region A and you add a global tables replica in Region B, the client and table in Region A will have the same latency as before adding Region B. If you call the [PutItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html) API operation in Region B, it'll eventually be available to read in Region A after a delay of approximately the `ReplicationLatency` statistic available in Amazon CloudWatch. Before it is replicated, you'd receive an empty response and after it's replicated, you'd receive the item; both calls would have approximately the same API latency. +## Fault injection testing + +MREC global tables integrate with the [AWS Fault Injection Service](https://docs.aws.amazon.com/resilience-hub/latest/userguide/testing.html) (AWS FIS) for performing fault injection experiments on your global table workloads. This enables you to test your application's response to a simulated Region isolation by pausing replication to and from a selected replica. For more information, see [ pausing global table replication](https://docs.aws.amazon.com/fis/latest/userguide/fis-actions-reference.html#dynamodb-actions-reference). @@ -62 +126 @@ Replication latency doesn't effect API latency. If you have a client and table i -You can use Time To Live (TTL) to specify an attribute name whose value indicates the time of expiration for the item. This value is given as a number in seconds since the start of the Unix epoch. After that time, DynamoDB can delete the item without incurring write costs. +Global tables configured for MREC support configuring [Time To Live](./TTL.html) (TTL) deletion. TTL settings are automatically synchronized for all replicas in a global table. When TTL deletes an item from a replica in a Region, the delete is replicated to all other replicas in the global table. TTL does not consume write capacity, so you are not charged for the TTL delete in the Region where the delete occurred. However, you are charged for the replicated delete in each other region with a replica in the global table. @@ -64 +128 @@ You can use Time To Live (TTL) to specify an attribute name whose value indicate -With global tables you configure TTL in one Region, and that setting is auto replicated to the other Region(s). When an item is deleted via a TTL rule, that work is performed without consuming Write Units on the source table - but the target table(s) will incur Replicated Write Unit costs. +TTL delete replication consumes write capacity on the replicas to which the delete is being replicated. Replicas configured for provisioned capacity may throttle requests if the combination of write throughput and TTL delete throughput is higher than the provisioned write capacity. @@ -66 +130 @@ With global tables you configure TTL in one Region, and that setting is auto rep -Be aware that if the source and target tables have very low Provisioned write capacities, this may cause throttling, as the TTL deletions require write capacity. +Global tables configured for multi-Region strong consistency (MRSC) do not support configuring Time To Live (TTL) deletion. @@ -68 +132 @@ Be aware that if the source and target tables have very low Provisioned write ca -## Streams and transactions with global tables +## Streams @@ -70 +134 @@ Be aware that if the source and target tables have very low Provisioned write ca -Each global table produces an independent stream based on all its writes, regardless of the origination point for those writes. You can choose to consume this DynamoDB stream in one Region or in all Regions independently. +Global tables configured for multi-Region eventual consistency (MREC) replicate changes by reading those changes from a [DynamoDB Stream](./Streams.html) on a replica table and applying that change to all other replica tables. Streams are therefore enabled by default on all replicas in an MREC global table, and cannot be disabled on those replicas. The MREC replication process may combine multiple changes in a short period of time into a single replicated write, resulting in each replica's Stream containing slightly different records. Streams records on MREC replicas are always ordered on a per-item basis, but ordering between items may differ between replicas. @@ -72 +136 @@ Each global table produces an independent stream based on all its writes, regard -If you want processed local writes but not replicated writes, you can add your own Region attribute to each item. Then you can use a Lambda event filter to invoke only the Lambda for writes in the local Region. +Global tables configured for multi-Region strong consistency (MRSC) do not use DynamoDB Streams for replication, so Streams are not enabled by default on MRSC replicas. You can enable Streams on an MRSC replica. Streams records on MRSC replicas are identical for every replica, inluding Stream record ordering. @@ -74 +138 @@ If you want processed local writes but not replicated writes, you can add your o -Transactional operations provide ACID (Atomicity, Consistency, Isolation, and Durability) guarantees only within the Region where the write is originally made. Transactions aren't supported across Regions in global tables. +If you want to write an application that processes Streams records for changes that occurred in a particular Region but not other Regions in a global table, you can add an attribute to each item that defines in which Region the change for that item occurred. You can use this attribute to filter Streams records for changes that occurred in other Regions, including the use of Lambda event filters to only invoke Lambda functions for changes in a specific Region. @@ -76 +140 @@ Transactional operations provide ACID (Atomicity, Consistency, Isolation, and Du -For example, if you have a global table with replicas in the US East (Ohio) and US West (Oregon) Regions and perform a `TransactWriteItems` operation in the US East (Ohio) Region, you may observe partially completed transactions in US West (Oregon) Region as changes are replicated. Changes will only be replicated to other Regions once they've been committed in the source Region. +## Transactions @@ -78 +142 @@ For example, if you have a global table with replicas in the US East (Ohio) and -###### Note +On a global table configured for MREC, DynamoDB transaction operations ( [`TransactWriteItems`](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html) and [`TransactGetItems`](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactGetItems.html)) are only atomic within the Region where the operation was invoked. Transactional writes are not replicated as a unit across Regions, meaning only some of the writes in a transaction may be returned by read operations in other replicas at a given point in time. @@ -80 +144 @@ For example, if you have a global table with replicas in the US East (Ohio) and - * Global tables “write around” DynamoDB Accelerator by updating DynamoDB directly. As a result DAX will not be aware it's holding stale data. The DAX cache will only be refreshed when the cache’s TTL expires. +For example, if you have a global table with replicas in the US East (Ohio) and US West (Oregon) Regions and perform a `TransactWriteItems` operation in the US East (Ohio) Region, you may observe partially completed transactions in the US West (Oregon) Region as changes are replicated. Changes will only be replicated to other Regions once they've been committed in the source Region. @@ -82 +146 @@ For example, if you have a global table with replicas in the US East (Ohio) and - * Tags on global tables don't automatically propagate. +Global tables configured for multi-Region strong consistency (MRSC) do not support transaction operations, and will return an error if those operations are invoked on an MRSC replica. @@ -83,0 +148 @@ For example, if you have a global table with replicas in the US East (Ohio) and +## Read and write throughput @@ -84,0 +150 @@ For example, if you have a global table with replicas in the US East (Ohio) and +Replication consumes write capacity. Replicas configured for provisioned capacity may throttle requests if the combination of write throughput and replication throughput is higher than the provisioned write capacity. Write capacity in on-demand mode is synchronized for all replicas in a global table. Global tables configured for provisioned capacity synchronize auto scaling settings between replicas. The actual provisioned write capacity setting may vary between replicas according to consumed write throughput. @@ -85,0 +152 @@ For example, if you have a global table with replicas in the US East (Ohio) and +You can independently configure read capacity settings for each replica in a global table. When adding a replica to a global table, the read capacity of the source table or replica is used as the initial value unless an override value is specified. @@ -87 +154,57 @@ For example, if you have a global table with replicas in the US East (Ohio) and -## Read and write throughput +## Settings synchronization + +Settings in DynamoDB global tables are configuration parameters that control various aspects of table behavior and replication. These settings are managed through the DynamoDB control plane APIs and can be configured when creating or modifying global tables. Global tables automatically synchronize certain settings across all replicas to maintain consistency, while allowing flexibility for region-specific optimizations. Understanding which settings synchronize and how they behave helps you configure your global table effectively. The settings fall into three main categories based on how they are synchronized across replicas. + +The following settings are always synchronized between replicas in a global table: + + * Capacity mode (provisioned capacity or on-demand) + + * Table provisioned write capacity + + * Table write auto scaling + + * Global Secondary Index (GSI) definition + + * GSI provisioned write capacity + + * GSI write auto scaling + + * Server-side Encryption (SSE) type