Connect to a cluster from an application

Before you begin

Obtain the cluster endpoint

You can connect to your Elasticsearch cluster by using an internal endpoint over a VPC private network or a public endpoint.

• Internal endpoint: Provides a low-latency, high-stability connection to your Elasticsearch cluster. This endpoint is enabled by default upon cluster creation.

• Public endpoint: Allows you to connect to your Elasticsearch cluster over the internet. You must enable this endpoint manually.

Enable public access

1. Log on to the Elasticsearch console and navigate to the Basic Information page of your instance.

2. In the navigation pane, choose Configuration and Management > Security Settings and enable public access. Public access is enabled once the cluster status changes from Initializing to Valid.

   After you enable public access, the public endpoint is in the format es-cn-<instance_ID>.public.elasticsearch.aliyuncs.com. The public IP whitelist is empty by default and must be configured.

   Important

   Using a public endpoint can compromise the security of your Elasticsearch cluster. If you use a public endpoint, be sure to configure an IP whitelist and disable public access when you are done.

Configure an IP whitelist

To secure your cluster, you must add the IP address of the device you want to use for access to the VPC private network or public IP whitelist of the Elasticsearch cluster. Only devices with IP addresses in the whitelist can access the cluster.

1. Obtain the IP address of the device you want to use for access.

   The following table explains how to obtain the IP address for different scenarios.

   Scenario	IP address	Method
   Connect to an Elasticsearch cluster from a local device	The public IP address of your local device. If your local device is on a local area network (LAN), such as a home or corporate network, you must add the public IP address of the LAN's gateway to the cluster's public IP whitelist.	Run the curl ipinfo.io/ip command to find the public IP of your local device.
   Connect to an Elasticsearch cluster from an ECS instance in a different VPC	The public IP of the ECS instance.	Log on to the ECS console to view it in the instance list.
   Connect to an Elasticsearch cluster from an ECS instance in the same VPC	The private IP of the ECS instance.	Log on to the ECS console to view it in the instance list.

2. Add this IP address to a whitelist group.

   1. Log on to the Elasticsearch console. On the Basic Information page of your instance, choose Configuration and Management > Security Settings in the navigation pane. Click Modify to configure the VPC private network or public IP whitelist.

   2. Click Configure to the right of the default group. In the dialog box that appears, add IP addresses to the VPC private network or public IP whitelist. You can add up to 300 IP addresses or CIDR blocks to a cluster. Separate multiple entries with a comma (,) and do not add spaces around it.

      • You can also click Add IP address whitelist Group to create a custom group.

      • Whitelist groups are for IP address management only and do not affect access permissions. All IP addresses across all groups have the same permissions.

      Configuration type	Format and example	Important notes
      IPv4 address format	Single IP: 192.168.0.1 CIDR block: 192.168.0.0/24	Deny all access: 127.0.0.1 Allow all access: 0.0.0.0/0 Important This poses a high security risk. We strongly recommend that you do not configure 0.0.0.0/0. Some cluster versions (such as 7.16 and 8.5) and regions do not support 0.0.0.0/0. Refer to the console UI or error messages for details.
      IPv6 address format (Supported only for v2 deployment architecture clusters in the China (Hangzhou) region)	Single IP: 2401:XXXX:1000:24::5 CIDR block: 2401:XXXX:1000::/48	Deny all access: ::1 Allow all access: ::/0 Important This poses a high security risk. We strongly recommend that you do not configure ::/0. Some cluster versions do not support ::/0. Refer to the console UI or configuration prompts for details.

   3. Click OK.

Basic connection example

Applies to public HTTPS or private HTTP connections:

package org.example;
import co.elastic.clients.elasticsearch.ElasticsearchClient;
import co.elastic.clients.elasticsearch.cat.IndicesResponse;
import co.elastic.clients.elasticsearch.indices.*;
import co.elastic.clients.json.jackson.JacksonJsonpMapper;
import co.elastic.clients.transport.ElasticsearchTransport;
import co.elastic.clients.transport.rest_client.RestClientTransport;
import org.apache.http.HttpHost;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.CredentialsProvider;
import org.apache.http.impl.client.BasicCredentialsProvider;
import org.apache.http.impl.nio.client.HttpAsyncClientBuilder;
import org.elasticsearch.client.*;
import java.io.IOException;
public class RestClientTest {
    public static void main(String[] args) {
        final CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
        credentialsProvider.setCredentials(AuthScope.ANY, new UsernamePasswordCredentials("{UserName}", "{YourPassword}"));
        // Use "https" for public HTTPS access or "http" for private HTTP access.
        RestClient restClient = RestClient.builder(new HttpHost("{YourEsHost}", 9200, "https"))
                .setHttpClientConfigCallback(new RestClientBuilder.HttpClientConfigCallback() {
                    @Override
                    public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder) {
                        return httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider);
                    }
                }).build();

        ElasticsearchTransport transport = new RestClientTransport(restClient, new JacksonJsonpMapper());
        ElasticsearchClient elasticsearchClient = new ElasticsearchClient(transport);
        try {
            CreateIndexResponse indexRequest = elasticsearchClient.indices().create(createIndexBuilder -> createIndexBuilder
                    .index("hr_test")
                    .aliases("foo", aliasBuilder -> aliasBuilder.isWriteIndex(true))
            );
            System.out.println("Index document successfully! " + indexRequest.acknowledged());
            transport.close();
            restClient.close();
        } catch (IOException ioException) {
            // Handle exceptions.
        }
    }
}

