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:
<div class="code-snippet-container">
<a fs-copyclip-element="click-2" href="#" class="btn w-button code-copy-button" title="Copy">
<img class="copy-image" src="https://global-uploads.webflow.com/63c81e4decde60c281417feb/6483934eeefb356710a1d2e9_icon-copy.svg" loading="lazy" alt="">
<img class="copied-image" src="https://assets-global.website-files.com/63c81e4decde60c281417feb/64839e207c2860eb9e6aa572_icon-copied.svg" loading="lazy" alt="">
</a>
<div class="code-snippet">
<pre><code fs-codehighlight-element="code" fs-copyclip-element="copy-this-2" class="hljs language-javascript">https://a1b2c3d4e:5f6g7h8i9@somehost-1234567.region-x-y.bonsaisearch.net
</code></pre>
</div>
</div>
This URL has the following parts:
Let's examine these in greater detail.
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:
<table>
<thead>
<tr>
<th>Port</th><th>Protocol</th><th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td>80</td><td>HTTP</td><td>Unencrypted</td>
</tr>
<tr>
<td>443</td><td>HTTPS</td><td>Default; recommended</td>
</tr>
<tr>
<td>9200</td><td>HTTP</td><td>Unencrypted</td>
</tr>
<tr>
<td>9300</td><td>Elasticsearch Native Binary Protocol</td><td>Not supported</td>
</tr>
</tbody>
</table>
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.
When your cluster is created, it is provided with a randomly generated set of credentials. In the example URL above, the API Key is <span class="inline-code"><pre><code>a1b2c3d4e</code></pre></span> and the API Secret is <span class="inline-code"><pre><code>5f6g7h8i9</code></pre></span>. 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.)
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.
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.
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.
Each Bonsai cluster has a unique hostname. In the example above, this is <span class="inline-code"><pre><code>somehost-1234567</code></pre></span>. 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.
When asking questions via our support channels, you may provide the unique identifier portion of your hostname (e.g., <span class="inline-code"><pre><code>somehost-1234567</code></pre></span>) to help us cross-reference with your account and your cluster's logs.
All Bonsai clusters have a region slug included in the URL. Some example slugs might be:
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.
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:
<div class="code-snippet-container">
<a fs-copyclip-element="click-3" href="#" class="btn w-button code-copy-button" title="Copy">
<img class="copy-image" src="https://global-uploads.webflow.com/63c81e4decde60c281417feb/6483934eeefb356710a1d2e9_icon-copy.svg" loading="lazy" alt="">
<img class="copied-image" src="https://assets-global.website-files.com/63c81e4decde60c281417feb/64839e207c2860eb9e6aa572_icon-copied.svg" loading="lazy" alt="">
</a>
<div class="code-snippet">
<pre><code fs-codehighlight-element="code" fs-copyclip-element="copy-this-3" class="hljs language-javascript">https://a1b2c3d4e:5f6g7h8i9@somehost-1234567.region-x-y.bonsaisearch.net
https://a1b2c3d4e:5f6g7h8i9@somehost-1234567.region-x-y.bonsai.io
</code></pre>
</div>
</div>
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.
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:
<div class="code-snippet-container">
<a fs-copyclip-element="click-4" href="#" class="btn w-button code-copy-button" title="Copy">
<img class="copy-image" src="https://global-uploads.webflow.com/63c81e4decde60c281417feb/6483934eeefb356710a1d2e9_icon-copy.svg" loading="lazy" alt="">
<img class="copied-image" src="https://assets-global.website-files.com/63c81e4decde60c281417feb/64839e207c2860eb9e6aa572_icon-copied.svg" loading="lazy" alt="">
</a>
<div class="code-snippet">
<pre><code fs-codehighlight-element="code" fs-copyclip-element="copy-this-4" class="hljs language-javascript">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"
}
</code></pre>
</div>
</div>
Curl can be used to create and remove indices, add data, check on cluster state and more:
<div class="code-snippet-container">
<a fs-copyclip-element="click-5" href="#" class="btn w-button code-copy-button" title="Copy">
<img class="copy-image" src="https://global-uploads.webflow.com/63c81e4decde60c281417feb/6483934eeefb356710a1d2e9_icon-copy.svg" loading="lazy" alt="">
<img class="copied-image" src="https://assets-global.website-files.com/63c81e4decde60c281417feb/64839e207c2860eb9e6aa572_icon-copied.svg" loading="lazy" alt="">
</a>
<div class="code-snippet">
<pre><code fs-codehighlight-element="code" fs-copyclip-element="copy-this-5" class="hljs language-javascript"># 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}
</code></pre>
</div>
</div>
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:
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.
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.
