The Elasticsearch transport module is deprecated and depends on functionality that might get removed at some point. We strongly recommend that you use the Java transport client instead, with the X-Pack or Shield security features for your version of Elasticsearch. To learn more, see Configure the Java Transport Client.
In order to connect to a cluster running at Elastic Cloud with the transport protocol, a plugin is required for the client. The reason for this plugin is to extend the transport protocol with three crucial features:
- Authentication
- SSL encryption
- Cluster handshake
The two first are an obvious necessity when sending your traffic over the internet and the last one is to let our proxies know which cluster your client is trying to connect to.
The transport module is backwards-compatible with the default transport module. This means that it can safely be added as a transport.type, and it will only enable its authentication and SSL support when connecting to a an Elasticsearch cluster hosted by Elastic Cloud. This equals less differences in settings between local development, staging and production.
The plugin is open source and published on GitHub.
In order to determine the version you should be using, please consult this version overview.
Releases of the plugin are built and published to the Maven central repository. To install, add a dependency to this module in your build system :
<dependency>
<groupId>no.found.elasticsearch</groupId>
<artifactId>elasticsearch-transport-module</artifactId>
<version>{version-from-the-above-overview}</version>
</dependency>The module is enabled by adding this project as a dependency to your application
and setting the transport.type setting in Elasticsearch to
no.found.elasticsearch.transport.netty.FoundNettyTransportModule.
Note: This is not a standard Elasticsearch plugin, it just needs to be on the application classpath. This also means that if you’re trying to make a pre-built third-party application connect to your Elasticsearch cluster, you can download the jar from Maven central and add it to the class path of the application.
In order to use this module, you must configure one or more API-keys. API-keys
are stored as a list of acceptable keys under api_keys at the root level of the ACL. For example:
default: deny
api_keys:
- s6aW9aAMZjDMbuhj
- 6hKZsTqBru9KnVaW
auth:
users:
...
rules:
- ...In the above example, both s6aW9aAMZjDMbuhj and 6hKZsTqBru9KnVaW would be
valid API-keys.
New settings introduced by this module:
-
transport.found.host-suffixes -
A comma-separated list of host suffixes that trigger our attempt to
authenticate with Elastic Cloud. Defaults to
foundcluster.com,found.no. -
transport.found.ssl-ports -
A comma-separated list of ports that trigger our SSL support. Defaults to
9343. -
transport.found.api-key -
An API-key which is used to authorize this client when connecting to Elastic Cloud. API-keys are managed via the console as a list of Strings
under the root level key "api_keys". Defaults to
missing-api-key -
transport.found.ssl.unsafe_allow_self_signed -
Whether to accept self-signed certificates when using SSL. This is unsafe and
allows for MITM-attacks, but may be useful for testing. Defaults to
false. -
transport.found.connection-keep-alive-interval -
The interval in which to send keep-alive messages. Defaults to
20s. Set to0to disable.
We recommend setting client.transport.nodes_sampler_interval to 30s and setting
client.transport.ping_timeout to 30s when using Elasticsearch over non-local networks (this also goes for deployments in the same Amazon EC2 region, as the connections may be routed across a regions availability zones).
Not doing so may greatly increase the number of disconnects and reconnects due to intermittent slow routers / congested networks / garbage collection and a host of other transient problems.
// Build the settings for our transport client.
Settings settings = ImmutableSettings.settingsBuilder()
// Setting "transport.type" enables this module:
.put("transport.type", "no.found.elasticsearch.transport.netty.FoundNettyTransportModule")
// Create an api key via the console and add it here:
.put("transport.found.api-key", "YOUR_API_KEY")
.put("cluster.name", "YOUR_CLUSTER_ID")
.put("client.transport.ignore_cluster_name", false)
.put("client.transport.nodes_sampler_interval", "30s")
.put("client.transport.ping_timeout", "30s")
.build();
// Instantiate a TransportClient and add Elastic Cloud to the list of addresses to connect to.
// Only port 9343 (SSL-encrypted) is currently supported.
Client client = new TransportClient(settings)
.addTransportAddress(new InetSocketTransportAddress("YOUR_CLUSTER_ID-REGION.foundcluster.com", 9343));while(true) {
try {
System.out.print("Getting cluster health... "); System.out.flush();
ActionFuture<ClusterHealthResponse> healthFuture = client.admin().cluster().health(Requests.clusterHealthRequest());
ClusterHealthResponse healthResponse = healthFuture.get(5, TimeUnit.SECONDS);
System.out.println("Got response: " + healthResponse.getStatus());
} catch(Throwable t) {
System.out.println("Error: " + t);
}
try {
Thread.sleep(3000);
} catch (InterruptedException ie) { ie.printStackTrace(); }
}Note that the JVM will cache DNS lookups infinitely, by default. Since this client is connecting to a load balancer which can change IPs, it’s important to disable this functionality.
This can be done by setting the security property networkaddress.cache.ttl in $JAVA_HOME/lib/security/java.security. You can also do it programmatically, e.g. java.security.Security.setProperty("networkaddress.cache.ttl" , "60").
Note that you can not configure it as a JVM-property with, for example, -Dnetworkaddress.cache.ttl=60.
A complete, runnable example can be found at https://github.com/foundit/elasticsearch-transport-module-example
Report issues in the issue tracker.