Document ccs for ppl

Signed-off-by: Sean Kao <[email protected]>

docs/user/ppl/admin/cross_cluster_search.rst

@@ -0,0 +1,108 @@
+.. highlight:: sh
+
+====================
+Cross-Cluster Search
+====================
+
+.. rubric:: Table of contents
+
+.. contents::
+   :local:
+   :depth: 1
+
+Introduction
+============
+Cross-cluster search lets any node in a cluster execute search requests against other clusters.
+It makes searching easy across all connected clusters, allowing users to use multiple smaller clusters instead of a single large one.
+
+
+Configuration
+=============
+On the local cluster, add the remote cluster name and the IP address with port 9300 for each seed node. ::
+
+    PUT _cluster/settings
+    {
+      "persistent": {
+        "cluster.remote": {
+          "<remote-cluster-name>": {
+            "seeds": ["<remote-cluster-IP-address>:9300"]
+          }
+        }
+      }
+    }
+
+
+Using Cross-Cluster Search in PPL
+=================================
+Perform cross-cluster search by using "<cluster-name>:<index-name>" as the index identifier.
+
+Example search command ::
+
+    >> search source = my_remote_cluster:my_index
+
+
+Limitation
+==========
+Since OpenSearch does not support cross cluster system index query, field mapping of a remote cluster index is not available to the local cluster.
+Therefore, the query engine requires that for any remote cluster index that the users need to search,
+the local cluster keep a field mapping system index with the same index name.
+This can be done by creating an index on the local cluster with the same name and schema as the remote cluster index.
+
+
+Authentication and Permission
+=============================
+
+1. The security plugin authenticates the user on the local cluster.
+2. The security plugin fetches the user’s backend roles on the local cluster.
+3. The call, including the authenticated user, is forwarded to the remote cluster.
+4. The user’s permissions are evaluated on the remote cluster.
+
+Check `Cross-cluster search access control <https://opensearch.org/docs/latest/security/access-control/cross-cluster-search/>`_ for more details.
+
+On the local cluster, create a new role and grant permission to access PPL plugin and access index, then map the user to this role::
+
+    PUT _plugins/_security/api/roles/ppl_role
+    {
+      "cluster_permissions":[
+        "cluster:admin/opensearch/ppl"
+      ],
+      "index_permissions":[
+        {
+          "index_patterns":["example_index"],
+          "allowed_actions":[
+            "indices:data/read/search",
+            "indices:admin/mappings/get",
+            "indices:monitor/settings/get"
+          ]
+        }
+      ]
+    }
+
+    PUT _plugins/_security/api/rolesmapping/ppl_role
+    {
+      "backend_roles" : [],
+      "hosts" : [],
+      "users" : ["test_user"]
+    }
+
+On the remote cluster, create a new role and grant permission to access index. Create a user the same as the local cluster, and map the user to this role::
+
+    PUT _plugins/_security/api/roles/example_index_ccs_role
+    {
+      "index_permissions":[
+        {
+          "index_patterns":["example_index"],
+          "allowed_actions":[
+            "indices:admin/shards/search_shards",
+            "indices:data/read/search"
+          ]
+        }
+      ]
+    }
+
+    PUT _plugins/_security/api/rolesmapping/example_index_ccs_role
+    {
+      "backend_roles" : [],
+      "hosts" : [],
+      "users" : ["test_user"]
+    }

docs/user/ppl/admin/security.rst

@@ -34,7 +34,8 @@ Example: Create the ppl_role for test_user. then test_user could use PPL to quer
         ],
         "allowed_actions": [
           "indices:data/read/search*",
-          "indices:admin/mappings/get"
+          "indices:admin/mappings/get",
+          "indices:monitor/settings/get"
         ]
       }]
     }

docs/user/ppl/cmd/search.rst

@@ -19,7 +19,7 @@ Syntax
 search source=<index> [boolean-expression]
 
 * search: search keywords, which could be ignore.
-* index: mandatory. search command must specify which index to query from.
+* index: mandatory. search command must specify which index to query from. The index name can be prefixed by "<cluster name>:" for cross-cluster search.
 * bool-expression: optional. any expression which could be evaluated to boolean value.
 
 

integ-test/src/test/java/org/opensearch/sql/multicluster/OpenSearchMultiClustersRestTestCase.java

@@ -33,7 +33,7 @@ public abstract class OpenSearchMultiClustersRestTestCase extends OpenSearchRest
    */
   private static RestClient remoteAdminClient;
 
-  // modified from initClient in OpenSearchRestTestCase
+  // Modified from initClient in OpenSearchRestTestCase
   public void initRemoteClient() throws IOException {
     if (remoteClient == null) {
       assert remoteAdminClient == null;
@@ -58,6 +58,9 @@ public void initRemoteClient() throws IOException {
     assert remoteAdminClient != null;
   }
 
+  /**
+   * Get a comma delimited list of [host:port] to which to send REST requests.
+   */
   protected String getTestRestCluster(String clusterName) {
     String cluster = System.getProperty("tests.rest." + clusterName + ".http_hosts");
     if (cluster == null) {
@@ -71,6 +74,9 @@ protected String getTestRestCluster(String clusterName) {
     return cluster;
   }
 
+  /**
+   * Get a comma delimited list of [host:port] for connections between clusters.
+   */
   protected String getTestTransportCluster(String clusterName) {
     String cluster = System.getProperty("tests.rest." + clusterName + ".transport_hosts");
     if (cluster == null) {
@@ -84,6 +90,10 @@ protected String getTestTransportCluster(String clusterName) {
     return cluster;
   }
 
+  /**
+   * Initialize rest client to remote cluster,
+   * and create a connection to it from the coordinating cluster.
+   */
   public void configureMultiClusters() throws IOException {
     initRemoteClient();
 
@@ -109,7 +119,7 @@ public static void closeRemoteClients() throws IOException {
   }
 
   /**
-   * Get the client to remote cluster used for ordinary api calls while writing a test
+   * Get the client to remote cluster used for ordinary api calls while writing a test.
    */
   protected static RestClient remoteClient() {
     return remoteClient;

opensearch/src/main/java/org/opensearch/sql/opensearch/request/OpenSearchRequest.java

@@ -69,7 +69,6 @@ class IndexName {
      */
     public IndexName(String indexName) {
       this.indexFullNames = indexName.split(COMMA);
-      // Remove all "<cluster>:" prefix if they exist
       this.indexNames = Arrays.stream(indexFullNames)
               .map(name -> name.substring(name.indexOf(COLON) + 1))
               .toArray(String[]::new);