Private HTTPS connection example

For private HTTPS, skip certificate verification:

package org.example;
import co.elastic.clients.elasticsearch.ElasticsearchClient;
import co.elastic.clients.json.jackson.JacksonJsonpMapper;
import co.elastic.clients.transport.ElasticsearchTransport;
import co.elastic.clients.transport.rest_client.RestClientTransport;
import org.apache.http.HttpHost;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.CredentialsProvider;
import org.apache.http.conn.ssl.NoopHostnameVerifier;
import org.apache.http.impl.client.BasicCredentialsProvider;
import org.apache.http.impl.nio.client.HttpAsyncClientBuilder;
import org.apache.http.ssl.SSLContexts;
import org.elasticsearch.client.*;
import javax.net.ssl.SSLContext;

public class RestClientTestPrivateHttps {
    public static void main(String[] args) throws Exception {
        final CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
        credentialsProvider.setCredentials(AuthScope.ANY, new UsernamePasswordCredentials("{UserName}", "{YourPassword}"));
        // Create an SSLContext that trusts all certificates.
        SSLContext sslContext = SSLContexts.custom()
          .loadTrustMaterial(null, (chain, authType) -> true)  // Trust all certificates.
          .build();
        RestClient restClient = RestClient.builder(new HttpHost("{YourEsHost}", 9200, "https"))
                .setHttpClientConfigCallback(new RestClientBuilder.HttpClientConfigCallback() {
                    @Override
                    public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder) {
                        return httpClientBuilder
                            .setDefaultCredentialsProvider(credentialsProvider)
                            .setSSLContext(sslContext)                          // Set the SSLContext.
                            .setSSLHostnameVerifier(NoopHostnameVerifier.INSTANCE);  // Skip hostname verification.
                    }
                }).build();

        ElasticsearchTransport transport = new RestClientTransport(restClient, new JacksonJsonpMapper());
        ElasticsearchClient elasticsearchClient = new ElasticsearchClient(transport);
        
        // Perform operations.
        System.out.println(elasticsearchClient.info());
        
        transport.close();
        restClient.close();
    }
}

Python

These examples use ES 8.17.0. Replace with your cluster version.

pip install elasticsearch==8.17.0from elasticsearch import Elasticsearch
es = Elasticsearch(
    hosts=['https://<YourEsHost>:9200'],  # Use 'https://' for public HTTPS access or 'http://' for private HTTP access.
    basic_auth=('<UserName>', '<YourPassword>'),
)
print(es.info())

from elasticsearch import Elasticsearch
import urllib3
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)  # Disable SSL warnings (optional).

es = Elasticsearch(
    hosts=['https://<YourEsHost>:9200'],
    basic_auth=('<UserName>', '<YourPassword>'),
    verify_certs=False,           # Skip certificate verification.
    ssl_show_warn=False,          # Disable SSL warnings.
)
print(es.info())

Go

These examples use the Elasticsearch Go Client for ES 8.x clusters.

go get github.com/elastic/go-elasticsearch/v8
package main

import (
    "github.com/elastic/go-elasticsearch/v8""log"
)

func main() {
    cfg := elasticsearch.Config{
        Addresses: []string{"https://<YourEsHost>:9200"},  // Use "https://" for public HTTPS access or "http://" for private HTTP access.
        Username:  "<UserName>",
        Password:  "<YourPassword>",
    }
    es, _ := elasticsearch.NewClient(cfg)
    res, _ := es.Info()
    defer res.Body.Close()
    log.Println(res)
}

package main

import (
    "crypto/tls""net/http""github.com/elastic/go-elasticsearch/v8""log"
)

func main() {
    cfg := elasticsearch.Config{
        Addresses: []string{"https://<YourEsHost>:9200"},
        Username:  "<UserName>",
        Password:  "<YourPassword>",
        Transport: &http.Transport{
            TLSClientConfig: &tls.Config{InsecureSkipVerify: true},  // Skip certificate verification.
        },
    }
    es, _ := elasticsearch.NewClient(cfg)
    res, _ := es.Info()
    defer res.Body.Close()
    log.Println(res)
}

FAQ

If the cluster status is healthy but the client cannot connect, troubleshoot using the following methods.

route -n

curl -u {UserName}:{YourPassword} https://{YourEsHost}:9200

RestClient restClient = RestClient.builder(new HttpHost("{YourEsHost}", 9200, "https"))
    .setRequestConfigCallback(builder -> builder
        .setConnectTimeout(10000)
        .setSocketTimeout(30000))
    .setHttpClientConfigCallback(httpClientBuilder ->
        httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider))
    .build();