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.