Terraform provider

About 7 min

Terraform provider

Event Store Cloud provider for Terraform is available in the public provider registry.

Provider documentation is available there as well, on the Documentation tab.

Installation

The current version of the provider is: 1.5.29. The releases are available in Terraform official registry and via GitHub releases.

The binaries are available for the following platforms:

Processor	Operating system	Filename
x64	macOS	`terraform-provider-eventstorecloud_{{ $frontmatter.terraform_current_version }}_darwin_amd64.zip`
x64	FreeBSD	`terraform-provider-eventstorecloud_{{ $frontmatter.terraform_current_version }}_freebsd_amd64.zip`
x64	Linux	`terraform-provider-eventstorecloud_{{ $frontmatter.terraform_current_version }}_linux_amd64.zip`
x64	Windows	`terraform-provider-eventstorecloud_{{ $frontmatter.terraform_current_version }}_windows_amd64.zip`
arm64	FreeBSD	`terraform-provider-eventstorecloud_{{ $frontmatter.terraform_current_version }}_freebsd_arm64.zip`
arm64	Linux	`terraform-provider-eventstorecloud_{{ $frontmatter.terraform_current_version }}_linux_arm64.zip`

Terraform 0.13+

Terraform supports third party modules installed via the plugin registry. Add the following to your terraform module configuration:

terraform {
  required_providers {
    eventstorecloud = {
      source  = "EventStore/eventstorecloud"
      version = "~>1.5.0"
    }
  }
}

Terraform 0.12

In order for Terraform to find the plugin, place the appropriate binary into the Terraform third-party plugin directory. The location varies by operating system:

Linux and macOS ~/.terraform.d/plugins
Windows %APPDATA%\terraform.d\plugins

Alternatively, the binary can be placed alongside the main terraform binary.

You can download the provider using the following commands:

Linux

curl -o ./terraform-provider-eventstorecloud.zip -L \
  https://github.com/EventStore/terraform-provider-eventstorecloud/releases/download/v1.5.12/terraform-provider-eventstorecloud_1.5.12_linux_amd64.zip
unzip ./terraform-provider-eventstorecloud.zip
mv ./terraform-provider-eventstorecloud ~/.terraform.d/plugins/terraform-provider-eventstorecloud

macOS

curl -o ./terraform-provider-eventstorecloud.zip -L \
  https://github.com/EventStore/terraform-provider-eventstorecloud/releases/download/v1.5.12/terraform-provider-eventstorecloud_1.5.12_darwin_amd64.zip
unzip ./terraform-provider-eventstorecloud.zip
mv ./terraform-provider-eventstorecloud ~/.terraform.d/plugins/terraform-provider-eventstorecloud

Windows

$source="https://github.com/EventStore/terraform-provider-eventstorecloud/releases/download/v1.5.12/terraform-provider-eventstorecloud_1.5.12_windows_amd64.zip"
$zip= "./terraform-provider-eventstorecloud.zip"
$tfPlugin="$env:APPDATA/terraform.d/plugins/terraform-provider-eventstorecloud/"
Invoke-WebRequest -Uri $source -OutFile $zip
Expand-Archive -Path $zip -DestinationPath $tfPlugin

Building from source

If you prefer to install from source, use the make install target in this repository. You will need a Go 1.13+ development environment.

Provider configuration

The Event Store Cloud provider must be configured with an access token. There are several additional options that may be useful. Provider configuration options are:

Option	Environment Variable	Description
`token`	`ESC_TOKEN`	Required, your access token for Event Store Cloud.
`organization_id`	`ESC_ORG_ID`	Required, your Event Store Cloud organization ID.
`url`	`ESC_URL`	Optional, the URL of the Event Store Cloud API. This defaults to the public cloud instance of Event Store Cloud.
`token_store`	`ESC_TOKEN_STORE`	Optional, the location on the local filesystem of the token cache. This is shared with the Event Store Cloud CLI.

Obtaining the access token

You can use the Event Store Cloud console or the Event Store Cloud CLI (esc-cli) to obtain a token

Use the following command to get the access token using esc-cli:

$ esc access tokens create --email <email>

Password:
Token created for audience https://api.eventstore.cloud
FDGco0u_1Ypw9WVVIfAHtIJh0ioUI_XbMhxMlEpiCUlHR

