Automations

In addition to the Cloud consoleopen in new window, Event Store Cloud provides the API, a Terraform provider, a Pulumi provideropen in new window, as well as a CLI toolopen in new window to automate any operation accessible from the console.

Terraform provider

Event Store Cloud provider for Terraform is available in the public provider registryopen in new window.

Provider documentation is available there as well, on the Documentation tabopen in new window.

Installation

The current version of the provider is: 1.5.7. The releases are available in Terraform official registryopen in new window and via GitHub releasesopen in new window.

The binaries are available for the following platforms:

ProcessorOperating systemFilename
x64macOSterraform-provider-eventstorecloud_1.5.7_darwin_amd64.zip
x64FreeBSDterraform-provider-eventstorecloud_1.5.7_freebsd_amd64.zip
x64Linuxterraform-provider-eventstorecloud_1.5.7_linux_amd64.zip
x64Windowsterraform-provider-eventstorecloud_1.5.7_windows_amd64.zip
arm64FreeBSDterraform-provider-eventstorecloud_1.5.7_freebsd_arm64.zip
arm64Linuxterraform-provider-eventstorecloud_1.5.7_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"
    }
  }
}
1
2
3
4
5
6
7
8

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.4/terraform-provider-eventstorecloud_1.5.4_linux_amd64.zip
unzip ./terraform-provider-eventstorecloud.zip
mv ./terraform-provider-eventstorecloud ~/.terraform.d/plugins/terraform-provider-eventstorecloud
1
2
3
4
curl -o ./terraform-provider-eventstorecloud.zip -L \
  https://github.com/EventStore/terraform-provider-eventstorecloud/releases/download/v1.5.4/terraform-provider-eventstorecloud_1.5.4_darwin_amd64.zip
unzip ./terraform-provider-eventstorecloud.zip
mv ./terraform-provider-eventstorecloud ~/.terraform.d/plugins/terraform-provider-eventstorecloud
1
2
3
4
$source="https://github.com/EventStore/terraform-provider-eventstorecloud/releases/download/v1.5.4/terraform-provider-eventstorecloud_1.5.4_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
1
2
3
4
5

Building from source

If you prefer to install from source, use the make install target in this repositoryopen in new window. 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:

OptionEnvironment VariableDescription
tokenESC_TOKENRequired, your access token for Event Store Cloud.
organization_idESC_ORG_IDRequired, your Event Store Cloud organization ID.
urlESC_URLOptional, the URL of the Event Store Cloud API. This defaults to the public cloud instance of Event Store Cloud.
token_storeESC_TOKEN_STOREOptional, 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 consoleopen in new window or the Event Store Cloud CLIopen in new window (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
1
2
3
4
5

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

token in cloud console

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"
1
2

In the Cloud Console, open the organisations pageopen in new window. Then, select the organisation from the list and go to its settings. There, you can copy the organisation ID:

organisation id in the cloud console

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 hereopen in new window.

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

Terraform resourceEvent Store Cloud resource
eventstorecloud_projectProject
eventstorecloud_networkNetwork
eventstorecloud_peeringNetwork peering
eventstorecloud_managed_clusterManaged 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
NameTypeDescription
namestringRequired, the name of the project.
Attributes

The Project Terraform resource will get the following attributes:

NameTypeDescription
idstringProject 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"
}
1
2
3

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
NameTypeDescription
namestringRequired, the new network name.
project_idstringRequired, the project ID of the new network (see Projects)
resource_providerstringRequired, the network cloud provider (aws , gcp , azure).
regionstringRequired, the cloud region of the new network (cloud provider-specific).
cidr_blockstringRequired, the new network IP range.
Attributes
NameTypeDescription
idstringThe 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"
}
1
2
3
4
5
6
7
8
9
10

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
NameTypeDescription
namestringRequired, the new peering name.
project_idstringRequired, the project ID for the new peering.
network_idstringRequired, the EventStore Cloud network ID, for which the peering will be created.
peer_resource_providerstringRequired, the cloud resource provider of the given network (aws , gcp , azure).
peer_network_regionstringRequired, the cloud region of your own network, which you are going to peer with.
peer_account_idstringRequired, your cloud account ID, your cloud network should belong to that account.
peer_network_idstringRequired, the network ID for your own cloud network.
routesstringRequired, 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:

CloudAccount ID is
AWSAccount ID
GCPProject ID
AzureTenant ID

For the peer_network_id, use the following cloud network property:

CloudNetwork ID is
AWSVPC ID
GCPVPC name
AzureVirtual 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:

NameTypeDescription
idstringThe peering ID.
provider_metadatastringThe peering resource metadata, set by the cloud provider.
aws_peering_link_idstringThe AWS peering link ID.
gcp_project_idstringGCP project ID.
gcp_network_namestringGCP VPC name.
gcp_network_idstringGCP 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>"]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

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
NameTypeDescription
namestringRequired, the name of the managed. cluster.
project_idstringRequired, the ID of the project in which the managed cluster should be created.
network_idstringRequired, the ID of the EventStore Cloud network into which the managed cluster should be created.
topologystringRequired, 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_typestringRequired, the size of the instances to use in the managed cluster.
disk_sizeintRequired, the size of the data disks in gigabytes. Minimal size is 10Gb. All cluster members will get a disk of the same size.
disk_typestringRequired, GP2 (AWS), premium-ssd-lrs (Azure), ssd (GCP).
server_versionstringRequired, 20.6 , 20.10.
projection_levelstringOptional, default: off , the mode in which to enable projections. Valid values are off , system , user.

Supported instance sizes are:

SizeSpecification
F12 vCPU 1Gb RAM (burstable instance, not suitable for production)
C42 vCPU 8Gb RAM
M82 vCPU 8Gb RAM (same resources as C4, but storage-optimised)
M164 vCPU 16Gb RAM
M328 vCPU 32Gb RAM
M6416 vCPU 64Gb RAM
M12832 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:

NameTypeDescription
idstringthe ID of the cluster.
dns_namestringthe DNS name at which the cluster can be found.
resource_providerstringthe resource provider into which the cluster was provisioned.
regionstringthe region in which the cluster was provisioned.
gcp_network_namestringnetwork name for the peering link in GCP.
gcp_network_idstringGCP 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 = "gp2"
  server_version = "20.10"
  projection_level = "user"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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 = "20.10"
  projection_level = "user"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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 = "20.10"
  projection_level = "user"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

Data sources

The following data source is available:

Terraform resourceEvent Store Cloud resource
eventstorecloud_projectProject

Project

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

Arguments
NameTypeDescription
namestringRequired, the name of the project.
idstringOptional, 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
}
1
2
3
4
5
6
7

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.

Last Updated: 9/22/2021, 1:59:50 PM
Contributors: Alexey Zimarev, Mathew McLoughlin, oskar.dudycz, ylorph