feat(perforce/p4-code-review): Migrate from ECS to EC2

[gabebatista]

Issue number: N/A

Summary

Changes

This PR migrates the P4 Code Review (Helix Swarm) module from a containerized ECS/Fargate deployment to a native EC2 Auto Scaling Group deployment with persistent storage.

Key changes:

• Packer Template: New AMI builder for Ubuntu 24.04 LTS (officially supported by Perforce until 2029), replacing the unsupported Amazon Linux 2023
• Terraform Module: Complete infrastructure refactor from ECS to EC2 Auto Scaling with:
  • Persistent EBS volume support with automatic attachment on instance replacement
  • Self-healing infrastructure via Auto Scaling Group
  • Native DEB package installation instead of containers
  • SSM Session Manager access (replacing SSH)
  • Comprehensive user-data script for runtime configuration
• P4 Server Integration:
  • Dual super user approach - always creates a super user for Swarm extension compatibility, plus optional custom super user
  • unlimited_timeout group for service accounts to prevent ticket expiration
  • Fixed Swarm extension configuration by establishing P4 trust and authentication before modifying extension settings
• Documentation:
  • Enhanced Packer README with architecture details, runtime configuration, and troubleshooting guides
  • Updated p4-code-review module README to reflect EC2 architecture (removed ECS/Fargate/Docker references)
  • Updated variable descriptions in parent perforce module for EC2-based fields
• Example: Updated to remove deprecated ECS-related variables

User experience

In the existing implementation, when the p4cr container is restarted jobs and queue data is lost due to the lack of Swarm-compatible persistent storage. The new implementation uses EC2 in place of ECS/Fargate, allowing for EBS volumes to handle persistent storage for /opt/perforce/swarm/data.

Files Changed

