Recipes

Working configurations for the things people actually build.

Working configurations for the things people actually build.

A cache, with the endpoint wired into something else

The common case: one database, and an application that needs to reach it.

resource "kividb_instance" "cache" {
  name         = "orders-cache"
  tier         = "essentials"
  cloud        = "aws"
  region       = "us-east-1"
  data_size_gb = 8
}

output "cache_endpoint" {
  value = kividb_instance.cache.endpoint
}

endpoint is known only after the database is ready, which is why the apply waits by default. Anything that consumes it — a task definition, a Kubernetes secret, an app config — can depend on it directly and Terraform will order things correctly.

High availability

resource "kividb_instance" "primary" {
  name          = "orders-primary"
  tier          = "pro"
  cloud         = "aws"
  region        = "us-east-1"
  data_size_gb  = 8
  replica_count = 2
  tls_enabled   = true
}

Pro gives you a writer and two read replicas with automatic failover. Mind the per-cloud minimum: 4 GB on AWS, 8 GB on Azure and Google Cloud.

The same database on several clouds

Nothing moves a database between clouds, so a multi-cloud setup is one database per cloud. A map plus for_each keeps it to one block:

variable "deployments" {
  type = map(object({
    cloud  = string
    region = string
    size   = number
  }))
  default = {
    us = { cloud = "aws", region = "us-east-1", size = 8 }
    eu = { cloud = "azure", region = "swedencentral", size = 8 }
    gc = { cloud = "gcp", region = "us-central1", size = 8 }
  }
}

resource "kividb_instance" "regional" {
  for_each = var.deployments

  name          = "orders-${each.key}"
  tier          = "pro"
  cloud         = each.value.cloud
  region        = each.value.region
  data_size_gb  = each.value.size
  replica_count = 1
}

output "endpoints" {
  value = { for k, v in kividb_instance.regional : k => v.endpoint }
}

Changing a value in that map is an in-place resize. Changing a cloud or region is a replacement, and it destroys the data — which is the honest outcome, because there is no operation that moves a database.

Environments

Use workspaces and let the name carry the environment, so two environments cannot collide on a name that must be unique across KiviDB:

locals {
  env = terraform.workspace
}

resource "kividb_instance" "app" {
  name          = "orders-${local.env}"
  tier          = local.env == "prod" ? "pro" : "essentials"
  cloud         = "aws"
  region        = "us-east-1"
  data_size_gb  = local.env == "prod" ? 16 : 2
  replica_count = local.env == "prod" ? 2 : 0
}

Keep separate API keys per environment. A key is scoped to one organization, so a production key in a staging pipeline is the mistake this prevents.

Taking a snapshot before a risky change

resource "kividb_disk_snapshot" "pre_upgrade" {
  instance_id = kividb_instance.app.id
  label       = "pre-upgrade"
}

resource "kividb_instance" "app" {
  # ...
  kividb_version = "1.1.0"
  depends_on     = [kividb_disk_snapshot.pre_upgrade]
}

Adopting databases that already exist

Write the configuration to match what is there, then import:

$ terraform import kividb_instance.cache 790df3ae-c064-45f5-b924-9ed89471fd72
$ terraform plan
No changes. Your infrastructure matches the configuration.

No changes is the goal. If the plan wants to modify something, your configuration disagrees with reality — fix the configuration, not the database. If it wants to replace something, stop and look: you have probably written a different region or aof_enabled than the database actually has.

For several databases, import blocks let you do it in one plan:

import {
  to = kividb_instance.cache
  id = "790df3ae-c064-45f5-b924-9ed89471fd72"
}

Reading a database you do not manage

data "kividb_instance" "shared" {
  id = "790df3ae-c064-45f5-b924-9ed89471fd72"
}

output "shared_endpoint" {
  value = data.kividb_instance.shared.endpoint
}

Useful when one team owns the database and another needs to point at it.

Running in CI

Use an API key with the admin role, from your CI secret store, as KIVIDB_API_KEY. Never in a .tf file and never as a Terraform variable — a variable ends up in state in plain text.

- name: terraform apply
  env:
    KIVIDB_API_KEY: ${{ secrets.KIVIDB_API_KEY }}
  run: terraform apply -auto-approve

For a pipeline that should only ever report, use a member key. It can read and plan but not modify, so an accidental apply fails instead of changing production.

A key is bound to one organization and has no person behind it, so it cannot do the things that need an identity — the free tier, for one, which is one per person and created while signed in.

Things worth not doing

Do not put the API key in a variable. State is not a secret store.

Do not approve a plan that says must be replaced unless you mean it. For a database, replacement destroys the data. The attributes that cause it are cloud, region, aof_enabled and tls_only.

Do not destroy and recreate under the same name in one apply. Deletion is accepted immediately and continues in the background, so the create can race the teardown. Use a different name, or apply twice.

Do not point a kividb_disk_snapshot at a different database to "move" it. That destroys the existing snapshot and takes a new one — you lose the restore point you were keeping.