Deploying Global Active tables using Terraform

It is easy to deploy a Global Active table on OCI using Terraform.

Terraform is an infrastructure-as-code tool that lets you build, change, and version cloud and onPremises resources safely and efficiently. To have a basic understanding of Terraform, read the brief introduction. Make sure, you have the OCI Terraform provider installed and configured.

Steps to deploy a Global table

The terraform script below does the following:

  • Creates the source table as a singleton table if it is not present.
  • Adds an index to the singleton table.
  • Creates a regional replica of the table and makes it a Global Active table.

Steps:

Step 1: Create Terraform configuration files for the Global Active table: You need to create the following config files for creating a Global Active table.

provider.tf:

In this file, you provide the OCI Terraform provider definition, and also associated variable definitions. The OCI Terraform provider requires ONLY the region argument. However, you might have to configure additional arguments with authentication credentials for an OCI account based on the authentication method. The OCI Terraform provider supports four authentication methods: API Key Authentication, Instance Principal Authorization, Resource Principal Authorization, and Security Token Authentication.

Example of provider.tf with API Key Authentication
variable "tenancy_ocid" {
}
variable "user_ocid" {
}
variable "fingerprint" {
}
variable "private_key_path" {
}
variable "region" {
}

provider "oci" {
   region = var.region
   tenancy_ocid = var.tenancy_ocid
   user_ocid = var.user_ocid
   fingerprint = var.fingerprint
   private_key_path = var.private_key_path
}
Example of provider.tf with Instance Principal Authorization
variable "region" {
}
provider "oci" {
  auth = "InstancePrincipal"
  region = var.region
}
Example of provider.tf with Resource Principal Authorization
variable "region" {
}

provider "oci" {
  auth = "ResourcePrincipal"
  region = var.region
}
Example of provider.tf with Security Token Authentication
variable "region" {
}
variable "config_file_profile" {
}
provider "oci" {
  auth = "SecurityToken"
  config_file_profile = var.config_file_profile
  region = var.region
}
nosql.tf: Resources are the most important element in the Terraform language. Terraform creates a singleton table, an index, and a table replica as a resource. In this file, you provide the definition of NoSQL terraform configuration resources for creating a Global Active table. In the example below, you are creating a Global Active table by adding a regional replica of this table.
  • The resources that are created below are oci_nosql_table, oci_nosql_index, and oci_nosql_table_replica.
  • The table DDL definition must include with schema frozen or with schema frozen force on the singleton table. For more details, see Creating a Global Active table.
  • The table limits of the sender table (read unit, write unit, and storage capacity) must be provided.
  • When you add a regional table replica, you can either specify the name of the table or the OCID of the table. If you specify the name of the table, then you need to specify the OCID of your compartment and the depends_on clause while defining the regional replica as shown below. If you are specifying the OCID of the table, then depends_on clause, and compartment OCID is optional.
See Resource syntax to understand how a resource block is constructed in Terraform. The syntax of the resource command includes the type of resource oci_nosql_table_replica which is a table replica and the name of the resource, for example replica_montreal. See Identifiers for details on how to define resource names in a Terraform script.

Note:

You can use one of the two options below (Option 1 - using OCID of the table or Option 2 - using the name of the table) in the nosql.tf script.
#Option 1 of adding a regional replica of the table
resource "oci_nosql_table_replica" "replica_montreal" {
  table_name_or_id = oci_nosql_table.mr_test.id
  region = "ca-montreal-1"
#Optional
  max_read_units     = "60"
  max_write_units    = "60"
}

# Option 2 of adding a regional replica of the table
resource "oci_nosql_table_replica" "replica_toronto" {
compartment_id = var.compartment_ocid
table_name_or_id = "mr_test"
region = "ca-toronto-1"  
depends_on = [oci_nosql_table.mr_test]
}
Sample nosql.tf file:
variable "compartment_ocid" {
}

variable "table_ddl_statement" {
  default = "CREATE TABLE IF NOT EXISTS mr_test(id INTEGER,
                            name STRING, info JSON,PRIMARY KEY(id))
                           using TTL 10 days with schema frozen"
}
#Add index resource "idx_age"
resource "oci_nosql_index" "idx_age" {
  table_name_or_id = oci_nosql_table.test_mrtable.id
  name = "idx_age"
  keys {
    column_name = "name"
  }
  keys {
    column_name = "info"
    json_path = "age"
    json_field_type = "anyatomic"
  }
}
resource "oci_nosql_table" "mr_test" {
  #Required
  compartment_id = var.compartment_ocid
  ddl_statement  = var.table_ddl_statement
  name           = "mr_test"

  table_limits {
    #Required
    max_read_units = 51
    max_write_units = 51
    max_storage_in_gbs = 2     
  }
}
#add a regional replica
resource "oci_nosql_table_replica" "replica_montreal" {
  table_name_or_id = oci_nosql_table.mr_test.id
  region = "ca-montreal-1"
  #Optional
  max_read_units     = "60"
  max_write_units    = "60"
}

Note:

The definition of the singleton table (CREATE TABLE IF NOT EXISTS mr_test...) must always be included in the terraform script even if the source table already exists. Removing the CREATE TABLE definition from the terraform script drops the table from the region.

terraform.tfvars: In this file, you provide the values for the required OCI Terraform provider arguments based on the authentication method.

Example of terraform.tfvars with API Key Authentication:
tenancy_ocid = "<tenancy_your_ocid>"
user_ocid = "<your_user_ocid">
fingerprint = "your_fingerprint>"
private_key_path = "<path_private_key>"
compartment_ocid = "<your_compartment_ocid>"
region = "<name of your region>"
Example of terraform.tfvars with Instance Principal Authorization:
compartment_ocid = "<your_compartment_ocid>"
region = "<name of your region>"
Example of terraform.tfvars with Resource Principal Authorization: 
compartment_ocid = "<your_compartment_ocid>"
region = "<name of your region>"
Example of terraform.tfvars with Security Token Authentication:
compartment_ocid = "<your_compartment_ocid>"
region = "<name of your region>"
config_file_profile = "PROFILE"

Note:

You could have a single terraform.tf file where the entire configuration details can be added, but it is recommended to have separate config files as shown above for clarity and easy maintenance.
Step 2: Invoke terraform and initialize the setup.
terraform init
Step 3: Run the following command to invoke the terraform script.
terraform apply
Terraform shows the plan to be applied and prompts for confirmation as shown below.
Do you want to perform these actions?
Terraform will perform the actions described above.
Only 'yes' will be accepted to approve.

On confirmation, the singleton table is created and an index is added to it. A regional replica of the table is then created, converting the singleton table to a GAT.