Manage SingleStore Helios using Terraform

1. Configure the Provider

1. Create a Terraform configuration file, main.tf, and then add the required_providers block from the Terraform Registry.

   Terraform

   Copy

   required_providers block from the Terraform Registry.
   
   terraform {
     required_providers {
       singlestoredb = {
         source = "singlestore-labs/singlestoredb"
         version = "0.1.0-alpha.5"
       }
     }
   }
   
   provider "singlestoredb" {
     # Configuration options
   }

   This configuration specifies the provider and its version.

2. Run the following command to initialize the configuration specified in the main.tf file:

   Shell

   Copy

   terraform init

   Terraform has been successfully initialized!

2. Assign the API Key

1. On the Cloud Portal, select your organization from the Organization menu on the top. Navigate to the left navigation pane and select API Keys > + Create API Key.

2. Enter a name for the API key, and set its expiration date. Select Create API Key.

3. Once the API key is created, copy and store it safely. The API key is displayed only once.

4. Assign the copied API key to the SINGLESTOREDB_API_KEY environment variable:

   Shell

   Copy

   export SINGLESTOREDB_API_KEY="xxxx"

3. Deploy a Workspace Group/Workspace

1. Add the following code to the main.tf file (do not remove the provider configuration added earlier):

   Terraform

   Copy

   data "singlestoredb_regions" "all" {}
   
   resource "singlestoredb_workspace_group" "example" {
     name            = "testwsgroup"
     firewall_ranges = ["0.0.0.0/0"] // Ensure restrictive ranges for production environments.
     expires_at      = "2222-01-01T00:00:00Z"
     region_id       = data.singlestoredb_regions.all.regions.0.id // Prefer specifying the explicit region ID in production environments as the list of regions may vary.
   }
   
   resource "singlestoredb_workspace" "this" {
     name               = "testworkspace"
     workspace_group_id = singlestoredb_workspace_group.example.id
     size               = "S-00"
     suspended          = false
   }
   
   output "endpoint" {
     value = singlestoredb_workspace.this.endpoint
   }
   
   output "admin_password" {
     value     = singlestoredb_workspace_group.example.admin_password
     sensitive = true
   }

2. Create a Terraform plan. Run the terraform plan command to display the actions the provider will take without performing them:

   Shell

   Copy

   terraform plan

   Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
     + create
   
   Terraform will perform the following actions:
   
     # singlestoredb_workspace.this will be created
     + resource "singlestoredb_workspace" "this" {
         + created_at         = (known after apply)
         + endpoint           = (known after apply)
         + id                 = (known after apply)
         + name               = "testworkspace"
         + size               = "S-00"
         + suspended          = false
         + workspace_group_id = (known after apply)
       }
   
     # singlestoredb_workspace_group.example will be created
     + resource "singlestoredb_workspace_group" "example" {
         + admin_password  = (sensitive value)
         + created_at      = (known after apply)
         + expires_at      = "2222-01-01T00:00:00Z"
         + firewall_ranges = [
             + "0.0.0.0/0",
           ]
         + id              = (known after apply)
         + name            = "testwsgroup"
         + region_id       = "04eb4250-5417-4300-9822-70cf4f114543"
       }
   
   Plan: 2 to add, 0 to change, 0 to destroy.
   
   Changes to Outputs:
     + admin_password = (sensitive value)
     + endpoint       = (known after apply)

   Note that this is only a preview of the actions that will be taken, and these actions are not yet applied.

3. Once you're ready, run the terraform apply command to deploy the configuration specified in the main.tf file (enter yes at the prompt):

   Shell

   Copy

   terraform apply

   Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
     + create
   
   Terraform will perform the following actions:
   
     # singlestoredb_workspace.this will be created
     + resource "singlestoredb_workspace" "this" {
         + created_at         = (known after apply)
         + endpoint           = (known after apply)
         + id                 = (known after apply)
         + name               = "testworkspace"
         + size               = "S-00"
         + suspended          = false
         + workspace_group_id = (known after apply)
       }
   
     # singlestoredb_workspace_group.example will be created
     + resource "singlestoredb_workspace_group" "example" {
         + admin_password  = (sensitive value)
         + created_at      = (known after apply)
         + expires_at      = "2222-01-01T00:00:00Z"
         + firewall_ranges = [
             + "0.0.0.0/0",
           ]
         + id              = (known after apply)
         + name            = "testwsgroup"
         + region_id       = "04eb4250-5417-4300-9822-70cf4f114543"
       }
   
   Plan: 2 to add, 0 to change, 0 to destroy.
   
   Changes to Outputs:
     + admin_password = (sensitive value)
     + endpoint       = (known after apply)
   
   Do you want to perform these actions?
     Terraform will perform the actions described above.
     Only 'yes' will be accepted to approve.
   
     Enter a value: yes
   
   ---- output omitted here ---
   
   Apply complete! Resources: 2 added, 0 changed, 0 destroyed.
   
   Outputs:
   admin_password = <sensitive>
   endpoint = "svc-XXXX-dml.aws-london-1.svc.singlestore.com"

   You can also view the progress of the deployment process on the Cloud Portal. Once the deployment is complete, a workspace group named testwsgroup and a workspace named testworkspace is created. You can connect to the workspace using the endpoint returned in the output. The endpoint is also displayed in the output of the terraform show command.

