createRemoteClusterConnection()

🎯API Stability

Short-TermThis API may change in future versions. Use with caution in production environments.

Summary

Multi-cluster search federates query execution across multiple LogScale clusters from a single view. Remote cluster connections let a multi-cluster view delegate search requests to a view on a separate cluster, identified by its public HTTPS endpoint. The MultiClusterSearch feature must be enabled before you can use this mutation.

The createRemoteClusterConnection() mutation creates a connection between an existing multi-cluster view on the local cluster and a view on a remote cluster. You must supply the multi-cluster view name, the remote cluster's public URL, and routing tags. You must also supply either a static access token or a refreshTokenConfig for automatic token rotation; you cannot omit both. The optional queryPrefix field restricts which events are visible through the connection. After creation, use updateRemoteClusterConnection() to modify connection settings, or checkRemoteClusterConnection() to verify connectivity.

To modify an existing remote cluster connection, use updateRemoteClusterConnection(). To verify that the connection to the remote cluster is active, use checkRemoteClusterConnection(). To remove a connection, use deleteClusterConnection().

Hide Query Example

Show Multi-Cluster Views Query

To list multi-cluster views and retrieve their names, use the querySearchDomains() query:

graphql

query {
     querySearchDomains(typeFilter: Views, sortBy: Name) {
       results {
         name,
         ... on View {
           clusterConnections { id }
         }
       }
     }
   }

Use the name value as the multiClusterViewName field when calling createRemoteClusterConnection(). The id values under clusterConnections identify existing connections on that view.

Syntax

graphql

createRemoteClusterConnection(
      input: CreateRemoteClusterConnectionInput!
   ): RemoteClusterConnection!

The mutation accepts a single required input argument of type CreateRemoteClusterConnectionInput. You must supply the multi-cluster view name or identifier (multiClusterViewName), the public URL of the remote cluster (publicUrl), and routing tags (tags). You must also provide either a static access token (token) or a refresh token configuration (refreshTokenConfig) for automatic token rotation. The optional queryPrefix field restricts event visibility through the connection. The Input Parameters section describes each field in detail.

The mutation returns a non-null RemoteClusterConnection object representing the newly created connection. The Returned Values section describes the available fields.

Example

Raw

graphql

mutation {
  createRemoteClusterConnection(input:
       { multiClusterViewName: "my-cluster-view",
        publicUrl: "https://cluster.company.com",
        token: "1234abc"
      } )
  { id }
}

Mac OS or Linux (curl)

shell

curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "mutation {
  createRemoteClusterConnection(input:
       { multiClusterViewName: \"my-cluster-view\",
        publicUrl: \"https://cluster.company.com\",
        token: \"1234abc\"
      } )
  { id }
}"
}
EOF

Mac OS or Linux (curl) One-line

shell

curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "mutation {
  createRemoteClusterConnection(input:
       { multiClusterViewName: \"my-cluster-view\",
        publicUrl: \"https://cluster.company.com\",
        token: \"1234abc\"
      } )
  { id }
}"
}
EOF

Windows Cmd and curl

shell

curl -v -X POST $YOUR_LOGSCALE_URL/graphql ^
    -H "Authorization: Bearer $TOKEN" ^
    -H "Content-Type: application/json" ^
    -d @'{"query" : "mutation { ^
  createRemoteClusterConnection(input: ^
       { multiClusterViewName: \"my-cluster-view\", ^
        publicUrl: \"https://cluster.company.com\", ^
        token: \"1234abc\" ^
      } ) ^
  { id } ^
}" ^
} '

Windows Powershell and curl

powershell

curl.exe -X POST 
    -H "Authorization: Bearer $TOKEN"
    -H "Content-Type: application/json"
    -d '{"query" : "mutation {
  createRemoteClusterConnection(input:
       { multiClusterViewName: \"my-cluster-view\",
        publicUrl: \"https://cluster.company.com\",
        token: \"1234abc\"
      } )
  { id }
}"
}'
    "$YOUR_LOGSCALE_URL/graphql"

Perl

perl

#!/usr/bin/perl

use HTTP::Request;
use LWP;

my $TOKEN = "TOKEN";

my $uri = '$YOUR_LOGSCALE_URL/graphql';

my $query = "mutation {
  createRemoteClusterConnection(input:
       { multiClusterViewName: \"my-cluster-view\",
        publicUrl: \"https://cluster.company.com\",
        token: \"1234abc\"
      } )
  { id }
}";
$query =~ s/\n/ /g;
my $json = sprintf('{"query" : "%s"}',$query);
my $req = HTTP::Request->new("POST", $uri );

