Timescale Terraform Provider

The Terraform provider for Timescale.

Does not work for Managed Service for TimescaleDB.

Requirements

• Terraform >= 1.0

Quick Start

Authorization

When you log in to your Timescale Account, navigate to the Project settings page. From here, you can create client credentials for programmatic usage. Click the Create credentials button to generate a new public/secret key pair.

Find more information on creating Client Credentials in the Timescale docs.

Example file and usage

The project ID can be found from the Services dashboard. In the upper right-hand side of the page, click on the three vertical dots to view the project ID.

Note

The example file creates:

• A single instance called tf-test that contains:
  • 0.5 CPUs
  • 2GB of RAM
  • the region set to us-west-2
  • a HA replica
  • the connection pooler enabled
• Outputs to display the connection info for:
  • the primary hostname and port
  • the ha-replica hostname and port
  • the pooler hostname and port

Into a new folder, create the main.tf file:

terraform {
  required_providers {
    timescale = {
      source  = "registry.terraform.io/providers/timescale"
      version = "~> 1.0"
    }
  }
}

provider "timescale" {
  project_id = var.ts_project_id
  access_key = var.ts_access_key
  secret_key = var.ts_secret_key
}

variable "ts_project_id" {
  type = string
}

variable "ts_access_key" {
  type = string
}

variable "ts_secret_key" {
  type = string
}

resource "timescale_service" "tf-test" {
  name                      = "tf-test"
  milli_cpu                 = 500
  memory_gb                 = 2
  region_code               = "us-west-2"
  connection_pooler_enabled = true
  enable_ha_replica         = true
}

## host connection info
output "host_addr" {
  value       = timescale_service.tf-test.hostname
  description = "Service Host Address"
}

output "host_port" {
  value       = timescale_service.tf-test.port
  description = "Service Host port"
}

## ha-replica connection info
output "replica_addr" {
  value       = timescale_service.tf-test.replica_hostname
  description = "Service Replica Host Address"
}

output "replica_port" {
  value       = timescale_service.tf-test.replica_port
  description = "Service Replica Host port"
}

## pooler connection info
output "pooler_addr" {
  value       = timescale_service.tf-test.pooler_hostname
  description = "Service Pooler Host Address"
}

output "pooler_port" {
  value       = timescale_service.tf-test.pooler_port
  description = "Service Pooler Host port"
}

and define the secret.tfvars file:

ts_project_id="WWWWWWWWWW"
ts_access_key="XXXXXXXXXXXXXXXXXXXXXXXXXX"
ts_secret_key="YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY"

Important

Replace the values above with the the ts_project_id, the ts_access_key, and ts_secret_key

Now use the terraform cli with the secrets.tfvars file, for example:

terraform plan --var-file=secrets.tfvars

Supported Service Configurations

Compute

• 500m CPU / 2 GB Memory
• 1000m CPU / 4 GB Memory
• 2000m CPU / 8 GB Memory
• 4000m CPU / 16 GB Memory
• 8000m CPU / 32 GB Memory
• 16000m CPU / 64 GB Memory
• 32000m CPU / 128 GB Memory

Storage

Since June 2023, you no longer need to allocate a fixed storage volume or worry about managing your disk size, and you'll be billed only for the storage you actually use. See more info in our blogpost

Regions

Please reference the docs for a list of currently supported regions.

Supported Operations

✅ Create service
✅ Rename service
✅ Resize service
✅ Pause/resume service
✅ Delete service
✅ Import service
✅ Enable High Availability replicas
✅ Enable read replicas
✅ VPC peering
✅ Connection pooling

Billing

Services are currently billed for hourly usage. If a service is running for less than an hour, it will still be charged for the full hour of usage.

Local Provider Usage and Development

Requirements

• Go >= v1.20

Building The Provider

1. Clone the repository
2. Enter the repository directory
3. Build the provider using the Go install command:

go install .

Generating the provider documentation

Doc is generated from ./templates files and in-file schema definitions.

go generate

Developing the Provider

Local provider development override

Important

Change the $HOME/go/bin variable to be the location of your GOBIN if necessary.

When using the local provider, is not necessary to run terraform init.

To use the locally built provider, create a ~/.terraformrc file with the following content:

provider_installation {
  dev_overrides {
      "registry.terraform.io/providers/timescale" = "$HOME/go/bin"
  }

  direct {}
}

Runing the acceptance tests

To compile the provider, run go install. This will build the provider and put the provider binary in the $GOPATH/bin directory.

To generate or update documentation, run go generate.

In order to run the full suite of Acceptance tests, run make testacc. You'll need to set all required secrets in environment variables to allow the tests to run:

export TF_VAR_ts_project_id=<project_id>
export TF_VAR_ts_access_key=<access_key>
export TF_VAR_ts_secret_key=<secret_key>
# this is the aws account id with which you want to test establishing vpc peering
export TF_VAR_ts_aws_acc_id=<aws_acc_id>

Warning

Acceptance tests create real resources.

make testacc