Provision a Databases for PostgreSQL instance with Terraform

In this tutorial, you learn how to use Terraform to provision a Databases for PostgreSQL instance.

Overview of the available tools

Before beginning the process of provisioning a database with Terraform, you need to have an IBM Cloud account.

In this tutorial, you provision your database by using Terraform, which enables you to safely and predictably create, change, and improve infrastructure. It is an open source tool that codifies APIs into declarative configuration files that can be shared among team members, which are treated as code, edited, reviewed, and versioned. It is infrastructure as code. You write down what your infrastructure should look like and Terraform will create, update, and remove cloud resources as needed. For more information, see Understand the basics of Terraform.

To support a multi-cloud approach, Terraform works with providers. A provider is responsible for understanding API interactions and exposing resources. IBM Cloud® has its provider for Terraform, enabling users of IBM Cloud® to manage resources with Terraform. Although Terraform is categorized as infrastructure as code, it is not limited to Infrastructure-As-A-Service resources. For more information, see ibm_database.

Step 1: Install Terraform

Follow the steps at Install Terraform to install Terraform.

Step 2: Configure the IBM Cloud® Provider plug-in

Create or retrieve an IBM Cloud® API key. The API key is used to authenticate with the IBM Cloud® platform and to determine your permissions for IBM Cloud® services.
Create a Terraform on IBM Cloud Databases project directory. The directory holds all your configuration files that you create as part of this tutorial. The directory in this tutorial is named tf-postgres, but you can use any name for the directory.
```
mkdir tf-postgres && cd tf-postgres
```
In your project directory, create a variable definition file that is named terraform.tfvars and specify the IBM Cloud API key that you retrieved. In addition, you specify the region where you want your IBM Cloud resources to be created. If no region is specified, the IBM Cloud® Provider plug-in automatically creates your resources in the us-south region. Variables that are defined in the terraform.tfvars file are automatically loaded by Terraform when the IBM Cloud Provider plug-in is initialized and you can reference them in every Terraform configuration file that you use.

Because the variable definitions file contains confidential information, do not push this file to a version control system. This file is meant to be on your local system only.

Example of terraform.tfvars file
```
  ibmcloud_api_key = "<ibmcloud_api_key>"
  region = "us-east"
```
The us-east region is provided as an example, not a requirement. Use the region that works best for your instance deployment.
Create a provider configuration file that is named provider.tf. Use this file to configure the IBM Cloud Provider plug-in with the IBM Cloud API key from your terraform.tfvars file. The plug-in uses this key to access IBM Cloud and to work with your IBM Cloud service. To access a variable value from the terraform.tfvars file, you must first declare the variable in the provider.tf file and then reference the variable by using the var.<variable_name> syntax.

Example provider.tf file
```
variable "ibmcloud_api_key" {}
variable "region" {}

provider "ibm" {
  ibmcloud_api_key = var.ibmcloud_api_key
  region           = var.region
}
```

Step 3: Provision a Databases for PostgreSQL instance

Create a Terraform configuration file that is named postgres.tf.

Example of postgres.tf file

data "ibm_resource_group" "postgres_tutorial" {
  name = "terraform_postgres"
}

resource "ibm_database" "postgresql_db" {
  resource_group_id = data.ibm_resource_group.postgres_tutorial.id
  name              = "terraform_postgres"
  service           = "databases-for-postgresql"
  plan              = "standard"
  location          = "us-east"
  adminpassword     = "password123"
  
  group {
    group_id = "member"
    memory {
      allocation_mb = 1024
    }
    disk {
      allocation_mb = 5120
    }
  }
 }

 output "Postgresql" {
   value = "http://${ibm_database.postgresql_db.connectionstrings[0].composed}"
 }

Resource group - the Resource Group value you declare.
Name - The service name can be any string and is the name that is used on the web and in the CLI to identify the new deployment.
Service - For Databases for PostgreSQL, the service ID is databases-for-postgresql. Choose the correct Service ID for your deployment.
Plan - This tutorial uses a Standard plan. For more information, see IBM Cloud® Pricing.
Location - Choose a suitable region for your deployment instance.
Admin Password - The Databases for PostgreSQL service is provisioned with an admin user, so you can manage PostgreSQL by using its command-line tool, psql. For more information, see Setting the Admin Password.
Group Scaling groups represent the various resources that are allocated to a deployment. To see an example for configuring and deploying a database that uses group attributes, see Sample database instance by using group attributes.
Group values - Memory, disk, and CPU values are all based on minimum requirements for provisioning a Databases for PostgreSQL instance.
Timeouts - Create, update, and delete values for this resource. ICD create typically takes in the range of 30 - 45 minutes. delete and update typically take 1 minute. Provisioning times are unpredictable. If the deployment fails due to a timeout, import the database resource once the create is complete.

Step 4: Test your configuration

Now that you configured the IBM Cloud® Provider plug-in for your resource, you can use Terraform on IBM Cloud® to initialize, run, plan, and apply commands to provision the resource. You need the following commands:

Table 1. Terrarform provisioning commands
Command Description	Command
`terraform init`	The `terraform init` command is used to initialize a working directory containing Terraform configuration files.
`terraform fmt`	The `terraform fmt` command is used to rewrite Terraform configuration files to a canonical format and style.
`terraform validate`	The `terraform validate` command validates the configuration files in a directory
`terraform apply`	The `terraform apply` command runs the actions that are proposed in a Terraform plan.

For more information, see Provisioning IBM Cloud® resources.

To view sample Terraform templates with the complete Terraform configuration files to test, refer to Sample templates.

For an overview of the Terraform resources and data sources that you can use, see the Index of Terraform on IBM Cloud® resources and data sources.