Creating a new instance with Terraform

IBM Cloud® Data Engine is deprecated. As of 18 February 2024 you can't create new instances, and access to free instances will be removed. Existing Standard plan instances are supported until 18 January 2025. Any instances that still exist on that date will be deleted.

Terraform on IBM Cloud® enables predictable and consistent provisioning of IBM Cloud services, so that you can rapidly build complex, multitiered cloud environments following Infrastructure as Code (IaC) principles. Similar to using the IBM Cloud CLI or API, you can automate the provisioning and deletion of your Data Engine instances by using HashiCorp Configuration Language (HCL).

Install the Terraform CLI and configure the IBM Cloud Provider plug-in

Follow the Terraform on IBM Cloud getting started tutorial to install the Terraform CLI and configure the IBM Cloud Provider plug-in for Terraform. The plug-in abstracts the IBM Cloud APIs that are used to provision, update, or delete Data Engine service instances and resources.

Work with Data Engine resources in Terraform

The following steps guide you through an example of creating a Data Engine service instance in Terraform.

Create a Terraform configuration file that is named main.tf. In this file, you declare the Data Engine service instance that you want to provision. The following example creates a Data Engine service instance that is named My Data Engine Instance in the us-south region.

terraform {
  required_version = ">=1.0.0, <2.0"
  required_providers {
    ibm = {
      source = "IBM-Cloud/ibm"
    }
  }
}
provider "ibm" {
}
data "ibm_resource_group" "group" {
  name = "default"
}
resource "ibm_resource_instance" "resource_instance" {
  name              = "My Data Engine Instance"
  service           = "sql-query"
  plan              = "standard"
  location          = "us-south"
  resource_group_id = data.ibm_resource_group.group.id
}

Provide the API key to allow Terraform to make the requested changes to your IBM Cloud instance. You can provide the API key as environment variable in the session where you also do the Terraform calls.
```
export IC_API_KEY="<ibmcloud_api_key>"
```
See the Terraform documentation for further options to provide credentials.
Initialize the Terraform CLI.
```
terraform init
```
Create a Terraform execution plan. The Terraform execution plan summarizes all the actions that have to be run to create the Data Engine service instance in your account.
```
terraform plan
```
Create the Data Engine service instance in the IBM Cloud.
```
terraform apply
```
In the IBM Cloud resource dashboard, find the Data Engine service instance that you created.

You can also create a Data Engine instance with user-managed key encryption (optional). You need the instance ID and the rootkey ID of a Key Protect instance. Add the following parameter section into the main.tf file.

resource "ibm_resource_instance" "resource_instance" {
  name              = "My Data Engine Instance"
  service           = "sql-query"
  plan              = "standard"
  location          = "us-south"
  resource_group_id = data.ibm_resource_group.group.id
  parameters = {
    customerKeyEncrypted: true,
    kms_instance_id: jsonencode({ "guid" = "<kms_instance_guid>", "url" = "https://us-south.kms.cloud.ibm.com" }),
    kms_rootkey_id: "<kms_rootkey_id>"
  }
}

For user-managed key encryption, you need a Standard plan. You cannot change the encryption parameters once the instance is created.

Next, give the new Data Engine instance access to your Key Protect key.

resource "ibm_iam_authorization_policy" "iam_authorization_policy" {
  source_service_name           = "sql-query"
  source_resource_instance_id = ibm_resource_instance.resource_instance.id
  target_service_name         = "kms"
  target_resource_instance_id = "<kms_instance_id>"
  roles                       = ["Reader"]
  description                 = "Service-to-service authorization: Data Engine access to Key Protect"
}