Connecting to Bonsai

Private Networks

The information provided in this section pertains to Bonsai clusters which have been provisioned on public networks (accessible across the Internet). Bonsai clusters that are provisioned in a Vault or Heroku Private Space can not be reached in this way.

This is by design -- why put a cluster on a private network if you want to access it from anywhere? Connecting to Bonsai clusters in private networks will require a user to establish a remote connection to the VPC before being able to interact with Elasticsearch.

Every Bonsai cluster is created with a unique URL designed for secure, authenticated access to an Elasticsearch cluster. This URL allows a wide array of platforms and application clients to communicate with Elasticsearch. This URL looks something like this:

https://a1b2c3d4e:5f6g7h8i9@somehost-1234567.region-x-y.bonsaisearch.net

This URL has the following parts:

• Protocol (ex: https). The protocol to use for communicating with Elasticsearch. This can be either HTTP or HTTPS. The primary difference between the two is that HTTPS is encrypted, whereas HTTP is not. Bonsai defaults to HTTPS to ensure that your data can not be read in transit.
• Authentication Credentials (ex: a1b2c3d4e:5f6g7h8i9). This is a randomly-generated username/password pair. By default, you will need to include these credentials with every request to your cluster, otherwise Bonsai will return an HTTP 401: Authorization required message.
• Hostname (ex: something-1234567). The hostname will be a concatenated string generated by your cluster's name, and a random number. This provides some security through obscurity by making guesses and enumeration extraordinarily difficult, as well as avoiding name collisions.
• Region (ex: us-east-1). This is the region in which the cluster is provisioned. There are a number of possible regions for this, and we use the AWS naming conventions to indicate where the cluster is located.
• Domain (ex: bonsaisearch.net). Bonsai clusters can be accessed via one of two domains: bonsai.io and bonsaisearch.net. This is to avoid the rare case of a TLD outage; if the .io or .net TLD is down for some reason, the cluster can still be accessed.

Let's examine these in greater detail.

Protocols and Ports

All Bonsai clusters default to secure HTTPS using recent versions of TLS for encrypted communication. These connections should use port 443, the standard for SSL/TLS.

We also support unencrypted HTTP access over ports 80 and 9200.

You can see a table describing the protocols and ports available here:

Unfortunately we do not support the native binary protocol on 9300 at this time. If your application strongly depends on the binary protocol, please contact our sales team at info@bonsai.io to design a custom cluster deployment.

Authentication Credentials

When your cluster is created, it is provided with a randomly generated set of credentials. In the example URL above, the API Key is a1b2c3d4e and the API Secret is 5f6g7h8i9. These are often supplied to various HTTP or Elasticsearch clients as the HTTP username and password, and encoded according to the Basic Authorization scheme. (Cf. RFC 2617 Section 2.)

Credentials are Random

The cluster credentials are not the same as what you would use to log into your Bonsai/Heroku account. These are randomly generated when the cluster is created.

HTTP 401: Authentication required

If you're seeing this message, then you're not including the correct authentication credentials in your request. Double check that the request includes the credentials shown in your dashboard and try again.

Keep Your URL Secret

Because the URL includes authentication information, anyone with the fully-qualified URL can access your cluster. Treat the URL like a password: don't hard-code it into applications, don't check it into source control, and for Pete's sake, never ever paste it into a StackOverflow question. If you need to share your cluster URL with us for support purposes, the auth-less host name is all you need:

Bad: "My cluster is https://username:password@somehost-1234567.us-east-1.bonsaisearch.net"

Good: "My cluster is somehost-1234567"

If your URL is leaked somehow, you can regenerate the credentials. See the dashboard documentation for more information.

Hostname

Each Bonsai cluster has a unique hostname. In the example above, this is somehost-1234567. The hostname is a blend of your cluster's name along with a unique identifier. The hostname is immutable: once the cluster has been created, the hostname can not be changed. Keep this in mind when creating your cluster.

