Custom resources

How to create and use custom resources such as external cloud accounts and leverage them within your Instruqt sandbox.

Overview

Custom resources allow you to import Terraform modules as resources managed by Instruqt sandboxes. You will need to be comfortable with Terraform modules and the Terraform Registry to proceed.

This guide assumes you have published a module to the Terraform Registry. If you are curious to learn more about this feature, please reach out in your Slack organization.

Create custom resources

You can add custom resources (Terraform registry modules) using the Web UI.

🌐 Web UI

1. Click Settings -> Custom Resources.

2. Click Import from Terraform Registry. ↳ The Search Terraform Modules page opens.

3. Search for and click on the Terraform module you wish to import.

4. In the top-left corner, select the module's version and click Import.

5. Give you resource a user-friendly name and description then confirm by clicking Import.

Use custom resources

You can add custom resources to sandboxes using the Web UI.

🌐 Web UI

1. Click the track you want to add custom resources to.

2. In the Sandbox section of the Track dashboard, click Edit.

3. On the Sandbox page, click Add a custom resource.

4. Select the custom resource you want to add.

5. Input a name, and customize inputs if any are presented.

6. Click Add resource in the upper-right corner.

The sandbox_id value is a reserved input name, and cannot be used for custom resources.

Accessing Resource Outputs

Custom Resources are provisioned ahead of other sandbox components. Outputs from these Terraform modules are provided as environment variables to host lifecycle scripts. The environment variable will be prefixed with the name given to the custom resource when added to the sandbox.

As an example, if you have a Custom Resource named sqldb that yields an output ENDPOINT, it will be available as an environment variable named $SQLDB_ENDPOINT.

Example of Custom AWS Account

For a walkthrough of how custom resources could be used with an AWS account, review the following video:

Terraform Module Examples

main.tf

resource "aws_instance" "ec2_instance" {
  ami           = var.aws_instance_ami
  instance_type = var.aws_instance_size
  key_name      = var.aws_instance_key

  tags = {
    Name = var.instance_name
  }
}

outputs.tf

output "public_ip" {
  value       = aws_instance.ec2_instance.public_ip
  description = "The public IP address of the deployed EC2 instance"
}

provider.tf

provider "aws" {
  access_key = var.aws_access_key
  secret_key = var.aws_secret_key
  region     = var.aws_instance_region 
}

variable.tf

variable "aws_access_key" {
  description = "AWS Access Key ID"
}

variable "aws_secret_key" {
  description = "AWS Secret Access Key"
}

variable "instance_name" {
  description = "Name of the EC2 instance"
}

variable "aws_instance_ami" {
  description = "ID of the EC2 AMI"
  default     = "ami-0e83be366243f524a"
}

variable "aws_instance_size" {
  description = "Size of the EC2 instance"
  default     = "t2.micro"
}

variable "aws_instance_key" {
  description = "Name of the EC2 key"
  default     = "instruqt"
}

variable "aws_instance_region" {
  description = "Region of the EC2 instance"
  default     = "us-east-2"
}