AWS solutions documentation change
Summary
Added documentation for replaying captured traffic archives from S3, updated workflow commands for starting/checking/stopping replays, enhanced configuration details for traffic transformations and result logging, and replaced 'Amazon OpenSearch Serverless' with 'Amazon OpenSearch Serverless NextGen' throughout.
Security assessment
The changes focus on functional improvements (S3 replay support, workflow command updates) and documentation clarity. No vulnerabilities or security incidents are addressed. While authentication headers are mentioned in tuple logs, this is existing functionality, not a new security feature.
Diff
diff --git a/solutions/latest/migration-assistant-for-amazon-opensearch-service/using-traffic-replayer.md b/solutions/latest/migration-assistant-for-amazon-opensearch-service/using-traffic-replayer.md index 101c2da13..fac24c721 100644 --- a//solutions/latest/migration-assistant-for-amazon-opensearch-service/using-traffic-replayer.md +++ b//solutions/latest/migration-assistant-for-amazon-opensearch-service/using-traffic-replayer.md @@ -7 +7 @@ -When to run Traffic ReplayerStarting Traffic ReplayerChecking replay statusStopping Traffic ReplayerDelivery guaranteesTime scalingTransformationsResult logsAmazon CloudWatch metrics +Replay a captured-traffic archive from Amazon S3When to run Traffic ReplayerStarting replayChecking replay statusStopping or replacing replayDelivery guaranteesTime scalingTransformationsResult logsAmazon CloudWatch metrics @@ -13 +13 @@ When to run Traffic ReplayerStarting Traffic ReplayerChecking replay statusStopp -This section is only relevant if you are using Capture and Replay to avoid downtime during a migration to Amazon OpenSearch Service or Amazon OpenSearch Serverless. If you are performing backfill only, skip this section. +This section is only relevant if you are using Capture and Replay to avoid downtime during a migration to Amazon OpenSearch Service or Amazon OpenSearch Serverless NextGen. If you are performing backfill only, skip this section. @@ -15 +15 @@ This section is only relevant if you are using Capture and Replay to avoid downt -Traffic Replayer replays captured traffic from the source cluster to the Amazon OpenSearch Service domain or Amazon OpenSearch Serverless collection. This verifies that the target can handle requests in the same way as the source and catches up to real-time traffic for a smooth migration. +Traffic Replayer replays captured traffic from the source cluster to the Amazon OpenSearch Service domain or Amazon OpenSearch Serverless NextGen collection. This verifies that the target can handle requests in the same way as the source and catches up to real-time traffic for a smooth migration. @@ -17 +17,42 @@ Traffic Replayer replays captured traffic from the source cluster to the Amazon -## When to run Traffic Replayer +## Replay a captured-traffic archive from Amazon S3 + +If you already have captured traffic exported from a Migration Assistant Kafka topic, configure it under `traffic.s3Sources`. The workflow loads the `*.proto.gz` archive into Kafka and replays that topic without creating a live capture proxy. Set the replayer’s `fromCapturedTraffic` field to the `s3Sources` key. The same `fromCapturedTraffic` field also references `traffic.proxies` when you replay live captured traffic. + + + { + "kafkaClusterConfiguration": { + "default": { + "autoCreate": { + "auth": { + "type": "none" + } + } + } + }, + "sourceClusters": {}, + "targetClusters": { + "target": { + "endpoint": "https://<TARGET_ENDPOINT>" + } + }, + "snapshotMigrationConfigs": [], + "traffic": { + "s3Sources": { + "loaded-dump": { + "s3Uri": "s3://traffic-bucket/captures/one.proto.gz", + "awsRegion": "us-east-1", + "sourceLabel": "original-source", + "kafkaTopic": "loaded-dump" + } + }, + "replayers": { + "replay1": { + "fromCapturedTraffic": "loaded-dump", + "toTarget": "target", + "replayerConfig": { + "speedupFactor": 2.0 + } + } + } + } + } @@ -19 +60 @@ Traffic Replayer replays captured traffic from the source cluster to the Amazon -Start Traffic Replayer only after all metadata and documents have been migrated. Running it before the document migration completes may cause operations to execute out of order. For example, a deletion captured after the snapshot was taken could execute before the document is added to the target. +The `s3Uri` must point to a gzipped captured-traffic export in the form `s3://<BUCKET>/<PATH>/<FILE>.proto.gz`. The loader uses the workflow pod’s AWS identity to read the object, so grant that identity `s3:GetObject` access to the bucket and prefix. The `awsRegion` is the Region of the S3 bucket. The `sourceLabel` is used for workflow resource labels and does not need to match a key in `sourceClusters`. The top-level `sourceClusters` field is still required by the workflow schema; use an empty object when the run only replays an S3 traffic archive and does not access a live source cluster. If you omit `kafka`, the workflow uses the `default` Kafka cluster. If you omit `kafkaTopic`, the workflow uses the `s3Sources` key, such as `loaded-dump`, as the topic name. Use `endpoint` only for a custom S3-compatible endpoint; valid schemes are `http://`, `https://`, `localstack://`, and `localstacks://`. @@ -21 +62 @@ Start Traffic Replayer only after all metadata and documents have been migrated. -## Starting Traffic Replayer +###### Important @@ -22,0 +64 @@ Start Traffic Replayer only after all metadata and documents have been migrated. +The workflow S3 loader does not mount Kafka SCRAM passwords, Kafka CA certificates, or a custom Kafka client property file. For `traffic.s3Sources`, configure the destination Kafka profile so the loader can write without SCRAM/TLS client material, such as an auto-created Kafka cluster with `auth.type: none` or an existing Kafka cluster with `auth.type: none`. Do not rely on the implicit workflow-managed Kafka default for S3 archive replay; when Kafka auth is omitted, workflow-managed Kafka resolves to SCRAM, and the S3 import step cannot use that SCRAM material. The capture proxy and replayer support SCRAM through `kafkaClusterConfiguration`, but the S3 import step is a separate loader path. @@ -24 +66 @@ Start Traffic Replayer only after all metadata and documents have been migrated. - console replay start +###### Important @@ -26 +68 @@ Start Traffic Replayer only after all metadata and documents have been migrated. -Example output: +An S3 captured-traffic source is loaded into Kafka exactly once. This prevents accidental duplicate replay if a workflow is retried. To replay a different `s3Uri` or reload the same object intentionally, use a new `traffic.s3Sources` key or delete the corresponding `CapturedTraffic` custom resource before rerunning the workflow. @@ -27,0 +70 @@ Example output: +###### Note @@ -29 +72 @@ Example output: - Replayer started successfully. +Names under `traffic.s3Sources` and `traffic.proxies` share one namespace because replayers resolve both through `fromCapturedTraffic`. Do not reuse the same name in both maps. @@ -31 +74,9 @@ Example output: -## Checking replay status +###### Note + +Each `traffic.proxies` entry and each `traffic.s3Sources` entry owns one captured-traffic topic. Within the same Kafka cluster, two captured-traffic sources cannot resolve to the same effective topic name. The effective topic is the explicit `kafkaTopic`, or the traffic source key when `kafkaTopic` is omitted. + +## When to run Traffic Replayer + +Run Traffic Replayer only after the backfill work it depends on has completed. In the workflow path, you normally express this by setting `dependsOnSnapshotMigrations` on the replayer, outside `replayerConfig`. The workflow then starts replay automatically after the captured-traffic source is ready and the listed snapshot migrations have completed. Running replay too early can apply operations out of order; for example, a deletion captured after the snapshot was taken could execute before the document is added to the target. + +## Starting replay @@ -34 +85,2 @@ Example output: - console replay status + workflow submit + workflow manage @@ -36 +88 @@ Example output: -The status reports: +For workflow-managed migrations, `workflow submit` starts the workflow and the Traffic Replayer starts when its dependencies are ready. Use `workflow manage` for the interactive run view and approval gates. @@ -38 +90,3 @@ The status reports: - * **Running** — How many container instances are actively running. +The legacy `console replay start` command controls a directly configured replayer deployment from older component-style console configurations. It is not the primary workflow path. + +## Checking replay status @@ -40 +93,0 @@ The status reports: - * **Pending** — How many instances are being provisioned. @@ -42 +95,2 @@ The status reports: - * **Desired** — The total number of instances that should be running. + workflow status --resource-view + workflow log resource trafficreplay.<NAME> -- --tail=100 @@ -43,0 +98 @@ The status reports: +The resource view groups migration resources by role and shows the `TrafficReplay` resource that owns the replayer pods. Use `workflow log resource --list` if you need the exact resource name. @@ -44,0 +100 @@ The status reports: +If you are using a legacy directly configured replayer, `console replay status` reports the number of running, pending, and desired instances for that deployment. @@ -45,0 +102 @@ The status reports: +## Stopping or replacing replay @@ -47 +103,0 @@ The status reports: -## Stopping Traffic Replayer @@ -48,0 +105 @@ The status reports: + workflow submit @@ -50 +107 @@ The status reports: - console replay stop +`workflow submit` automatically stops and replaces an existing workflow with the same workflow name before submitting the new run. Use `workflow reset` only when you need to delete migration custom resources left from an abandoned or failed run. For legacy directly configured replayers, use `console replay stop`. @@ -54 +111 @@ The status reports: -Traffic Replayer retrieves traffic from Apache Kafka and updates its commit cursor after sending requests to the target. This provides an "at least once" delivery guarantee. Monitor metrics and validate externally to confirm the Amazon OpenSearch Service domain or Amazon OpenSearch Serverless collection is functioning as expected. +Traffic Replayer retrieves traffic from Apache Kafka and updates its commit cursor after sending requests to the target. This provides an "at least once" delivery guarantee. Monitor metrics and validate externally to confirm the Amazon OpenSearch Service domain or Amazon OpenSearch Serverless NextGen collection is functioning as expected. @@ -69 +126 @@ Traffic Replayer sends requests in the same order they were received on each con -If the Amazon OpenSearch Service domain or Amazon OpenSearch Serverless collection cannot respond quickly enough, Traffic Replayer waits for the previous request to complete before sending the next one. +If the Amazon OpenSearch Service domain or Amazon OpenSearch Serverless NextGen collection cannot respond quickly enough, Traffic Replayer waits for the previous request to complete before sending the next one. @@ -73 +130 @@ If the Amazon OpenSearch Service domain or Amazon OpenSearch Serverless collecti -During migrations, some requests may need to be transformed between versions. Traffic Replayer automatically rewrites host and authentication headers. For more complex transformations, specify custom transformation rules in your workflow configuration using the `replayerConfig` section. +Traffic Replayer automatically rewrites host and authentication headers. For more complex transformations, including Elasticsearch content-type header compatibility, see [Transform live traffic (Traffic Replayer)](./transform-replayer.html). @@ -75,5 +132 @@ During migrations, some requests may need to be transformed between versions. Tr -### Elasticsearch content-type header compatibility - -Newer Elasticsearch clients (version 7.11 and later, including all 8.x versions) use Elasticsearch-specific media types in `Content-Type` and `Accept` headers, such as `application/vnd.elasticsearch+json;compatible-with=8`. Amazon OpenSearch Service and Amazon OpenSearch Serverless do not support these media types. - -If you are migrating traffic from Elasticsearch clients version 7.11 or later, apply a transformation to convert these headers to standard `application/json`: +## Result logs @@ -81 +134 @@ If you are migrating traffic from Elasticsearch clients version 7.11 or later, a - 1. Create a JavaScript transformation file in the Migration Console pod: +Traffic Replayer can write tuple audit records for HTTP transactions from the source capture and those replayed to the Amazon OpenSearch Service domain or Amazon OpenSearch Serverless NextGen collection. For Amazon EKS workflow runs, configure tuple output to Amazon S3. The following fragment shows only the relevant fields; keep the rest of the replayer configuration unchanged: @@ -83,3 +135,0 @@ If you are migrating traffic from Elasticsearch clients version 7.11 or later, a - cat > /shared-logs-output/content-type-transformer.js << 'SCRIPT' - const NEW_CONTENT_TYPE = "application/json"; - const ELASTIC_CONTENT_TYPE = "application/vnd.elasticsearch+json"; @@ -87,18 +137,7 @@ If you are migrating traffic from Elasticsearch clients version 7.11 or later, a - function transform(request, context) { - let headers = request.get("headers"); - if (headers) { - let contentType = headers.get("Content-Type"); - if (Array.isArray(contentType)) { - headers.set("Content-Type", contentType.map(v => v.includes(ELASTIC_CONTENT_TYPE) ? NEW_CONTENT_TYPE : v)); - } else if (typeof contentType === "string") { - if (contentType.includes(ELASTIC_CONTENT_TYPE)) { - headers.set("Content-Type", NEW_CONTENT_TYPE); - } - } - let accept = headers.get("Accept"); - if (Array.isArray(accept)) { - headers.set("Accept", accept.map(v => v.includes(ELASTIC_CONTENT_TYPE) ? NEW_CONTENT_TYPE : v)); - } else if (typeof accept === "string") { - if (accept.includes(ELASTIC_CONTENT_TYPE)) { - headers.set("Accept", NEW_CONTENT_TYPE); - } + { + "traffic": { + "replayers": { + "<REPLAYER_NAME>": { + "replayerConfig": { + "tupleS3Bucket": "<DEFAULT_MIGRATION_BUCKET>", + "tupleS3Region": "<REGION>" @@ -107 +145,0 @@ If you are migrating traffic from Elasticsearch clients version 7.11 or later, a - return request; @@ -109,5 +146,0 @@ If you are migrating traffic from Elasticsearch clients version 7.11 or later, a - - function main(context) { - return (request) => { - if (Array.isArray(request)) { - return request.flat().map(item => transform(item, context)); @@ -115,2 +147,0 @@ If you are migrating traffic from Elasticsearch clients version 7.11 or later, a - return transform(request, context); - }; @@ -118,2 +148,0 @@ If you are migrating traffic from Elasticsearch clients version 7.11 or later, a - (() => main)(); - SCRIPT @@ -121,12 +150 @@ If you are migrating traffic from Elasticsearch clients version 7.11 or later, a - 2. Create a transformation configuration file: - - cat > /shared-logs-output/replayer-transformation.json << 'EOF' - [ - { - "JsonJSTransformerProvider": { - "initializationScriptFile": "/shared-logs-output/content-type-transformer.js", - "bindingsObject": "{}" - } - } - ] - EOF +You can use the Migration Assistant-managed default bucket. Retrieve its name and Region from the `migrations-default-s3-config` ConfigMap: @@ -134 +151,0 @@ If you are migrating traffic from Elasticsearch clients version 7.11 or later, a - 3. Reference the transformation in your workflow configuration under `replayerConfig` or pass as extra args. @@ -135,0 +153,2 @@ If you are migrating traffic from Elasticsearch clients version 7.11 or later, a + kubectl get configmap migrations-default-s3-config -n ma \ + -o jsonpath='{.data.BUCKET_NAME}{"\n"}{.data.AWS_REGION}{"\n"}'