Compare commits

..

7 Commits

Author SHA1 Message Date
aetter 01a9fb6d6d Adding async back in, just in case 2021-09-28 11:10:36 -07:00
aetter cbdefc2463 Improve permissions introduction
Also corrects some permissions names that still use `opendistro`, adds missing permissions, adds some short () description to unclear permissions.
2021-09-28 10:54:04 -07:00
aetter d2ba96967b Give CCS Compose file unique node names
Avoid weird conflicts if you use our main Compose file and then try to use this one.
2021-09-24 13:49:48 -07:00
aetter a9144167d8 Note that ISM doesn't run jobs on red clusters 2021-09-23 10:29:51 -07:00
aetter 07b0650128 Add remote cluster information operation 2021-09-22 12:59:25 -07:00
Andrew Etter bff43bed13 Merge pull request #181 from piellick/patch-1
change ES_HOME env variable to OPENSEARCH_HOME
2021-09-22 11:47:53 -07:00
piellick 75efdfeae8 change ES_HOME env variable to OPENSEARCH_HOME
env variable looks wrong on "Launch the agent CLI"
2021-09-22 10:57:09 +02:00
8 changed files with 194 additions and 212 deletions
+1 -15
View File
@@ -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 -1
View File
@@ -1,7 +1,7 @@
---
layout: default
title: Java high-level REST client
nav_order: 60
nav_order: 97
---
# Java high-level REST client
-128
View File
@@ -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)
```
+1
View File
@@ -89,6 +89,7 @@ Make sure that the alias that you enter already exists. For more information abo
After you attach a policy to an index, ISM creates a job that runs every 5 minutes by default to perform policy actions, check conditions, and transition the index into different states. To change the default time interval for this job, see [Settings]({{site.url}}{{site.baseurl}}/im-plugin/ism/settings/).
ISM does not run jobs if the cluster state is red.
### Step 3: Manage indices
+1 -1
View File
@@ -111,7 +111,7 @@ In a tarball installation, Performance Analyzer collects data when it is enabled
1. Launch the agent CLI:
```bash
ES_HOME="$PWD" ./bin/performance-analyzer-agent-cli
OPENSEARCH_HOME="$PWD" ./bin/performance-analyzer-agent-cli
```
1. In a separate window, enable the Performance Analyzer plugin:
+40
View File
@@ -0,0 +1,40 @@
---
layout: default
title: Remote cluster information
parent: REST API reference
nav_order: 25
---
# Remote cluster information
Introduced 1.0
{: .label .label-purple }
This operation provides connection information for any remote OpenSearch clusters that you've configured for the local cluster, such as the remote cluster alias, connection mode (`sniff` or `proxy`), IP addresses for seed nodes, and timeout settings.
The response is more comprehensive and useful than a call to `_cluster/settings`, which only includes the cluster alias and seed nodes.
## Path and HTTP methods
```
GET _remote/info
```
## Response
```json
{
"opensearch-cluster2": {
"connected": true,
"mode": "sniff",
"seeds": [
"172.28.0.2:9300"
],
"num_nodes_connected": 1,
"max_connections_per_cluster": 3,
"initial_connect_timeout": "30s",
"skip_unavailable": false
}
}
```
@@ -65,11 +65,11 @@ Save this file as `docker-compose.yml` and run `docker-compose up` to start two
```yml
version: '3'
services:
opensearch-node1:
opensearch-ccs-node1:
image: opensearchproject/opensearch:{{site.opensearch_version}}
container_name: opensearch-node1
container_name: opensearch-ccs-node1
environment:
- cluster.name=opensearch-cluster1
- cluster.name=opensearch-ccs-cluster1
- discovery.type=single-node
- bootstrap.memory_lock=true # along with the memlock settings below, disables swapping
- "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" # minimum and maximum Java heap size, recommend setting both to 50% of system RAM
@@ -85,11 +85,11 @@ services:
networks:
- opensearch-net
opensearch-node2:
opensearch-ccs-node2:
image: opensearchproject/opensearch:{{site.opensearch_version}}
container_name: opensearch-node2
container_name: opensearch-ccs-node2
environment:
- cluster.name=opensearch-cluster2
- cluster.name=opensearch-ccs-cluster2
- discovery.type=single-node
- bootstrap.memory_lock=true # along with the memlock settings below, disables swapping
- "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" # minimum and maximum Java heap size, recommend setting both to 50% of system RAM
@@ -118,26 +118,26 @@ After the clusters start, verify the names of each:
```json
curl -XGET -u 'admin:admin' -k 'https://localhost:9200'
{
"cluster_name" : "opensearch-cluster1",
"cluster_name" : "opensearch-ccs-cluster1",
...
}
curl -XGET -u 'admin:admin' -k 'https://localhost:9250'
{
"cluster_name" : "opensearch-cluster2",
"cluster_name" : "opensearch-ccs-cluster2",
...
}
```
Both clusters run on `localhost`, so the important identifier is the port number. In this case, use port 9200 (`opensearch-node1`) as the remote cluster, and port 9250 (`opensearch-node2`) as the coordinating cluster.
Both clusters run on `localhost`, so the important identifier is the port number. In this case, use port 9200 (`opensearch-ccs-node1`) as the remote cluster, and port 9250 (`opensearch-ccs-node2`) as the coordinating cluster.
To get the IP address for the remote cluster, first identify its container ID:
```bash
docker ps
CONTAINER ID IMAGE PORTS NAMES
6fe89ebc5a8e opensearchproject/opensearch:{{site.opensearch_version}} 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp, 9300/tcp opensearch-node1
2da08b6c54d8 opensearchproject/opensearch:{{site.opensearch_version}} 9300/tcp, 0.0.0.0:9250->9200/tcp, 0.0.0.0:9700->9600/tcp opensearch-node2
6fe89ebc5a8e opensearchproject/opensearch:{{site.opensearch_version}} 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp, 9300/tcp opensearch-ccs-node1
2da08b6c54d8 opensearchproject/opensearch:{{site.opensearch_version}} 9300/tcp, 0.0.0.0:9250->9200/tcp, 0.0.0.0:9700->9600/tcp opensearch-ccs-node2
```
Then get that container's IP address:
@@ -154,7 +154,7 @@ curl -k -XPUT -H 'Content-Type: application/json' -u 'admin:admin' 'https://loca
{
"persistent": {
"search.remote": {
"opensearch-cluster1": {
"opensearch-ccs-cluster1": {
"seeds": ["172.31.0.3:9300"]
}
}
@@ -171,11 +171,11 @@ curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://loca
At this point, cross-cluster search works. You can test it using the `admin` user:
```bash
curl -XGET -k -u 'admin:admin' 'https://localhost:9250/opensearch-cluster1:books/_search?pretty'
curl -XGET -k -u 'admin:admin' 'https://localhost:9250/opensearch-ccs-cluster1:books/_search?pretty'
{
...
"hits": [{
"_index": "opensearch-cluster1:books",
"_index": "opensearch-ccs-cluster1:books",
"_type": "_doc",
"_id": "1",
"_score": 1.0,
@@ -196,7 +196,7 @@ curl -XPUT -k -u 'admin:admin' 'https://localhost:9250/_plugins/_security/api/in
Then run the same search as before with `booksuser`:
```json
curl -XGET -k -u booksuser:password 'https://localhost:9250/opensearch-cluster1:books/_search?pretty'
curl -XGET -k -u booksuser:password 'https://localhost:9250/opensearch-ccs-cluster1:books/_search?pretty'
{
"error" : {
"root_cause" : [
@@ -225,11 +225,11 @@ Both clusters must have the user, but only the remote cluster needs the role and
Finally, repeat the search:
```bash
curl -XGET -k -u booksuser:password 'https://localhost:9250/opensearch-cluster1:books/_search?pretty'
curl -XGET -k -u booksuser:password 'https://localhost:9250/opensearch-ccs-cluster1:books/_search?pretty'
{
...
"hits": [{
"_index": "opensearch-cluster1:books",
"_index": "opensearch-ccs-cluster1:books",
"_type": "_doc",
"_id": "1",
"_score": 1.0,
+133 -50
View File
@@ -7,58 +7,129 @@ nav_order: 50
# Permissions
This page is a complete list of available permissions in the security plugin. Each permission controls access to a data type or API.
Each permission in the security plugin controls access to some action that the OpenSearch cluster can perform, such as indexing a document or checking cluster health.
Rather than creating new action groups from individual permissions, you can often achieve your desired security posture using some combination of the default action groups. To learn more, see [Default Action Groups]({{site.url}}{{site.baseurl}}/security-plugin/access-control/default-action-groups/).
Most permissions are self-describing. For example, `cluster:admin/ingest/pipeline/get` lets you retrieve information about ingest pipelines. _In many cases_, a permission correlates to a specific REST API operation, such as `GET _ingest/pipeline`.
Despite this correlation, permissions do **not** directly map to REST API operations. Operations such as `POST _bulk` and `GET _msearch` can access many indices and perform many actions in a single request. Even a simple request, such as `GET _cat/nodes`, performs several actions in order to generate its response.
In short, controlling access to the REST API is insufficient. Instead, the security plugin controls access to the underlying OpenSearch actions.
For example, consider the following `_bulk` request:
```json
POST _bulk
{ "delete": { "_index": "test-index", "_id": "tt2229499" } }
{ "index": { "_index": "test-index", "_id": "tt1979320" } }
{ "title": "Rush", "year": 2013 }
{ "create": { "_index": "test-index", "_id": "tt1392214" } }
{ "title": "Prisoners", "year": 2013 }
{ "update": { "_index": "test-index", "_id": "tt0816711" } }
{ "doc" : { "title": "World War Z" } }
```
For this request to succeed, you must have the following permissions for `test-index`:
- indices:data/write/bulk*
- indices:data/write/delete
- indices:data/write/index
- indices:data/write/update
These permissions also allow you add, update, or delete documents (e.g. `PUT test-index/_doc/tt0816711`), because they govern the underlying OpenSearch actions of indexing and deleting documents rather than a specific API path and HTTP method.
## Test permissions
If you want a user to have the absolute minimum set of permissions necessary to perform some function---the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege)----the best way is to send representative requests to your cluster as a new test user. In the case of a permissions error, the security plugin is very explicit about which permissions are missing. Consider this request and response:
```json
GET _cat/shards?v
{
"error": {
"root_cause": [{
"type": "security_exception",
"reason": "no permissions for [indices:monitor/stats] and User [name=test-user, backend_roles=[], requestedTenant=null]"
}]
},
"status": 403
}
```
[Create a user and a role]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles/), map the role to the user, and start sending signed requests using curl, Postman, or any other client. Then gradually add permissions to the role as you encounter errors. Even after you resolve one permissions error, the same request might generate new errors; the plugin only returns the first error it encounters, so keep trying until the request succeeds.
Rather than individual permissions, you can often achieve your desired security posture using a combination of the default action groups. See [Default action groups]({{site.url}}{{site.baseurl}}/security-plugin/access-control/default-action-groups/) for descriptions of the permissions that each group grants.
{: .tip }
## Cluster
## Cluster permissions
These permissions are for the cluster and can't be applied granularly. For example, you either have permissions to take snapshots (`cluster:admin/snapshot/create`) or you don't. You can't have permissions to take snapshots only for certain indices.
- cluster:admin/ingest/pipeline/delete
- cluster:admin/ingest/pipeline/get
- cluster:admin/ingest/pipeline/put
- cluster:admin/ingest/pipeline/simulate
- cluster:admin/ingest/processor/grok/get
- cluster:admin/opensearch/ad/detector/delete
- cluster:admin/opensearch/ad/detector/jobmanagement
- cluster:admin/opensearch/ad/detector/run
- cluster:admin/opensearch/ad/detector/search
- cluster:admin/opensearch/ad/detector/stats
- cluster:admin/opensearch/ad/detector/write
- cluster:admin/opensearch/ad/detectors/get
- cluster:admin/opensearch/ad/result/search
- cluster:admin/opensearch/alerting/alerts/ack
- cluster:admin/opensearch/alerting/alerts/get
- cluster:admin/opensearch/alerting/destination/delete
- cluster:admin/opensearch/alerting/destination/email_account/delete
- cluster:admin/opensearch/alerting/destination/email_account/get
- cluster:admin/opensearch/alerting/destination/email_account/search
- cluster:admin/opensearch/alerting/destination/email_account/write
- cluster:admin/opensearch/alerting/destination/email_group/delete
- cluster:admin/opensearch/alerting/destination/email_group/get
- cluster:admin/opensearch/alerting/destination/email_group/search
- cluster:admin/opensearch/alerting/destination/email_group/write
- cluster:admin/opensearch/alerting/destination/get
- cluster:admin/opensearch/alerting/destination/write
- cluster:admin/opensearch/alerting/monitor/delete
- cluster:admin/opensearch/alerting/monitor/execute
- cluster:admin/opensearch/alerting/monitor/get
- cluster:admin/opensearch/alerting/monitor/search
- cluster:admin/opensearch/alerting/monitor/write
- cluster:admin/opensearch/asynchronous_search/stats
- cluster:admin/opensearch/asynchronous_search/delete
- cluster:admin/opensearch/asynchronous_search/get
- cluster:admin/opensearch/asynchronous_search/submit
- cluster:admin/opensearch/reports/definition/create
- cluster:admin/opensearch/reports/definition/delete
- cluster:admin/opensearch/reports/definition/get
- cluster:admin/opensearch/reports/definition/list
- cluster:admin/opensearch/reports/definition/on_demand
- cluster:admin/opensearch/reports/definition/update
- cluster:admin/opensearch/reports/instance/get
- cluster:admin/opensearch/reports/instance/list
- cluster:admin/opensearch/reports/menu/download
- cluster:admin/opendistro/ad/detector/delete
- cluster:admin/opendistro/ad/detector/info
- cluster:admin/opendistro/ad/detector/jobmanagement
- cluster:admin/opendistro/ad/detector/preview
- cluster:admin/opendistro/ad/detector/run
- cluster:admin/opendistro/ad/detector/search
- cluster:admin/opendistro/ad/detector/stats
- cluster:admin/opendistro/ad/detector/write
- cluster:admin/opendistro/ad/detectors/get
- cluster:admin/opendistro/ad/result/search
- cluster:admin/opendistro/ad/tasks/search
- cluster:admin/opendistro/alerting/alerts/ack (acknowledge)
- cluster:admin/opendistro/alerting/alerts/get
- cluster:admin/opendistro/alerting/destination/delete
- cluster:admin/opendistro/alerting/destination/email_account/delete
- cluster:admin/opendistro/alerting/destination/email_account/get
- cluster:admin/opendistro/alerting/destination/email_account/search
- cluster:admin/opendistro/alerting/destination/email_account/write
- cluster:admin/opendistro/alerting/destination/email_group/delete
- cluster:admin/opendistro/alerting/destination/email_group/get
- cluster:admin/opendistro/alerting/destination/email_group/search
- cluster:admin/opendistro/alerting/destination/email_group/write
- cluster:admin/opendistro/alerting/destination/get
- cluster:admin/opendistro/alerting/destination/write
- cluster:admin/opendistro/alerting/monitor/delete
- cluster:admin/opendistro/alerting/monitor/execute
- cluster:admin/opendistro/alerting/monitor/get
- cluster:admin/opendistro/alerting/monitor/search
- cluster:admin/opendistro/alerting/monitor/write
- cluster:admin/opendistro/asynchronous_search/stats
- cluster:admin/opendistro/asynchronous_search/delete
- cluster:admin/opendistro/asynchronous_search/get
- cluster:admin/opendistro/asynchronous_search/submit
- cluster:admin/opendistro/ism/managedindex/add
- cluster:admin/opendistro/ism/managedindex/change
- cluster:admin/opendistro/ism/managedindex/remove
- cluster:admin/opendistro/ism/managedindex/explain
- cluster:admin/opendistro/ism/managedindex/retry
- cluster:admin/opendistro/ism/policy/write
- cluster:admin/opendistro/ism/policy/get
- cluster:admin/opendistro/ism/policy/search
- cluster:admin/opendistro/ism/policy/delete
- cluster:admin/opendistro/rollup/index
- cluster:admin/opendistro/rollup/get
- cluster:admin/opendistro/rollup/search
- cluster:admin/opendistro/rollup/delete
- cluster:admin/opendistro/rollup/start
- cluster:admin/opendistro/rollup/stop
- cluster:admin/opendistro/rollup/explain
- cluster:admin/opendistro/reports/definition/create
- cluster:admin/opendistro/reports/definition/update
- cluster:admin/opendistro/reports/definition/on_demand
- cluster:admin/opendistro/reports/definition/delete
- cluster:admin/opendistro/reports/definition/get
- cluster:admin/opendistro/reports/definition/list
- cluster:admin/opendistro/reports/instance/list
- cluster:admin/opendistro/reports/instance/get
- cluster:admin/opendistro/reports/menu/download
- cluster:admin/reindex/rethrottle
- cluster:admin/repository/delete
- cluster:admin/repository/get
@@ -94,7 +165,9 @@ Rather than creating new action groups from individual permissions, you can ofte
- cluster:monitor/tasks/list
## Indices
## Index permissions
These permissions apply to an index or index pattern. You might want a user to have read access to all indices (i.e. `*`), but write access to only a few (e.g. `web-logs` and `product-catalog`).
- indices:admin/aliases
- indices:admin/aliases/exists
@@ -102,13 +175,22 @@ Rather than creating new action groups from individual permissions, you can ofte
- indices:admin/analyze
- indices:admin/cache/clear
- indices:admin/close
- indices:admin/create
- indices:admin/delete
- indices:admin/close*
- indices:admin/create (create indices)
- indices:admin/data_stream/create
- indices:admin/data_stream/delete
- indices:admin/data_stream/get
- indices:admin/delete (delete indices)
- indices:admin/exists
- indices:admin/flush
- indices:admin/flush*
- indices:admin/forcemerge
- indices:admin/get
- indices:admin/get (retrieve index and mapping)
- indices:admin/index_template/delete
- indices:admin/index_template/get
- indices:admin/index_template/put
- indices:admin/index_template/simulate
- indices:admin/index_template/simulate_index
- indices:admin/mapping/put
- indices:admin/mappings/fields/get
- indices:admin/mappings/fields/get*
@@ -137,22 +219,23 @@ Rather than creating new action groups from individual permissions, you can ofte
- indices:data/read/mget*
- indices:data/read/msearch
- indices:data/read/msearch/template
- indices:data/read/mtv
- indices:data/read/mtv (multi-term vectors)
- indices:data/read/mtv*
- indices:data/read/scroll
- indices:data/read/scroll/clear
- indices:data/read/search
- indices:data/read/search*
- indices:data/read/search/template
- indices:data/read/tv
- indices:data/read/tv (term vectors)
- indices:data/write/bulk
- indices:data/write/bulk*
- indices:data/write/delete
- indices:data/write/delete (delete documents)
- indices:data/write/delete/byquery
- indices:data/write/index
- indices:data/write/index (add documents to existing indices)
- indices:data/write/reindex
- indices:data/write/update
- indices:data/write/update/byquery
- indices:monitor/data_stream/stats
- indices:monitor/recovery
- indices:monitor/segments
- indices:monitor/settings/get