Skip to main content

Cluster API Introduction

Rob Sears

Alpha Stage

The Bonsai API is currently in its Alpha release phase. It may not be feature-complete, and is subject to change without notice. If you have any questions about the roadmap of the API, please reach out to support.

The Clusters API provides a means of managing clusters on your account. This API supports the following actions:

  • View all clusters in your account
  • View a single cluster in your account
  • Create a new cluster
  • Update a cluster in your account
  • Destroy a cluster in your account

All calls to the Clusters API must be authenticated with an active API token.

The Bonsai Cluster Object

The Bonsai API provides a standard format for Cluster objects. A Cluster object includes:

Attribute Description
slug A string representing a unique, machine-readable name for the cluster. A cluster slug is based its name at creation, to which a random integer is concatenated.
name A string representing the human-readable name of the cluster.
uri A URI to get more information about this cluster.
plan An Object with some information about the cluster's current subscription plan. This hash has two keys:

  • slug. The unique, machine-readable name of the plan.
  • uri. A URI to retrieve more information about this plan.

You can see more details about the plan by passing the slug to the Plans API.

release An Object with some information about the cluster's current release. This hash has five keys:

  • version. The version of the release this cluster is running on.
  • slug. The unique slug of the release. 
  • package_name. The package name of the release.
  • service_type. The name of the search service.
  • uri. A URI to retrieve more information about this plan.

You can see more details about the release by passing the slug to the Releases API.

space An Object with some information about where the cluster is running. This has three keys:

  • path. The path to the space. This string maps to a geographic region or data center.
  • region. The geographic region in which the cluster is running.
  • uri. A URI with more information about the space

You can see more details about the space by passing the path to the Spaces API.

stats An Object with a collection of statistics about the cluster. This hash has four keys:

  • docs. The number of documents in the index.
  • shards_used. The number of shards the cluster is using.
  • data_bytes_used. Integer representing the number of bytes the cluster is using on disk.

This attribute should not be used for real-time monitoring! Stats are updated every 10-15 minutes. To monitor real-time metrics, monitor your cluster directly, via the Index Stats API.
access An Object containing information about connecting to the cluster. This hash has several keys:

  • host. The host name of the cluster.
  • port. The HTTP port the cluster is running on.
  • scheme. The HTTP scheme needed to access the cluster (defaults to "https")
state A String representing the current state of the cluster. This indicates what the cluster is doing at any given moment. There are 8 defined states:

  • DEPROVISIONED. The cluster has been destroyed.
  • DEPROVISIONING. The cluster is in the process of being destroyed.
  • DISABLED. The cluster has been disabled.
  • MAINTENANCE. The cluster is in maintenance mode.
  • PROVISIONED. The cluster has been created and is ready for use.
  • PROVISIONING. The cluster is in the process of being created.
  • READONLY. The cluster is in read only mode.
  • UPDATING PLAN. The cluster's plan is being updated.

View all clusters

The Bonsai API provides a method to get a list of all active clusters on your account. An HTTP GET call is made to the /clusters endpoint, and Bonsai will return a JSON list of Cluster objects. This API call will not return deprovisioned clusters. This call uses pagination, so you may need to make multiple requests to fetch all clusters.

Supported Parameters (Query String Parameters)
Param Description
q Optional. A query string for filtering matching clusters. This currently works on name
tenancy Optional. A string which will constrain results to parent or child cluster. Valid values are: parent, child
location Optional. A string representing the account, region, space, or cluster path where the cluster is located. You can get a list of available spaces with the Spaces API. Space path prefixes work here, so you can find all clusters in a given region for a given cloud.
HTTP Request

An HTTP GET call is made to /clusters.

HTTP Response

Upon success, Bonsai responds with an HTTP 200: OK code, along with a JSON list representing the clusters on your account:

{
  "pagination": {
    "page_number": 1,
    "page_size": 2,
    "total_records": 2
  },
  "clusters": [
    {
      "slug": "first-testing-cluste-1234567890",
      "name": "first_testing_cluster",
      "uri": "https://api.bonsai.io/clusters/first-testing-cluste-1234567890",
      "plan": {
        "slug": "sandbox-aws-us-east-1",
        "uri": "https://api.bonsai.io/plans/sandbox-aws-us-east-1"
      },
      "release": {
        "version": "7.2.0",
        "slug": "elasticsearch-7.2.0",
	"package_name": "7.2.0",
	"service_type": "elasticsearch",
        "uri": "https://api.bonsai.io/releases/elasticsearch-7.2.0"
      },
      "space": {
        "path": "omc/bonsai/us-east-1/common",
        "region": "aws-us-east-1",
        "uri": "https://api.bonsai.io/spaces/omc/bonsai/us-east-1/common"
      },
      "stats": {
        "docs": 0,
        "shards_used": 0,
        "data_bytes_used": 0
      },
      "access": {
        "host": "first-testing-cluste-1234567890.us-east-1.bonsaisearch.net",
        "port": 443,
        "scheme": "https"
      },
      "state": "PROVISIONED"
    },
    {
      "slug": "second-testing-clust-1234567890",
      "name": "second_testing_cluster",
      "uri": "https://api.bonsai.io/clusters/second-testing-clust-1234567890",
      "plan": {
        "slug": "sandbox-aws-us-east-1",
        "uri": "https://api.bonsai.io/plans/sandbox-aws-us-east-1"
      },
      "release": {
        "version": "7.2.0",
        "slug": "elasticsearch-7.2.0",
	"package_name": "7.2.0",
	"service_type": "elasticsearch",
        "uri": "https://api.bonsai.io/releases/elasticsearch-7.2.0"
      },
      "space": {
        "path": "omc/bonsai/us-east-1/common",
        "region": "aws-us-east-1",
        "uri": "https://api.bonsai.io/spaces/omc/bonsai/us-east-1/common"
      },
      "stats": {
        "docs": 0,
        "shards_used": 0,
        "data_bytes_used": 0
      },
      "access": {
        "host": "second-testing-clust-1234567890.us-east-1.bonsaisearch.net",
        "port": 443,
        "scheme": "https"
      },
      "state": "PROVISIONED"
    }
  ]
}

