AWS solutions documentation change
Summary
Updated terminology to 'NextGen', changed bootstrap script URL, clarified TLS and authentication setup, added mTLS documentation, and various documentation improvements
Security assessment
The changes enhance security documentation by clarifying TLS behavior (explicitly warning against disabling TLS), improving credential management instructions, and adding mTLS guidance. No specific vulnerability is addressed, but security best practices are better documented.
Diff
diff --git a/solutions/latest/migration-assistant-for-amazon-opensearch-service/deploy-the-solution.md b/solutions/latest/migration-assistant-for-amazon-opensearch-service/deploy-the-solution.md index 75aa47222..8d68f4c1d 100644 --- a//solutions/latest/migration-assistant-for-amazon-opensearch-service/deploy-the-solution.md +++ b//solutions/latest/migration-assistant-for-amazon-opensearch-service/deploy-the-solution.md @@ -31 +31 @@ To deploy this solution on Amazon EKS, you need: - * Network connectivity from the Amazon EKS cluster to your source cluster and your Amazon OpenSearch Service domain or Amazon OpenSearch Serverless collection. + * Network connectivity from the Amazon EKS cluster to your source cluster and your Amazon OpenSearch Service domain or Amazon OpenSearch Serverless NextGen collection. @@ -57 +57 @@ Throughout this guide, `<STAGE>` is a short label such as `dev`, `staging`, or ` - "https://github.com/opensearch-project/opensearch-migrations/releases/latest/download/aws-bootstrap.sh" \ + "https://solutions-reference.s3.amazonaws.com/migration-assistant-for-amazon-opensearch-service/latest/aws-bootstrap.sh" \ @@ -76 +76 @@ Group | Flag | Purpose -**Versioning** | `--version <tag>` | Pin to a published GitHub release tag (find tags at [OpenSearch Migrations Releases](https://github.com/opensearch-project/opensearch-migrations/releases)). Use this for reproducible deployments. +**Versioning** | `--version <tag>` | Pin to a specific release version. Use this for reproducible deployments. See the [Migration Assistant documentation](https://docs.aws.amazon.com/solutions/migration-assistant-for-amazon-opensearch-service/) for available versions. @@ -85,2 +85,2 @@ Group | Flag | Purpose -**TLS (Capture proxy)** | `--tls-mode none` | No TLS termination on the capture proxy (default) -| `--tls-mode self-signed` | cert-manager-issued self-signed certificate +**TLS (Capture proxy)** | `--tls-mode none` | Do not enable AWS Private CA integration. The workflow still provisions self-signed proxy certificates by default; set a proxy’s `tls.mode` to `plaintext` only when you intentionally want no proxy TLS. +| `--tls-mode self-signed` | Use the default cert-manager-issued self-signed certificate path for capture proxy TLS @@ -150 +150 @@ You should see the Migration Console (`migration-console-0`), the Argo workflow -Once you are in the Migration Console pod, the migration flow is the same regardless of source: confirm the version, load the sample workflow configuration, run a pilot, validate, and then run the full migration. See [Use the solution](./use-the-solution.html). +Once you are in the Migration Console pod, the migration flow is the same regardless of source: confirm the version, load the sample workflow configuration, run a pilot, validate, and then run the full migration. See [Configure and run workflows](./use-the-solution.html). @@ -163 +163 @@ The deployment creates a default Amazon S3 bucket for migration artifacts and sn -The default bucket is mounted on the Migration Console pod for direct artifact access. +The default bucket is mounted read-only on the Migration Console pod at `/s3/artifacts` for direct artifact access. @@ -179 +179 @@ If your workflow needs a snapshot role ARN, look it up from the AWS CloudFormati -For sources that require basic authentication, create a Kubernetes secret in the `ma` namespace and reference it in `authConfig.basic.secretName` in your workflow configuration: +For sources that require basic authentication, create managed HTTP Basic credentials from the Migration Console pod and reference the name in `authConfig.basic.secretName` in your workflow configuration: @@ -182,4 +182,3 @@ For sources that require basic authentication, create a Kubernetes secret in the - kubectl create secret generic source-credentials \ - --from-literal=username=<SOURCE_USER> \ - --from-literal=password=<SOURCE_PASSWORD> \ - -n ma + workflow configure credentials create source-credentials + +For non-interactive setup, use `workflow configure credentials create source-credentials --stdin` and pass one `USERNAME:PASSWORD` line on stdin. If you already manage the value in an external secrets system, sync it into a Kubernetes Secret in the `ma` namespace and reference that Kubernetes Secret name from `authConfig.basic.secretName`. @@ -189 +188 @@ For sources that require basic authentication, create a Kubernetes secret in the -For Amazon OpenSearch Service domains, Amazon OpenSearch Serverless collections, and other AWS services that authenticate with SigV4, the Amazon EKS stack uses [EKS Pod Identity](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html) to give two sets of pods an AWS identity: +For Amazon OpenSearch Service domains, Amazon OpenSearch Serverless NextGen collections, and other AWS services that authenticate with SigV4, the Amazon EKS stack uses [EKS Pod Identity](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html) to give two sets of pods an AWS identity: @@ -198 +197,7 @@ For Amazon OpenSearch Service domains, Amazon OpenSearch Serverless collections, -The Migration Console and the migration jobs can authenticate to Amazon OpenSearch Service, Amazon OpenSearch Serverless, and other AWS services without manually distributing long-lived AWS credentials. +The Migration Console and the migration jobs can authenticate to Amazon OpenSearch Service, Amazon OpenSearch Serverless NextGen, and other AWS services without manually distributing long-lived AWS credentials. + +Use `es` as the SigV4 service name when targeting an Amazon OpenSearch Service domain, and `aoss` when targeting an Amazon OpenSearch Serverless NextGen collection. Verify the identity inside the Migration Console pod with `aws sts get-caller-identity`. + +### Cluster mutual TLS + +Do not confuse cluster mTLS with Capture Proxy listener mTLS. Proxy listener mTLS controls client connections into the capture proxy and is configured under `traffic.proxies.<proxy>.proxyConfig.tls.clientAuth`. See [TLS behavior](./reroute-to-proxy.html#reroute-tls). @@ -200 +205 @@ The Migration Console and the migration jobs can authenticate to Amazon OpenSear -Use `es` as the SigV4 service name when targeting an Amazon OpenSearch Service domain, and `aoss` when targeting an Amazon OpenSearch Serverless collection. Verify the identity inside the Migration Console pod with `aws sts get-caller-identity`. +The workflow schema exposes `authConfig.mtls` with `caCert` and `clientSecretName`, but the current documented workflow path is centered on basic authentication and SigV4. The standard workflow templates do not mount and pass the `clientSecretName` certificate and key pair through every migration phase, and the Traffic Replayer target-auth path derives request authentication for SigV4 and basic auth only. Treat cluster mTLS as an advanced custom-wiring path and validate the exact phases you plan to run before using it. @@ -259 +264 @@ For additional troubleshooting, see [Troubleshooting](./troubleshooting.html). -The legacy Amazon ECS deployment is in support-only mode and will reach end of support on **July 15, 2026**. No new features will be developed for the Amazon ECS deployment. New deployments should use the Amazon EKS deployment described in this guide. +The legacy Amazon ECS deployment has reached end of support (**July 15, 2026**). No new features will be developed for the Amazon ECS deployment. New deployments should use the Amazon EKS deployment described in this guide. @@ -271 +276 @@ Quotas -Monitor the solution +Run a migration