# Custom resources

## Overview

Custom resources allow you to import Terraform modules as resources managed by Instruqt sandboxes. You will need to be comfortable with [Terraform modules](https://developer.hashicorp.com/terraform/language/modules) and the [Terraform Registry](https://registry.terraform.io/) to proceed. 

{% hint style="info" %}
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. 
{% endhint %}

## Create custom resources

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

{% tabs %}
{% tab title="🌐 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.**
   {% endtab %}
   {% endtabs %}

## Use custom resources

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

{% tabs %}
{% tab title="🌐 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. 
   {% endtab %}
   {% endtabs %}

{% hint style="warning" %}
The `sandbox_id` value is a reserved input name, and cannot be used for custom resources. 
{% endhint %}

## **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:<br>

{% embed url="<https://www.loom.com/share/c3b9a5dd86084873a1e40c5e6d42a4a1?sid=e838cc05-d9ee-4620-9229-3ca918a5e027>" %}

### Terraform Module Examples

{% code title="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
  }
}
```

{% endcode %}

{% code title="outputs.tf" %}

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

{% endcode %}

{% code title="provider.tf" %}

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

{% endcode %}

{% code title="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"
}
```

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.instruqt.com/sandboxes/manage/custom-resources.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.