Using Object Storage as a Terraform Backend

Civo recently made object storage generally available, which is exciting for two reasons.

The first is object storage. What’s not to love?

The second reason is the Civo Terraform provider. If you have used Terraform to provision infrastructure on Civo, you might have noticed no native way to store your Terraform state in the platform.

This tutorial teaches you how to use Civo’s object storage as a backend for Terraform state files. However, before we jump into the guide, let’s take a quick look at what Terraform state is and why it matters.

Terraform state

To keep track of the current state of your infrastructure, Terraform maintains a state. This is typically a JSON file that contains information about resources currently deployed and their dependencies. Without this, Terraform wouldn’t be able to compare the current of your infrastructure with the desired state.

Challenges of managing Terraform state locally

By default, Terraform stores its state file in the root directory where your project was initialized in a file called terraform.tfstate. This is great if you're trying to quickly spin up a few resources for testing or creating a small project. However, this approach quickly brings a new set of challenges as the size and complexity of your project grows.

One major challenge with local state files is keeping them in sync when multiple people work on the same project.

A typical way to solve this is to check it in version control with the rest of your Terraform code. This is largely discouraged because state files often contain sensitive data stored in plaintext. You can refer to this section of the Terraform documentation for more information on the types of sensitive data that can end up in your state file.

Another case where local state management falls short is the event where you lose your state file. Depending on your state file, you can reinitialize Terraform to keep your resources in sync, which is a great way to cause state drift.

Remote state management

Storing your state remotely means Terraform writes state information to a remote data store. Terraform supports Postgres, S3-compatible object stores, Consul, and Kubernetes, to mention a few.

Storing state in a central location solves the problem of keeping state in sync across teams while also addressing the issue of accidentally leaking sensitive data. Remotely storing your state also enables you to take as many backups as possible in the unfortunate event of data store deletion or data loss.

A remote backend also gives you state locking, so two people cannot write to the same state at the same time. We will enable that later in this guide.

Now that we understand what Terraform state management is and why storing your state files remotely is important, let's implement this using Civo's object storage.

Prerequisites

This tutorial assumes some familiarity with Terraform. In addition, you will also need the following:

• A Civo account
• The Civo CLI installed and authenticated
• The Terraform CLI (this guide was verified on Terraform 1.15)

Generating Object Store Credentials

We'll begin by generating object store credentials before creating the object store. Using the Civo CLI:

1civo objectstore credentials create tf-experiments

You can retrieve the access key and secret straight from the CLI, no dashboard detour needed:

1civo objectstore credential ls
2civo objectstore credential secret --access-key=<YOUR-ACCESS-KEY-ID>

Copy your Access Key ID and Secret Key, as we'll be needing these later.

Creating an Object store

Next, we create an object storage bucket and associate the credentials we generated earlier with it:

1civo objectstore create tf-store --owner-access-key tf-experiments --wait
2

This creates an object store owned by the tf-experiments credentials. Refer to the Object Store documentation for more information on object store and credentials management.

Provisioning infrastructure

Now we have an object store, the next step is to write some Terraform! In this guide, we will create a Kubernetes cluster using the Civo Terraform provider.

Create a file called main.tf and follow along with the code below:

1terraform {
2  required_providers {
3    civo = {
4      source  = "civo/civo"
5      version = "~> 1.0"
6    }
7  }
8
9
10  backend "s3" {
11    bucket = "tf-store"
12    key    = "terraform.tfstate"
13    region = "LON1"
14
15
16    endpoints = {
17      s3 = "https://objectstore.lon1.civo.com"
18    }
19
20
21    access_key = "OBJECT-STORE-ACCESS-KEY-ID"
22    secret_key = "YOUR-SECRET-KEY"
23
24
25    use_path_style              = true
26    use_lockfile                = true
27    skip_region_validation      = true
28    skip_credentials_validation = true
29    skip_metadata_api_check     = true
30    skip_requesting_account_id  = true
31    skip_s3_checksum            = true
32  }
33}
34
35
36provider "civo" {
37  # reads your API token from the CIVO_TOKEN environment variable
38  region = "LON1"
39}
40
41
42# Query xsmall instance size
43data "civo_size" "xsmall" {
44  filter {
45    key    = "type"
46    values = ["kubernetes"]
47  }
48
49
50  sort {
51    key       = "ram"
52    direction = "asc"
53  }
54}
55
56
57# Create a firewall with an inline rule for the Kubernetes API server
58resource "civo_firewall" "my-firewall" {
59  name                 = "my-firewall"
60  create_default_rules = false # needs to be false when custom rules are applied
61
62
63  ingress_rule {
64    protocol   = "tcp"
65    port_range = "6443"
66    cidr       = ["0.0.0.0/0"]
67    label      = "kubernetes-api-server"
68    action     = "allow"
69  }
70}
71
72
73# Create a cluster
74resource "civo_kubernetes_cluster" "my-cluster" {
75  name         = "my-terraform-cluster"
76  applications = "Redis"
77  firewall_id  = civo_firewall.my-firewall.id
78  pools {
79    label      = "front-end" // Optional
80    size       = element(data.civo_size.xsmall.sizes, 0).name
81    node_count = 3
82  }
83}

A couple of notes on what changed from older versions of this guide. 

The standalone civo_firewall_rule resource is deprecated, so the firewall rule now lives as an ingress_rule block inside civo_firewall, with create_default_rules = false since custom rules replace the defaults. The provider token is no longer hardcoded; export it instead:

1export CIVO_TOKEN=<your-civo-api-token>

Configuring Terraform backend

The important part of this configuration is the backend block:

• endpoints.s3 tells Terraform the address of the object store, which you can retrieve by running civo objectstore info tf-store
• bucket is the name of the object store we created earlier
• key allows you to specify what name Terraform should store the state file under
• use_path_style addresses the bucket by path rather than subdomain, which S3-compatible stores expect
• use_lockfile enables state locking (Terraform 1.10 and later), so concurrent runs cannot corrupt your state
• the skip_* flags disable AWS-specific checks. skip_requesting_account_id and skip_s3_checksum are required on current Terraform: without the first, terraform init fails trying to reach a nonexistent AWS STS endpoint, and without the second, state uploads are rejected

One more piece is required on Terraform 1.11 and later. The AWS SDK inside Terraform now sends checksum trailers that S3-compatible stores reject, so run all Terraform commands with:

1export AWS_REQUEST_CHECKSUM_CALCULATION=when_required

Rather than hardcoding access_key and secret_key in main.tf, you can also pass them at init time with terraform init -backend-config="access_key=..." -backend-config="secret_key=...", or via the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables, which keeps credentials out of version control.

To apply the changes, run the following commands:

1# initialize the terraform provider
2terraform init
3
4
5# preview the infrastructure
6terraform plan
7
8
9# apply the changes
10terraform apply --auto-approve

Once your cluster has been provisioned, you can confirm the state file landed in the bucket without leaving the terminal:

1aws s3 ls s3://tf-store --endpoint-url https://objectstore.lon1.civo.com
22026-07-18 09:18:08       3748 terraform.tfstate

You should see the same file listed in your dashboard under the object storage bucket.

Cleaning up

When you are done experimenting, destroy the Terraform-managed resources, then remove the object store and credentials:

1terraform destroy --auto-approve
2civo objectstore remove tf-store
3civo objectstore credential delete tf-experiments

Summary

State management is a crucial part of what Terraform does as it enables it to track your resources and their dependencies, ensuring that resources are always in their desired state.

Through this tutorial, we discussed some of the challenges associated with storing your state files locally and how to leverage Civo's S3-compatible storage to manage your state files remotely.

Further resources

If you are interested in other options that Terraform supports, check out the backend section of the documentation. HashiCorp also has a hands-on tutorial on managing resource drift.