Hostnames and Support

When asking questions via our support channels, you may provide the unique identifier portion of your hostname (e.g., somehost-1234567) to help us cross-reference with your account and your cluster's logs.

Region

All Bonsai clusters have a region slug included in the URL. Some example slugs might be:

• us-east-1
• us-west-2
• eu-west-1
• ... and so on.

These slugs are based on the AWS Regions and AZs and Google Cloud Regions and Zones, and indicate where on the planet your cluster is running. Ideally, this will be as close as possible to your application servers, to minimize latency.

Domain

All Bonsai clusters can be accessed via either of two domains: bonsai.io or bonsaisearch.net. In other words, both of these URLs will work:

https://a1b2c3d4e:5f6g7h8i9@somehost-1234567.region-x-y.bonsaisearch.net
https://a1b2c3d4e:5f6g7h8i9@somehost-1234567.region-x-y.bonsai.io

This is a failover option to accommodate for the rare, but not unheard of, TLD outage. If there is an outage impacting .net or .io domains, users can point their application to whichever TLD is operational.

Connecting to Elasticsearch via Curl

One way to connect to Elasticsearch is with a command line tool called `curl`. Curl is easy to use and comes preinstalled on many operating systems (and is widely available for download and installation). Curl can send and receive data from your Bonsai Elasticsearch cluster like so:

curl https://a1b2c3d4e:5f6g7h8i9@somehost-1234567.region-x-y.bonsaisearch.net
{
  "name" : "PvRcoFq",
  "cluster_name" : "elasticsearch",
  "cluster_uuid" : "DNlbVYS0TIGYwbQ6CUNwTw",
  "version" : {
    "number" : "5.4.3",
    "build_hash" : "eed30a8",
    "build_date" : "2017-06-22T00:34:03.743Z",
    "build_snapshot" : false,
    "lucene_version" : "6.5.1"
  },
  "tagline" : "You Know, for Search"
}

Curl can be used to create and remove indices, add data, check on cluster state and more:

  # Create an index called 'test'
  curl -s -XPUT https://a1b2c3d4e:5f6g7h8i9@somehost-1234567.region-x-y.bonsaisearch.net/test
  {"acknowledged":true,"shards_acknowledged":true}

  # Add a document to the 'test' index
  curl -s -XPUT https://a1b2c3d4e:5f6g7h8i9@somehost-1234567.region-x-y.bonsaisearch.net/test/doc/1 -d '{"title":"test doc"}'
  {"_index":"test","_type":"doc","_id":"1","_version":1,"result":"created","_shards":{"total":2,"successful":2,"failed":0},"created":true}

  # Delete the 'test' index
  curl -s -XDELETE https://a1b2c3d4e:5f6g7h8i9@somehost-1234567.region-x-y.bonsaisearch.net/test
  {"acknowledged":true}

Connecting to Elasticsearch via Browser

Another way to connect to Elasticsearch is via your browser of choice. Simply copy the full URL from the Bonsai dashboard, and paste it into the browser's address bar. It should look something like this:

HTTP 401: Authorization required When Using a Browser

Some browsers, as a security feature, will strip the authentication credentials from the URL to prevent them from being displayed in the address bar. The credentials are stored in a local session. However, if you subsequently copy/paste the URL from the address bar, it will drop the credentials. There are some other conditions that can cause the credentials to be lost from the active window.

If you're using a browser to interact with Elasticsearch and you are seeing HTTP 401 errors, try to copy/paste the credentials back into the address bar.

This method is good for reading the cluster state, but not so great for creating indices, updating data, etc.

Connecting to Elasticsearch via Interactive Console

The Bonsai dashboard offers an interactive console which allows users to engage with their cluster. This console simplifies the process of communicating with the cluster, and it obviates the need for dealing with credentials altogether

It should be noted that Bonsai offers Private Spaces and when a space is private the Interactive Console is not accessible.