diff --git a/_api-reference/replication-apis/create-replication-rule.md b/_api-reference/replication-apis/create-replication-rule.md new file mode 100644 index 00000000000..5be2a3c8683 --- /dev/null +++ b/_api-reference/replication-apis/create-replication-rule.md @@ -0,0 +1,87 @@ +--- +layout: default +title: Create Replication Rule API +parent: Replication APIs +nav_order: 55 +--- + +# Create Replication Rule API +Introduced 1.0 +{: .label .label-purple } + +The Create Replication Rule API establishes automatic replication patterns (auto-follow rules) that monitor for new indexes matching specified patterns and automatically configure them for replication. This allows for automated replication management without requiring manual setup for each new index. + + +## Endpoints +```json +POST /_plugins/_replication/_autofollow +``` + + +## Request body fields + +The following table lists the available request body fields. + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `leader_alias` | String | The name of an index alias to use when referring to the leader index. | +| `name` | String | The name of the replication rule. Required. | +| `pattern` | String | The pattern used to match indexes for automatic replication. Required. | +| `use_roles` | Object | Object containing custom roles for the replication connection. | + +
+ + Request body fields: use_roles + + {: .text-delta} + +`use_roles` is a JSON object with the following fields: + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `follower_cluster_role` | String | The role used for the follower cluster during replication. | +| `leader_cluster_role` | String | The role used for the leader cluster during replication. | +
+ +## Example request + +The following example creates a replication rule named "logs-rule" that automatically replicates any index matching the "logs-*" pattern: + +```json +POST /_plugins/_replication/_autofollow +{ + "name": "logs-rule", + "pattern": "logs-*", + "leader_alias": "logs-primary" +} +``` +{% include copy-curl.html %} + +The following example creates a replication rule with custom roles: + +```json +POST /_plugins/_replication/_autofollow +{ + "name": "metrics-rule", + "pattern": "metrics-*", + "leader_alias": "metrics-primary", + "use_roles": { + "leader_cluster_role": "replication_leader_role", + "follower_cluster_role": "replication_follower_role" + } +} +``` +{% include copy-curl.html %} + +## Example response + +The following example shows a successful API response: + +```json +{ + "acknowledged": true +} +``` diff --git a/_api-reference/replication-apis/delete-replication-rule.md b/_api-reference/replication-apis/delete-replication-rule.md new file mode 100644 index 00000000000..48f05dd7ddf --- /dev/null +++ b/_api-reference/replication-apis/delete-replication-rule.md @@ -0,0 +1,56 @@ +--- +layout: default +title: Delete Replication Rule API +parent: Replication APIs +nav_order: 60 +--- + +# Delete Replication Rule API +Introduced 1.0 +{: .label .label-purple } + +The Delete Replication Rule API removes an existing auto-follow replication rule. When deleted, the rule will no longer trigger automatic replication for new indexes that match its pattern. However, existing replication relationships that were established by the rule will continue to operate until explicitly stopped. + + +## Endpoints +```json +DELETE /_plugins/_replication/_autofollow +``` + + + +## Request body fields + +The request body is __required__. It is a JSON object with the following fields. + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `leader_alias` | String | The name of an index alias. | +| `name` | String | The name of the replication rule to delete. | + + + +## Example request + +The following example deletes a replication rule named "logs-rule": + +```json +DELETE /_plugins/_replication/_autofollow?name=logs-rule +``` +{% include copy-curl.html %} + +## Example response + +The following example shows a successful API response: + +```json +{ + "acknowledged": true +} +``` diff --git a/_api-reference/replication-apis/get-autofollow-stats.md b/_api-reference/replication-apis/get-autofollow-stats.md new file mode 100644 index 00000000000..ceaa7cdd3be --- /dev/null +++ b/_api-reference/replication-apis/get-autofollow-stats.md @@ -0,0 +1,95 @@ +--- +layout: default +title: Get Auto-follow Stats API +parent: Replication APIs +nav_order: 45 +--- + +# Get Auto-follow Stats API +Introduced 1.0 +{: .label .label-purple } + +The Get Auto-follow Stats API retrieves statistics about auto-follow patterns and their replication activities. This API helps you monitor the performance and status of automatic index replication configured through auto-follow patterns. + + +## Endpoints +```json +GET /_plugins/_replication/autofollow_stats +``` + + +## Example request + +The following example gets statistics for all configured auto-follow patterns: + +```json +GET /_plugins/_replication/autofollow_stats +``` +{% include copy-curl.html %} + +## Example response + +The following example shows a successful API response with statistics for two auto-follow patterns: + +```json +{ + "num_success_start_replication": 12, + "num_failed_start_replication": 1, + "num_failed_leader_calls": 0, + "failed_indices": ["logs-2023-error"], + "autofollow_stats": [ + { + "name": "logs-pattern", + "pattern": "logs-*", + "num_success_start_replication": 10, + "num_failed_start_replication": 1, + "num_failed_leader_calls": 0, + "last_execution_time": 1645729365423, + "failed_indices": ["logs-2023-error"] + }, + { + "name": "metrics-pattern", + "pattern": "metrics-*", + "num_success_start_replication": 2, + "num_failed_start_replication": 0, + "num_failed_leader_calls": 0, + "last_execution_time": 1645729245895, + "failed_indices": [] + } + ] +} +``` + +## Response body fields + +The following table lists all response body fields. + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `autofollow_stats` | Array of Objects | A list of statistics for each auto-follow pattern. | +| `failed_indices` | Array of Strings | The list of indexes that failed to replicate across all patterns. | +| `num_failed_leader_calls` | Float | The number of failed calls to the leader cluster across all patterns. | +| `num_failed_start_replication` | Float | The number of failed replication starts across all patterns. | +| `num_success_start_replication` | Float | The number of successful replication starts across all patterns. | + +
+ + Response body fields: autofollow_stats + + {: .text-delta} + +`autofollow_stats` is an array of JSON objects. Each object represents a single auto-follow pattern and has the following fields: + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `failed_indices` | Array of Strings | The list of indexes that failed to replicate for this pattern. | +| `last_execution_time` | Float | When the last execution of this auto-follow pattern occurred. | +| `name` | String | The name of the auto-follow pattern. | +| `num_failed_leader_calls` | Float | The number of failed calls to the leader cluster for this pattern. | +| `num_failed_start_replication` | Float | The number of failed replication starts for this pattern. | +| `num_success_start_replication` | Float | The number of successful replication starts for this pattern. | +| `pattern` | String | The pattern used for auto-following indexes. | +
\ No newline at end of file diff --git a/_api-reference/replication-apis/get-follower-stats.md b/_api-reference/replication-apis/get-follower-stats.md new file mode 100644 index 00000000000..e5416d8545d --- /dev/null +++ b/_api-reference/replication-apis/get-follower-stats.md @@ -0,0 +1,119 @@ +--- +layout: default +title: Get Follower Stats API +parent: Replication APIs +nav_order: 40 +--- + +# Get Follower Stats API +Introduced 1.0 +{: .label .label-purple } + +The Get Follower Stats API retrieves statistics about follower indexes in the replication process. This API provides detailed metrics about operations, progress, and performance of follower indexes during replication activities. + +## Endpoints + +```json +GET /_plugins/_replication/follower_stats +``` + +## Example request + +The following example gets statistics about all follower indexes in the replication process: + +```json +GET /_plugins/_replication/follower_stats +``` +{% include copy-curl.html %} + +## Example response + +The following example shows a successful API response with statistics for two follower indexes: + +```json +{ + "num_shard_tasks": 7, + "num_index_tasks": 2, + "num_bootstrapping_indices": 0, + "num_syncing_indices": 2, + "num_paused_indices": 0, + "num_failed_indices": 0, + "operations_read": 1254, + "operations_written": 1254, + "failed_read_requests": 0, + "failed_write_requests": 0, + "throttled_read_requests": 5, + "throttled_write_requests": 2, + "leader_checkpoint": 42, + "follower_checkpoint": 40, + "total_write_time_millis": 1850, + "index_stats": { + "customer-data": { + "operations_read": 854, + "operations_written": 854, + "failed_read_requests": 0, + "failed_write_requests": 0, + "throttled_read_requests": 3, + "throttled_write_requests": 1, + "leader_checkpoint": 27, + "follower_checkpoint": 25, + "total_write_time_millis": 1250 + }, + "product-data": { + "operations_read": 400, + "operations_written": 400, + "failed_read_requests": 0, + "failed_write_requests": 0, + "throttled_read_requests": 2, + "throttled_write_requests": 1, + "leader_checkpoint": 15, + "follower_checkpoint": 15, + "total_write_time_millis": 600 + } + } +} +``` + +## Response body fields + +The following table lists all response body fields. + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `failed_read_requests` | Float | The number of failed read requests during replication. | +| `failed_write_requests` | Float | The number of failed write requests during replication. | +| `follower_checkpoint` | Float | The current checkpoint of the follower index. | +| `index_stats` | Object | Per-index statistics for all indexes being replicated. | +| `leader_checkpoint` | Float | The current checkpoint of the leader index. | +| `num_bootstrapping_indices` | Float | The number of indexes currently bootstrapping. | +| `num_failed_indices` | Float | The number of indexes that have failed replication. | +| `num_index_tasks` | Float | The number of active index-level replication tasks. | +| `num_paused_indices` | Float | The number of indexes currently paused. | +| `num_shard_tasks` | Float | The number of active shard-level replication tasks. | +| `num_syncing_indices` | Float | The number of indexes currently syncing. | +| `operations_read` | Float | The total number of operations read during replication. | +| `operations_written` | Float | The total number of operations written during replication. | +| `throttled_read_requests` | Float | The number of throttled read requests during replication. | +| `throttled_write_requests` | Float | The number of throttled write requests during replication. | +| `total_write_time_millis` | Integer or String | The total time in milliseconds spent writing operations. | + +
+ + Response body fields: index_stats + + {: .text-delta} + +`index_stats` is a JSON object with index names as keys. Each index entry contains the following fields: + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `failed_read_requests` | Float | The number of failed read requests for this index during replication. | +| `failed_write_requests` | Float | The number of failed write requests for this index during replication. | +| `follower_checkpoint` | Float | The current checkpoint of this follower index. | +| `leader_checkpoint` | Float | The current checkpoint of the leader index for this follower. | +| `operations_read` | Float | The number of operations read for this index during replication. | +| `operations_written` | Float | The number of operations written for this index during replication. | +| `throttled_read_requests` | Float | The number of throttled read requests for this index during replication. | +| `throttled_write_requests` | Float | The number of throttled write requests for this index during replication. | +| `total_write_time_millis` | Integer or String | The total time in milliseconds spent writing operations for this index. | +
\ No newline at end of file diff --git a/_api-reference/replication-apis/get-leader-stats.md b/_api-reference/replication-apis/get-leader-stats.md new file mode 100644 index 00000000000..bae6ef45bc7 --- /dev/null +++ b/_api-reference/replication-apis/get-leader-stats.md @@ -0,0 +1,103 @@ +--- +layout: default +title: Get Leader Stats API +parent: Replication APIs +nav_order: 35 +--- + +# Get Leader Stats API +Introduced 1.0 +{: .label .label-purple } + +The Get Leader Stats API retrieves statistics about leader indexes in the replication process. This API provides detailed metrics about operations, data volumes, and performance during replication activities. + + +## Endpoints +```json +GET /_plugins/_replication/leader_stats +``` + + +## Example request + +The following example gets statistics about all leader indexes in the replication process: + +```json +GET /_plugins/_replication/leader_stats +``` +{% include copy-curl.html %} + +## Example response + +The following example shows a successful API response with statistics for two indexes: + +```json +{ + "num_replicated_indices": 2, + "operations_read": 1254, + "operations_read_lucene": 1134, + "operations_read_translog": 120, + "bytes_read": 25678, + "translog_size_bytes": 4582, + "total_read_time_lucene_millis": 1450, + "total_read_time_translog_millis": 235, + "index_stats": { + "customer-data": { + "operations_read": 854, + "operations_read_lucene": 784, + "operations_read_translog": 70, + "bytes_read": 18425, + "translog_size_bytes": 3210, + "total_read_time_lucene_millis": 980, + "total_read_time_translog_millis": 120 + }, + "product-data": { + "operations_read": 400, + "operations_read_lucene": 350, + "operations_read_translog": 50, + "bytes_read": 7253, + "translog_size_bytes": 1372, + "total_read_time_lucene_millis": 470, + "total_read_time_translog_millis": 115 + } + } +} +``` + +## Response body fields + +The following table lists all response body fields. + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `bytes_read` | Integer | The total size in bytes read during replication. | +| `index_stats` | Object | Per-index statistics for all indexes being replicated. | +| `num_replicated_indices` | Float | The number of indexes being replicated. | +| `operations_read` | Float | The total number of operations read during replication. | +| `operations_read_lucene` | Float | The number of operations read from Lucene during replication. | +| `operations_read_translog` | Float | The number of operations read from the translog during replication. | +| `total_read_time_lucene_millis` | Integer or String | The total time in milliseconds spent reading from Lucene. | +| `total_read_time_translog_millis` | Integer or String | The total time in milliseconds spent reading from the translog. | +| `translog_size_bytes` | Integer | The size in bytes of the translog. | + +
+ + Response body fields: index_stats + + {: .text-delta} + +`index_stats` is a JSON object with index names as keys. Each index entry contains the following fields: + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `bytes_read` | Integer | The size in bytes read for this specific index. | +| `operations_read` | Float | The number of operations read for this index during replication. | +| `operations_read_lucene` | Float | The number of operations read from Lucene for this index during replication. | +| `operations_read_translog` | Float | The number of operations read from the translog for this index during replication. | +| `total_read_time_lucene_millis` | Integer or String | The total time in milliseconds spent reading from Lucene for this index. | +| `total_read_time_translog_millis` | Integer or String | The total time in milliseconds spent reading from the translog for this index. | +| `translog_size_bytes` | Integer | The size in bytes of the translog for this index. | +
\ No newline at end of file diff --git a/_api-reference/replication-apis/get-replication-status.md b/_api-reference/replication-apis/get-replication-status.md new file mode 100644 index 00000000000..fedc0e23521 --- /dev/null +++ b/_api-reference/replication-apis/get-replication-status.md @@ -0,0 +1,74 @@ +--- +layout: default +title: Get Replication Status API +parent: Replication APIs +nav_order: 15 +--- + +# Get Replication Status API +Introduced 1.0 +{: .label .label-purple } + +The Get Replication Status API retrieves detailed information about the current state of replication for a specified index. This API helps you monitor the progress and health of the replication process between leader and follower indices. + + +## Endpoints +```json +GET /_plugins/_replication/{index}/_status +``` + + +## Path parameters + +The following table lists the available path parameters. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `index` | String | The name of the data stream, index, or index alias to get replication status for. Required. | + +## Example request + +The following example gets the replication status for the `customer-data` index: + +```json +GET /_plugins/_replication/customer-data/_status +``` +{% include copy-curl.html %} + +## Example response + +The following example shows a successful API response: + +```json +{ + "status": "RUNNING", + "reason": "Replication is active", + "leader_index": "leader-customer-data", + "follower_index": "follower-customer-data", + "leader_alias": "customer-data", + "syncing_details": { + "leader_checkpoint": 42, + "follower_checkpoint": 40, + "seq_no": 1023 + } +} +``` + +## Response body fields + +The following table lists all response body fields. + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `follower_index` | String | The name of the follower index in the replication process. | +| `leader_alias` | String | The name of an index alias used for the leader index. | +| `leader_index` | String | The name of the leader index in the replication process. | +| `reason` | String | The reason for the current replication status. | +| `status` | String | The current status of the replication process. Valid values are: `BOOTSTRAPPING`, `PAUSED`, `REPLICATION NOT IN PROGRESS`, `RUNNING`, and `SYNCING`. | +| `syncing_details` | Object | Details about the synchronization process. | +| `syncing_details.follower_checkpoint` | Integer | The checkpoint of the follower index in the replication process. | +| `syncing_details.leader_checkpoint` | Integer | The checkpoint of the leader index in the replication process. | +| `syncing_details.seq_no` | Integer | The sequence number of the document. | \ No newline at end of file diff --git a/_api-reference/replication-apis/index.md b/_api-reference/replication-apis/index.md new file mode 100644 index 00000000000..94da636d391 --- /dev/null +++ b/_api-reference/replication-apis/index.md @@ -0,0 +1,71 @@ +--- +layout: default +title: Replication APIs +has_children: true +nav_order: 83 +--- + +# Replication APIs +**Introduced 1.0** +{: .label .label-purple } + +The Replication APIs enable you to configure, manage, and monitor replication between OpenSearch indexes. Replication establishes a primary-replica relationship where changes made to a leader index are automatically propagated to one or more follower indexes. This capability provides resilience, improves read scalability, and enables disaster recovery across multiple OpenSearch clusters. + +## What is replication? + +Replication in OpenSearch creates a one-way relationship between indexes where: + +- A **leader index** serves as the leading replica for all copies. +- One or more **follower indexes** maintain consistent copies of the leader. +- Changes to the leader are automatically replicated to followers. +- Followers can exist within the same cluster or on remote clusters. + +This mechanism allows for maintaining synchronized copies of data across different locations or environments, supporting various resilience and scaling strategies. + +## Use cases for replication + +Replication supports the following operational scenarios: + +- **Disaster recovery**: Maintain backup copies of indexes in separate geographical regions +- **Read scaling**: Distribute query load across multiple followers for high-traffic indexes +- **Data locality**: Place replicas closer to users in different geographical regions to reduce latency +- **Blue/green deployments**: Facilitate non-disruptive upgrades by maintaining parallel environments +- **Analytics offloading**: Create replicas specifically for running intensive analytical workloads without impacting production performance + +## Available APIs + + +The Replication APIs: +- [Start Replication API]({{site.url}}{{site.baseurl}}/api-reference/replication-apis/start-replication/): Establish a new replication relationship between indexes. +- [Pause Replication API]({{site.url}}{{site.baseurl}}/api-reference/replication-apis/stop-replication/): Temporarily suspend replication activities. +- [Resume Replication API]({{site.url}}{{site.baseurl}}/api-reference/replication-apis/resume-replication/): Restart previously paused replication. +- [Stop Replication API]({{site.url}}{{site.baseurl}}/api-reference/replication-apis/stop-replication/): Permanently end a replication relationship. +- [Get Replication Status API]({{site.url}}{{site.baseurl}}/api-reference/replication-apis/get-replication-status/): Check the current status of replication for an index. +- [Get Leader Stats API]({{site.url}}{{site.baseurl}}/api-reference/replication-apis/get-leader-stats/): Retrieve performance metrics for leader indexes. +- [Get Follower Stats API]({{site.url}}{{site.baseurl}}/api-reference/replication-apis/get-follower-stats/): Retrieve performance metrics for follower indexes. +- [Update Replication Settings API]({{site.url}}{{site.baseurl}}/api-reference/replication-apis/update-replication-settings/): Modify configuration parameters for replication. +- [Create Replication Rule API]({{site.url}}{{site.baseurl}}/api-reference/replication-apis/create-replication-rule/): Establish automatic replication patterns for new indexes. +- [Delete Replication Rule API]({{site.url}}{{site.baseurl}}/api-reference/replication-apis/delete-replication-rule/): Remove an existing automatic replication rule. +- [Get Auto-follow Stats API]({{site.url}}{{site.baseurl}}/api-reference/replication-apis/get-autofollow-stats/): Retrieve statistics about automatic replication rules. + +## Security considerations + +Replication involves data transfer between indexes and potentially between clusters, requiring careful security planning: + +- Use appropriate roles and permissions to control who can configure and manage replication +- When replicating between clusters, ensure secure cross-cluster communication +- Consider encrypting data in transit between clusters +- Set up proper authentication between leader and follower clusters +- Regularly audit replication configurations and activities + + +## Best practices + +For optimal replication management, remember the following best practices: + +- **Capacity planning**: Make sure you have sufficient resources on both leader and follower clusters. +- **Monitoring**: Set up alerts for replication delays or failures. +- **Connection resilience**: Plan for network issues between clusters +- **Index compatibility**: Maintain consistent mappings between leader and follower indexes. +- **Performance tuning**: Adjust replication settings based on network conditions and data volume. +- **Testing**: Validate failover procedures before relying on replication for disaster recovery. diff --git a/_api-reference/replication-apis/pause-replication.md b/_api-reference/replication-apis/pause-replication.md new file mode 100644 index 00000000000..57d8058eb98 --- /dev/null +++ b/_api-reference/replication-apis/pause-replication.md @@ -0,0 +1,57 @@ +--- +layout: default +title: Pause Replication API +parent: Replication APIs +nav_order: 20 +--- + +# Pause Replication API +Introduced 1.0 +{: .label .label-purple } + +The Pause Replication API temporarily suspends the replication process for a specified index without removing the replication configuration. This allows you to pause replication activities when needed and resume them later. + + +## Endpoints +```json +POST /_plugins/_replication/{index}/_pause +``` + + +## Path parameters + +The following table lists the available path parameters. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `index` | String | The name of the data stream, index, or index alias to pause replication on. Required. | + +## Example request + +The following example pauses replication on the `customer-data` index: + +```json +POST /_plugins/_replication/customer-data/_pause +``` +{% include copy-curl.html %} + +## Example response + +The following example shows a successful API response: + +```json +{ + "acknowledged": true +} +``` + +## Response body fields + +The following table lists all response body fields. + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `acknowledged` | Boolean | Whether the request was acknowledged. | diff --git a/_api-reference/replication-apis/resume-replication.md b/_api-reference/replication-apis/resume-replication.md new file mode 100644 index 00000000000..63de405b090 --- /dev/null +++ b/_api-reference/replication-apis/resume-replication.md @@ -0,0 +1,57 @@ +--- +layout: default +title: Resume Replication API +parent: Replication APIs +nav_order: 25 +--- + +# Resume Replication API +Introduced 1.0 +{: .label .label-purple } + +The Resume Replication API restarts a previously paused replication process for a specified index. This API allows you to continue replication activities between leader and follower indices after they have been temporarily suspended. + + +## Endpoints +```json +POST /_plugins/_replication/{index}/_resume +``` + + +## Path parameters + +The following table lists the available path parameters. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `index` | String | The name of the data stream, index, or index alias to resume replication on. Required. | + +## Example request + +The following example resumes replication on the `customer-data` index: + +```json +POST /_plugins/_replication/customer-data/_resume +``` +{% include copy-curl.html %} + +## Example response + +The following example shows a successful API response: + +```json +{ + "acknowledged": true, +} +``` + +## Response body fields + +The following table lists all response body fields. + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `acknowledged` | Boolean | Whether the request was acknowledged. | diff --git a/_api-reference/replication-apis/start-replication.md b/_api-reference/replication-apis/start-replication.md new file mode 100644 index 00000000000..8823abc5821 --- /dev/null +++ b/_api-reference/replication-apis/start-replication.md @@ -0,0 +1,98 @@ +--- +layout: default +title: Start Replication API +parent: Replication APIs +nav_order: 10 +--- + +# Start Replication API +**Introduced 1.1** +{: .label .label-purple } + +The Start Replication API initiates a replication connection between two indexes. This API designates one index as the leader and another as the follower, establishing a one-way replication where changes made to the leader index are automatically replicated to the follower index. + + +## Endpoints +```json +PUT /_plugins/_replication/{index}/_start +``` + + + +## Path parameters + +The following table lists the available path parameters. + +| Parameter | Required | Data type | Description | +| :--- | :--- | :--- | :--- | +| `index` | **Required** | String | The name of the data stream, index, or index alias to perform bulk actions on. | + + + +## Request body fields + +The request body is **required**. It is a JSON object with the following fields: + +| Property | Required | Data type | Description | +| :--- | :--- | :--- | :--- | +| `leader_index` | **Required** | String | The name of the source index that will be replicated from. | +| `leader_alias` | Optional | String | The name of an index alias pointing to the leader index. Use this when the leader index name might change. | +| `use_roles` | Optional | Object | Defines custom roles for the replication connection. | + +
+ + Request body fields: use_roles + + {: .text-delta} + +`use_roles` is a JSON object with the following fields: + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `leader_cluster_role` | String | The role used for the leader cluster during replication. This role must have appropriate read permissions on the leader index. | +| `follower_cluster_role` | String | The role used for the follower cluster during replication. This role must have appropriate write permissions on the follower index. | + +
+ +## Example request + +The following example starts replication from `leader-index` to `follower-index`: + +```json +PUT /_plugins/_replication/follower-index/_start +{ + "leader_index": "leader-index" +} +``` +{% include copy-curl.html %} + +The following example uses custom roles for the replication connection: + +```json +PUT /_plugins/_replication//_start +{ + "leader_alias":"", + "leader_index":"", + "use_roles":{ + "leader_cluster_role":"", + "follower_cluster_role":"" + } +} +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "acknowledged": true +} +``` + + diff --git a/_api-reference/replication-apis/stop-replication.md b/_api-reference/replication-apis/stop-replication.md new file mode 100644 index 00000000000..4488a60bb13 --- /dev/null +++ b/_api-reference/replication-apis/stop-replication.md @@ -0,0 +1,56 @@ +--- +layout: default +title: Stop Replication API +parent: Replication APIs +nav_order: 30 +--- + +# Stop Replication API +Introduced 1.0 +{: .label .label-purple } + +The Stop Replication API halts the ongoing replication process for the specified index. This API lets you discontinue replication between the leader and follower indices when it's no longer needed. + + +## Endpoints +```json +POST /_plugins/_replication/{index}/_stop +``` + + + +## Path parameters + +The following table lists the available path parameters. + +| Parameter | Required | Data type | Description | +| :--- | :--- | :--- | :--- | +| `index` | **Required** | String | The name of the data stream, index, or index alias to perform bulk actions on. | + + + +## Example request + +The following example stops replication on the `customer-data` index: + +```json +POST /_plugins/_replication/customer-data/_stop +``` +{% include copy-curl.html %} + +## Example response + +The following example shows a successful API response: + +```json +{ + "acknowledged": true, + "shards_stopped": 5 +} +``` diff --git a/_api-reference/replication-apis/update-replication-settings.md b/_api-reference/replication-apis/update-replication-settings.md new file mode 100644 index 00000000000..de76588aa9e --- /dev/null +++ b/_api-reference/replication-apis/update-replication-settings.md @@ -0,0 +1,91 @@ +--- +layout: default +title: Update Replication Settings API +parent: Replication APIs +nav_order: 50 +--- + +# Update Replication Settings API +Introduced 1.0 +{: .label .label-purple } + +The Update Replication Settings API allows you to modify configuration settings for an index that is being replicated. This API enables you to adjust replication parameters such as the number of replicas and shards without stopping the replication process. + + +## Endpoints +```json +PUT /_plugins/_replication/{index}/_update +``` + + +## Path parameters + +The following table lists the available path parameters. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `index` | String | The name of the data stream, index, or index alias to update replication settings for. Required. | + +## Request body fields + +The following table lists the available request body fields. + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `settings` | Object | Object containing the settings to update for the replicated index. Required. | + +
+ + Request body fields: settings + + {: .text-delta} + +`settings` is a JSON object with the following fields: + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `index` | Object | Object containing index-specific settings to update. | + +
+ + Request body fields: settings > index + + {: .text-delta} + +`index` is a JSON object with the following fields: + +| Field | Data type | Description | +| :--- | :--- | :--- | +| `number_of_replicas` | Integer | The number of replicas for the index. | +| `number_of_shards` | Integer | The number of shards for the index. | +
+
+ +## Example request + +The following example updates the number of replicas for the `customer-data` index to 2: + +```json +PUT /_plugins/_replication/customer-data/_update +{ + "settings": { + "index": { + "number_of_replicas": 2 + } + } +} +``` +{% include copy-curl.html %} + +## Example response + +The following example shows a successful API response: + +```json +{ + "acknowledged": true +} +```