If you prefer to use the Cloud Console, navigate to the Authentication Tokens page, then click on "Request refresh token" button.

Obtaining the organisation ID

As for the token, you can use the Cloud Console, or esc-cli to get the organisation ID.

That's how you do it with esc-cli:

$ esc resources organizations list
Organization { id: OrgId("9bdf0s5qr76g981z5820"), name: "Event Store Ltd"

In the Cloud Console, open the organisations page. Then, select the organisation from the list and go to its settings. There, you can copy the organisation ID.

Resources

All resources in Event Store Cloud can be provisioned using the Terraform provider. Existing projects can be queried using a data source in the provider. More complete samples can be found here.

Using the Terraform provider, you can create, manipulate, and delete the following resources in Event Store Cloud:

Terraform resource	Event Store Cloud resource
`eventstorecloud_project`	Project
`eventstorecloud_network`	Network
`eventstorecloud_peering`	Network peering
`eventstorecloud_managed_cluster`	Managed EventStoreDB instance or cluster

You can create Event Store Cloud projects for the organisation using the eventstorecloud_project resource. You only need to provide the new project name, which must be unique within the organisation.

You need a project to provision any other resource.

Arguments

Name	Type	Description
`name`	`string`	Required, the name of the project.

Attributes

The Project Terraform resource will get the following attributes:

Name	Type	Description
`id`	`string`	Project ID

You will need the project ID to provision other resources within the project.

Creating a project

Here is an example of a Terraform script to create a project in Event Store Cloud:

resource "eventstorecloud_project" "production" {
  name = "Production Project"
}

Networks

Before provisioning a database cluster, you need a network, which the cluster will connect to. Use the eventstorecloud_network resource to provision a new Event Store Cloud network. The network should be in the same cloud provider, which you plan to use for the database cluster.

Arguments

Name	Type	Description
`name`	`string`	Required, the new network name.
`project_id`	`string`	Required, the project ID of the new network (see Projects)
`resource_provider`	`string`	Required, the network cloud provider (`aws`, `gcp`, `azure`).
`region`	`string`	Required, the cloud region of the new network (cloud provider-specific).
`cidr_block`	`string`	Required, the new network IP range.

Attributes

Name	Type	Description
`id`	`string`	The project ID

Region names must be in the format used by the cloud resource provider, for example us-west-2 for AWS, East US for Azure, us-east1 for GCP.

Note For the IP range, the maximum prefix length is /9 and the minimum is /24. However, cloud providers have their own limitations on the network ranges they support. Learn more in your cloud provider documentation:

Smaller networks can hold fewer managed clusters, but may be easier to peer to infrastructure hosting your applications.

Creating a network

resource "eventstorecloud_project" "production" {
  name = "Production Project"
}
resource "eventstorecloud_network" "production_network" {
  name              = "Production Network"
  project_id        = data.eventstorecloud_project.production.id
  resource_provider = "aws"
  region            = "us-west-2"
  cidr_block        = "172.21.0.0/16"
}

Network peerings

When you got a network provisioned, you can already start creating database clusters. However, you won't be able to connect to your new cluster, unless you create a peering link between the network in Event Store Cloud, and the network on your own cloud account or project.

Use the eventstorecloud_peering resource to initiate the peering link. You will need to collect the details about your own cloud network (VPC or Virtual Network) as described in the arguments list below. Depending on the cloud provider, you'll need to complete some actions on your side to confirm the peering.

At the moment, you can only peer the networks, which are in the same cloud region.

Tips

The format of the following arguments depends on the cloud provider:

peer_account_id
peer_network_region
peer_network_id

Arguments

Name	Type	Description
`name`	`string`	Required, the new peering name.
`project_id`	`string`	Required, the project ID for the new peering.
`network_id`	`string`	Required, the EventStore Cloud network ID, for which the peering will be created.
`peer_resource_provider`	`string`	Required, the cloud resource provider of the given network (`aws`, `gcp`, `azure`).
`peer_network_region`	`string`	Required, the cloud region of your own network, which you are going to peer with.
`peer_account_id`	`string`	Required, your cloud account ID, your cloud network should belong to that account.
`peer_network_id`	`string`	Required, the network ID for your own cloud network.
`routes`	`string`	Required, CIDR blocks in your cloud network, which should be routed to the Event Store Cloud network.

Use the following provider-specific values for the peer_account_id argument:

Cloud	Account ID is
AWS	Account ID
GCP	Project ID
Azure	Tenant ID

For the peer_network_id, use the following cloud network property:

Cloud	Network ID is
AWS	VPC ID
GCP	VPC name
Azure	Virtual network resource ID

Tips

peer_resource_provider - currently, this must be the same as the resource provider of the Event Store Cloud network.
peer_network_region - currently, this must be the same as the region of the Event Store Cloud network, and specified in the format used by your cloud. For example us-west-2 for AWS, westus2 for Azure and us-east1 for GCP
routes - typically, this consists of one element, the address space of a subnet in your managed network.

Attributes

After completing the operation, the peering Terraform resource will get the following attributes:

Name	Type	Description
`id`	`string`	The peering ID.
`provider_metadata`	`string`	The peering resource metadata, set by the cloud provider.
`aws_peering_link_id`	`string`	The AWS peering link ID.
`gcp_project_id`	`string`	GCP project ID.
`gcp_network_name`	`string`	GCP VPC name.
`gcp_network_id`	`string`	GCP network ID in URL format, which can be passed to `google_compute_network_peering` resources.

For AWS, you'd need to confirm the peering request, use the aws_peering_link_id resource attribute for that purpose.

For GCP, you need to initiate a peering from your cloud account to Event Store Cloud. Use the resource attributes with gcp prefix to automate that part.

Creating a peering

Here is an example how to initiate a peering from Event Store Cloud to your own AWS account:

resource "eventstorecloud_project" "production" {
  name = "Production Project"
}

resource "eventstorecloud_network" "production" {
  name = "Production Network"

  project_id = data.eventstorecloud_project.production.id

  resource_provider = "aws"
  region            = "us-west-2"
  cidr_block        = "172.21.0.0/16"
}

resource "eventstorecloud_peering" "production" {
  name = "Peering from AWS into Production Network"

  project_id = eventstorecloud_network.Production.project_id
  network_id = eventstorecloud_network.Production.id

  peer_resource_provider = eventstorecloud_network.Production.resource_provider
  peer_network_region    = eventstorecloud_network.Production.region

  peer_account_id = "<Customer AWS Account ID>"
  peer_network_id = "<Customer VPC ID>"
  routes          = ["<Address space of the customer VPC>"]
}

Managed EventStoreDB

Use the eventstorecloud_managed_cluster resource to provision an EventStoreDB cluster or instance. You will need the Project and the Network resource information from previously created resources.

Arguments

Name	Type	Description
`name`	`string`	Required, the name of the managed. cluster.
`project_id`	`string`	Required, the ID of the project in which the managed cluster should be created.
`network_id`	`string`	Required, the ID of the EventStore Cloud network into which the managed cluster should be created.
`topology`	`string`	Required, the topology of the managed cluster. This determines the fault tolerance of the cluster. Valid values are `single-node` and `three-node-multi-zone`.
`instance_type`	`string`	Required, the size of the instances to use in the managed cluster.
`disk_size`	`int`	Required, the size of the data disks in gigabytes. Minimal size is 10Gb. All cluster members will get a disk of the same size.
`disk_type`	`string`	Required, `GP2`, `GP3` (AWS), `premium-ssd-lrs` (Azure), `ssd` (GCP).
`disk_iops`	`int`	Optional, the number of IOPS for data disk. Required if disk_type is `GP3`.
`disk_throughput`	`int`	Optional, throughput in MB/s for data disk. Required if disk_type is `GP3`.
`server_version`	`string`	Required, `20.6`, `20.10`, `21.6`, `21.10`.
`projection_level`	`string`	Optional, default: `off` , the mode in which to enable projections. Valid values are `off` , `system` , `user`.

Supported instance sizes are:

Size	Specification
`F1`	2 vCPU 1Gb RAM (burstable instance, not suitable for production)
`C4`	2 vCPU 8Gb RAM
`M8`	2 vCPU 8Gb RAM (same resources as `C4`, but storage-optimised)
`M16`	4 vCPU 16Gb RAM
`M32`	8 vCPU 32Gb RAM
`M64`	16 vCPU 64Gb RAM
`M128`	32 vCPU 128Gb RAM

Tips

The actual implementation of each topology is specific to the resource provider.

For GCP and AWS clusters you can resize the disks without downtime. In Azure, it is currently not supported, please plan the disk size according to your projected database size.

Attributes

After completing the operation, the EventStoreDB cluster Terraform resource will get the following attributes:

Name	Type	Description
`id`	`string`	the ID of the cluster.
`dns_name`	`string`	the DNS name at which the cluster can be found.
`resource_provider`	`string`	the resource provider into which the cluster was provisioned.
`region`	`string`	the region in which the cluster was provisioned.
`gcp_network_name`	`string`	network name for the peering link in GCP.
`gcp_network_id`	`string`	GCP Network ID in URL format which can be passed to `google_compute_network_peering` resources.

Tips

Attribute values for region and resource_provider are controlled by the network in which the cluster is created.

Creating a cluster

Here are the cloud-specific examples of a Terraform script to create a managed EventStoreDB cluster:

AWS

data "eventstorecloud_project" "production" {
  name = "Production Project"
}

resource "eventstorecloud_network" "production" {
  name              = "Production Network"
  project_id        = data.eventstorecloud_project.production.id
  resource_provider = "aws"
  region            = "us-west-2"
  cidr_block        = "172.21.0.0/16"
}

resource "eventstorecloud_managed_cluster" "production" {
  name             = "Production Cluster"
  project_id       = eventstorecloud_project.Production.project_id
  network_id       = eventstorecloud_network.Production.id
  topology         = "three-node-multi-zone"
  instance_type    = "F1"
  disk_size        = 10
  disk_type        = "gp3"
  disk_iops        = 3000
  disk_throughput  = 125
  server_version   = "21.10"
  projection_level = "user"
}

Azure

data "eventstorecloud_project" "production" {
  name = "Production Project"
}

resource "eventstorecloud_network" "production" {
  name              = "Production Network"
  project_id        = data.eventstorecloud_project.production.id
  resource_provider = "azure"
  region            = "westus2"
  cidr_block        = "172.21.0.0/16"
}

resource "eventstorecloud_managed_cluster" "production" {
  name             = "Production Cluster"
  project_id       = eventstorecloud_project.Production.project_id
  network_id       = eventstorecloud_network.Production.id
  topology         = "three-node-multi-zone"
  instance_type    = "F1"
  disk_size        = 10
  disk_type        = "premium-ssd-lrs"
  server_version   = "21.10"
  projection_level = "user"
}

GCP

data "eventstorecloud_project" "production" {
  name = "Production Project"
}

resource "eventstorecloud_network" "production" {
  name              = "Production Network"
  project_id        = data.eventstorecloud_project.production.id
  resource_provider = "gcp"
  region            = "us-central1"
  cidr_block        = "172.21.0.0/16"
}

resource "eventstorecloud_managed_cluster" "production" {
  name             = "Production Cluster"
  project_id       = eventstorecloud_project.Production.project_id
  network_id       = eventstorecloud_network.Production.id
  topology         = "three-node-multi-zone"
  instance_type    = "F1"
  disk_size        = 10
  disk_type        = "ssd"
  server_version   = "21.10"
  projection_level = "user"
}

Data sources

The following data source is available:

Terraform resource	Event Store Cloud resource
`eventstorecloud_project`	Project

Project

Use the eventstorecloud_project data source to query your Event Store Cloud projects.

Arguments

Name	Type	Description
name	string	Required, the name of the project.
id	string	Optional, the name of the project.

Looking up a project

# This assumes a project with the name "Production" exists
data "eventstorecloud_project" "production" {
  name = "Production Project"
}
output "project_id" {
  value = data.eventstorecloud_project.production.id
}

Tips

The value of eventstorecloud_project.name is case-sensitive, so Production Project is not the same as ^production project.

FAQ

Error error obtaining access token: error 400 requesting access token

You need to add the access token to your environment variables or the provider configuration. See here.

Error ... Forbidden: Access to the requested method for the requested resources was denied

Make sure you used the correct organisation ID. Use these guidelines to get the correct value.

Error Your query returned no results. Please change your search criteria and try again.

Ensure you entered the correct project name. Remember that data source names are case-sensitive. See here.