AWS AmazonElastiCache: ElastiCache Serverless migration prerequisites: auth, TLS, network, troubleshooting
Summary
Restructures the online-migration prerequisites page: converts prose bullets into requirement/limitation tables, adds a 'Troubleshooting a failed prepare step' section and an 'If a key name exceeds 4 KiB' recovery procedure, and expands network requirements (private IP binding, security group inbound rules, subnet/AZ and ENI quota needs, keeping the Secrets Manager secret). Adds explicit guidance on source authentication via Secrets Manager, TLS CA certificates, and the IAM/KMS permissions and secret/key policy conditions required for ElastiCache to read the secret.
Security assessment
The added content documents security-relevant configuration for migrations: storing source credentials in Secrets Manager, granting ElastiCache read access, supplying TLS configuration, restricting inbound TCP to the target cache's security group/subnets, and the required secretsmanager:GetSecretValue / kms:Decrypt permissions plus aws:SourceAccount/aws:SourceArn conditions on the secret and key policies. This is security best-practice/hardening documentation rather than a fix for a specific vulnerability, so it is not security_issue_related, but it does add security documentation.
Evidence
+Authentication and encryption | If your source requires authentication, store the credentials in Secrets Manager and grant ElastiCache permission to read the secret. The user name and password in the secret must meet the ElastiCache requirements, whether you created the secret or ElastiCache created it for you. If your source requires TLS, provide the source TLS configuration. For more information, see [Source authentication for online migration to ElastiCache Serverless](./migration-to-serverless-auth.html). | Prepare and start
Diff
diff --git a/AmazonElastiCache/latest/dg/migration-to-serverless-prerequisites.md b/AmazonElastiCache/latest/dg/migration-to-serverless-prerequisites.md index 3a01bca..a1e0236 100644 --- a//AmazonElastiCache/latest/dg/migration-to-serverless-prerequisites.md +++ b//AmazonElastiCache/latest/dg/migration-to-serverless-prerequisites.md @@ -7 +7 @@ -Source cache requirementsTarget cache requirementsNetwork requirementsCommand behavior during a migrationClient configurationWhat ElastiCache manages and what you manageLimitationsRelated topics +Source cache requirementsTarget cache requirementsNetwork requirementsCommand behavior during a migrationClient configurationWhat ElastiCache manages and what you manageLimitationsTroubleshooting a failed prepare stepIf a key name exceeds 4 KiBRelated topics @@ -11 +11 @@ Source cache requirementsTarget cache requirementsNetwork requirementsCommand be -Before you start an online migration, confirm that your source cache and your target cache meet the following requirements. ElastiCache checks these requirements when you prepare the migration and checks some of them again when you start the data sync. If a requirement is not met, the step fails. ElastiCache reports a failure event on the cache that names the requirement. If the prepare step fails, the migration is rolled back and your cache returns to `available`. Correct the requirement, then try again. +Before you start an online migration, confirm that your source cache and your target cache meet the following requirements. ElastiCache checks these requirements when you prepare the migration and checks some of them again when you start the data sync. If a requirement is not met, the step fails. ElastiCache reports a failure event on the cache that names the requirement. If the prepare step fails, ElastiCache rolls back the migration, removes the `Migration` object and returns your cache to `available`. Correct the requirement, then try again. @@ -28,0 +29,6 @@ Protected mode | Protected mode turned off (`protected-mode no`) on a source tha +Replication commands | Your source must accept a replica connection from the migration path. It must support `PSYNC` and `REPLCONF`. If you renamed or disabled these commands on your source, restore them before you migrate. | Prepare and start +Key name size | No key name in your source can exceed 4 KiB, which is the ElastiCache Serverless limit. An oversized key name fails the migration during the initial data load, and you cannot start the data sync again. ElastiCache writes the key to your target before it reports the failure. To recover, see If a key name exceeds 4 KiB. | During the initial data load +CPU headroom on source primaries | Your source primaries serve your application's traffic for the whole migration, up until cutover. You need CPU headroom on your source primaries to serve your full read and write workload while the migration runs. Review your workload and scale out before you prepare the migration. A source primary that becomes overloaded can compromise the health of the migration. For more information about when traffic moves off your source, see [Cutover modes for online migration to ElastiCache Serverless](./migration-to-serverless-cutover.html). | Not checked. Your responsibility. +Memory for the initial full sync | ElastiCache replicates your data with the replication protocol, which starts with a full sync. A full sync forks the process on your source primary. That fork needs memory available on the primary beyond what your dataset already uses. How much it needs rises with your write rate during the sync, because your source primary must hold writes that arrive during the fork. | Not checked. Your responsibility. +Stable environment | Your environment must stay stable for the whole migration. Three things must stay valid until the migration completes: your network path, your source TLS certificate, and your AWS Secrets Manager credentials. If any of them changes mid-migration, ElastiCache reports a migration error event, and the migration cannot be started again. For more information, see [Cutover modes for online migration to ElastiCache Serverless](./migration-to-serverless-cutover.html). | During the migration +Authentication and encryption | If your source requires authentication, store the credentials in Secrets Manager and grant ElastiCache permission to read the secret. The user name and password in the secret must meet the ElastiCache requirements, whether you created the secret or ElastiCache created it for you. If your source requires TLS, provide the source TLS configuration. For more information, see [Source authentication for online migration to ElastiCache Serverless](./migration-to-serverless-auth.html). | Prepare and start @@ -34,12 +39,0 @@ A second, separate check applies while the migration is running. If your source -**Key name size.** No key name in your source can exceed 4 KiB, which is the ElastiCache Serverless limit. An oversized key name fails the migration during the initial data load, and you cannot start the data sync again. ElastiCache writes the key to your target before it reports the failure. To try again, first point your application back at your source's own endpoint, and then end the migration with force complete, which switches the migration endpoint to your target. Then flush the target, remove or rename every key on your source whose name exceeds 4 KiB, and prepare a new migration. For more information, see [Cutover modes for online migration to ElastiCache Serverless](./migration-to-serverless-cutover.html). - -**Replication support.** Your source must accept a replica connection from the migration path. It must support `PSYNC` and `REPLCONF`. If you renamed or disabled these commands on your source, restore them before you migrate. - -**Stable environment.** Your environment must stay stable for the whole migration. Three things must stay valid until the migration completes: your network path, your source TLS certificate, and your AWS Secrets Manager credentials. If any of them changes mid-migration, ElastiCache reports a migration error event, and the migration cannot be started again. For more information, see [Cutover modes for online migration to ElastiCache Serverless](./migration-to-serverless-cutover.html). - -**Source primary capacity.** Your source primaries serve your application's traffic for the whole migration, up until cutover. You need CPU headroom on your source primaries to serve your full read and write workload while the migration runs. Review your workload and scale out before you prepare the migration. A source primary that becomes overloaded can compromise the health of the migration. For more information about when traffic moves off your source, see [Cutover modes for online migration to ElastiCache Serverless](./migration-to-serverless-cutover.html). - -**Memory for the initial full sync.** ElastiCache replicates your data with the replication protocol, which starts with a full sync. A full sync forks the process on your source primary. That fork needs memory available on the primary beyond what your dataset already uses. How much it needs rises with your write rate during the sync, because your source primary must hold writes that arrive during the fork. - -**Authentication and encryption.** If your source requires authentication, store the credentials in Secrets Manager and grant ElastiCache permission to read the secret. The user name and password in the secret must meet the ElastiCache requirements, whether you created the secret or ElastiCache created it for you. If your source requires TLS, provide the source TLS configuration. For more information, see [Source authentication for online migration to ElastiCache Serverless](./migration-to-serverless-auth.html). - @@ -71 +65,9 @@ Key name length | 4 KiB -ElastiCache connects to your source from the VPC of your target cache. Confirm that your source is reachable on a private endpoint from that VPC. Also confirm that your source security group allows inbound traffic from ElastiCache. +ElastiCache connects to your source from the VPC of your target cache. Confirm the following: + + 1. Confirm that your source is reachable on a private endpoint from that VPC. Also confirm that your source security group allows inbound traffic from ElastiCache. + + 2. Your source nodes must listen on addresses that this VPC can reach. The default Valkey and Redis OSS configuration file binds to `127.0.0.1`, which accepts only local connections, so bind each node to its private IP address. Each node must also report a reachable address in its cluster topology, because ElastiCache discovers the rest of your nodes from the first one. + + 3. For the security group rule, allow inbound TCP traffic on your source port from the security group of your target cache, or from the IPv4 CIDR ranges of its subnets. + + 4. For the source address, enter the private IP address of a source node, or a host name that resolves through public DNS. A host name that resolves only in your VPC's private DNS fails the prepare step. @@ -73 +75,5 @@ ElastiCache connects to your source from the VPC of your target cache. Confirm t -Your source nodes must listen on addresses that this VPC can reach. The default Valkey and Redis OSS configuration file binds to `127.0.0.1`, which accepts only local connections, so bind each node to its private IP address. Each node must also report a reachable address in its cluster topology, because ElastiCache discovers the rest of your nodes from the first one. For the security group rule, allow inbound TCP traffic on your source port from the security group of your target cache, or from the IPv4 CIDR ranges of its subnets. + 5. Create your target cache with at least three subnets in different Availability Zones, each with free IP addresses. You cannot change the subnets of a serverless cache after you create it. If the prepare step or the data sync fails on subnets, the error message names the Availability Zones that need a subnet. Because you cannot change the subnets of a serverless cache, create a new target cache with a subnet in each Availability Zone that the message names, and prepare the migration again. + + 6. Preparing a migration creates network interfaces in the subnets of your target cache. They use the security groups of your target cache, and ElastiCache deletes them when the migration completes. The prepare step fails if your target's subnets have no free IP addresses or your VPC has no network interface quota headroom. + + 7. Keep the Secrets Manager secret that you provided until the migration completes. If a node is replaced during the migration, ElastiCache runs network and authentication setup again, and a missing secret fails that step. @@ -75 +80,0 @@ Your source nodes must listen on addresses that this VPC can reach. The default -Create your target cache with at least three subnets in different Availability Zones, each with free IP addresses. You cannot change the subnets of a serverless cache after you create it. If the prepare step or the data sync fails on subnets, the error message names the Availability Zones that need a subnet. Because you cannot change the subnets of a serverless cache, create a new target cache with a subnet in each Availability Zone that the message names, and prepare the migration again. @@ -77 +81,0 @@ Create your target cache with at least three subnets in different Availability Z -Preparing a migration creates network interfaces in the subnets of your target cache. They use the security groups of your target cache, and ElastiCache deletes them when the migration completes. The prepare step fails if your target's subnets have no free IP addresses or your VPC has no network interface quota headroom. @@ -79 +82,0 @@ Preparing a migration creates network interfaces in the subnets of your target c -**Resources to keep.** Keep the Secrets Manager secret that you provided until the migration completes. If a node is replaced during the migration, ElastiCache runs network and authentication setup again, and a missing secret fails that step. @@ -89 +92 @@ Some commands behave differently on ElastiCache Serverless than on a self-manage -**Do not send writes directly to your source during the migration.** Commands that ElastiCache Serverless does not support are not replicated. A client can bypass the migration endpoint and write an unsupported command straight to your source. That makes your target diverge. ElastiCache reports a migration error event when it detects this. After ElastiCache reports that error, you cannot start the migration again. To end it, you complete the migration with force, which accepts the inconsistency. +###### Writes during the migration @@ -91 +94 @@ Some commands behave differently on ElastiCache Serverless than on a self-manage -**Scripts.** Scripts you loaded on your source before the migration are not replicated to your target. Re-issue `SCRIPT LOAD` for them through the migration endpoint any time after the migration reaches `ready-to-sync` and before cutover. A script that is missing on the target returns `NOSCRIPT` after cutover. +Do not send writes directly to your source during the migration. Commands that ElastiCache Serverless does not support are not replicated. A client can bypass the migration endpoint and write an unsupported command straight to your source. That makes your target diverge. ElastiCache reports a migration error event when it detects this. After ElastiCache reports that error, you cannot start the migration again. To end it, you complete the migration with force, which accepts the inconsistency. @@ -93 +96,6 @@ Some commands behave differently on ElastiCache Serverless than on a self-manage -**Pub/sub subscriptions.** Pub/sub subscriptions do not survive cutover. Subscribed clients are disconnected at cutover and have to reconnect and re-subscribe. +The following commands need your attention during a migration: + +What | What to do +---|--- +Scripts | Scripts you loaded on your source before the migration are not replicated to your target. Re-issue `SCRIPT LOAD` for them through the migration endpoint any time after the migration reaches `ready-to-sync` and before cutover. A script that is missing on the target returns `NOSCRIPT` after cutover. +Pub/sub subscriptions | Pub/sub subscriptions do not survive cutover. Subscribed clients are disconnected at cutover and have to reconnect and re-subscribe. @@ -121 +129,35 @@ The ElastiCache Service Level Agreement applies to your ElastiCache Serverless c -**Default cutover mode.** Cutover is manual by default. You can opt in to automatic cutover when you start the data sync. For more information, see [Cutover modes for online migration to ElastiCache Serverless](./migration-to-serverless-cutover.html). +The following limitations apply during a migration: + +Limitation | What to do +---|--- +Permanent errors | Migration errors are reported as permanent. A migration that has reported an error cannot be started again, even after you fix the underlying problem. You can stop it, and your only way to end it is to complete the migration with force. For more information, see [Cutover modes for online migration to ElastiCache Serverless](./migration-to-serverless-cutover.html). +Force complete | Force complete does not roll back. It skips the pre-cutover health check and the cluster-wide convergence check. For more information, see [Cutover modes for online migration to ElastiCache Serverless](./migration-to-serverless-cutover.html). +Rollback after cutover | There is no rollback after cutover. To return to your source cache, you must move your application traffic back to it yourself. Writes that your application makes after cutover exist only on your target. For more information, see [Cutover modes for online migration to ElastiCache Serverless](./migration-to-serverless-cutover.html). +The reader endpoint is not supported during a migration | Send your traffic to the migration endpoint and not the cache's reader endpoint. +One migration per cache | A cache can be the target of only one migration at a time. +Pipelining is not supported during the migration | If your application pipelines commands, the migration endpoint serializes them from the moment the migration reads `ready-to-sync`. A batch of 100 commands then takes 100 round trips instead of one. Latency for those batches increases in proportion to the batch depth. +RESP3 Pub/Sub with regular commands on the same connection | RESP3 lets a client run regular commands on a connection that has active Pub/Sub subscriptions (`SUBSCRIBE` or `SSUBSCRIBE`). This isn't supported while a migration is in progress. During migration, use separate connections for Pub/Sub and for regular commands. Most client libraries do this by default. This restriction ends when the migration completes. +Total migration throughput scales with your source shard count | A source with many shards migrates faster than a source with few. +High-throughput sources with few shards | This release is not suited to a high-throughput source with few shards. Migration throughput is provisioned per source shard. A source that concentrates high traffic into a small number of shards is most likely to be limited. If that describes your source, review the CPU headroom on source primaries prerequisite in the source cache requirements, or plan the migration for a lower-traffic period. +Billing after you stop the data sync | Billing does not stop when you stop the data sync. `StopMigration` leaves the migration infrastructure provisioned. `CompleteMigration` is the call that ends the migration and its charges. Your target ElastiCache Serverless cache continues to bill until you delete it. + +## Troubleshooting a failed prepare step + +When the prepare step fails, the target cache's Events tab shows the reason. The following table lists the reasons and what to check. + +Reason in the event | What to check +---|--- +"The serverless cache must have no keys before migration can begin." | Your target contains data. Run `FLUSHALL` on the target before you prepare the migration, or choose an empty cache. +"The serverless cache is not yet ready for migration. Please try again later." | Wait, and then prepare the migration again. +"Unable to connect to source cluster." | This reason covers several causes. Check each of the following: + + * The source security group allows inbound TCP on the source port from the target cache's security group or subnets. + * Each source node binds to its private IP address and reports a reachable address in its cluster topology. + * The source address is a private IP address or a host name that resolves through public DNS. + * Protected mode is off on a source that has no password. + * The migration user has every permission in [Permissions for the migration user](./migration-to-serverless-auth.html#migration-to-serverless-auth-permissions). + + +An access denied message for the secret | The secret's resource policy grants `secretsmanager:GetSecretValue` to `elasticache.amazonaws.com`, the key policy grants `kms:Decrypt`, neither statement has an `aws:SourceAccount` or `aws:SourceArn` condition, and your IAM identity has `secretsmanager:GetSecretValue`, `kms:Decrypt` and `ec2:DescribeSubnets`. +A subnet message that names Availability Zones | Create a new target cache with a subnet in each Availability Zone that the message names, and prepare the migration again. +A failure after you provide TLS settings | Provide the PEM-encoded CA certificates with `verify-ca`. The event might not name the certificate authority. @@ -123 +165 @@ The ElastiCache Service Level Agreement applies to your ElastiCache Serverless c -**Stopping the data sync.** You can stop the data sync while it is in progress. Your application continues to be served by your source cache. For more information, see [Cutover modes for online migration to ElastiCache Serverless](./migration-to-serverless-cutover.html). +## If a key name exceeds 4 KiB @@ -125 +167 @@ The ElastiCache Service Level Agreement applies to your ElastiCache Serverless c -**Permanent errors.** Migration errors are reported as permanent. A migration that has reported an error cannot be started again, even after you fix the underlying problem. You can stop it, and your only way to end it is to complete the migration with force. For more information, see [Cutover modes for online migration to ElastiCache Serverless](./migration-to-serverless-cutover.html). +An oversized key name fails the migration during the initial data load. Recover as follows: @@ -127 +169 @@ The ElastiCache Service Level Agreement applies to your ElastiCache Serverless c -**Force complete.** Force complete does not roll back. It skips the pre-cutover health check and the cluster-wide convergence check. For more information, see [Cutover modes for online migration to ElastiCache Serverless](./migration-to-serverless-cutover.html). + 1. Point your application back at your source's own endpoint. @@ -129 +171 @@ The ElastiCache Service Level Agreement applies to your ElastiCache Serverless c -**Rollback after cutover.** There is no rollback after cutover. To return to your source cache, you must move your application traffic back to it yourself. Writes that your application makes after cutover exist only on your target. For more information, see [Cutover modes for online migration to ElastiCache Serverless](./migration-to-serverless-cutover.html). + 2. End the migration with force complete, which switches the migration endpoint to your target. @@ -131 +173 @@ The ElastiCache Service Level Agreement applies to your ElastiCache Serverless c -**The reader endpoint is not supported during a migration.** Send your traffic to the migration endpoint and not the cache's reader endpoint. + 3. Flush the target. @@ -133 +175 @@ The ElastiCache Service Level Agreement applies to your ElastiCache Serverless c -**One migration per cache.** A cache can be the target of only one migration at a time. + 4. Remove or rename every key on your source whose name exceeds 4 KiB. @@ -135 +177 @@ The ElastiCache Service Level Agreement applies to your ElastiCache Serverless c -**Pipelining is not supported during the migration.** If your application pipelines commands, the migration endpoint serializes them from the moment the migration reads `ready-to-sync`. A batch of 100 commands then takes 100 round trips instead of one. Latency for those batches increases in proportion to the batch depth. + 5. Prepare a new migration. @@ -137 +178,0 @@ The ElastiCache Service Level Agreement applies to your ElastiCache Serverless c -**RESP3 Pub/Sub with regular commands on the same connection.** RESP3 lets a client run regular commands on a connection that has active Pub/Sub subscriptions (`SUBSCRIBE` or `SSUBSCRIBE`). This isn't supported while a migration is in progress. During migration, use separate connections for Pub/Sub and for regular commands. Most client libraries do this by default. This restriction ends when the migration completes. @@ -139 +179,0 @@ The ElastiCache Service Level Agreement applies to your ElastiCache Serverless c -**Total migration throughput scales with your source shard count.** A source with many shards migrates faster than a source with few. @@ -141 +180,0 @@ The ElastiCache Service Level Agreement applies to your ElastiCache Serverless c -**High-throughput sources with few shards.** This release is not suited to a high-throughput source with few shards. Migration throughput is provisioned per source shard. A source that concentrates high traffic into a small number of shards is most likely to be limited. If that describes your source, review the source primary capacity prerequisite in the source cache requirements, or plan the migration for a lower-traffic period. @@ -143 +182 @@ The ElastiCache Service Level Agreement applies to your ElastiCache Serverless c -**Billing after you stop the data sync.** Billing does not stop when you stop the data sync. `StopMigration` leaves the migration infrastructure provisioned. `CompleteMigration` is the call that ends the migration and its charges. Your target ElastiCache Serverless cache continues to bill until you delete it. +For more information, see [Cutover modes for online migration to ElastiCache Serverless](./migration-to-serverless-cutover.html).