4. Connect to the Workspace

Use the endpoint from the output to connect to the workspace created in the previous step. The following example uses the endpoint of the workspace with the admin user's password and runs the SHOW DATABASES command on the workspace:

export endpoint=$(terraform output -raw endpoint)
export admin_password=$(terraform output -raw admin_password)
mysql -u admin -h $endpoint -P 3306 --default-auth=mysql_native_password --password=$admin_password -e 'SHOW DATABASES'

+--------------------+
| Database           |
+--------------------+
| cluster            |
| information_schema |
| memsql             |
+--------------------+

5. Display Information about the Deployment

Run the terraform show command to get information about your deployed SingleStore Helios resources and display it:

terraform show

# data.singlestoredb_regions.all:
data "singlestoredb_regions" "all" {
    id      = "internal"
    regions = [
        {
            id       = "04eb4250-XXXX-70cf4f114543"
            provider = "AWS"
            region   = "Europe West 2 (London)"
        },
--- output omitted here ---
     ]
}

# singlestoredb_workspace.this:
resource "singlestoredb_workspace" "this" {
    created_at         = "2023-07-06T11:55:41.391981Z"
    endpoint           = "svc-XXXX-dml.aws-london-1.svc.singlestore.com"
    id                 = "e8704b30-XXXX-4388633ab0b4"
    name               = "testworkspace"
    size               = "S-00"
    suspended          = false
    workspace_group_id = "959ca590-XXXX-3d94ae2a9570"
}

# singlestoredb_workspace_group.example:
resource "singlestoredb_workspace_group" "example" {
    admin_password  = (sensitive value)
    created_at      = "2023-07-06T11:52:24.250554Z"
    expires_at      = "2222-01-01T00:00:00Z"
    firewall_ranges = [
        "0.0.0.0/0",
    ]
    id              = "959ca590-XXXX-3d94ae2a9570"
    name            = "testwsgroup"
    region_id       = "04eb4250-XXXX-70cf4f114543"
}

Outputs:

admin_password = (sensitive value)
endpoint = "svc-XXXX-dml.aws-london-1.svc.singlestore.com"

This command displays a list of all the available regions and information on the deployed workspace group and the workspace attached to it.

6. Terminate the Workspace Group and the Workspace

Run the terraform destroy command to terminate the workspace group created earlier (enter yes at the prompt):

terraform destroy

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  - destroy

Terraform will perform the following actions:

  # singlestoredb_workspace.this will be destroyed
  - resource "singlestoredb_workspace" "this" {
      - created_at         = "2023-07-06T11:55:41.391981Z" -> null
      - endpoint           = "svc-XXXX-dml.aws-london-1.svc.singlestore.com" -> null
      - id                 = "e8704b30-XXXX-4388633ab0b4" -> null
      - name               = "testworkspace" -> null
      - size               = "S-00" -> null
      - suspended          = false -> null
      - workspace_group_id = "959ca590-XXXX-3d94ae2a9570" -> null
    }

  # singlestoredb_workspace_group.example will be destroyed
  - resource "singlestoredb_workspace_group" "example" {
      - admin_password  = (sensitive value) -> null
      - created_at      = "2023-07-06T11:52:24.250554Z" -> null
      - expires_at      = "2222-01-01T00:00:00Z" -> null
      - firewall_ranges = [
          - "0.0.0.0/0",
        ] -> null
      - id              = "959ca590-XXXX-3d94ae2a9570" -> null
      - name            = "testwsgroup" -> null
      - region_id       = "04eb4250-XXXX-70cf4f114543" -> null
    }

Plan: 0 to add, 0 to change, 2 to destroy.

Changes to Outputs:
  - admin_password = (sensitive value) -> null
  - endpoint       = "svc-XXXX-dml.aws-london-1.svc.singlestore.com" -> null

Do you really want to destroy all resources?
  Terraform will destroy all your managed infrastructure, as shown above.
  There is no undo. Only 'yes' will be accepted to confirm.

  Enter a value: yes

singlestoredb_workspace.this: Destroying... [id=e8704b30-XXXX-4388633ab0b4]
singlestoredb_workspace.this: Destruction complete after 3s
singlestoredb_workspace_group.example: Destroying... [id=959ca590-XXXX-3d94ae2a9570]
singlestoredb_workspace_group.example: Destruction complete after 0s

The workspace group and the workspace attached to it have now been terminated.