# Terraform provider

# Installation

The current version of the provider is: 1.5.1. The releases are available in Terraform official registry (opens new window) and via GitHub releases (opens new window).

The binaries are available for the following platforms:

Processor Operating system Filename
x64 macOS terraform-provider-eventstorecloud_1.5.1_darwin_amd64.zip
x64 FreeBSD terraform-provider-eventstorecloud_1.5.1_freebsd_amd64.zip
x64 Linux terraform-provider-eventstorecloud_1.5.1_linux_amd64.zip
x64 Windows terraform-provider-eventstorecloud_1.5.1_windows_amd64.zip
arm64 FreeBSD terraform-provider-eventstorecloud_1.5.1_freebsd_arm64.zip
arm64 Linux terraform-provider-eventstorecloud_1.5.1_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.1/terraform-provider-eventstorecloud_1.5.1_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.1/terraform-provider-eventstorecloud_1.5.1_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.1/terraform-provider-eventstorecloud_1.5.1_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
    // Make sure to add code blocks to your code group

    # Building from source

    If you prefer to install from source, use the make install target in this repository (opens 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:

    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 (opens new window) or the Event Store Cloud CLI (opens new window) (esc-cli) to obtain a token

    Use the following command to ge 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 (opens 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"
    

    In the Cloud Console, open the organisations page (opens 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 here (opens new window).

    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:

    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 (AWS), premium-ssd-lrs (Azure), ssd (GCP).
    server_version string Required, 20.6 , 20.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 = "gp2"
        server_version = "20.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 = "20.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 = "20.10"
        projection_level = "user"
      }
      // Make sure to add code blocks to your code group

      # 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.

      Last Updated: 3/18/2021, 10:11:16 AM