TerraDB
A centralized database and REST API for Terraform data.
What is it?
TerraDB is a centralized database and REST API dedicated to hosting and serving
Terraform data. It can be used as a native HTTP backend to store Terraform
remote states.
Eventually, Terraboard will be
ported to use TerraDB as a backend, and we are also working
on InSpec plugins to perform compliance and
acceptance tests on Terraform resources.
Requirements
- A MongoDB (>= 3.4) database
Why MongoDB?
As Terraform states are json documents, we think that a document-oriented
database makes sense. We'd also like to be able to use a Database-as-a-Service
so that we don't have to manage it. Thus, MongoDB is one (if not the only)
obvious choice. However, to avoid blocking this tool adoption because of the bad
reputation MongoDB may have to some sysadmins, we added an abstraction layer
that will easily allow to add new storage backends.
Install from code
$ go get github.com/camptocamp/terradb
Usage
Command line options
Usage:
terradb [OPTIONS]
Application Options:
-V, --version Display version.
MongoDB options:
--mongodb-url= MongoDB URL [$MONGODB_URL]
--mongodb-username= MongoDB Username [$MONGODB_USERNAME]
--mongodb-password= MongoDB Password [$MONGODB_PASSWORD]
API server options:
--api-address= Address on to bind the API server (default: 127.0.0.1) [$API_ADDRESS]
--api-port= Port on to listen (default: 8080) [$API_PORT]
--page-size= Page size for list results (default: 100) [$API_PAGE_SIZE]
Help Options:
-h, --help Show this help message
As a docker container
$ docker run -e MONGODB_URL="mongodb://mongo" \
-e MONGODB_USERNAME="user" \
-e MONGODB_PASSWORD="pass" \
-e API_ADDRESS="0.0.0.0" \
-p 8080:8080 camptocamp/terradb
You can use TerraDB as an HTTP remote backend for Terraform:
terraform {
backend "http" {
address = "http://<terradb>:<port>/v1/states/<name>"
lock_address = "http://<terradb>:<port>/v1/states/<name>"
unlock_address = "http://<terradb>:<port>/v1/states/<name>"
}
}
Note: do not use the /
character in the project name.
API Documentation
The current API root is /v1
.
Below is a list of endpoints, usable with the GET
verb.
Endpoints returning lists are paginated; the page number and total number of results
appear in a metadata
section of the results.
/states
Returns the latest serial of each state stored in the database, along with its
lock information.
/states/{name}
Returns the latest serial of a single state by its name, along with its lock
information.
/states/{name}/serials
Returns all serials of a single state by its name. Lock information is not
provided.
/resources/${state}/${module}/${name}
/resources/${state}/${name}
Architecture schema
Planned plugins
Grafana datasource
With a Grafana datasource we'll be able, among other, to display the plan status
in a nice dashboard.
Terraboard
We plan to use TerraDB as a backend for Terrboard.
Prometheus Service Discovery
We could use TerraDB as a source for a Service Discovery to populate Prometheus' targets.
InSpec
We'd like to use TerraDB to make InSpec assertions. For example, verify that all resources of one kind on a cloud account are managed by Terraform.