Merge pull request #192 from opensearch-project/cross-cluster-replication
Cross-cluster replication docs
This commit is contained in:
Andrew Etter
GitHub
commit
83a6779bb9
@ -45,6 +45,9 @@ collections:
|
||||
im-plugin:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
replication-plugin:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
monitoring-plugins:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
@ -81,6 +84,9 @@ just_the_docs:
|
||||
im-plugin:
|
||||
name: Index management plugin
|
||||
nav_fold: true
|
||||
replication-plugin:
|
||||
name: Replication plugin
|
||||
nav_fold: true
|
||||
monitoring-plugins:
|
||||
name: Monitoring plugins
|
||||
nav_fold: true
|
||||
|
||||
391
_replication-plugin/api.md
Normal file
391
_replication-plugin/api.md
Normal file
@ -0,0 +1,391 @@
|
||||
---
|
||||
layout: default
|
||||
title: API
|
||||
nav_order: 50
|
||||
---
|
||||
|
||||
# Cross-cluster replication API
|
||||
|
||||
Use these replication operations to programmatically manage cross-cluster replication.
|
||||
|
||||
#### Table of contents
|
||||
- TOC
|
||||
{:toc}
|
||||
|
||||
## Start replication
|
||||
Introduced 1.1
|
||||
{: .label .label-purple }
|
||||
|
||||
Initiate replication of an index from the leader cluster to the follower cluster. Send this request to the follower cluster.
|
||||
|
||||
|
||||
#### Request
|
||||
|
||||
```json
|
||||
PUT /_plugins/_replication/<follower-index>/_start
|
||||
{
|
||||
"leader_alias":"<connection-alias-name>",
|
||||
"leader_index":"<index-name>",
|
||||
"use_roles":{
|
||||
"leader_cluster_role":"<role-name>",
|
||||
"follower_cluster_role":"<role-name>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Specify the following options:
|
||||
|
||||
Options | Description | Type | Required
|
||||
:--- | :--- |:--- |:--- |
|
||||
`leader_alias` | The name of the cross-cluster connection. You define this alias when you [set up a cross-cluster connection]({{site.url}}{{site.baseurl}}/replication-plugin/get-started/#set-up-a-cross-cluster-connection). | `string` | Yes
|
||||
`leader_index` | The index on the leader cluster that you want to replicate. | `string` | Yes
|
||||
`use_roles` | The roles to use for all subsequent backend replication tasks between the indices. Specify a `leader_cluster_role` and `follower_cluster_role`. See [Map the leader and follower cluster roles]({{site.url}}{{site.baseurl}}/replication-plugin/permissions/#map-the-leader-and-follower-cluster-roles). | `string` | If security plugin is enabled
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"acknowledged": true
|
||||
}
|
||||
```
|
||||
|
||||
## Stop replication
|
||||
Introduced 1.1
|
||||
{: .label .label-purple }
|
||||
|
||||
Terminates replication and converts the follower index to a standard index. Send this request to the follower cluster.
|
||||
|
||||
#### Request
|
||||
|
||||
```json
|
||||
POST /_plugins/_replication/<follower-index>/_stop
|
||||
{}
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"acknowledged": true
|
||||
}
|
||||
```
|
||||
|
||||
## Pause replication
|
||||
Introduced 1.1
|
||||
{: .label .label-purple }
|
||||
|
||||
Pauses replication of the leader index. Send this request to the follower cluster.
|
||||
|
||||
#### Request
|
||||
|
||||
```json
|
||||
POST /_plugins/_replication/<follower-index>/_pause
|
||||
{}
|
||||
```
|
||||
|
||||
You can't resume replication after it's been paused for more than 12 hours. You must [stop replication]({{site.url}}{{site.baseurl}}/replication-plugin/api/#stop-replication), delete the follower index, and restart replication of the leader.
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"acknowledged": true
|
||||
}
|
||||
```
|
||||
|
||||
## Resume replication
|
||||
Introduced 1.1
|
||||
{: .label .label-purple }
|
||||
|
||||
Resumes replication of the leader index. Send this request to the follower cluster.
|
||||
|
||||
#### Request
|
||||
|
||||
```json
|
||||
POST /_plugins/_replication/<follower-index>/_resume
|
||||
{}
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"acknowledged": true
|
||||
}
|
||||
```
|
||||
|
||||
## Get replication status
|
||||
Introduced 1.1
|
||||
{: .label .label-purple }
|
||||
|
||||
Gets the status of index replication. Possible statuses are `SYNCING`, `BOOTSTRAPING`, `PAUSED`, and `REPLICATION NOT IN PROGRESS`. Use the syncing details to measure replication lag. Send this request to the follower cluster.
|
||||
|
||||
#### Request
|
||||
|
||||
```json
|
||||
GET /_plugins/_replication/<follower-index>/_status
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"status" : "SYNCING",
|
||||
"reason" : "User initiated",
|
||||
"leader_alias" : "my-connection-name",
|
||||
"leader_index" : "leader-01",
|
||||
"follower_index" : "follower-01",
|
||||
"syncing_details" : {
|
||||
"leader_checkpoint" : 19,
|
||||
"follower_checkpoint" : 19,
|
||||
"seq_no" : 0
|
||||
}
|
||||
}
|
||||
```
|
||||
To include shard replication details in the response, add the `&verbose=true` parameter.
|
||||
|
||||
The leader and follower checkpoint values begin as negative integers and reflect the shard count (-1 for one shard, -5 for five shards, and so on). The values increment toward positive integers with each change that you make. For example, when you make a change on the leader index, the `leader_checkpoint` becomes `0`. The `follower_checkpoint` is initially still `-1` until the follower index pulls the change from the leader, at which point it increments to `0`. If the values are the same, it means the indices are fully synced.
|
||||
|
||||
## Get leader cluster stats
|
||||
Introduced 1.1
|
||||
{: .label .label-purple }
|
||||
|
||||
Gets information about replicated leader indices on a specified cluster.
|
||||
|
||||
#### Request
|
||||
|
||||
```json
|
||||
GET /_plugins/_replication/leader_stats
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"num_replicated_indices": 2,
|
||||
"operations_read": 15,
|
||||
"translog_size_bytes": 1355,
|
||||
"operations_read_lucene": 0,
|
||||
"operations_read_translog": 15,
|
||||
"total_read_time_lucene_millis": 0,
|
||||
"total_read_time_translog_millis": 659,
|
||||
"bytes_read": 1000,
|
||||
"index_stats":{
|
||||
"leader-index-1":{
|
||||
"operations_read": 7,
|
||||
"translog_size_bytes": 639,
|
||||
"operations_read_lucene": 0,
|
||||
"operations_read_translog": 7,
|
||||
"total_read_time_lucene_millis": 0,
|
||||
"total_read_time_translog_millis": 353,
|
||||
"bytes_read":466
|
||||
},
|
||||
"leader-index-2":{
|
||||
"operations_read": 8,
|
||||
"translog_size_bytes": 716,
|
||||
"operations_read_lucene": 0,
|
||||
"operations_read_translog": 8,
|
||||
"total_read_time_lucene_millis": 0,
|
||||
"total_read_time_translog_millis": 306,
|
||||
"bytes_read": 534
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Get follower cluster stats
|
||||
Introduced 1.1
|
||||
{: .label .label-purple }
|
||||
|
||||
Gets information about follower (syncing) indices on a specified cluster.
|
||||
|
||||
#### Request
|
||||
|
||||
```json
|
||||
GET /_plugins/_replication/follower_stats
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"num_syncing_indices": 2,
|
||||
"num_bootstrapping_indices": 0,
|
||||
"num_paused_indices": 0,
|
||||
"num_failed_indices": 0,
|
||||
"num_shard_tasks": 2,
|
||||
"num_index_tasks": 2,
|
||||
"operations_written": 3,
|
||||
"operations_read": 3,
|
||||
"failed_read_requests": 0,
|
||||
"throttled_read_requests": 0,
|
||||
"failed_write_requests": 0,
|
||||
"throttled_write_requests": 0,
|
||||
"follower_checkpoint": 1,
|
||||
"leader_checkpoint": 1,
|
||||
"total_write_time_millis": 2290,
|
||||
"index_stats":{
|
||||
"follower-index-1":{
|
||||
"operations_written": 2,
|
||||
"operations_read": 2,
|
||||
"failed_read_requests": 0,
|
||||
"throttled_read_requests": 0,
|
||||
"failed_write_requests": 0,
|
||||
"throttled_write_requests": 0,
|
||||
"follower_checkpoint": 1,
|
||||
"leader_checkpoint": 1,
|
||||
"total_write_time_millis": 1355
|
||||
},
|
||||
"follower-index-2":{
|
||||
"operations_written": 1,
|
||||
"operations_read": 1,
|
||||
"failed_read_requests": 0,
|
||||
"throttled_read_requests": 0,
|
||||
"failed_write_requests": 0,
|
||||
"throttled_write_requests": 0,
|
||||
"follower_checkpoint": 0,
|
||||
"leader_checkpoint": 0,
|
||||
"total_write_time_millis": 935
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Get auto-follow stats
|
||||
Introduced 1.1
|
||||
{: .label .label-purple }
|
||||
|
||||
Gets information about auto-follow activity and any replication rules configured on the specified cluster.
|
||||
|
||||
#### Request
|
||||
|
||||
```json
|
||||
GET /_plugins/_replication/autofollow_stats
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"num_success_start_replication": 2,
|
||||
"num_failed_start_replication": 0,
|
||||
"num_failed_leader_calls": 0,
|
||||
"failed_indices":[
|
||||
|
||||
],
|
||||
"autofollow_stats":[
|
||||
{
|
||||
"name":"my-replication-rule",
|
||||
"pattern":"movies*",
|
||||
"num_success_start_replication": 2,
|
||||
"num_failed_start_replication": 0,
|
||||
"num_failed_leader_calls": 0,
|
||||
"failed_indices":[
|
||||
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Update settings
|
||||
Introduced 1.1
|
||||
{: .label .label-purple }
|
||||
|
||||
Updates settings on the follower index.
|
||||
|
||||
#### Request
|
||||
|
||||
```json
|
||||
PUT /_plugins/_replication/<follower-index>/_update
|
||||
{
|
||||
"settings":{
|
||||
"index.number_of_shards": 4,
|
||||
"index.number_of_replicas": 2
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"acknowledged": true
|
||||
}
|
||||
```
|
||||
|
||||
## Create replication rule
|
||||
Introduced 1.1
|
||||
{: .label .label-purple }
|
||||
|
||||
Automatically starts replication on indices matching a specified pattern. If a new index on the leader cluster matches the pattern, OpenSearch automatically creates a follower index and begins replication. You can also use this API to update existing replication rules.
|
||||
|
||||
Send this request to the follower cluster.
|
||||
|
||||
Make sure to note the names of all auto-follow patterns after you create them. The replication plugin currently does not include an API operation to retrieve a list of existing patterns.
|
||||
{: .tip }
|
||||
|
||||
#### Request
|
||||
|
||||
```json
|
||||
POST /_plugins/_replication/_autofollow
|
||||
{
|
||||
"leader_alias" : "<connection-alias-name>",
|
||||
"name": "<auto-follow-pattern-name>",
|
||||
"pattern": "<pattern>",
|
||||
"use_roles":{
|
||||
"leader_cluster_role": "<role-name>",
|
||||
"follower_cluster_role": "<role-name>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Specify the following options:
|
||||
|
||||
Options | Description | Type | Required
|
||||
:--- | :--- |:--- |:--- |
|
||||
`leader_alias` | The name of the cross-cluster connection. You define this alias when you [set up a cross-cluster connection]({{site.url}}{{site.baseurl}}/replication-plugin/get-started/#set-up-a-cross-cluster-connection). | `string` | Yes
|
||||
`name` | A name for the auto-follow pattern. | `string` | Yes
|
||||
`pattern` | An array of index patterns to match against indices in the specified leader cluster. Supports wildcard characters. For example, `leader-*`. | `string` | Yes
|
||||
`use_roles` | The roles to use for all subsequent backend replication tasks between the indices. Specify a `leader_cluster_role` and `follower_cluster_role`. See [Map the leader and follower cluster roles]({{site.url}}{{site.baseurl}}/replication-plugin/permissions/#map-the-leader-and-follower-cluster-roles). | `string` | If security plugin is enabled
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"acknowledged": true
|
||||
}
|
||||
```
|
||||
|
||||
## Delete replication rule
|
||||
Introduced 1.1
|
||||
{: .label .label-purple }
|
||||
|
||||
Deletes the specified replication rule. This operation prevents any new indices from being replicated but does not stop existing replication that the rule has already initiated.
|
||||
|
||||
Send this request to the follower cluster.
|
||||
|
||||
#### Request
|
||||
|
||||
```json
|
||||
DELETE /_plugins/_replication/_autofollow
|
||||
{
|
||||
"leader_alias" : "<connection-alias-name>",
|
||||
"name": "<auto-follow-pattern-name>",
|
||||
}
|
||||
```
|
||||
|
||||
Specify the following options:
|
||||
|
||||
Options | Description | Type | Required
|
||||
:--- | :--- |:--- |:--- |
|
||||
`leader_alias` | The name of the cross-cluster connection. You define this alias when you [set up a cross-cluster connection]({{site.url}}{{site.baseurl}}/replication-plugin/get-started/#set-up-a-cross-cluster-connection). | `string` | Yes
|
||||
`name` | The name of the pattern. | `string` | Yes
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"acknowledged": true
|
||||
}
|
||||
```
|
||||
104
_replication-plugin/auto-follow.md
Normal file
104
_replication-plugin/auto-follow.md
Normal file
@ -0,0 +1,104 @@
|
||||
---
|
||||
layout: default
|
||||
title: Auto-follow
|
||||
nav_order: 20
|
||||
has_children: false
|
||||
|
||||
---
|
||||
|
||||
# Auto-follow for cross-cluster replication
|
||||
|
||||
Auto-follow lets you automatically replicate indices created on the leader cluster based on matching patterns. When you create an index on the leader cluster with a name that matches a specified pattern (for example, `index-01*`), a corresponding follower index is automatically created on the follower cluster.
|
||||
|
||||
You can configure multiple replication rules for a single cluster. The patterns currently only support wildcard matching.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
You need to [set up a cross-cluster connection]({{site.url}}{{site.baseurl}}/replication-plugin/get-started/#set-up-a-cross-cluster-connection) between two clusters before you can enable auto-follow.
|
||||
|
||||
## Permissions
|
||||
|
||||
If the security plugin is enabled, non-admin users need to be mapped to the appropriate permissions in order to perform replication actions. For index and cluster-level permissions requirements, see [Cross-cluster replication permissions]({{site.url}}{{site.baseurl}}/replication-plugin/permissions/).
|
||||
|
||||
## Get started with auto-follow
|
||||
|
||||
Replication rules are a collection of patterns that you create against a single remote cluster. When you create a replication rule, it automatically starts replicating any *new* indices that match the pattern, but does not replicate matching indices that were previously created.
|
||||
|
||||
Create a replication rule on the follower cluster:
|
||||
|
||||
```bash
|
||||
curl -XPOST -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/_autofollow?pretty' -d '
|
||||
{
|
||||
"leader_alias" : "my-connection-alias",
|
||||
"name": "my-replication-rule",
|
||||
"pattern": "movies*",
|
||||
"use_roles":{
|
||||
"leader_cluster_role": "all_access",
|
||||
"follower_cluster_role": "all_access"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
If the security plugin is disabled, you can leave out the `use_roles` parameter. If it's enabled, however, you need to specify the leader and follower cluster roles that OpenSearch uses to authenticate requests. This example uses `all_access` for simplicity, but we recommend creating a replication user on each cluster and [mapping it accordingly]({{site.url}}{{site.baseurl}}/replication-plugin/permissions/#map-the-leader-and-follower-cluster-roles).
|
||||
{: .tip }
|
||||
|
||||
To test the rule, create a matching index on the leader cluster:
|
||||
|
||||
```bash
|
||||
curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9201/movies-0001?pretty'
|
||||
```
|
||||
|
||||
And confirm its replica shows up on the follower cluster:
|
||||
|
||||
```bash
|
||||
curl -XGET -u 'admin:admin' -k 'https://localhost:9200/_cat/indices?v'
|
||||
```
|
||||
|
||||
It might take several seconds for the index to appear.
|
||||
|
||||
```bash
|
||||
health status index uuid pri rep docs.count docs.deleted store.size pri.store.size
|
||||
yellow open movies-0001 kHOxYYHxRMeszLjTD9rvSQ 1 1 0 0 208b 208b
|
||||
```
|
||||
|
||||
## Retrieve replication rules
|
||||
|
||||
To retrieve a list of existing replication rules configured on a cluster, send the following request:
|
||||
|
||||
```bash
|
||||
curl -XGET -u 'admin:admin' -k 'https://localhost:9200/_plugins/_replication/autofollow_stats'
|
||||
|
||||
{
|
||||
"num_success_start_replication": 1,
|
||||
"num_failed_start_replication": 0,
|
||||
"num_failed_leader_calls": 0,
|
||||
"failed_indices":[
|
||||
|
||||
],
|
||||
"autofollow_stats":[
|
||||
{
|
||||
"name":"my-replication-rule",
|
||||
"pattern":"movies*",
|
||||
"num_success_start_replication": 1,
|
||||
"num_failed_start_replication": 0,
|
||||
"num_failed_leader_calls": 0,
|
||||
"failed_indices":[
|
||||
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Delete a replication rule
|
||||
|
||||
When you delete a replication rule, OpenSearch stops replicating *new* indices that match the pattern, but existing indices that the rule previously created continue to replicate. If you need to stop existing replication activity, use the [stop replication API operation]({{site.url}}{{site.baseurl}}/replication-plugin/api/#stop-replication).
|
||||
|
||||
```bash
|
||||
curl -XDELETE -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/_autofollow?pretty' -d '
|
||||
{
|
||||
"leader_alias" : "my-conection-alias",
|
||||
"name": "my-replication-rule"
|
||||
}'
|
||||
```
|
||||
|
||||
273
_replication-plugin/get-started.md
Normal file
273
_replication-plugin/get-started.md
Normal file
@ -0,0 +1,273 @@
|
||||
---
|
||||
layout: default
|
||||
title: Get started
|
||||
nav_order: 10
|
||||
---
|
||||
|
||||
# Get started with cross-cluster replication
|
||||
|
||||
With cross-cluster replication, you index data to a leader index, and OpenSearch replicates that data to one or more read-only follower indices. All subsequent operations on the leader are replicated on the follower, such as creating, updating, or deleting documents.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Cross-cluster replication has the following prerequisites:
|
||||
- Both the leader and follower cluster must have the replication plugin installed.
|
||||
- If you've overridden `node.roles` in `opensearch.yml` on the remote cluster, make sure it also includes the `remote_cluster_client` role:
|
||||
|
||||
```yaml
|
||||
node.roles: [<other_roles>, remote_cluster_client]
|
||||
```
|
||||
|
||||
## Permissions
|
||||
|
||||
Make sure the security plugin is either enabled on both clusters or disabled on both clusters. If you disabled the security plugin, you can skip this section. However, we strongly recommend enabling the security plugin in production scenarios.
|
||||
|
||||
If the security plugin is enabled, non-admin users need to be mapped to the appropriate permissions in order to perform replication actions. For index and cluster-level permissions requirements, see [Cross-cluster replication permissions]({{site.url}}{{site.baseurl}}/replication-plugin/permissions/).
|
||||
|
||||
In addition, add the following setting to `opensearch.yml` on the leader cluster so it allows connections from the follower cluster:
|
||||
|
||||
```yml
|
||||
plugins.security.nodes_dn_dynamic_config_enabled: true
|
||||
```
|
||||
|
||||
## Example setup
|
||||
|
||||
Save this sample file as `docker-compose.yml` and run `docker-compose up` to start two single-node clusters on the same network:
|
||||
|
||||
```yml
|
||||
version: '3'
|
||||
services:
|
||||
replication-node1:
|
||||
image: opensearchproject/opensearch:{{site.opensearch_version}}
|
||||
container_name: replication-node1
|
||||
environment:
|
||||
- cluster.name=leader-cluster
|
||||
- discovery.type=single-node
|
||||
- bootstrap.memory_lock=true
|
||||
- "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m"
|
||||
ulimits:
|
||||
memlock:
|
||||
soft: -1
|
||||
hard: -1
|
||||
volumes:
|
||||
- opensearch-data2:/usr/share/opensearch/data
|
||||
ports:
|
||||
- 9201:9200
|
||||
- 9700:9600 # required for Performance Analyzer
|
||||
networks:
|
||||
- opensearch-net
|
||||
replication-node2:
|
||||
image: opensearchproject/opensearch:{{site.opensearch_version}}
|
||||
container_name: replication-node2
|
||||
environment:
|
||||
- cluster.name=follower-cluster
|
||||
- discovery.type=single-node
|
||||
- bootstrap.memory_lock=true
|
||||
- "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m"
|
||||
ulimits:
|
||||
memlock:
|
||||
soft: -1
|
||||
hard: -1
|
||||
volumes:
|
||||
- opensearch-data1:/usr/share/opensearch/data
|
||||
ports:
|
||||
- 9200:9200
|
||||
- 9600:9600 # required for Performance Analyzer
|
||||
networks:
|
||||
- opensearch-net
|
||||
|
||||
volumes:
|
||||
opensearch-data1:
|
||||
opensearch-data2:
|
||||
|
||||
networks:
|
||||
opensearch-net:
|
||||
```
|
||||
|
||||
After the clusters start, verify the names of each:
|
||||
|
||||
```bash
|
||||
curl -XGET -u 'admin:admin' -k 'https://localhost:9201'
|
||||
{
|
||||
"cluster_name" : "leader-cluster",
|
||||
...
|
||||
}
|
||||
|
||||
curl -XGET -u 'admin:admin' -k 'https://localhost:9200'
|
||||
{
|
||||
"cluster_name" : "follower-cluster",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
For this example, use port 9201 (`replication-node1`) as the leader and port 9200 (`replication-node2`) as the follower cluster.
|
||||
|
||||
To get the IP address for the leader cluster, first identify its container ID:
|
||||
|
||||
```bash
|
||||
docker ps
|
||||
CONTAINER ID IMAGE PORTS NAMES
|
||||
3b8cdc698be5 opensearchproject/opensearch:{{site.opensearch_version}} 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp, 9300/tcp replication-node2
|
||||
731f5e8b0f4b opensearchproject/opensearch:{{site.opensearch_version}} 9300/tcp, 0.0.0.0:9201->9200/tcp, 0.0.0.0:9700->9600/tcp replication-node1
|
||||
```
|
||||
|
||||
Then get that container's IP address:
|
||||
|
||||
```bash
|
||||
docker inspect --format='{% raw %}{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}{% endraw %}' 731f5e8b0f4b
|
||||
172.22.0.3
|
||||
```
|
||||
|
||||
## Set up a cross-cluster connection
|
||||
|
||||
Cross-cluster replication follows a "pull" model, so most changes occur on the follower cluster, not the leader cluster.
|
||||
|
||||
On the follower cluster, add the IP address (with port 9300) for each seed node. Because this is a single-node cluster, you only have one seed node. Provide a descriptive name for the connection, which you'll use in the request to start replication:
|
||||
|
||||
```bash
|
||||
curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9200/_cluster/settings?pretty' -d '
|
||||
{
|
||||
"persistent": {
|
||||
"cluster": {
|
||||
"remote": {
|
||||
"my-connection-alias": {
|
||||
"seeds": ["172.22.0.3:9300"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
## Start replication
|
||||
|
||||
To get started, create an index called `leader-01` on the leader cluster:
|
||||
|
||||
```bash
|
||||
curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9201/leader-01?pretty'
|
||||
```
|
||||
|
||||
Then start replication from the follower cluster. In the request body, provide the connection name and leader index that you want to replicate, along with the security roles you want to use:
|
||||
|
||||
```bash
|
||||
curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/follower-01/_start?pretty' -d '
|
||||
{
|
||||
"leader_alias": "my-connection-alias",
|
||||
"leader_index": "leader-01",
|
||||
"use_roles":{
|
||||
"leader_cluster_role": "all_access",
|
||||
"follower_cluster_role": "all_access"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
If the security plugin is disabled, omit the `use_roles` parameter. If it's enabled, however, you must specify the leader and follower cluster roles that OpenSearch will use to authenticate the request. This example uses `all_access` for simplicity, but we recommend creating a replication user on each cluster and [mapping it accordingly]({{site.url}}{{site.baseurl}}/replication-plugin/permissions/#map-the-leader-and-follower-cluster-roles).
|
||||
{: .tip }
|
||||
|
||||
This command creates an identical read-only index named `follower-01` on the local cluster that continuously stays updated with changes to the `leader-01` index on the remote cluster. Starting replication creates a follower index from scratch; you can't convert an existing index to a follower index.
|
||||
|
||||
## Confirm replication
|
||||
|
||||
After replication starts, get the status:
|
||||
|
||||
```bash
|
||||
curl -XGET -k -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/follower-01/_status?pretty'
|
||||
|
||||
{
|
||||
"status" : "SYNCING",
|
||||
"reason" : "User initiated",
|
||||
"leader_alias" : "my-connection-alias",
|
||||
"leader_index" : "leader-01",
|
||||
"follower_index" : "follower-01",
|
||||
"syncing_details" : {
|
||||
"leader_checkpoint" : -1,
|
||||
"follower_checkpoint" : -1,
|
||||
"seq_no" : 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Possible statuses are `SYNCING`, `BOOTSTRAPING`, `PAUSED`, and `REPLICATION NOT IN PROGRESS`.
|
||||
|
||||
The leader and follower checkpoint values begin as negative numbers and reflect the shard count (-1 for one shard, -5 for five shards, and so on). The values increment with each change and illustrate how many updates the follower is behind the leader. If the indices are fully synced, the values are the same.
|
||||
|
||||
To confirm that replication is actually happening, add a document to the leader index:
|
||||
|
||||
```bash
|
||||
curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9201/leader-01/_doc/1?pretty' -d '{"The Shining": "Stephen King"}'
|
||||
```
|
||||
|
||||
Then validate the replicated content on the follower index:
|
||||
|
||||
```bash
|
||||
curl -XGET -k -u 'admin:admin' 'https://localhost:9200/follower-01/_search?pretty'
|
||||
|
||||
{
|
||||
...
|
||||
"hits": [{
|
||||
"_index": "follower-01",
|
||||
"_type": "_doc",
|
||||
"_id": "1",
|
||||
"_score": 1.0,
|
||||
"_source": {
|
||||
"The Shining": "Stephen King"
|
||||
}
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
## Pause and resume replication
|
||||
|
||||
You can temporarily pause replication of an index if you need to remediate issues or reduce load on the leader cluster:
|
||||
|
||||
```bash
|
||||
curl -XPOST -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/follower-01/_pause?pretty' -d '{}'
|
||||
```
|
||||
|
||||
To confirm replication is paused, get the status:
|
||||
|
||||
```bash
|
||||
curl -XGET -k -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/follower-01/_status?pretty'
|
||||
|
||||
{
|
||||
"status" : "PAUSED",
|
||||
"reason" : "User initiated",
|
||||
"leader_alias" : "my-connection-alias",
|
||||
"leader_index" : "leader-01",
|
||||
"follower_index" : "follower-01"
|
||||
}
|
||||
```
|
||||
|
||||
When you're done making changes, resume replication:
|
||||
|
||||
```bash
|
||||
curl -XPOST -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/follower-01/_resume?pretty' -d '{}'
|
||||
```
|
||||
|
||||
When replication resumes, the follower index picks up any changes that were made to the leader index while replication was paused.
|
||||
|
||||
Note that you can't resume replication after it's been paused for more than 12 hours. You must [stop replication]({{site.url}}{{site.baseurl}}/replication-plugin/api/#stop-replication), delete the follower index, and restart replication of the leader.
|
||||
|
||||
## Stop replication
|
||||
|
||||
Terminate replication of a specified index from the follower cluster:
|
||||
|
||||
```bash
|
||||
curl -XPOST -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/follower-01/_stop?pretty' -d '{}'
|
||||
```
|
||||
|
||||
When you stop replication, the follower index un-follows the leader and becomes a standard index that you can write to. You can't restart replication after stopping it.
|
||||
|
||||
Get the status to confirm that the index is no longer being replicated:
|
||||
|
||||
```bash
|
||||
curl -XGET -k -u 'admin:admin' 'https://localhost:9200/_plugins/_replication/follower-01/_status?pretty'
|
||||
|
||||
{
|
||||
"status" : "REPLICATION NOT IN PROGRESS"
|
||||
}
|
||||
```
|
||||
|
||||
You can further confirm that replication is stopped by making modifications to the leader index and confirming they don't show up on the follower index.
|
||||
|
||||
|
||||
22
_replication-plugin/index.md
Normal file
22
_replication-plugin/index.md
Normal file
@ -0,0 +1,22 @@
|
||||
---
|
||||
layout: default
|
||||
title: Cross-cluster replication
|
||||
nav_order: 1
|
||||
has_children: false
|
||||
|
||||
---
|
||||
|
||||
# Cross-cluster replication
|
||||
|
||||
The cross-cluster replication plugin lets you replicate indices, mappings, and metadata from one OpenSearch cluster to another. Cross-cluster replication has the following benefits:
|
||||
- By replicating your indices, you ensure that you can continue to handle search requests in the event of an outage.
|
||||
- Replicating data across geographically distant data centers minimizes the distance between the data and the application server, reducing expensive latencies.
|
||||
- You can replicate data from multiple smaller clusters to a centralized reporting cluster, which is useful when it's inefficient to query across a large network.
|
||||
|
||||
Replication follows an active-passive model where the follower index (where the data is replicated) pulls data from the leader (remote) index.
|
||||
|
||||
The replication plugin supports replication of indices using wildcard pattern matching and provides commands to pause, resume, and stop replication. Once replication starts on an index, it initiates persistent background tasks on all primary shards on the follower cluster, which continuously poll corresponding shards from the leader cluster for updates.
|
||||
|
||||
You can use the replication plugin with the security plugin to encrypt cross-cluster traffic with node-to-node encryption and control access to replication activities.
|
||||
|
||||
To start, see [Get started with cross-cluster replication]({{site.url}}{{site.baseurl}}/replication-plugin/get-started/).
|
||||
78
_replication-plugin/permissions.md
Normal file
78
_replication-plugin/permissions.md
Normal file
@ -0,0 +1,78 @@
|
||||
---
|
||||
layout: default
|
||||
title: Permissions
|
||||
nav_order: 30
|
||||
---
|
||||
|
||||
# Cross-cluster replication permissions
|
||||
|
||||
You can use the [security plugin]({{site.url}}{{site.baseurl}}/security-plugin/index/) with cross-cluster replication to limit users to certain actions. For example, you might want certain users to only perform replication activity on the leader or follower cluster.
|
||||
|
||||
Because cross-cluster replication involves multiple clusters, it's possible that clusters might have different security configurations. The following configurations are supported:
|
||||
|
||||
- Security plugin fully enabled on both clusters
|
||||
- Security plugin enabled only for TLS on both clusters (`plugins.security.ssl_only`)
|
||||
- Security plugin absent or disabled on both clusters (not recommended)
|
||||
|
||||
Enable node-to-node encryption on both the leader and the follower cluster to ensure that replication traffic between the clusters is encrypted.
|
||||
|
||||
## Basic permissions
|
||||
|
||||
In order for non-admin users to perform replication activities, they must be mapped to the appropriate permissions.
|
||||
|
||||
The security plugin has two built-in roles that cover most replication use cases: `cross_cluster_replication_leader_full_access`, which provides replication permissions on the leader cluster, and `cross_cluster_replication_follower_full_access`, which provides replication permissions on the follower cluster. For descriptions of each, see [Predefined roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles#predefined-roles).
|
||||
|
||||
If you don't want to use the default roles, you can combine individual replication [permissions]({{site.url}}{{site.baseurl}}/replication-plugin/permissions/#replication-permissions) to meet your needs. Most permissions correspond to specific REST API operations. For example, the `indices:admin/plugins/replication/index/pause` permission lets you pause replication.
|
||||
|
||||
## Map the leader and follower cluster roles
|
||||
|
||||
The [start replication]({{site.url}}{{site.baseurl}}/replication-plugin/api/#start-replication) and [create replication rule]({{site.url}}{{site.baseurl}}/replication-plugin/api/#create-replication-rule) operations are special cases. They involve background processes on the leader and follower clusters that must be associated with roles. When you perform one of these actions, you must explicitly pass the `leader_cluster_role` and
|
||||
`follower_cluster_role` in the request, which OpenSearch then uses in all backend replication tasks.
|
||||
|
||||
To enable non-admins to start replication and create replication rules, create an identical user on each cluster (for example, `replication_user`) and map them to the `cross_cluster_replication_leader_full_access` role on the remote cluster and `cross_cluster_replication_follower_full_access` on the follower cluster. For instructions, see [Map users to roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles/#map-users-to-roles).
|
||||
|
||||
Then add those roles to the request, and sign it with the appropriate credentials:
|
||||
|
||||
```bash
|
||||
curl -XPUT -k -H 'Content-Type: application/json' -u 'replication_user:password' 'https://localhost:9200/_plugins/_replication/follower-01/_start?pretty' -d '
|
||||
{
|
||||
"leader_alias": "leader-cluster",
|
||||
"leader_index": "leader-01",
|
||||
"use_roles":{
|
||||
"leader_cluster_role": "cross_cluster_replication_leader_full_access",
|
||||
"follower_cluster_role": "cross_cluster_replication_follower_full_access"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
You can create your own, custom leader and follower cluster roles using individual permissions, but we recommend using the default roles, which are a good fit for most use cases.
|
||||
|
||||
## Replication permissions
|
||||
|
||||
The following sections list the available index and cluster-level permissions for cross-cluster replication.
|
||||
|
||||
### Follower cluster
|
||||
|
||||
The security plugin supports these permissions for the follower cluster:
|
||||
|
||||
```
|
||||
indices:admin/plugins/replication/index/setup/validate
|
||||
indices:admin/plugins/replication/index/start
|
||||
indices:admin/plugins/replication/index/pause
|
||||
indices:admin/plugins/replication/index/resume
|
||||
indices:admin/plugins/replication/index/stop
|
||||
indices:admin/plugins/replication/index/update
|
||||
indices:admin/plugins/replication/index/status_check
|
||||
indices:data/write/plugins/replication/changes
|
||||
cluster:admin/plugins/replication/autofollow/update
|
||||
```
|
||||
|
||||
### Leader cluster
|
||||
|
||||
The security plugin supports these permissions for the leader cluster:
|
||||
|
||||
```
|
||||
indices:admin/plugins/replication/validate
|
||||
indices:data/read/plugins/replication/file_chunk
|
||||
indices:data/read/plugins/replication/changes
|
||||
```
|
||||
34
_replication-plugin/settings.md
Normal file
34
_replication-plugin/settings.md
Normal file
@ -0,0 +1,34 @@
|
||||
---
|
||||
layout: default
|
||||
title: Settings
|
||||
nav_order: 40
|
||||
---
|
||||
|
||||
# Replication settings
|
||||
|
||||
The replication plugin adds several settings to the standard OpenSearch cluster settings.
|
||||
The settings are dynamic, so you can change the default behavior of the plugin without restarting your cluster.
|
||||
You can mark settings as `persistent` or `transient`.
|
||||
|
||||
For example, to update how often the follower cluster polls the leader cluster for updates:
|
||||
|
||||
```json
|
||||
PUT _cluster/settings
|
||||
{
|
||||
"persistent": {
|
||||
"plugins.replication.follower.metadata_sync_interval": "30s"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
These settings manage the resources consumed by remote recoveries. We don’t recommend changing these settings; the defaults should work well for most use cases.
|
||||
|
||||
Setting | Default | Description
|
||||
:--- | :--- | :---
|
||||
`plugins.replication.follower.index.recovery.chunk_size` | 10MB | The chunk size requested by the follower cluster during file transfer. Specify the chunk size as a value and unit, for example, 10MB, 5KB. See [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
`plugins.replication.follower.index.recovery.max_concurrent_file_chunks` | 4 | The number of file chunk requests that can be sent in parallel for each recovery.
|
||||
`plugins.replication.follower.index.ops_batch_size` | 5000 | The number of operations that can be fetched at a time during the syncing phase of replication.
|
||||
`plugins.replication.follower.concurrent_readers_per_shard` | 2 | The number of concurrent requests from the follower cluster per shard during the syncing phase of replication.
|
||||
`plugins.replication.autofollow.fetch_poll_interval` | 30s | How often auto-follow tasks poll the leader cluster for new matching indices.
|
||||
`plugins.replication.follower.metadata_sync_interval` | 60s | How often the follower cluster polls the leader cluster for updated index metadata.
|
||||
|
||||
@ -130,6 +130,7 @@ These permissions are for the cluster and can't be applied granularly. For examp
|
||||
- cluster:admin/opendistro/reports/instance/list
|
||||
- cluster:admin/opendistro/reports/instance/get
|
||||
- cluster:admin/opendistro/reports/menu/download
|
||||
- cluster:admin/plugins/replication/autofollow/update
|
||||
- cluster:admin/reindex/rethrottle
|
||||
- cluster:admin/repository/delete
|
||||
- cluster:admin/repository/get
|
||||
@ -196,6 +197,13 @@ These permissions apply to an index or index pattern. You might want a user to h
|
||||
- indices:admin/mappings/fields/get*
|
||||
- indices:admin/mappings/get
|
||||
- indices:admin/open
|
||||
- indices:admin/plugins/replication/index/setup/validate
|
||||
- indices:admin/plugins/replication/index/start
|
||||
- indices:admin/plugins/replication/index/pause
|
||||
- indices:admin/plugins/replication/index/resume
|
||||
- indices:admin/plugins/replication/index/stop
|
||||
- indices:admin/plugins/replication/index/update
|
||||
- indices:admin/plugins/replication/index/status_check
|
||||
- indices:admin/refresh
|
||||
- indices:admin/refresh*
|
||||
- indices:admin/resolve/index
|
||||
@ -221,6 +229,8 @@ These permissions apply to an index or index pattern. You might want a user to h
|
||||
- indices:data/read/msearch/template
|
||||
- indices:data/read/mtv (multi-term vectors)
|
||||
- indices:data/read/mtv*
|
||||
- indices:data/read/plugins/replication/file_chunk
|
||||
- indices:data/read/plugins/replication/changes
|
||||
- indices:data/read/scroll
|
||||
- indices:data/read/scroll/clear
|
||||
- indices:data/read/search
|
||||
@ -231,6 +241,7 @@ These permissions apply to an index or index pattern. You might want a user to h
|
||||
- indices:data/write/bulk*
|
||||
- indices:data/write/delete (delete documents)
|
||||
- indices:data/write/delete/byquery
|
||||
- indices:data/write/plugins/replication/changes
|
||||
- indices:data/write/index (add documents to existing indices)
|
||||
- indices:data/write/reindex
|
||||
- indices:data/write/update
|
||||
|
||||
@ -109,6 +109,8 @@ Role | Description
|
||||
`anomaly_full_access` | Grants full permissions to all anomaly detection actions.
|
||||
`anomaly_read_access` | Grants permissions to view detectors, but not create, modify, or delete detectors.
|
||||
`all_access` | Grants full access to the cluster: all cluster-wide operations, write to all indices, write to all tenants.
|
||||
`cross_cluster_replication_follower_full_access` | Grants full access to perform cross-cluster replication actions on the follower cluster.
|
||||
`cross_cluster_replication_leader_full_access` | Grants full access to perform cross-cluster replication actions on the leader cluster.
|
||||
`kibana_read_only` | A special role that prevents users from making changes to visualizations, dashboards, and other OpenSearch Dashboards objects. See `opensearch_security.readonly_mode.roles` in `opensearch_dashboards.yml`. Pair with the `kibana_user` role.
|
||||
`kibana_user` | Grants permissions to use OpenSearch Dashboards: cluster-wide searches, index monitoring, and write to various OpenSearch Dashboards indices.
|
||||
`logstash` | Grants permissions for Logstash to interact with the cluster: cluster-wide searches, cluster monitoring, and write to the various Logstash indices.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user