View a single cluster

The Bonsai API provides a method to retrieve information about a single cluster on your account.
Supported Parameters

No parameters are supported for this action.

HTTP Request

An HTTP GET call is made to  /clusters/[:slug].

HTTP Response

Upon success, Bonsai will respond with an HTTP 200: OK code, along with a JSON body representing the Cluster object:

{
  "cluster": {
    "slug": "second-testing-clust-1234567890",
    "name": "second_testing_cluster",
    "uri": "https://api.bonsai.io/clusters/second-testing-clust-1234567890",
    "plan": {
      "slug": "sandbox-aws-us-east-1",
      "uri": "https://api.bonsai.io/plans/sandbox-aws-us-east-1"
    },
    "release": {
      "version": "7.2.0",
      "slug": "elasticsearch-7.2.0",
      "package_name": "7.2.0",
      "service_type": "elasticsearch",
      "uri": "https://api.bonsai.io/releases/elasticsearch-7.2.0"
    },
    "space": {
      "path": "omc/bonsai/us-east-1/common",
      "region": "aws-us-east-1",
      "uri": "https://api.bonsai.io/spaces/omc/bonsai/us-east-1/common"
    },
    "stats": {
      "docs": 0,
      "shards_used": 0,
      "data_bytes_used": 0
    },
    "access": {
      "host": "second-testing-clust-1234567890.us-east-1.bonsaisearch.net",
      "port": 443,
      "scheme": "https"
    },
    "state": "PROVISIONED"
  }
}

Create a new cluster

The Bonsai API provides a method to create new clusters on your account. An HTTP POST call is made to the /clusters endpoint, and Bonsai will create the cluster.

Supported Parameters
Param Description
name Required. A String representing the name for your new cluster.
plan A String representing the slug of the new plan for your cluster. You can get a list of available plans via the Plans API.
space A String representing the Space slug where the new cluster will be created. You can get a list of available spaces with the Spaces API.
release A String representing the search service release to use. You can get a list of available versions with the Releases API.
HTTP Request

An HTTP POST call is made to /clusters along with a JSON payload of the supported parameters.

HTTP Response

Bonsai will respond with an HTTP 202: Accepted code, along with a short message and details about the cluster that was created:

{
  "message": "Your cluster is being provisioned.",
  "monitor": "https://api.bonsai.io/clusters/test-5-x-3968320296",
  "access": {
    "user": "utji08pwu6",
    "pass": "18v1fbey2y",
    "host": "test-5-x-3968320296",
    "port": 443,
    "scheme": "https",
    "url": "https://utji08pwu6:18v1fbey2y@test-5-x-3968320296.us-east-1.bonsaisearch.net:443"
  },
  "status": 202
}
Error
An HTTP 422 Unprocessable Entity error may arise if you are trying to create one too many Sandbox clusters on your account: 


{
  "errors": [
    "The requested plan is not available for provisioning. Solution: Please use the plans endpoint for a list of available plans.",
    "Your request could not be processed. "
  ],
  "status":422
}

If you are not creating a Sandbox cluster, please refer to the API Error 422: Unprocessable Entity documentation.

Update a cluster

The Bonsai API provides a method to update the name or plan of your cluster. An HTTP PUT call is made to the /clusters endpoint, and Bonsai will update the cluster. 

Supported Parameters
Param Description
name A String representing the new name for your cluster. Changing the cluster name will not change its URL.
plan A String representing the slug of the new plan for your cluster. Updating the plan may trigger a data migration. You can get a list of available plans via the Plans API.
HTTP Request

To make a change to an existing cluster, make an HTTP PUT call to  /clusters/[:slug] with a JSON body for one or more of the supported params.

HTTP Response

Bonsai will respond with an HTTP 202: Accepted code, along with short message:

{
    "message": "Your cluster is being updated.",
    "monitor": "https://api.bonsai.io/clusters/[:slug]",
    "status": 202
}

Destroy a cluster

The Bonsai API provides a method to delete a cluster from your account.

Supported Parameters

No parameters are supported for this action.

HTTP Request

An HTTP DELETE call is made to the  /clusters/[:slug] endpoint.

HTTP Response

Bonsai will respond with an HTTP 202: Accepted code, along with a short message: 

{
    "message": "Your cluster is being deprovisioned.",
    "monitor": "https://api.bonsai.io/clusters/[:slug]",
    "status": 202
}

Related articles