Make cloud instance sizes configurable

TROUBLESHOOTING.md

@@ -0,0 +1,115 @@
+# TROUBLESHOOTING
+
+This guide shows examples of errors you might see when deploying the linux-ctfs lab, and how to fix them using simple commands.
+
+- [AWS](#aws)
+- [AWS: Region / endpoint / Auth errors](#aws-region--endpoint--auth-errors)
+- [AWS: Quota / vCPU limit errors](#aws-quota--vcpu-limit-errors)
+- [AWS: Service Control Policy (SCP) / Explicit deny errors](#aws-service-control-policy-scp--explicit-deny-errors)
+- [Azure](#azure)
+- [GCP](#gcp)
+
+## AWS
+
+<!-- Placeholder for future screenshots: ![AWS troubleshooting screenshot](docs/images/aws-troubleshooting.png) -->
+
+The Terraform commands in this AWS section assume you are running them from the `aws/` directory.
+
+Before your first AWS deploy, list the regions that are enabled for your account:
+
+```sh
+aws ec2 describe-regions \
+  --region us-east-1 \
+  --all-regions \
+  --query "Regions[?OptInStatus=='opt-in-not-required' || OptInStatus=='opted-in'].{Name:RegionName,Status:OptInStatus}" \
+  --output table
+```
+
+Choose a region where `Status` is `opt-in-not-required` or `opted-in`, then pass it to Terraform:
+
+```sh
+terraform apply -var="aws_region=us-east-1"
+```
+
+### AWS: Region / endpoint / Auth errors
+
+Some AWS regions are disabled by default or require opt-in. If Terraform tries to deploy into one of those regions, you may see authentication or endpoint-related errors.
+
+Example error snippets:
+
+```text
+AuthFailure
+```
+
+```text
+Could not connect to the endpoint URL
+```
+
+If you see an Auth or endpoint error for a specific region, first list the enabled regions for your account:
+
+```sh
+aws ec2 describe-regions \
+  --region us-east-1 \
+  --all-regions \
+  --query "Regions[?OptInStatus=='opt-in-not-required' || OptInStatus=='opted-in'].{Name:RegionName,Status:OptInStatus}" \
+  --output table
+```
+
+Then retry with one of those enabled regions, for example `us-east-1`:
+
+```sh
+terraform apply -var="aws_region=us-east-1"
+```
+
+### AWS: Quota / vCPU limit errors
+
+If your AWS account has a low EC2 quota in the selected region, Terraform may fail with errors like:
+
+```text
+VcpuLimitExceeded
+```
+
+```text
+EC2 QUOTA EXCEEDED
+```
+
+This usually means the account does not have enough EC2 vCPU quota available in that region for the requested instance type.
+
+Try a smaller instance type:
+
+```sh
+terraform apply -var="aws_instance_type=t3.micro"
+```
+
+If you need a larger size, you can request a quota increase in the AWS console for the region you want to use.
+
+### AWS: Service Control Policy (SCP) / Explicit deny errors
+
+A Service Control Policy (SCP) is an organization-level AWS policy that can block actions even if your IAM user or role normally has permission. The linux-ctfs Terraform code cannot override those restrictions.
+
+You may see an error message that includes text like:
+
+```text
+explicit deny in a service control policy
+```
+
+If that happens, either:
+
+- Use a personal AWS account that does not have strict organization policies.
+- Ask your cloud administrator which regions and instance types are allowed, then retry with those values.
+
+Example:
+
+```sh
+terraform apply \
+  -var="aws_region=<allowed-region>" \
+  -var="aws_instance_type=<allowed-instance-type>"
+```
+
+## Azure
+
+(Coming soon) - common deployment issues and how to adjust `azure_vm_size`.
+
+## GCP
+
+(Coming soon) - common deployment issues and how to adjust `gcp_machine_type`.

aws/README.md

@@ -14,22 +14,49 @@
     cd linux-ctfs/aws
     ```
 
-2. (Optional) Modify the AWS region by creating a `terraform.tfvars` file:
+2. Check which AWS regions are enabled for your account:
+
+    ```sh
+    aws ec2 describe-regions \
+      --region us-east-1 \
+      --all-regions \
+      --query "Regions[?OptInStatus=='opt-in-not-required' || OptInStatus=='opted-in'].{Name:RegionName,Status:OptInStatus}" \
+      --output table
+    ```
+
+    For a copy-paste command flow, see [docs/AWS_COMMANDS.md](../docs/AWS_COMMANDS.md).
+
+3. Export one of the enabled regions before running Terraform:
+
+    ```sh
+    export AWS_REGION=us-east-1
+    ```
+
+4. (Optional) Set the AWS region in a `terraform.tfvars` file using one of the enabled regions:
 
     ```sh
     aws_region = "us-east-1"
     ```
 
-3. Initialize and apply Terraform:
+    If you prefer not to use a `terraform.tfvars` file, you can pass the exported value directly to Terraform in the next step.
+
+5. Initialize and apply Terraform:
 
     ```sh
     terraform init
+
+    # If you set aws_region in terraform.tfvars
     terraform apply
+
+    # Or, if you want to pass the exported region directly
+    terraform apply -var="aws_region=$AWS_REGION"
     ```
 
     Type `yes` when prompted.
 
-4. Note the `public_ip_address` output—you'll use this to connect.
+    If you run into errors when deploying, see [TROUBLESHOOTING.md](../TROUBLESHOOTING.md) for common issues and fixes.
+
+6. Note the `public_ip_address` output—you'll use this to connect.
 
 ## Accessing the Lab
 

aws/main.tf

@@ -19,6 +19,12 @@ variable "aws_region" {
   default     = "us-east-1" # Default region if not specified
 }
 
+variable "aws_instance_type" {
+  description = "The AWS instance type to deploy the CTF lab"
+  type        = string
+  default     = "t3.micro"
+}
+
 variable "use_local_setup" {
   description = "Upload and run the local setup package instead of using a pinned release asset (for contributor testing)"
   type        = bool
@@ -252,7 +258,7 @@ data "aws_ami" "ubuntu" {
 
 resource "aws_instance" "ctf_instance" {
   ami           = data.aws_ami.ubuntu.id
-  instance_type = "t3.micro"
+  instance_type = var.aws_instance_type
 
   vpc_security_group_ids = [aws_security_group.ctf_sg.id]
   subnet_id              = aws_subnet.ctf_subnet.id

azure/README.md

@@ -24,6 +24,8 @@
     az login
     ```
 
+    For a copy-paste command flow, see [docs/AZURE_COMMANDS.md](../docs/AZURE_COMMANDS.md).
+
 3. Initialize and apply Terraform:
 
     ```sh
@@ -37,6 +39,8 @@
 
     Type `yes` when prompted.
 
+    If you run into errors when deploying, see [TROUBLESHOOTING.md](../TROUBLESHOOTING.md) for common issues and fixes.
+
 4. Note the `public_ip_address` output—you'll use this to connect.
 
 ## Accessing the Lab

azure/main.tf

@@ -20,6 +20,12 @@ variable "az_region" {
   default     = "East US"
 }
 
+variable "azure_vm_size" {
+  description = "The Azure VM size to deploy the CTF lab"
+  type        = string
+  default     = "Standard_B1s"
+}
+
 variable "subscription_id" {
   description = "Your Azure Subscription ID"
   type        = string
@@ -249,7 +255,7 @@ resource "azurerm_linux_virtual_machine" "ctf_vm" {
   name                = "ctf-vm"
   resource_group_name = azurerm_resource_group.ctf_rg.name
   location            = azurerm_resource_group.ctf_rg.location
-  size                = "Standard_B1s"
+  size                = var.azure_vm_size
   admin_username      = "ctf_user"
   network_interface_ids = [
     azurerm_network_interface.ctf_nic.id,

docs/AWS_COMMANDS.md

@@ -0,0 +1,36 @@
+# AWS Commands
+
+Use these commands to discover an enabled AWS region first, then run Terraform with an explicit region and instance type.
+
+## Check enabled regions
+
+```sh
+aws ec2 describe-regions \
+  --region us-east-1 \
+  --all-regions \
+  --query "Regions[?OptInStatus=='opt-in-not-required' || OptInStatus=='opted-in'].{Name:RegionName,Status:OptInStatus}" \
+  --output table
+```
+
+Choose a region where `Status` is `opt-in-not-required` or `opted-in`.
+
+## Export variables
+
+```sh
+export AWS_REGION=us-east-1
+export AWS_INSTANCE_TYPE=t3.micro
+```
+
+## Run Terraform
+
+```sh
+cd aws
+terraform init
+terraform apply \
+  -var="aws_region=$AWS_REGION" \
+  -var="aws_instance_type=$AWS_INSTANCE_TYPE"
+```
+
+## Troubleshooting
+
+If deployment fails, see [TROUBLESHOOTING.md](../TROUBLESHOOTING.md).

docs/AZURE_COMMANDS.md

@@ -0,0 +1,47 @@
+# Azure Commands
+
+Use these commands to choose your Azure subscription, region, and VM size before running Terraform.
+
+## Sign in and get your subscription ID
+
+```sh
+az login
+az account show --query id -o tsv
+```
+
+## Check VM size availability
+
+```sh
+az vm list-skus \
+  --location eastus \
+  --resource-type virtualMachines \
+  --size Standard_B1s \
+  --all \
+  --query "[?name=='Standard_B1s'].{name:name, restrictions:restrictions}" \
+  -o json
+```
+
+If `restrictions` is `[]`, that VM size is available for your subscription in that region.
+
+## Export variables
+
+```sh
+export AZURE_SUBSCRIPTION_ID="<your-subscription-id>"
+export AZURE_REGION="East US"
+export AZURE_VM_SIZE="Standard_B1s"
+```
+
+## Run Terraform
+
+```sh
+cd azure
+terraform init
+terraform apply \
+  -var="subscription_id=$AZURE_SUBSCRIPTION_ID" \
+  -var="az_region=$AZURE_REGION" \
+  -var="azure_vm_size=$AZURE_VM_SIZE"
+```
+
+## Troubleshooting
+
+If deployment fails, see [TROUBLESHOOTING.md](../TROUBLESHOOTING.md).

docs/GCP_COMMANDS.md

@@ -0,0 +1,42 @@
+# GCP Commands
+
+Use these commands to choose your GCP project, region, zone, and machine type before running Terraform.
+
+## Sign in and check your active project
+
+```sh
+gcloud auth login
+gcloud auth application-default login
+gcloud config list project
+```
+
+## Check machine types in a zone
+
+```sh
+gcloud compute machine-types list --zones=us-central1-a
+```
+
+## Export variables
+
+```sh
+export GCP_PROJECT="<your-gcp-project-id>"
+export GCP_REGION="us-central1"
+export GCP_ZONE="us-central1-a"
+export GCP_MACHINE_TYPE="e2-micro"
+```
+
+## Run Terraform
+
+```sh
+cd gcp
+terraform init
+terraform apply \
+  -var="gcp_project=$GCP_PROJECT" \
+  -var="gcp_region=$GCP_REGION" \
+  -var="gcp_zone=$GCP_ZONE" \
+  -var="gcp_machine_type=$GCP_MACHINE_TYPE"
+```
+
+## Troubleshooting
+
+If deployment fails, see [TROUBLESHOOTING.md](../TROUBLESHOOTING.md).

gcp/README.md

@@ -22,6 +22,8 @@
     gcloud auth application-default login
     ```
 
+    For a copy-paste command flow, see [docs/GCP_COMMANDS.md](../docs/GCP_COMMANDS.md).
+
 3. Initialize and apply Terraform:
 
     ```sh
@@ -36,6 +38,8 @@
 
     Type `yes` when prompted.
 
+    If you run into errors when deploying, see [TROUBLESHOOTING.md](../TROUBLESHOOTING.md) for common issues and fixes.
+
 4. Note the `public_ip_address` output—you'll use this to connect.
 
 

gcp/main.tf

@@ -25,6 +25,12 @@ variable "gcp_zone" {
   default     = "us-central1-a"
 }
 
+variable "gcp_machine_type" {
+  description = "The GCP machine type to deploy the CTF lab"
+  type        = string
+  default     = "e2-micro"
+}
+
 variable "use_local_setup" {
   description = "Upload and run the local setup package instead of using a pinned release asset (for contributor testing)"
   type        = bool
@@ -185,7 +191,7 @@ resource "google_compute_firewall" "ctf_firewall_http" {
 # Create a compute instance
 resource "google_compute_instance" "ctf_instance" {
   name         = "ctf-instance"
-  machine_type = "e2-micro"
+  machine_type = var.gcp_machine_type
   zone         = var.gcp_zone
 
   tags = ["ctf-instance"]