Hold Up!
Bonsai clusters can be provisioned in a few different ways. These instructions are for Heroku users. If you have an account on Bonsai.io, then you will not need these instructions. Instead, check out:
Heroku makes it quick and easy to get started with Bonsai.
1. Install Bonsai
Adding Bonsai to your app automatically creates a cluster for you. It also adds a variable called BONSAI_URL to your application’s environment, which will contain the canonical URL and credentials to your cluster. This automation makes it fast and easy to get started with your new cluster.
Our Heroku Add-on
We offer a free Hobby plan for development and testing on Heroku. A list of all available plans and capacities can be found at https://elements.heroku.com/addons/bonsai.
There are two ways to add Bonsai to your Heroku app:
1. Through the Heroku CLI tool
2. Through the Heroku app dashboard
Using the Heroku CLI tool
You can add Bonsai to your app with this command:
$ heroku addons:add bonsai
----- Adding bonsai to some-appname-4005... done, v18 (free)
You can verify that the operation was successful by running heroku config:get BONSAI_URL:
$ heroku config:get BONSAI_URL
----- http://username:password@redwood-12345.us-east-1.bonsai.io/
If this value is null, then Bonsai was not properly added to your account. Try again and look for error messages. If you still have problems, give us a shout.
Once the Add-on has been successfully added, you can check on the status of your cluster by running $ heroku addons:open bonsai -a
Specifying a Search Engine
Bonsai supports multiple search engines. The default is Elasticsearch, which will be used if nothing is specified on creation. Users can specify which search engine to use with the --engine parameter. To use it on the command line, you would use something like this:
heroku addons:create bonsai:[plan] [-a APP_NAME] [--engine=elasticsearch]
Allowed values are: "elasticsearch" and "opensearch".
Adding a specific version of a Search Engine
You have a fair amount of flexibility to choose the search engine version your cluster can run. There is a command line flag for specifying which version to use. This flag is called --version , and it can be invoked in a couple different ways. To use it on the command line, you would use something like this:
heroku addons:create bonsai:[plan] [-a APP_NAME] [--version=X.Y]
Bonsai only supports certain versions of a given search engine, so users cannot provision any version. If you request a version that is not available, Bonsai will default to the latest available version.
There is a list of available versions documented here: Supported Elasticsearch Versions. In short, the options available will be determined by three factors:
- Region. Your cluster will be provisioned in the same AWS region where your Heroku app is located. However, some regions support more versions than other regions, based on demand.
- Plan. Versions are rolled out to Hobby and Staging tier plans in advance of Production grade plans. Additionally, older versions of Elasticsearch may only be supported on Business tier plans.
- Age. Bonsai will occasionally deprecate older versions of Elasticsearch. If you need a version of Elasticsearch that is no longer supported, the only way to get it will be to upgrade to a Business plan.
The version and engine parameters also work in your app.json, if you use PR apps and Heroku pipelines:
{
"name": "Small Sharp Tool",
"description": "This app does one little thing, and does it well.",
"keywords": [
"productivity",
"HTML5",
"scalpel"
],
"addons" : [
{
"plan": "bonsai:hobby",
"options": {
"version": "6.5.4",
"engine": "elasticsearch"
}
}
]
}
To view a list of our current supported regions, see our documentation here:
For further help with your app.json and addons, see Heroku’s documentation here:
Using the Heroku dashboard
To add Bonsai through the Heroku UI, open up your application in the Heroku dashboard
Click on either the Resources tab, or the “Configure Add-ons” link. This menu will have a search bar for various Add-ons. Begin typing “bonsai,” and the autocomplete will find the Bonsai Elasticsearch Add-on:
Click on the Add-on to add it to your application. This will bring up a new screen where you will be able to select a payment plan for your new cluster. See the Bonsai Heroku Add-ons page for details about what each plan offers.
When you are ready, click on “Provision.” Your new cluster will be instantly created. Your dashboard will now show this:
When Bonsai is added to your application, a new environment variable called BONSAI_URL is created and initialized with the URL to your cluster. This is the URL that you will need in order to interact with your cluster.
Your application should be configured to read this URL directly from the environment, and should not be hard-coded or shared with others. If you would like to confirm that Elasticsearch is up and running, you can retrieve the URL by clicking no the Settings tab in the Heroku Dashboard.
There will be a section called “Config Vars”:
Click on “Reveal Config Vars” to see your environment variables. This will reveal the value of each variable like so:
You can copy the contents of the BONSAI_URL to your clipboard and paste it into a browser or curl command to see the response from Elasticsearch:
$ curl https://username:password@somehost-1234567.us-east-1.bonsai.io
{
"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"
}
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.
2. Scale Your Cluster
When it’s time to scale, you can easily upgrade your shared plan, or migrate to a dedicated cluster.
How to Update Your Cluster Plan
Note on plan changes
Most plan changes take effect instantly. However, if you’re trying to upgrade or downgrade across an architecture class, there will be a delay in processing.
Updating your cluster plan with Heroku is fairly simple. You can do this in either of two ways:
- Through the Heroku CLI tool
- Through the Heroku UI - your app dashboard
Using the Command Line
You can view all of our available plans for Heroku users on the Bonsai Heroku Add-on page:
From there, choose the plan you’d like to change your cluster to and note the plan slug. For example, our Standard SM has a plan slug of standard-sm, our Private Compute LG has a slug of private-compute-lg, etc. Open up your project in a terminal and run:
If you have several applications with Bonsai Add-ons, you can specify which one you would like to upgrade or downgrade with the -a flag:
$ heroku addons:upgrade bonsai:standard-sm -a mycoolelasticsearchapp
Using the Heroku app Dashboard
Log into your Heroku account and open your app dashboard. In this example, the app is called mycoolelasticsearchapp:
Click on the Resources tab to view your Add-ons:
You’ll see a list of your Add-ons, with a carot menu on the far right side.
Clicking on the carot icon will open up a dropdown menu. Select Modify Plan to open a modal, and you can choose a new plan for your cluster:
How Heroku Handles Billing
Heroku handles all of the billing, and prorates by the second.
A contrived example: a customer signs up for a $50/mo plan at 00:00:00, then decides to upgrade to a $150 plan at 00:10:30, then downgrades back down to a $50 plan at 01:00:00, then destroys it at 02:45:00. The customer’s bill would be roughly calculated as:
- 630s on a $50/mo plan = $0.012
- 2970s on a $150/mo plan = $0.17
- 6300s on a $50/mo plan = $0.12
- Total: $0.30
This amount would be added to the customer’s next invoice from Heroku.
Migrating Across Architectures
Bonsai offers two main architecture classes: multi-tenant and single tenant. The multi-tenant class – sometimes called “shared” – is designed to allow clusters to share hardware resources while still being sandboxed from one another. This allows us to provide unparalleled performance per dollar in a way that’s also extremely affordable.
The single tenant class – sometimes called “dedicated” – maps one cluster to a private set of hardware resources. Because these resources are not shared with any other cluster, single tenant configurations provide maximum performance for a slightly higher price.
Plan changes within the multi-tenant class take place instantly. However, moving a cluster from one class to another will take some time. This is because data will need to be moved across a network boundary and search resources may need to be created.
In other words, if a customer upgrades from a “Shared” plan to a “Dedicated,” the Bonsai app will need to provision and configure new private servers, wait for them to come online and pass health checks, then migrate their cluster’s data out of the multi-tenant class and into their new single tenant class.
Alternately, if a customer downgrades from a “Dedicated” plan to a “Shared” plan, a data migration will need to be performed, and the old servers torn down.
The time required for these migrations can vary. If you have questions or concerns, please send us a note at support@bonsai.io
3. Remove the Bonsai Add-on
Bonsai Elasticsearch can be removed via the command line or Heroku’s app Dashboard.
Danger!
This will destroy all associated data and cannot be undone!
Using the Command Line
The Bonsai Add-on can be removed from the application via Heroku’s command line tool:
heroku addons:destroy bonsai ----- Removing bonsai from sharp-mountain-4005... done, v20 (free)
This will destroy the cluster and all of its data instantly.
Using the Heroku Dashboard
To remove the Bonsai Add-on from the Heroku Dashboard, log in to your Heroku account and click on the app the Add-on is attached to. In this example, that Add-on is mycoolelasticsearchapp:
Next, click on the Resources tab:
Find the Bonsai Add-on in the list of application Add-ons, then click the carot menu:
Select “Delete Add-on” from the list of options. You will need to type in the app’s name to confirm the removal of the Bonsai Add-on:
Click on “Remove Add-on” to complete the process.