Instruqt GCP Project Custom Resource

This Terraform module provisions a complete Google Cloud Platform environment for use with Instruqt custom resources. It creates an isolated GCP project with a dedicated user and service account for each Instruqt sandbox.

What This Module Provisions

• GCP Project: A new project within your organization's folder structure
• Google Workspace User: A dedicated user account with randomized password
• Service Account: A service account with generated key for programmatic access
• API Services: Enables specified GCP services (e.g., Compute Engine, Cloud Storage)
• IAM Roles: Grants specified roles to the user and service account

Prerequisites

• A Google Cloud organization with billing enabled
• A Google Workspace account with admin access
• A parent GCP project with necessary APIs enabled
• Service account credentials with permissions to:
  • Create projects in the organization
  • Create users in Google Workspace
  • Assign IAM roles

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: Parent GCP project name
   • parent_organization_domain: Your organization's domain
   • project_folder_name: Folder for projects (e.g., "Instruqt-Projects")
   • billing_account_id: GCP billing account ID
   • project_name: Display name (e.g., "Student Project")
   • sandbox_id: Use the ${SANDBOX_ID} variable
   • googleworkspace_impersonated_user_email: Admin email
   • services: List of APIs to enable (compute, storage, etc.)
   • roles: IAM roles to grant (owner, editor, etc.)

Required Variables

Variable	Description
credentials	JSON credentials for authenticating with GCP
project	Parent GCP project name
parent_organization_domain	Your organization's domain (e.g., "company.com")
project_folder_name	Folder name where projects will be created
billing_account_id	GCP billing account ID
sandbox_id	Unique identifier for the Instruqt sandbox
project_name	Display name for the new project
googleworkspace_impersonated_user_email	Admin email for Google Workspace operations
services	List of GCP services to enable
roles	List of IAM roles to grant

Optional Variables

Variable	Default	Description
region	"europe-west1"	Default GCP region
project_prefix	"s"	Prefix for project IDs
googleworkspace_consumer_id	"googleworkspace"	Google Workspace consumer ID
googleworkspace_org_unit_path	null	Organizational unit for user creation

Outputs

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

Output	Description	Sensitive
project_id	The generated GCP project ID	No
project_name	The project display name	No
user_email	The created user's email address	No
user_password	The user's generated password	Yes
service_account_email	The service account email	No
service_account_key	The service account private key (base64)	Yes

Accessing Outputs in Instruqt

Use outputs in your track's lifecycle scripts or challenge scripts:

# Access outputs using environment variables
echo "Project ID: ${GOOGLE_CLOUD_PROJECT_ID}"
echo "User Email: ${GOOGLE_CLOUD_USER_EMAIL}"

# Use service account for authentication
echo "${GOOGLE_CLOUD_SERVICE_ACCOUNT_KEY}" | base64 -d > /tmp/key.json
gcloud auth activate-service-account --key-file=/tmp/key.json
gcloud config set project "${GOOGLE_CLOUD_PROJECT_ID}"

Project ID Format

Projects are created with the following ID format:

{prefix}-{sandbox_id}-{random_string}

Example: s-abc123def-xjkpmqrt

This ensures unique project IDs while maintaining traceability to the sandbox.

Security Considerations

• User passwords are randomly generated and marked as sensitive
• Service account keys are base64-encoded and marked as sensitive
• Projects are automatically labeled with the sandbox ID for tracking
• Consider implementing automatic project cleanup after sandbox completion

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	instruqt-parent-project
parent_organization_domain	example.com
project_folder_name	Instruqt-Sandboxes
billing_account_id	012345-6789AB-CDEF01
project_name	Student Lab Environment
sandbox_id	${SANDBOX_ID} (Instruqt variable)
googleworkspace_impersonated_user_email	admin@example.com
services	["compute.googleapis.com", "storage.googleapis.com", "cloudresourcemanager.googleapis.com", "iam.googleapis.com"]
roles	["roles/owner"]

Cleanup

Instruqt will automatically destroy resources when the sandbox ends. The module is designed to clean up:

• The GCP project (which cascades to all resources within)
• The Google Workspace user account
• The service account and its keys

Support

For issues with:

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

License

See LICENSE file for details.