Bonsai has created and supports a Terraform Provider to enable creation and management of Bonsai Elasticsearch and OpenSearch Clusters from within your infrastructure as code.
Terraform is an infrastructure as code (IaC) tool designed to define and manage both cloud and on-premises resources through human-readable configuration files. These files can be versioned, reused, and shared, enabling streamlined collaboration and iterative development. Bonsai has created and supports a Terraform Provider to enable creation and management of Bonsai Elasticsearch and OpenSearch Clusters from within your infrastructure as code.
The Bonsai Terraform Provider works by integrating with the Bonsai REST API via the (also newly created) Bonsai Cloud Go API Client. To create resources with the Bonsai API, you'll need a way to authenticate your requests. Currently, both the Bonsai Go API Client and the Bonsai Terraform Provider support HTTP Basic Authentication over TLS, using an API Key and Secret Token combination.
To generate an API Key and Secret Token, head over to your account's API Tokens overview page.
and click the "Generate Token" button.
More in-depth instructions are available at the Bonsai Documentation site!
Next, you'll need to configure the Bonsai Terraform Provider with the API Key and Token pair generated in the previous step.
There are two options here:
Choose an option that best fits your use case, and you're ready to start creating Elasticsearch and OpenSearch clusters!
# provider.tf
# Configure the Bonsai Provider using the required_providers stanza.
terraform {
required_providers {
bonsai = {
source = "omc/bonsai"
version = "~> 1.0"
}
}
}
provider "bonsai" {
# Default: The Bonsai Terraform Provider will fetch the api_key configuration
# value from the BONSAI_API_KEY environment variable.
#
# Uncomment the following line to set directly via variable.
# api_key = var.bonsai_api_key
# Default: The Bonsai Terraform Provider will fetch the api_token configuration
# value from the BONSAI_API_TOKEN environment variable.
#
# Uncomment the following line to set directly via variable.
# api_token = var.bonsai_api_token
}
Configuring a Bonsai Elasticsearch or OpenSearch cluster is easy, we only need to make 4 decisions, reflected as Terraform Resource Attributes for our cluster:
Details about the plans, spaces, and releases available to your account are available either within the Bonsai.io control plane, via the API (we recommend using the Bonsai Cloud Go API Client), or via the Terraform Data Sources.
Here's an example of listing all available Plans, Releases, and Spaces.
Related note! You really only need to output the bonsai_plans data list, as each Plan object will embed a list of the spaces it's available in, and the various Elasticsearch/OpenSearch releases that the plan supports.
# data.tf
// Fetch all Available Bonsai Plans
data "bonsai_plans" "list" {}
// Fetch all Available Bonsai Spaces
data "bonsai_spaces" "list" {}
// Fetch all Available Bonsai Releases
data "bonsai_releases" "list" {}
// Output collected data
output "bonsai_spaces" {
value = data.bonsai_spaces.list
}
output "bonsai_release" {
value = data.bonsai_releases.list
}
output "bonsai_plans" {
value = data.bonsai_plans.list
}
With that output, we can create an optimized OpenSearch cluster that matches our needs.
Related note! We've built an awesome (if we do say so ourselves...) interactive tool to help you estimate the best plan for your use-case! We're also always happy to help your team navigate the sizing process, reach out to us via the Support button in your console!
# main.tf
resource "bonsai_cluster" "test" {
name = "Terraform Created Cluster"
plan = {
slug = "sandbox"
}
space = {
path = "omc/bonsai/us-east-1/common"
}
release = {
slug = "opensearch-2.6.0-mt"
}
}
And finally, we'll configure our infrastructure data output, so that we can reference our newly created cluster directly in the rest of our infrastructure.
Related note! If you're wondering what the sensitive = true configuration does below, it's required because the cluster's user and password are treated as sensitive outputs by the provider.
If you don't mark their output as sensitive, you'll receive an error to reduce the risk of accidentally exporting sensitive information as plain text!
We also recommend encrypting your Terraform state at rest, and if possible, before storage.
output "bonsai_cluster_id" {
value = bonsai_cluster.test.id
}
output "bonsai_cluster_name" {
value = bonsai_cluster.test.name
}
output "bonsai_cluster_host" {
value = bonsai_cluster.test.access.host
}
output "bonsai_cluster_port" {
value = bonsai_cluster.test.access.port
}
output "bonsai_cluster_scheme" {
value = bonsai_cluster.test.access.scheme
}
output "bonsai_cluster_url" {
value = bonsai_cluster.test.access.url
}
output "bonsai_cluster_slug" {
value = bonsai_cluster.test.slug
}
output "bonsai_cluster_user" {
value = bonsai_cluster.test.access.user
sensitive = true
}
output "bonsai_cluster_password" {
value = bonsai_cluster.test.access.password
sensitive = true
}
output "bonsai_cluster_state" {
value = bonsai_cluster.test.state
}
output "bonsai_cluster_stats" {
value = bonsai_cluster.test.stats
}
output "bonsai_cluster_plan" {
value = bonsai_cluster.test.plan
}
output "bonsai_cluster_release" {
value = bonsai_cluster.test.release
}
output "bonsai_cluster_space" {
value = bonsai_cluster.test.space
}
For additional details on managing your Bonsai resources with Terraform, check out our blog post, "Introducing Bonsai's Terraform Provider for Elasticsearch and OpenSearch".
Check out the Provider on GitHub and the official HashiCorp Terraform Registry!