Automations

In addition to the Cloud console, Event Store Cloud provides the API, a Terraform provider, a Pulumi provider, as well as a CLI tool to automate any operation accessible from the console.

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.12. 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_1.5.12_darwin_amd64.zip
x64	FreeBSD	terraform-provider-eventstorecloud_1.5.12_freebsd_amd64.zip
x64	Linux	terraform-provider-eventstorecloud_1.5.12_linux_amd64.zip
x64	Windows	terraform-provider-eventstorecloud_1.5.12_windows_amd64.zip
arm64	FreeBSD	terraform-provider-eventstorecloud_1.5.12_freebsd_arm64.zip
arm64	Linux	terraform-provider-eventstorecloud_1.5.12_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:

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

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

$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

Projects

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:

• AWS VPC Addressing
• Azure Virtual Network FAQ
• GCP VPC Network

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.

TIP

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

TIP

• 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

TIP

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.

TIP

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:

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"
}

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"
}

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
}

TIP

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.