Terraform Provider

The VeloDB Terraform provider manages VeloDB Cloud warehouses, compute clusters, network access, PrivateLink registrations, and connection metadata through the VeloDB Cloud Management API.

Get started

Step 1: Create an API key

1. Log in to the VeloDB Cloud console.
2. In the upper-left corner, click the organization name to open the Organization Overview page.
3. In the left navigation pane, click Organization Settings.
4. In the API Keys section, click Manage Keys to open the API Keys page.
5. Click + Create API Key, choose the least-privileged role and an expiration, then copy the key immediately. It is shown only once.

Store the key in an environment variable, not in Terraform files or source control:

export VELODB_API_KEY='key-...'

Step 2: Set the API host

The VeloDB Cloud Management API host is api.velodb.cloud. Set it as an environment variable:

export VELODB_HOST='api.velodb.cloud'

Note:

host is a bare hostname. Do not include https://. The provider adds it automatically.

Step 3: Configure Terraform

Declare the provider in your Terraform configuration:

terraform {
  required_providers {
    velodb = {
      source  = "velodb/velodb"
      version = "~> 1.1"
    }
  }
}

provider "velodb" {
  host    = var.velodb_host
  api_key = var.velodb_api_key
}

variable "velodb_host" {
  type        = string
  description = "VeloDB Cloud Management API host, without https://."
  default     = "api.velodb.cloud"
}

variable "velodb_api_key" {
  type        = string
  description = "VeloDB Cloud Management API key."
  sensitive   = true
}

You can also pass credentials via environment variables directly, without declaring variables:

export VELODB_HOST='api.velodb.cloud'
export VELODB_API_KEY='key-...'
terraform plan

Example usage

Create a SaaS warehouse with an initial compute cluster:

resource "velodb_warehouse" "analytics" {
  name            = "analytics"
  deployment_mode = "SaaS"
  cloud_provider  = "aws"
  region          = "us-east-1"
  admin_password  = var.admin_password

  initial_cluster {
    zone         = "us-east-1a"
    compute_vcpu = 4
    cache_gb     = 100

    auto_pause {
      enabled              = true
      idle_timeout_minutes = 30
    }
  }
}

Add a compute cluster:

resource "velodb_cluster" "etl" {
  warehouse_id  = velodb_warehouse.analytics.id
  name          = "etl"
  cluster_type  = "COMPUTE"
  zone          = "us-east-1a"
  compute_vcpu  = 8
  cache_gb      = 200
  desired_state = "running"
}

Read connection information for applications and automation:

data "velodb_warehouse_connections" "analytics" {
  warehouse_id = velodb_warehouse.analytics.id
}

output "jdbc_urls" {
  value = [
    for ep in data.velodb_warehouse_connections.analytics.public_endpoints :
    ep.url if ep.protocol == "jdbc"
  ]
}

Import an existing BYOC warehouse:

import {
  to = velodb_warehouse.byoc
  id = "AWVA7PYB"
}

resource "velodb_warehouse" "byoc" {
  name            = "test_cli"
  deployment_mode = "BYOC"
  cloud_provider  = "aws"
  region          = "us-east-1"
}

Create a BYOC warehouse using existing cloud credentials 、network configuration and an initial compute cluster:

resource "velodb_warehouse" "byoc" {
  name            = "analytics-byoc"
  deployment_mode = "BYOC"
  cloud_provider  = "aws"
  region          = "us-east-1"
  admin_password  = var.admin_password

  setup_mode        = "advanced"
  vpc_mode          = "existing"
  credential_id     = var.credential_id
  network_config_id = var.network_config_id
  # Optional
  # tde_encryption_key_id = var.tde_encryption_key_id
  # ebs_encryption_key_id = var.ebs_encryption_key_id

  initial_cluster {
    zone         = "us-east-1a"
    compute_vcpu = 4
    cache_gb     = 100

    auto_pause {
      enabled              = true
      idle_timeout_minutes = 30
    }
  }
    # Optional
    #tags = {
    # environment = "production"
    #  managed_by  = "terraform"
    #}
}

Resources

Resource	Purpose
velodb_warehouse	Create, update, and delete SaaS warehouses; import and read existing BYOC warehouses.
velodb_cluster	Manage COMPUTE clusters inside a warehouse, including resize, pause, resume, and reboot.
velodb_warehouse_public_access_policy	Manage public endpoint access policy and CIDR allowlists.
velodb_warehouse_private_endpoint	Register and describe inbound PrivateLink endpoints for warehouse access.
velodb_private_link_endpoint_service	Register external endpoint services that VeloDB Cloud can access through PrivateLink.

Data sources

Data source	Purpose
velodb_warehouses	List warehouses by ID, name, cloud provider, region, or deployment mode.
velodb_clusters	List clusters in a warehouse by ID, name, status, type, or billing model.
velodb_warehouse_connections	Read public/private endpoints, compute clusters, observer groups, and PrivateLink service names.
velodb_warehouse_versions	List valid warehouse upgrade target version IDs.
velodb_private_link_endpoint_services	List outbound PrivateLink endpoint services and connected endpoints.

Known limitations

• BYOC warehouses can be created, imported, and read with this provider.
• setup_mode supports guided and advanced.
• vpc_mode supports new and existing, and applies only when setup_mode = "guided".
• tde_encryption_key_id, ebs_encryption_key_id, and tags are optional.
• Advanced setup is currently supported only for AWS and requires credential_id and network_config_id.
• velodb_cluster manages COMPUTE clusters only. SQL and OBSERVER cluster types are blocked at plan time.
• CPU and cache resize are applied one dimension at a time. When increasing compute_vcpu, set cache_gb to the minimum for the new CPU size, then apply any additional cache-only change in a later run.
• admin_password is write-only in the API and is stored in Terraform state as a sensitive value so Terraform can detect password rotation.