Compare commits
3 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 aetter
|
c91b99037b | ||
|
aetter
|
25c4b70046 | ||
|
aetter
|
d4342aab59 |
@@ -196,17 +196,17 @@ If you're making major changes to the documentation and need to see the rendered
|
||||
## New releases
|
||||
|
||||
1. Branch.
|
||||
1. Change the `opensearch_version` and `opensearch_major_minor_version` variables in `_config.yml`.
|
||||
1. Change the `opensearch_version`, `opensearch_major_minor_version`, and `lucene_version` variables in `_config.yml`.
|
||||
1. Start up a new cluster using the updated Docker Compose file in `docs/install/docker.md`.
|
||||
1. Update the version table in `version-history.md`.
|
||||
|
||||
Use `curl -XGET https://localhost:9200 -u admin:admin -k` to verify the OpenSearch version.
|
||||
Use `curl -XGET https://localhost:9200 -u admin:admin -k` to verify the OpenSearch and Lucene versions.
|
||||
|
||||
1. Update the plugin compatibility table in `docs/install/plugin.md`.
|
||||
1. Update the plugin compatibility table in `_opensearch/install/plugin.md`.
|
||||
|
||||
Use `curl -XGET https://localhost:9200/_cat/plugins -u admin:admin -k` to get the correct version strings.
|
||||
|
||||
1. Update the plugin compatibility table in `docs/opensearch-dashboards/plugins.md`.
|
||||
1. Update the plugin compatibility table in `_dashboards/install/plugins.md`.
|
||||
|
||||
Use `docker ps` to find the ID for the OpenSearch Dashboards node. Then use `docker exec -it <opensearch-dashboards-node-id> /bin/bash` to get shell access. Finally, run `./bin/opensearch-dashboards-plugin list` to get the plugins and version strings.
|
||||
|
||||
|
||||
-145
@@ -1,145 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Go client
|
||||
nav_order: 80
|
||||
---
|
||||
|
||||
# Go client
|
||||
|
||||
The OpenSearch Go client lets you connect your Go application with the data in your OpenSearch cluster.
|
||||
|
||||
|
||||
## Setup
|
||||
|
||||
If you're creating a new project:
|
||||
|
||||
```go
|
||||
go mod init
|
||||
```
|
||||
|
||||
To add the client to your project, import it like any other module:
|
||||
|
||||
```go
|
||||
go get github.com/opensearch-project/opensearch-go
|
||||
```
|
||||
|
||||
## Sample code
|
||||
|
||||
This sample code creates a client, adds an index with non-default settings, inserts a document, searches for the document, deletes the document, and finally deletes the index:
|
||||
|
||||
```go
|
||||
package main
|
||||
import (
|
||||
"os"
|
||||
"context"
|
||||
"crypto/tls"
|
||||
"fmt"
|
||||
opensearch "github.com/opensearch-project/opensearch-go"
|
||||
opensearchapi "github.com/opensearch-project/opensearch-go/opensearchapi"
|
||||
"net/http"
|
||||
"strings"
|
||||
)
|
||||
const IndexName = "go-test-index1"
|
||||
func main() {
|
||||
// Initialize the client with SSL/TLS enabled.
|
||||
client, err := opensearch.NewClient(opensearch.Config{
|
||||
Transport: &http.Transport{
|
||||
TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
|
||||
},
|
||||
Addresses: []string{"https://localhost:9200"},
|
||||
Username: "admin", // For testing only. Don't store credentials in code.
|
||||
Password: "admin",
|
||||
})
|
||||
if err != nil {
|
||||
fmt.Println("cannot initialize", err)
|
||||
os.Exit(1)
|
||||
}
|
||||
|
||||
// Print OpenSearch version information on console.
|
||||
fmt.Println(client.Info())
|
||||
|
||||
// Define index mapping.
|
||||
mapping := strings.NewReader(`{
|
||||
'settings': {
|
||||
'index': {
|
||||
'number_of_shards': 4
|
||||
}
|
||||
}
|
||||
}`)
|
||||
|
||||
// Create an index with non-default settings.
|
||||
res := opensearchapi.CreateRequest{
|
||||
Index: IndexName,
|
||||
Body: mapping,
|
||||
}
|
||||
fmt.Println("creating index", res)
|
||||
|
||||
// Add a document to the index.
|
||||
document := strings.NewReader(`{
|
||||
"title": "Moneyball",
|
||||
"director": "Bennett Miller",
|
||||
"year": "2011"
|
||||
}`)
|
||||
|
||||
docId := "1"
|
||||
req := opensearchapi.IndexRequest{
|
||||
Index: IndexName,
|
||||
DocumentID: docId,
|
||||
Body: document,
|
||||
}
|
||||
insertResponse, err := req.Do(context.Background(), client)
|
||||
if err != nil {
|
||||
fmt.Println("failed to insert document ", err)
|
||||
os.Exit(1)
|
||||
}
|
||||
fmt.Println(insertResponse)
|
||||
|
||||
// Search for the document.
|
||||
content := strings.NewReader(`{
|
||||
"size": 5,
|
||||
"query": {
|
||||
"multi_match": {
|
||||
"query": "miller",
|
||||
"fields": ["title^2", "director"]
|
||||
}
|
||||
}
|
||||
}`)
|
||||
|
||||
search := opensearchapi.SearchRequest{
|
||||
Body: content,
|
||||
}
|
||||
|
||||
searchResponse, err := search.Do(context.Background(), client)
|
||||
if err != nil {
|
||||
fmt.Println("failed to search document ", err)
|
||||
os.Exit(1)
|
||||
}
|
||||
fmt.Println(searchResponse)
|
||||
|
||||
// Delete the document.
|
||||
delete := opensearchapi.DeleteRequest{
|
||||
Index: IndexName,
|
||||
DocumentID: docId,
|
||||
}
|
||||
|
||||
deleteResponse, err := delete.Do(context.Background(), client)
|
||||
if err != nil {
|
||||
fmt.Println("failed to delete document ", err)
|
||||
os.Exit(1)
|
||||
}
|
||||
fmt.Println("deleting document")
|
||||
fmt.Println(deleteResponse)
|
||||
|
||||
// Delete previously created index.
|
||||
deleteIndex := opensearchapi.IndicesDeleteRequest{
|
||||
Index: []string{IndexName},
|
||||
}
|
||||
|
||||
deleteIndexResponse, err := deleteIndex.Do(context.Background(), client)
|
||||
if err != nil {
|
||||
fmt.Println("failed to delete index ", err)
|
||||
os.Exit(1)
|
||||
}
|
||||
fmt.Println("deleting index", deleteIndexResponse)
|
||||
}
|
||||
```
|
||||
+1
-15
@@ -9,20 +9,6 @@ redirect_from:
|
||||
|
||||
# OpenSearch client compatibility
|
||||
|
||||
OpenSearch provides clients for several popular programming languages, with more coming. In general, clients are compatible with clusters running the same major version of OpenSearch (`major.minor.patch`).
|
||||
|
||||
For example, a 1.0.0 client works with an OpenSearch 1.1.0 cluster, but might not support any non-breaking API changes in OpenSearch 1.1.0. A 1.2.0 client works with the same cluster, but might allow you to pass unsupported options in certain functions. We recommend using the same version for both, but if your tests pass after a cluster upgrade, you don't necessarily need to upgrade your clients immediately.
|
||||
|
||||
{% comment %}
|
||||
* [OpenSearch Java client]({{site.url}}{{site.baseurl}}/clients/java/)
|
||||
{% endcomment %}
|
||||
* [OpenSearch Python client]({{site.url}}{{site.baseurl}}/clients/python/)
|
||||
* [OpenSearch JavaScript (Node.js) client]({{site.url}}{{site.baseurl}}/clients/javascript/)
|
||||
* [OpenSearch Go client]({{site.url}}{{site.baseurl}}/clients/go/)
|
||||
|
||||
|
||||
## Legacy clients
|
||||
|
||||
Most clients that work with Elasticsearch OSS 7.10.2 *should* work with OpenSearch, but the latest versions of those clients might include license or version checks that artificially break compatibility. This page includes recommendations around which versions of those clients to use for best compatibility with OpenSearch.
|
||||
|
||||
Client | Recommended version
|
||||
@@ -32,7 +18,7 @@ Client | Recommended version
|
||||
[Python Elasticsearch client](https://pypi.org/project/elasticsearch/7.13.4/) | 7.13.4
|
||||
[Elasticsearch Node.js client](https://www.npmjs.com/package/@elastic/elasticsearch/v/7.13.0) | 7.13.0
|
||||
|
||||
If you test a legacy client and verify that it works, please [submit a PR](https://github.com/opensearch-project/documentation-website/pulls) and add it to this table.
|
||||
Clients exist for a wide variety of languages, so if you test a client and verify that it works, please [submit a PR](https://github.com/opensearch-project/documentation-website/pulls) and add it to this table.
|
||||
|
||||
|
||||
{% comment %}
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
---
|
||||
layout: default
|
||||
title: Elasticsearch OSS Java high-level REST client
|
||||
nav_order: 60
|
||||
title: Java high-level REST client
|
||||
nav_order: 97
|
||||
---
|
||||
|
||||
# Elasticsearch OSS Java high-level REST client
|
||||
# Java high-level REST client
|
||||
|
||||
The Elasticsearch OSS Java high-level REST client allows you to interact with your OpenSearch clusters and indices through Java methods and data structures rather than HTTP methods and JSON.
|
||||
|
||||
@@ -22,7 +22,7 @@ To start using the Elasticsearch OSS Java high-level REST client, ensure that yo
|
||||
</dependency>
|
||||
```
|
||||
|
||||
You can now start your OpenSearch cluster. The 7.10.2 Elasticsearch OSS high-level REST client works with the 1.x versions of OpenSearch.
|
||||
You can now start your OpenSearch cluster. The 7.10.2 high-level REST client works with the 1.x versions of OpenSearch.
|
||||
|
||||
## Sample code
|
||||
|
||||
|
||||
@@ -1,141 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: JavaScript client
|
||||
nav_order: 90
|
||||
---
|
||||
|
||||
# JavaScript client
|
||||
|
||||
The OpenSearch JavaScript client provides a safer and easier way to interact with your OpenSearch cluster. Rather than using OpenSearch from the browser and potentially exposing your data to the public, you can build an OpenSearch client that takes care of sending requests to your cluster.
|
||||
|
||||
The client contains a library of APIs that let you perform different operations on your cluster and return a standard response body. The example here demonstrates some basic operations like creating an index, adding documents, and searching your data.
|
||||
|
||||
## Setup
|
||||
|
||||
To add the client to your project, install it from [npm](https://www.npmjs.com):
|
||||
|
||||
```bash
|
||||
npm install @opensearch-project/opensearch
|
||||
```
|
||||
|
||||
To install a specific major version of the client, run the following command:
|
||||
|
||||
```bash
|
||||
npm install @opensearch-project/opensearch@<version>
|
||||
```
|
||||
|
||||
If you prefer to add the client manually or just want to examine the source code, see [opensearch-js](https://github.com/opensearch-project/opensearch-js) on GitHub.
|
||||
|
||||
Then require the client:
|
||||
|
||||
```javascript
|
||||
const { Client } = require("@opensearch-project/opensearch");
|
||||
```
|
||||
|
||||
## Sample code
|
||||
|
||||
```javascript
|
||||
"use strict";
|
||||
|
||||
var host = "localhost";
|
||||
var protocol = "https";
|
||||
var port = 9200;
|
||||
var auth = "admin:admin"; // For testing only. Don't store credentials in code.
|
||||
var ca_certs_path = "/full/path/to/root-ca.pem";
|
||||
|
||||
// Optional client certificates if you don't want to use HTTP basic authentication.
|
||||
// var client_cert_path = '/full/path/to/client.pem'
|
||||
// var client_key_path = '/full/path/to/client-key.pem'
|
||||
|
||||
// Create a client with SSL/TLS enabled.
|
||||
var { Client } = require("@opensearch-project/opensearch");
|
||||
var fs = require("fs");
|
||||
var client = new Client({
|
||||
node: protocol + "://" + auth + "@" + host + ":" + port,
|
||||
ssl: {
|
||||
ca: fs.readFileSync(ca_certs_path),
|
||||
// You can turn off certificate verification (rejectUnauthorized: false) if you're using self-signed certificates with a hostname mismatch.
|
||||
// cert: fs.readFileSync(client_cert_path),
|
||||
// key: fs.readFileSync(client_key_path)
|
||||
},
|
||||
});
|
||||
|
||||
async function search() {
|
||||
// Create an index with non-default settings.
|
||||
var index_name = "books";
|
||||
var settings = {
|
||||
settings: {
|
||||
index: {
|
||||
number_of_shards: 4,
|
||||
number_of_replicas: 3,
|
||||
},
|
||||
},
|
||||
};
|
||||
|
||||
var response = await client.indices.create({
|
||||
index: index_name,
|
||||
body: settings,
|
||||
});
|
||||
|
||||
console.log("Creating index:");
|
||||
console.log(response.body);
|
||||
|
||||
// Add a document to the index.
|
||||
var document = {
|
||||
title: "The Outsider",
|
||||
author: "Stephen King",
|
||||
year: "2018",
|
||||
genre: "Crime fiction",
|
||||
};
|
||||
|
||||
var id = "1";
|
||||
|
||||
var response = await client.index({
|
||||
id: id,
|
||||
index: index_name,
|
||||
body: document,
|
||||
refresh: true,
|
||||
});
|
||||
|
||||
console.log("Adding document:");
|
||||
console.log(response.body);
|
||||
|
||||
// Search for the document.
|
||||
var query = {
|
||||
query: {
|
||||
match: {
|
||||
title: {
|
||||
query: "The Outsider",
|
||||
},
|
||||
},
|
||||
},
|
||||
};
|
||||
|
||||
var response = await client.search({
|
||||
index: index_name,
|
||||
body: query,
|
||||
});
|
||||
|
||||
console.log("Search results:");
|
||||
console.log(response.body.hits);
|
||||
|
||||
// Delete the document.
|
||||
var response = await client.delete({
|
||||
index: index_name,
|
||||
id: id,
|
||||
});
|
||||
|
||||
console.log("Deleting document:");
|
||||
console.log(response.body);
|
||||
|
||||
// Delete the index.
|
||||
var response = await client.indices.delete({
|
||||
index: index_name,
|
||||
});
|
||||
|
||||
console.log("Deleting index:");
|
||||
console.log(response.body);
|
||||
}
|
||||
|
||||
search().catch(console.log);
|
||||
```
|
||||
@@ -1,128 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Python client
|
||||
nav_order: 70
|
||||
---
|
||||
|
||||
# Python client
|
||||
|
||||
The OpenSearch Python client provides a more natural syntax for interacting with your cluster. Rather than sending HTTP requests to a given URL, you can create an OpenSearch client for your cluster and call the client's built-in functions.
|
||||
|
||||
{% comment %}
|
||||
`opensearch-py` is the lower-level of the two Python clients. If you want a general client for assorted operations, it's a great choice. If you want a higher-level client strictly for indexing and search operations, consider [opensearch-dsl-py]({{site.url}}{{site.baseurl}}/clients/python-dsl/).
|
||||
{% endcomment %}
|
||||
|
||||
|
||||
## Setup
|
||||
|
||||
To add the client to your project, install it using [pip](https://pip.pypa.io/):
|
||||
|
||||
```bash
|
||||
pip install opensearch-py
|
||||
```
|
||||
|
||||
Then import it like any other module:
|
||||
|
||||
```python
|
||||
from opensearchpy import OpenSearch
|
||||
```
|
||||
|
||||
If you prefer to add the client manually or just want to examine the source code, see [opensearch-py on GitHub](https://github.com/opensearch-project/opensearch-py).
|
||||
|
||||
|
||||
## Sample code
|
||||
|
||||
```python
|
||||
from opensearchpy import OpenSearch
|
||||
|
||||
host = 'localhost'
|
||||
port = 9200
|
||||
auth = ('admin', 'admin') # For testing only. Don't store credentials in code.
|
||||
ca_certs_path = '/full/path/to/root-ca.pem' # Provide a CA bundle if you use intermediate CAs with your root CA.
|
||||
|
||||
# Optional client certificates if you don't want to use HTTP basic authentication.
|
||||
# client_cert_path = '/full/path/to/client.pem'
|
||||
# client_key_path = '/full/path/to/client-key.pem'
|
||||
|
||||
# Create the client with SSL/TLS enabled, but hostname verification disabled.
|
||||
client = OpenSearch(
|
||||
hosts = [{'host': host, 'port': port}],
|
||||
http_compress = True, # enables gzip compression for request bodies
|
||||
http_auth = auth,
|
||||
# client_cert = client_cert_path,
|
||||
# client_key = client_key_path,
|
||||
use_ssl = True,
|
||||
verify_certs = True,
|
||||
ssl_assert_hostname = False,
|
||||
ssl_show_warn = False,
|
||||
ca_certs = ca_certs_path
|
||||
)
|
||||
|
||||
# Create an index with non-default settings.
|
||||
index_name = 'python-test-index'
|
||||
index_body = {
|
||||
'settings': {
|
||||
'index': {
|
||||
'number_of_shards': 4
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
response = client.indices.create(index_name, body=index_body)
|
||||
print('\nCreating index:')
|
||||
print(response)
|
||||
|
||||
# Add a document to the index.
|
||||
document = {
|
||||
'title': 'Moneyball',
|
||||
'director': 'Bennett Miller',
|
||||
'year': '2011'
|
||||
}
|
||||
id = '1'
|
||||
|
||||
response = client.index(
|
||||
index = index_name,
|
||||
body = document,
|
||||
id = id,
|
||||
refresh = True
|
||||
)
|
||||
|
||||
print('\nAdding document:')
|
||||
print(response)
|
||||
|
||||
# Search for the document.
|
||||
q = 'miller'
|
||||
query = {
|
||||
'size': 5,
|
||||
'query': {
|
||||
'multi_match': {
|
||||
'query': q,
|
||||
'fields': ['title^2', 'director']
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
response = client.search(
|
||||
body = query,
|
||||
index = index_name
|
||||
)
|
||||
print('\nSearch results:')
|
||||
print(response)
|
||||
|
||||
# Delete the document.
|
||||
response = client.delete(
|
||||
index = index_name,
|
||||
id = id
|
||||
)
|
||||
|
||||
print('\nDeleting document:')
|
||||
print(response)
|
||||
|
||||
# Delete the index.
|
||||
response = client.indices.delete(
|
||||
index = index_name
|
||||
)
|
||||
|
||||
print('\nDeleting index:')
|
||||
print(response)
|
||||
```
|
||||
+3
-9
@@ -5,9 +5,9 @@ baseurl: "/docs" # the subpath of your site, e.g. /blog
|
||||
url: "https://opensearch.org" # the base hostname & protocol for your site, e.g. http://example.com
|
||||
permalink: /:path/
|
||||
|
||||
opensearch_version: 1.0.1
|
||||
opensearch_major_minor_version: 1.0
|
||||
lucene_version: 8_8_2
|
||||
opensearch_version: 1.1.0
|
||||
opensearch_major_minor_version: 1.1
|
||||
lucene_version: 8_9_0
|
||||
|
||||
# Build settings
|
||||
markdown: kramdown
|
||||
@@ -45,9 +45,6 @@ collections:
|
||||
im-plugin:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
replication-plugin:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
monitoring-plugins:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
@@ -84,9 +81,6 @@ 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
|
||||
|
||||
@@ -28,6 +28,21 @@ If you don't want to use the all-in-one installation options, you can install th
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>1.1.0</td>
|
||||
<td>
|
||||
<pre>alertingDashboards 1.1.0.0
|
||||
anomalyDetectionDashboards 1.1.0.0
|
||||
ganttChartDashboards 1.1.0.0
|
||||
indexManagementDashboards 1.1.0.0
|
||||
notebooksDashboards 1.1.0.0
|
||||
queryWorkbenchDashboards 1.1.0.0
|
||||
reportsDashboards 1.1.0.0
|
||||
securityDashboards 1.1.0.0
|
||||
traceAnalyticsDashboards 1.1.0.0
|
||||
</pre>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>1.0.1</td>
|
||||
<td>
|
||||
|
||||
@@ -14,9 +14,10 @@ nav_order: 30
|
||||
```bash
|
||||
# x64
|
||||
tar -zxf opensearch-dashboards-{{site.opensearch_version}}-linux-x64.tar.gz
|
||||
cd opensearch-dashboards{% comment %}# ARM64
|
||||
cd opensearch-dashboards
|
||||
# ARM64
|
||||
tar -zxf opensearch-dashboards-{{site.opensearch_version}}-linux-arm64.tar.gz
|
||||
cd opensearch-dashboards{% endcomment %}
|
||||
cd opensearch-dashboards
|
||||
```
|
||||
|
||||
1. If desired, modify `config/opensearch_dashboards.yml`.
|
||||
@@ -26,5 +27,3 @@ nav_order: 30
|
||||
```bash
|
||||
./bin/opensearch-dashboards
|
||||
```
|
||||
|
||||
1. See the [OpenSearch Dashboards documentation]({{site.url}}{{site.baseurl}}/dashboards/index/).
|
||||
|
||||
@@ -29,6 +29,24 @@ If you don't want to use the all-in-one OpenSearch installation options, you can
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>1.1.0</td>
|
||||
<td>
|
||||
<pre>opensearch-alerting 1.1.0.0
|
||||
opensearch-anomaly-detection 1.1.0.0
|
||||
opensearch-asynchronous-search 1.1.0.0
|
||||
opensearch-cross-cluster-replication 1.1.0.0
|
||||
opensearch-index-management 1.1.0.0
|
||||
opensearch-job-scheduler 1.1.0.0
|
||||
opensearch-knn 1.1.0.0
|
||||
opensearch-notebooks 1.1.0.0
|
||||
opensearch-performance-analyzer 1.1.0.0
|
||||
opensearch-reports-scheduler 1.1.0.0
|
||||
opensearch-security 1.1.0.0
|
||||
opensearch-sql 1.1.0.0
|
||||
</pre>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>1.0.1</td>
|
||||
<td>
|
||||
|
||||
@@ -18,9 +18,10 @@ The tarball supports most Linux distributions, including CentOS 7, Amazon Linux
|
||||
```bash
|
||||
# x64
|
||||
tar -zxf opensearch-{{site.opensearch_version}}-linux-x64.tar.gz
|
||||
cd opensearch-{{site.opensearch_version}}{% comment %}# ARM64
|
||||
cd opensearch-{{site.opensearch_version}}
|
||||
# ARM64
|
||||
tar -zxf opensearch-{{site.opensearch_version}}-linux-arm64.tar.gz
|
||||
cd opensearch-{{site.opensearch_version}}{% endcomment %}
|
||||
cd opensearch-{{site.opensearch_version}}
|
||||
```
|
||||
|
||||
1. Run OpenSearch:
|
||||
|
||||
@@ -1,391 +0,0 @@
|
||||
---
|
||||
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
|
||||
}
|
||||
```
|
||||
@@ -1,104 +0,0 @@
|
||||
---
|
||||
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"
|
||||
}'
|
||||
```
|
||||
|
||||
@@ -1,273 +0,0 @@
|
||||
---
|
||||
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.
|
||||
|
||||
|
||||
@@ -1,22 +0,0 @@
|
||||
---
|
||||
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/).
|
||||
@@ -1,78 +0,0 @@
|
||||
---
|
||||
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
|
||||
```
|
||||
@@ -1,34 +0,0 @@
|
||||
---
|
||||
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,7 +130,6 @@ 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
|
||||
@@ -197,13 +196,6 @@ 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
|
||||
@@ -229,8 +221,6 @@ 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
|
||||
@@ -241,7 +231,6 @@ 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,8 +109,6 @@ 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.
|
||||
|
||||
@@ -9,6 +9,7 @@ permalink: /version-history/
|
||||
|
||||
OpenSearch version | Release highlights | Release date
|
||||
:--- | :--- | :--- | :---
|
||||
[1.1.0](https://github.com/opensearch-project/opensearch-build/tree/main/release-notes/opensearch-release-notes-1.1.0.md) | Adds cross-cluster replication, security for Index Management, ARM support, bucket-level alerting, a CLI to help with upgrading from Elasticsearch OSS to OpenSearch, and enhancements to high cardinality data in the anomaly detection plugin. | 5 October 2021
|
||||
[1.0.1](https://github.com/opensearch-project/opensearch-build/tree/main/release-notes/opensearch-release-notes-1.0.1.md) | Bug fixes. | 1 September 2021
|
||||
[1.0.0](https://github.com/opensearch-project/opensearch-build/tree/main/release-notes/opensearch-release-notes-1.0.0.md) | General availability release. Adds compatibility setting for clients that require a version check before connecting. | 12 July 2021
|
||||
[1.0.0-rc1](https://github.com/opensearch-project/opensearch-build/tree/main/release-notes/opensearch-release-notes-1.0.0-rc1.md) | First release candidate. | 7 June 2021
|
||||
|
||||
Reference in New Issue
Block a user