$req->header("Authorization" => "Bearer $TOKEN");
$req->header("Content-Type" => "application/json");

$req->content( $json );

my $lwp = LWP::UserAgent->new;

my $result = $lwp->request( $req );

print $result->{"_content"},"\n";

Python

python

#! /usr/local/bin/python3

import requests

url = '$YOUR_LOGSCALE_URL/graphql'
mydata = r'''{"query" : "mutation {
  createRemoteClusterConnection(input:
       { multiClusterViewName: \"my-cluster-view\",
        publicUrl: \"https://cluster.company.com\",
        token: \"1234abc\"
      } )
  { id }
}"
}'''

resp = requests.post(url,
                     data = mydata,
                     headers = {
   "Authorization" : "Bearer $TOKEN",
   "Content-Type" : "application/json"
}
)

print(resp.text)

Node.js

javascript

const https = require('https');

const data = JSON.stringify(
    {"query" : "mutation {
  createRemoteClusterConnection(input:
       { multiClusterViewName: \"my-cluster-view\",
        publicUrl: \"https://cluster.company.com\",
        token: \"1234abc\"
      } )
  { id }
}"
}
);


const options = {
  hostname: '$YOUR_LOGSCALE_URL',
  path: 'graphql',
  port: 443,
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': data.length,
    Authorization: 'BEARER ' + process.env.TOKEN,
    'User-Agent': 'Node',
  },
};

const req = https.request(options, (res) => {
  let data = '';
  console.log(`statusCode: ${res.statusCode}`);

  res.on('data', (d) => {
    data += d;
  });
  res.on('end', () => {
    console.log(JSON.parse(data).data);
  });
});

req.on('error', (error) => {
  console.error(error);
});

req.write(data);
req.end();

Input Parameters

The input argument requires three fields: the multi-cluster view name or identifier (multiClusterViewName), the public HTTPS endpoint of the remote cluster (publicUrl), and routing tags (tags). Tags are ClusterConnectionInputTag key-value pairs; LogScale uses them to route queries to this connection. You must also supply authentication credentials: set token to a static access token for the remote cluster, or set refreshTokenConfig to enable automatic token rotation. You cannot omit both fields. The optional queryPrefix field accepts any valid LogScale query expression; only events matching that expression are visible through this connection. Omit queryPrefix to make all events visible.

Table: CreateRemoteClusterConnectionInput Input Datatype

Parameter	Type	Required	Stability	Availability	Description
multiClusterViewName	String	yes	`Short-Term`		The name or unique identifier of the multi-cluster view to add.
publicUrl	String	yes	`Short-Term`		The public URL of the remote cluster.
queryPrefix	String		`Short-Term`		Filter query that restricts the data visible through this connection.
refreshTokenConfig	FederatedRefreshTokenConfigInput			added in 1.257	Refresh token configuration for automatic token rotation. Either this or token must be set.
tags	ClusterConnectionInputTag	yes	`Short-Term`		Additional tags that can be used to filter queries. See ClusterConnectionInputTag.
token	String		`Short-Term`		The access token for connecting to the remote view.

Returned Values

The mutation returns a RemoteClusterConnection object representing the newly created connection. The id field contains the unique connection identifier; store this value to update or delete the connection later using updateRemoteClusterConnection() or deleteClusterConnection(). The clusterId field identifies the cluster that owns the connection. The publicUrl field reflects the remote cluster endpoint. The queryPrefix field contains the active event filter expression; a null or empty value means all events on the remote view are visible. The tags field returns the routing tags on the connection as ClusterConnectionTag objects. The following table lists all available fields:

Table: RemoteClusterConnection Datatype

Parameter	Type	Required	Stability	Description
clusterId	string	yes	`Short-Term`	Cluster identity of the connection.
id	string	yes	`Short-Term`	The unique identifier of the connection.
publicUrl	string	yes	`Short-Term`	Public URL of the remote cluster with which to connect.
queryPrefix	string	yes	`Short-Term`	The cluster connection query prefix.
tags	[ClusterConnectionTag]	yes	`Short-Term`	Cluster connection tags. See ClusterConnectionTag.

Versions of this Page

GraphQL Mutations

GraphQL API

GraphQL Queries

GraphQL Datatypes