Developers and DevOps teams commonly utilize Infrastructure as Code (IaC) tools and scripts to manage their software and infrastructure deployments in a repeatable and consistent manner. With IaC tools, users can automate the life cycle of deployments including provisioning, configuration, deployment and destruction of resources. Hashicorp Terraform is a very popular IaC tool.

We’re pleased to announce the general availability of version 1.0 of the Couchbase Capella Terraform Provider, which will allow users to programmatically manage Couchbase Capella deployments. This version supersedes the v0.2 of the Capella provider which is now deprecated and will be unsupported shortly.

In this post, we give you a quick example walkthrough of the Capella Terraform provider.


Earlier this year, we announced the launch of our new version of Capella Management API – a revamped version of the Capella public API that allows users to programmatically control Couchbase Capella resources through RESTful interface.

The Couchbase Capella Terraform provider v1.0 leverages the Capella Management API. As such, the set of Capella resources that can be managed via the provider is dependent on the underlying API. As the API evolves to support new endpoints. The Terraform provider will be extended correspondingly in order to support the management of the corresponding resources exposed via the endpoints.

Provider Walkthrough

In this example, we will demonstrate the use of the Capella Terraform provider to deploy a Capella project, a cluster and provision a bucket.

The GitHub repo has an extensive set of examples for managing each of the supported resources including users, projects, clusters, buckets, database credentials, allowed CIDRs, App Services, backup/restore and more. 


    • Terraform >= 1.5.2
    • Go >= 1.20
    • A Capella paid account.

Note that the current version of the provider is not supported on Capella free trials. Support for trials will be available when the underlying Capella management API supports orchestration of trial deployments.

Authentication & Authorization

All operations by the Capella Terraform provider are authenticated and authorized via Capella Management API key. In a production environment, you will use something like HashiCorp Vault or a secrets manager offered by a Cloud Service Provider such as AWS Secrets Manager to manage your API keys. Reference to the secrets manager would be specified as input to the Terraform provider.

For purposes of this demonstration, we will set the credentials in a local environment variables file: 

  1. Create a file named and add the following variables definitions. We will use these variables within our config file.

2. Create a file named terraform.template.tfvars and add the following lines. Here, we specify the values of key variables associated with the deployment

    • auth_token: You can create the API key via Capella UI or via the management API. Depending on the scope of the resources that is managed by the provider, you must create an Organization level or Project level API key with the right set of roles.
    • organization_id: You can get this from organization management API or from the browser URL of Capella UI (look for “oid” parameter)–4018–84a3-xxxxxxxxxxxxx

Configuration for sample deployment

As mentioned earlier, the GitHub repo of the Provider has an extensive set of configuration templates. In this post, I am using a simple example to demonstrate the use of the provider to create a profile, deploy a cluster and a bucket within the cluster. 

    1. Create a file named and add the following configuration. The configuration does the following
    2. Creates project within specified Organization 
    3. Creates a cluster within the project 
    4. Creates bucket within the cluster

Deploy and Manage Resources

Use standard Terraform commands to initialize and deploy the resources

1. Initialize the Terraform provider

Terraform must be initialized the very first time you use the provider:

2. Review the Terraform plan

Use the following command to review the resources that will be deployed:

3. Execute the Terraform Plan

Deploy the Couchbase Capella resources using the following command:

You should see output similar to the following. It will take a few minutes to deploy the resources:

4. Get the current state of the resources

You should see output similar to the following which shows the three resources that are created:

5. Get the detailed state of any deployed resource

You should see output similar to the following which shows the three resources that are created:

6. Destroy the resources

Execute the following command to destroy the resources:

You should see output similar to the following. It will take a few minutes to destroy the resources.

Resources and Next Steps

Version 1.0 of the Provider supersedes the v0.0.2 of the Capella provider which is deprecated and will be removed shortly. So, if you are using the old provider, you should plan to migrate to the new provider.

Here are direct links to a few helpful resources:

If you have questions or feedback, please leave a comment below. The Couchbase Forums or Couchbase discord channels are another good place to reach out with questions.


Posted by Priya Rajagopal, Senior Director, Product Management

Priya Rajagopal is a Senior Director of Product Management at Couchbase responsible for developer platforms for the cloud and the edge. She has been professionally developing software for over 20 years in several technical and product leadership positions, with 10+ years focused on mobile technologies. As a TISPAN IPTV standards delegate, she was a key contributor to the IPTV standards specifications. She has 22 patents in the areas of networking and platform security.

Leave a reply