Instruqt GCP VM Custom Resource

This Terraform module provisions a Google Compute Engine virtual machine with SSH access for use with Instruqt custom resources. It automatically generates SSH key pairs and configures the VM for immediate access.

What This Module Provisions

• Compute Instance: An e2-micro VM running Debian 11
• SSH Key Pair: Automatically generated RSA 4096-bit key pair
• Public IP: External IP address for accessing the VM
• SSH Access: Pre-configured SSH access with the generated key

Prerequisites

• A Google Cloud project with billing enabled
• Compute Engine API enabled
• Service account credentials with permissions to:
  • Create compute instances
  • Manage instance metadata

Usage with 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. Use in Track Configuration

Once imported, you can 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:
   • credentials: Your GCP service account credentials (use secrets)
   • project: Your GCP project ID
   • name: VM name (e.g., "student-vm")
   • sandbox_id: Use the ${SANDBOX_ID} variable
   • region: GCP region (optional, defaults to "europe-west1")
   • zone: GCP zone (optional, defaults to "europe-west1-b")
   • ssh_username: SSH username (optional, defaults to "instruqt")

Required Variables

Variable	Description
credentials	JSON credentials for authenticating with GCP
project	The Google Cloud project ID
name	Name of the virtual machine (will be prefixed with sandbox_id)
sandbox_id	Unique identifier for the Instruqt sandbox

Optional Variables

Variable	Default	Description
region	"europe-west1"	The region to deploy the VM
zone	"europe-west1-b"	The zone to deploy the VM
ssh_username	"instruqt"	Username for SSH access to the VM

Outputs

The following outputs are available for use in your Instruqt track:

Output	Description	Sensitive
id	The self-link of the VM instance	No
external_ip	External IP address of the VM	No
ssh_private_key	Private SSH key in OpenSSH format	Yes
ssh_public_key	Public SSH key in OpenSSH format	No
ssh_username	Username for SSH access	No
ssh_command	Ready-to-use SSH command	No

SSH Access in Instruqt

The module automatically generates SSH keys and configures the VM. Use these outputs in your track's lifecycle scripts or challenge scripts:

Save the Private Key

# Create SSH directory if it doesn't exist
mkdir -p /root/.ssh

# Save the private key
echo "${GCP_VM_SSH_PRIVATE_KEY}" > /root/.ssh/gcp_vm_key
chmod 600 /root/.ssh/gcp_vm_key

Connect to the VM

# Method 1: Use the generated SSH command (copy the key first)
ssh -i /root/.ssh/gcp_vm_key -o StrictHostKeyChecking=no \
  ${GCP_VM_SSH_USERNAME}@${GCP_VM_EXTERNAL_IP}

# Method 2: Using gcloud (if available)
gcloud compute ssh ${GCP_VM_SSH_USERNAME}@<vm-name> \
  --zone=${zone} \
  --ssh-key-file=/root/.ssh/gcp_vm_key

Setup Script Example

#!/bin/bash
# Save this as a setup script for your Instruqt challenge

# Configure SSH key
mkdir -p /root/.ssh
echo "${GCP_VM_SSH_PRIVATE_KEY}" > /root/.ssh/gcp_vm_key
chmod 600 /root/.ssh/gcp_vm_key

# Test SSH connection
ssh -i /root/.ssh/gcp_vm_key \
  -o StrictHostKeyChecking=no \
  -o UserKnownHostsFile=/dev/null \
  ${GCP_VM_SSH_USERNAME}@${GCP_VM_EXTERNAL_IP} \
  "echo 'SSH connection successful!'"

# Create SSH config for easier access
cat > /root/.ssh/config <<EOF
Host gcp-vm
  HostName ${GCP_VM_EXTERNAL_IP}
  User ${GCP_VM_SSH_USERNAME}
  IdentityFile /root/.ssh/gcp_vm_key
  StrictHostKeyChecking no
  UserKnownHostsFile /dev/null
EOF

# Now you can simply use: ssh gcp-vm

VM Configuration

The module creates a VM with the following specifications:

• Machine Type: e2-micro (2 vCPUs, 1 GB memory)
• Operating System: Debian 11
• Network: Default VPC with external IP
• Disk: Standard persistent disk (default size)

To customize the VM, you can modify main.tf to expose additional variables for machine type, image, or disk configuration.

Instance Naming

VMs are created with the following naming format:

{sandbox_id}-{name}

Example: abc123def-student-vm

This ensures unique instance names and easy identification of sandbox resources.

Security Considerations

• SSH keys are automatically generated for each sandbox
• Private keys are marked as sensitive in Terraform outputs
• Public keys are stored in VM metadata
• External IP is exposed for direct SSH access
• Consider adding firewall rules if additional network security is needed
• VMs are automatically destroyed when the sandbox ends

Example Configuration Values

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

Input	Example Value
credentials	${GOOGLE_CREDENTIALS} (secret variable)
project	my-gcp-project
name	linux-server
sandbox_id	${SANDBOX_ID} (Instruqt variable)
region	us-central1
zone	us-central1-a
ssh_username	student

Advanced Usage

Multiple VMs

To provision multiple VMs, add the custom resource multiple times in the Instruqt UI with different names:

1. Add the custom resource once and name it "web-server"
   • Set name input to "web"
2. Add the custom resource again and name it "database-server"
   • Set name input to "db"

Each instance will have its own set of outputs prefixed with the resource name you chose in Instruqt.

Using in Challenge Scripts

#!/bin/bash
# Example challenge check script

# SSH into the VM and check if a service is running
ssh -i /root/.ssh/gcp_vm_key \
  -o StrictHostKeyChecking=no \
  -o UserKnownHostsFile=/dev/null \
  ${GCP_VM_SSH_USERNAME}@${GCP_VM_EXTERNAL_IP} \
  "systemctl is-active nginx" &> /dev/null

if [ $? -eq 0 ]; then
  echo "Success: Nginx is running"
  exit 0
else
  echo "Error: Nginx is not running"
  exit 1
fi

Cleanup

Instruqt automatically destroys the VM when the sandbox ends. The module handles cleanup of:

• The compute instance
• Associated persistent disks
• The generated SSH key pair (from Terraform state)

Note: The VM's external IP is ephemeral and will be released automatically.

Troubleshooting

SSH Connection Issues

If you cannot connect to the VM:

1. Verify the VM is running:

   gcloud compute instances list --filter="name:${SANDBOX_ID}"

2. Check the external IP is accessible:

   ping ${GCP_VM_EXTERNAL_IP}

3. Verify SSH key permissions:

   ls -la /root/.ssh/gcp_vm_key
   # Should show: -rw------- (600)

4. Test SSH with verbose output:

   ssh -vvv -i /root/.ssh/gcp_vm_key ${GCP_VM_SSH_USERNAME}@${GCP_VM_EXTERNAL_IP}

VM Not Created

If the VM fails to create:

1. Check that Compute Engine API is enabled in your project
2. Verify service account has compute.instances.create permission
3. Check quota limits in your GCP project
4. Review Terraform logs in Instruqt sandbox output

Support

For issues with:

• This Terraform module: Open an issue in this repository
• Instruqt custom resources: See Instruqt documentation
• GCP Compute Engine: Consult Google Cloud documentation

License

See LICENSE file for details.