Manage KiviDB with Terraform
Murtaza Shajapurwala ·
Today we're launching the KiviDB Terraform provider. Your KiviDB Cloud databases can now live in the same configuration as the rest of your infrastructure, on AWS, Azure or Google Cloud.
It's published on the Terraform Registry as kividbio/kividb.
terraform {
required_providers {
kividb = {
source = "kividbio/kividb"
version = "~> 0.2"
}
}
}
provider "kividb" {}
resource "kividb_instance" "cache" {
name = "orders-cache"
tier = "essentials"
cloud = "aws"
region = "us-east-1"
data_size_gb = 8
}
export KIVIDB_API_KEY=kvdb_live_...
terraform apply
One configuration, three clouds
A map and for_each give you the same database on every cloud. Here's a real plan from that configuration, one Pro database each on AWS, Azure and Google Cloud:
variable "deployments" {
default = {
us = { cloud = "aws", region = "us-east-1" }
eu = { cloud = "azure", region = "swedencentral" }
gc = { cloud = "gcp", region = "us-central1" }
}
}
resource "kividb_instance" "orders" {
for_each = var.deployments
name = "orders-${each.key}"
tier = "pro"
cloud = each.value.cloud
region = each.value.region
data_size_gb = 8
replica_count = 1
}

endpoint is known once the database is ready, and the apply waits for that by default. Anything that needs the endpoint, like a Kubernetes secret, a task definition or an app config, can depend on it directly.
The plan tells you the truth
KiviDB doesn't have a general "update this database" call, and the provider doesn't pretend it does. Each attribute maps to the operation that actually changes it, and the ones nothing can change are marked as replacements:
| Change | What happens |
|---|---|
name | Renamed in place |
data_size_gb, throughput_mode | Resized in place |
replica_count | Scaled in place, 1 to 3 |
tier | Upgraded in place |
kividb_version, lua_enabled, tls_enabled | Applied with a rolling restart |
cloud, region, aof_enabled, tls_only | Replaces the database |
Nothing moves a database between clouds or regions, so changing region plans a destroy and a create, and the plan says so in plain words. Read any plan that says must be replaced before you approve it: for a database, replacement means new, empty storage.
An update also waits for the change to actually take effect. If a resize is accepted but doesn't land, the apply fails and names the attribute that's still wrong, instead of reporting success over a database that didn't change.
Snapshots as configuration
kividb_disk_snapshot takes a named, point-in-time copy. The useful pattern is taking one right before something you might want to undo, and letting Terraform enforce the order:
resource "kividb_disk_snapshot" "pre_upgrade" {
instance_id = kividb_instance.app.id
label = "pre-upgrade"
}
resource "kividb_instance" "app" {
# ...
kividb_version = "1.0.5"
depends_on = [kividb_disk_snapshot.pre_upgrade]
}
For recurring backups, use scheduled snapshots in the console. They run without an apply and are kept according to their retention.
Bring what you already have
Databases you created in the console can be adopted without touching them. Write the configuration to match, import, and look for No changes:
terraform import kividb_instance.cache 790df3ae-c064-45f5-b924-9ed89471fd72
terraform plan
# No changes. Your infrastructure matches the configuration.
The kividb_instance data source reads a database you don't manage, which helps when one team owns it and another needs its endpoint.
Keys, roles and CI
The provider authenticates with a KiviDB API key in KIVIDB_API_KEY. The key carries the organization and the role, so there's no account id, region or endpoint to configure.
- An admin key can create and change databases. Use it for the pipeline that applies.
- A member key can read and plan but not change anything. Use it for pipelines that should only report, so an accidental
applyfails instead of touching production. - Keep the key in your CI secret store, never in a
.tffile or a Terraform variable. Variables end up in state, in plain text.
- name: terraform apply
env:
KIVIDB_API_KEY: ${{ secrets.KIVIDB_API_KEY }}
run: terraform apply -auto-approve
A revoked key fails at terraform plan with a message saying so, not halfway through an apply.
Get started
- Registry: registry.terraform.io/providers/kividbio/kividb
- Docs: KiviDB with Terraform, the
kividb_instanceresource, recipes - Mint an API key in the console under API keys.