Instruqt AWS EC2 Custom Resource

This is an example Terraform module that demonstrates how to create a custom resource for Instruqt sandboxes. It provisions an AWS EC2 instance that can be used in your Instruqt tracks.

About Instruqt Custom Resources

Instruqt allows you to define custom infrastructure resources using Terraform modules. This enables you to create specialized environments beyond the default sandbox options. Learn more in the Instruqt Custom Resources Documentation.

What This Module Does

This module creates a single AWS EC2 instance with the following features:

• Automatically generates an SSH key pair for secure access
• Configurable AMI selection
• Configurable instance size/type
• Configurable region
• Custom naming

The module outputs the public IP address and SSH keys, which can be used in your Instruqt track to provide access to the instance.

Usage in Instruqt

To use this module as a custom resource in Instruqt, follow these steps:

1. Publish to Terraform Registry

First, publish this module to the Terraform Registry:

1. Ensure your module follows Terraform's standard module structure
2. Tag a release in your GitHub repository (e.g., v1.0.0)
3. The module will be automatically published to the registry if your repository is public and properly configured

2. Import in Instruqt

1. Navigate to your Instruqt organization settings
2. Go to the Custom Resources section
3. Click Import from Terraform Registry
4. Search for and select your published module
5. Configure the module with any organization-wide defaults

3. Configure AWS Credentials

Store your AWS credentials as Instruqt secrets in your organization settings:

• AWS_ACCESS_KEY - Your AWS Access Key ID
• AWS_SECRET_KEY - Your AWS Secret Access Key

4. Add to Your Track

Once imported, add the custom resource to your track through the Instruqt UI:

1. Open your track in the Instruqt editor
2. Navigate to the Sandbox configuration
3. Click Add Resource
4. Select your imported custom resource
5. Configure the required inputs:
   • aws_access_key: ${AWS_ACCESS_KEY} (secret variable)
   • aws_secret_key: ${AWS_SECRET_KEY} (secret variable)
   • instance_name: e.g., "instruqt-lab-vm"
   • aws_instance_ami: e.g., "ami-0e83be366243f524a" (Amazon Linux 2023 in us-east-2)
   • aws_instance_size: e.g., "t2.micro"
   • aws_instance_region: e.g., "us-east-2"

5. Access the Instance in Challenges

The module outputs can be accessed in your challenge scripts using environment variables. For example, if you named your resource "aws_vm" in Instruqt:

# Save the private key and connect to the instance
echo "${AWS_VM_PRIVATE_KEY}" > /tmp/instance_key.pem
chmod 600 /tmp/instance_key.pem
ssh -i /tmp/instance_key.pem ec2-user@${AWS_VM_PUBLIC_IP}

Example Configuration Values

When configuring this custom resource in the Instruqt UI, here are example values you might use:

Input	Example Value
aws_access_key	${AWS_ACCESS_KEY} (secret variable)
aws_secret_key	${AWS_SECRET_KEY} (secret variable)
instance_name	instruqt-lab-vm
aws_instance_ami	ami-0e83be366243f524a (Amazon Linux 2023, us-east-2)
aws_instance_size	t2.micro
aws_instance_region	us-east-2

Module Variables

Variable	Description	Default	Required
aws_access_key	AWS Access Key ID	-	Yes
aws_secret_key	AWS Secret Access Key	-	Yes
instance_name	Name tag for the EC2 instance	-	Yes
aws_instance_ami	EC2 AMI ID	ami-0e83be366243f524a	No
aws_instance_size	EC2 instance type	t2.micro	No
aws_instance_region	AWS region	us-east-2	No

Module Outputs

Output	Description
public_ip	The public IP address of the deployed EC2 instance
private_key	The private SSH key (PEM format) for connecting to the instance
public_key	The public SSH key (OpenSSH format)

Local Development

To test this module locally:

# Initialize Terraform
terraform init

# Create a terraform.tfvars file
cat > terraform.tfvars <<EOF
aws_access_key = "your-access-key"
aws_secret_key = "your-secret-key"
instance_name = "test-instance"
EOF

# Plan the deployment
terraform plan

# Apply the configuration
terraform apply

# Get the outputs
terraform output public_ip
terraform output public_key

# Get the private key (marked as sensitive)
terraform output -raw private_key > instance_key.pem
chmod 600 instance_key.pem

# Connect to the instance
ssh -i instance_key.pem ec2-user@$(terraform output -raw public_ip)

# Clean up
terraform destroy

Requirements

• Terraform >= 1.0
• AWS Account with EC2 and Key Pair creation permissions
• Valid AWS credentials
• AWS Provider (~> 5.0)
• TLS Provider (~> 4.0)

Notes

• The module automatically generates a unique SSH key pair for each deployment
• The private key is marked as sensitive and won't be displayed in plan/apply output
• Ensure the AMI ID is valid for your selected region
• The default AMI is for Amazon Linux 2023 in us-east-2
• Make sure your AWS account has sufficient permissions to create EC2 instances and key pairs
• Remember to clean up resources after testing to avoid unnecessary charges
• The SSH key is generated using RSA 4096-bit encryption for enhanced security

License

See LICENSE file for details.

Related Resources

• Instruqt Custom Resources Documentation
• AWS EC2 Terraform Resource