From f6a9a7cc59177eb09bb609957f626f33382a09be Mon Sep 17 00:00:00 2001
From: Harsh Mishra <erbeusgriffincasper@gmail.com>
Date: Mon, 24 Aug 2026 14:38:38 +0530
Subject: [PATCH] DOC-267: Document Replicator skip-existing behavior

Explain how to preserve existing target resources and identify skipped resources across replication strategies.
---
 .../developer-tools/aws-replicator/index.mdx  | 47 +++++++++++++++++--
 1 file changed, 43 insertions(+), 4 deletions(-)

diff --git a/src/content/docs/aws/developer-tools/aws-replicator/index.mdx b/src/content/docs/aws/developer-tools/aws-replicator/index.mdx
index acc0d0911..53cc81b13 100644
--- a/src/content/docs/aws/developer-tools/aws-replicator/index.mdx
+++ b/src/content/docs/aws/developer-tools/aws-replicator/index.mdx
@@ -81,7 +81,7 @@ The [supported resources](#supported-resources) table shows which strategies are
 Two options apply regardless of strategy:
 
 - **Cross-region source discovery**: if the resource lives in a different AWS region than your credentials' default region (or its ARN has no region component, as with S3 buckets), set a source region explicitly.
-- **Skip existing resources**: by default a job fails if the target resource already exists. Set `ignore_already_existing` to skip it instead and continue the job.
+- **Skip existing resources**: by default a job fails if the target resource already exists. Set [`ignore_already_existing`](#skip-existing-resources) to skip it instead and continue the job.
 
 #### Using the LocalStack CLI
 
@@ -148,7 +148,46 @@ localstack replicator start \
 
 Check the [supported resources](#supported-resources) table for which resource types accept extra configuration and which keys they support.
 
-By default, a job fails if the target resource already exists. To skip it instead and continue the job, add `--extra-config ignore_already_existing=true`.
+##### Skip existing resources
+
+By default, a replication job fails when creating a resource that already exists in LocalStack.
+To keep the existing resource unchanged and continue the job, set `ignore_already_existing` to `true`:
+
+```bash
+localstack replicator start \
+  --resource-type AWS::SSM::Parameter \
+  --resource-identifier myparam \
+  --extra-config ignore_already_existing=true
+```
+
+```json title="Output"
+{
+  "job_id": "50005865-1589-4f6d-a720-c86f5a5dd021",
+  "state": "TESTING_CONNECTION",
+  "resources": {"succeeded": [], "failed": [], "skipped": []},
+  "error_message": null,
+  "type": "SINGLE_RESOURCE",
+  "explore_strategy": "SIMPLE"
+}
+```
+
+Only conflicts caused by an existing target resource are skipped.
+The Replicator does not overwrite or synchronize the existing resource, and other errors still fail the job.
+After the job completes, the identifier appears in `resources.skipped` and the job state is `SUCCEEDED`:
+
+```json
+{
+  "job_id": "50005865-1589-4f6d-a720-c86f5a5dd021",
+  "state": "SUCCEEDED",
+  "resources": {"succeeded": [], "failed": [], "skipped": ["myparam"]},
+  "error_message": null,
+  "type": "SINGLE_RESOURCE",
+  "explore_strategy": "SIMPLE"
+}
+```
+
+The option applies to single, batch, and tree replication jobs.
+Tree replication also automatically skips some shared related resources, such as an IAM managed policy referenced by multiple roles.
 
 #### Using the HTTP API
 
@@ -237,7 +276,7 @@ For example, to replicate an entire organization tree:
 When omitted, `explore_strategy` defaults to `SIMPLE`, which replicates only the requested resource.
 The related resources replicated by `TREE` are listed in the [supported resources](#supported-resources) table, along with the additional IAM actions they require.
 
-`replication_job_config` also accepts `source_region_name` and `ignore_already_existing`, and any resource-specific extra configuration such as `master_user_password`, as additional keys alongside `resource_type`/`resource_identifier`.
+`replication_job_config` also accepts `source_region_name`, any resource-specific extra configuration such as `master_user_password`, and `ignore_already_existing: true` to use the [skip existing resources](#skip-existing-resources) behavior.
 
 To list every replication job instead of one, send a `GET` request to the same `/_localstack/replicator/jobs` endpoint without a job ID.
 
@@ -271,7 +310,7 @@ This command returns the job status in JSON format. For example, here's a single
 ```
 
 `state` is one of `TESTING_CONNECTION`, `RUNNING`, `SUCCEEDED`, or `ERROR`.
-`resources` lists the identifiers of resources that succeeded, failed, or were skipped (see `ignore_already_existing` above) — for a single-resource job these lists have at most one entry, for a batch job they can have many:
+`resources` lists the identifiers of resources that succeeded, failed, or were [skipped](#skip-existing-resources) — for a single-resource job these lists have at most one entry, for a batch job they can have many:
 
 ```json
 {