Terraform

To deploy RavenDB using Terraform, you need:

• RavenDB license

  • Find here what features are supported by each RavenDB license, and acquire the product that suits your needs.
  • The license you acquire will be provided to RavenDB via the Terraform configuration file to validate your product and determine which of its features would be enabled.

• Hosts
  RavenDB can be hosted by both on-premise servers and cloud instances.

  • Make sure you have the IP addresses and SSH keys of the servers or cloud instances intended to host RavenDB nodes.
  • Cloud providers that support Terraform are listed in Terraform's providers list.

• Terraform Configuration File

  • Learn here the basics of Terraform's configuration language.
  • Read below how to set the configuration file to provision RavenDB.

• Terraform Application
  The Terraform application is executed via CLI to apply the infrastructure configuration.

  • Download the application here.
  • Learn to use it here.

• A Terraform configuration file is defined in a simple declarative language.

  • The configuration file defines your desired infrastructure topology.
    It does not specify the actions required to apply this infrastructure.

• When the configuration file is applied, Terraform will -

  • Compare the current infrastructure state with your design.
  • Figure out what actions need to be taken and create an execution plan.
  • Create, Update, and Destroy infrastructure resources by the execution plan, until the infrastructure's state matches the requested configuration.

Provider

Use the provider object to set RavenDB as the provider.

Note that the version number relates to the RavenDB Terraform Provider version, not to the RavenDB Product version (that is defined in the resource block's package field).

provider "ravendb" {
  version = "1.0.2"
}

Terraform Local Parameters

Use the locals block to define local configuration properties that your resources definitions will be able to refer, including:

locals {
    # Node Tags
    # The tags that will be given to cluster nodes.
    nodes = toset([
        "a", "b", "c"
    ])

    # Hosts IPs
    # IP addresses of host servers that RavenDB cluster nodes will be deployed to
    hosts = [
        "3.95.238.149", 
        "3.87.248.150", 
        "3.95.220.189" 
    ]

    # Node IPs
    # For an Unsecure Setup
    ravendb_nodes_urls_unsecure = [
        "http://3.95.238.149:8080", 
        "http://3.87.248.150:8080", 
        "http://3.95.220.189:8080"
    ]
  
    # Node Addresses 
    # For a Secure Setup
    ravendb_nodes_urls_secure = [
        "https://a.domain.development.run", 
        "https://b.domain.development.run", 
        "https://c.domain.development.run" 
    ]
}

RavenDB Resource

Use the resource block to define your RavenDB node, its hosts, and its properties.
Terraform will use this resource to create your cluster nodes.

resource "ravendb_server" "server" {

    # Host IP addresses (see Terraform Local Parameters above) (Required)
    # Type: list
    hosts = local.hosts

    # RavenDB Database Name. If the database doesn't exist, it will be created (Optional)
    # Type: string
    database = "sampleDB"

    # Setup Type (Optional)
    # false => Secure RavenDB server (Recommended)
    # true => Unsecure RavenDB server (Not Recommended)
    # Type: bool
    unsecured = false

    # The path to a setup zip file used by RavenDB for a secure cluster setup (Optional)
    # Type: string
    cluster_setup_zip  = "/path/to/cluster/setup.zip"
        package {
        # RavenDB version (Required)
        # Type: string
        version = "6.0.1"

        # Processor Architecture (Optional)
        # Type: string
        arch = "arm64"

        # Ubuntu Version (Optional)
        # Type: string
        UbuntuVersion  = "20.04"
    }

    url {
        # Nodes URLs (see Terraform Local Parameters above) (Required)
        # Type: list(string)
        list = local.ravendb_nodes_urls_secure

        # HTTP port (Optional)
        # Type: int
        http_port = 8080

        # TCP port (Optional)
        # Type: int
        tcp_port = 38880
    }
  
    # Path to RavenDB product license (Required)
    # Type: filebase64
    license = filebase64("/path/to/license.json")
  
    # Settings defined here will override settings set by settings.json
    # Optional
    settings_override = {
        "Indexing.MapBatchSize": 16384
    }
  
    # Paths to files you want to upload to the server for future usage (Optional)
    # Left side of the equation: Server path (absolute) to load to 
    # Right side of the equation: Original file path (absolute)
    assets = {
        "/path/to/file/file_name.extension" = filebase64("/path/to/file_name.extension")
    }
  
    # A User name and a path to an Access Key to your server (Required)
    ssh {
        user = "ubuntu"
        pem  = filebase64("/path/to/server.pem")
    }
}

Terraform Output Values

Defining Output Values makes Terraform return values you're interested in after applying your configuration.

# Return a list of installed RavenDB instances 
output "public_instance_ips" {
    value = local.list
}

# Verify that a database with the defined name exists 
output "database_name" {
    value = ravendb_server.server.database
}

To apply your configuration, pass your configuration file to the Terraform application via CLI.

• Learn here to make the application parse your configuration and create an execution plan.
• Learn Here to execute the actions proposed in the execution plan.
• Learn Here to destroy your infrastructure (e.g. if you created it as a temporary testing environment).