Area	Files	Description
Packer	assets/packer/perforce/p4-code-review/*	New AMI builder for Ubuntu 24.04 with Swarm
Packer	assets/packer/perforce/p4-server/p4_configure.sh	Dual super user + unlimited_timeout group
Terraform	modules/perforce/modules/p4-code-review/*	EC2 ASG, EBS, launch template, user-data
Terraform	modules/perforce/sg.tf	Security group rules for P4 Server ↔ Swarm
Terraform	modules/perforce/variables.tf	Updated p4_code_review_config descriptions
Example	modules/perforce/examples/create-resources-complete/main.tf	Removed ECS variables

How to Test

Prerequisites

1. AWS account with appropriate permissions
2. Packer installed (>= 1.8.0)
3. Terraform installed (>= 1.0)
4. A Route53 hosted zone for DNS records
5. An ACM certificate for HTTPS

Step 1: Build the P4 Code Review AMI

cd assets/packer/perforce/p4-code-review
packer init p4_code_review_x86.pkr.hcl
packer build p4_code_review_x86.pkr.hcl

Note the AMI ID from the output (e.g., ami-0abc123def456789).

Step 2: Build the P4 Server AMI (if not already available)

cd assets/packer/perforce/p4-server
packer init p4_al2023_x86.pkr.hcl
packer build p4_al2023_x86.pkr.hcl

Step 3: Deploy the Infrastructure

Use the example configuration or create your own:

cd modules/perforce/examples/create-resources-complete

# Create terraform.tfvars with your values
cat > terraform.tfvars <<TFVARS
project_prefix = "test"
certificate_arn = "arn:aws:acm:us-east-1:ACCOUNT:certificate/CERT-ID"
route53_public_hosted_zone_id = "Z0123456789ABCDEFGHIJ"
fully_qualified_domain_name = "perforce.example.com"
TFVARS

terraform init
terraform apply

Step 4: Verify the Deployment

1. P4 Server: Connect using P4V or p4 CLI

   p4 -p ssl:perforce.example.com:1666 info

2. P4 Code Review (Swarm):

   • Navigate to https://review.perforce.example.com
   • Log in with a Perforce user
   • Verify changes are visible and queue workers are running

3. Verify Swarm Extension (via SSM on P4 Server):

   # Check extension is installed
   p4 extension --list --type extensions
   
   # Verify Swarm-Secure is set correctly
   p4 extension --configure Perforce::helix-swarm -o | grep Swarm-Secure
   # Should show: Swarm-Secure: false

4. Test Instance Recovery:

   • Terminate the Swarm EC2 instance from AWS Console
   • Verify Auto Scaling Group launches a new instance
   • Confirm Swarm is accessible again with data intact (EBS volume reattaches)

Expected Outcomes

• ✅ P4 Server accepts SSL connections on port 1666
• ✅ Swarm web UI loads and shows P4 changes
• ✅ Queue workers are running (check via Swarm API: curl https://review.example.com/api/v10/queue/workers)
• ✅ Swarm extension installed on P4 Server with Swarm-Secure: false
• ✅ Data persists across instance replacement

Checklist

• I have performed a self-review of this change
• Changes have been tested
• Changes are documented

Is this a breaking change?

Yes, this is a breaking change.

Users currently running P4 Code Review using the ECS-based module will need to:

1. Build new AMIs using the updated Packer template
2. Migrate their data from ECS containers to the new EBS-backed EC2 instances
3. Update their Terraform configurations to use the new EC2-based variables

Migration guide and detailed documentation have been included in the module README.

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created might not be successful.

[github-actions]

📚 Documentation Preview

✅ Preview deployed successfully!

🔗 Preview URL: https://aws-games.github.io/cloud-game-development-toolkit/preview-pr-852/

🔒 Maintainer Action Required

The preview requires approval before it's accessible. A maintainer must approve the GitHub Pages deployment in the Environments section.

Once approved, the preview will be accessible within 1-2 minutes.

Build Information

• Status: ✅ Deployed (awaiting approval)
• Commit: f7e56004a34c9a1129182a0232e01df90f989b3a
• Workflow Run: #114

---

This preview will be automatically deleted when the PR is merged or closed.

[hwkiem]

Plenty of comments and some minor changes requested or clarification needed. Also, can you change the name of the PR to conventional commit if the plan is to squash and merge? or is the plan to rebase and merge?

[hwkiem]

⚠️ Potential Data Corruption Risk

I've identified a critical issue in modules/perforce/modules/p4-code-review/user-data.sh.tpl (lines 85-93) that could lead to data corruption.

The Issue

The force detach operation could potentially cause data corruption if the previous instance is still writing to the volume:

aws ec2 detach-volume \
    --region "$REGION" \
    --volume-id "$VOLUME_ID" \
    --force 2>&1 | tee -a /tmp/swarm-setup.log || log "Warning: Force detach may have failed"

Recommended Fix

Add an instance state check before force detaching to ensure the previous instance is truly terminated:

# Check if the attached instance is terminated before force detaching
if [ "$ATTACHED_INSTANCE" != "none" ] && [ "$ATTACHED_INSTANCE" != "null" ]; then
    INSTANCE_STATE=$(aws ec2 describe-instances \
        --region "$REGION" \
        --instance-ids "$ATTACHED_INSTANCE" \
        --query 'Reservations[0].Instances[0].State.Name' \
        --output text 2>/dev/null || echo "unknown")
    
    if [ "$INSTANCE_STATE" = "terminated" ] || [ "$INSTANCE_STATE" = "unknown" ]; then
        log "Previous instance $ATTACHED_INSTANCE is terminated/unknown, safe to force detach"
        aws ec2 detach-volume --region "$REGION" --volume-id "$VOLUME_ID" --force
    else
        log "ERROR: Volume attached to running instance $ATTACHED_INSTANCE (state: $INSTANCE_STATE)"
        exit 1
    fi
fi

This ensures we only force detach from terminated instances, preventing potential corruption of the Swarm data volume.

[hwkiem]

Only other feedback - lets review the documentation. It built and deployed a preview to GH pages (see docs comment near the top of this PR). The architecture diagram is outdated.

[github-actions]

❌ Terraform validation failed for modules/perforce/examples/create-resources-complete

View detailed logs: Workflow run

[github-actions]

❌ Terraform validation failed for modules/perforce/modules/p4-code-review

View detailed logs: Workflow run

[github-actions]

❌ Terraform validation failed for modules/perforce

View detailed logs: Workflow run

[hwkiem]

LGTM