Manage SingleStore Helios using Terraform

The Terraform provider for SingleStore Helios ("the provider") allows you to deploy and manage SingleStore Helios resources, such as compute workspaces, with your Terraform workflow and configuration files. Here are a few operations that you can perform using this integration:

  • Create, update, or delete workspace groups

  • Create, resize, or delete workspaces, request information on workspaces

  • List all the available regions

Refer to Terraform Documentation for information on SingleStore Helios resources that you can deploy and manage using the provider. The provider uses the Management API for managing SingleStore Helios instances. Refer to this GitHub repository for its source code and related information.

Prerequisites

Configure the Terraform Provider for SingleStore Helios

To configure the provider to connect with SingleStore Helios,

  1. Assign the API key generated earlier to the SINGLESTOREDB_API_KEY environment variable:

    export SINGLESTOREDB_API_KEY="<your_API_key>"
  2. Add the required_providers block to your Terraform configuration file main.tf, and specify the SingleStore provider. You can copy the required_providers block from the Terraform Registry (go to Terraform provider for SingleStore Helios > USE PROVIDER). Here's a sample configuration:

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

    This required_providers block configures Terraform to use the provider for SingleStore. You can specify additional configuration options for the provider in the provider "singlestoredb" block.

  3. Run the following command to initialize the current configuration and the SingleStore provider plugins:

    terraform init
    Terraform has been successfully initialized!

After a successful initialization, the Terraform provider is configured to connect with SingleStore Helios. You can now deploy and manage SingleStore Helios instances using Terraform.

Example

The following example demonstrates how to perform the following tasks using the provider:

  1. Configure the provider.

  2. Assign the API key.

  3. Deploy a workspace group/workspace in the Cloud Portal.

  4. Connect to the deployed workspace.

  5. Display information about the deployed workspace group/workspace.

  6. Terminate the workspace group and the workspace.

Install Terraform before proceeding with the example.

1. Configure the Provider

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

    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:

    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:

    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):

    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:

    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):

    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.

Next Steps

Refer to Terraform Documentation for SingleStore provider for information on SingleStore Helios resources that you can deploy and manage using the provider.

Last modified: July 19, 2024

Was this article helpful?