Migration Guide¶

Guide for migrating existing Security Group infrastructure to be managed by the SG Provisioner.

Table of Contents¶

Migrating from Manually Created Security Groups
Migrating from Terraform
Migrating from AWS CDK
Migrating from CloudFormation (Manual Templates)
Parallel Deployment Strategy
Rollback Procedures

Migrating from Manually Created Security Groups¶

Step 1: Inventory Existing Security Groups¶

Export your current security group configuration for reference:

# Export security groups for a specific VPC
aws ec2 describe-security-groups \
  --filters "Name=vpc-id,Values=vpc-0abc123def456" \
  --region us-west-2 \
  --query 'SecurityGroups[].{Name:GroupName,Id:GroupId,Description:Description}' \
  --output table

# Export full rules for a specific security group
aws ec2 describe-security-groups \
  --group-ids sg-0abc123 \
  --region us-west-2 > existing-sg.json

Step 2: Select the Closest Scenario¶

Review available scenarios and select the one that best matches your existing architecture:

docker run --rm \
  -v ~/.aws:/home/sguser/.aws:ro \
  -v $(pwd)/sg/configs:/app/configs:ro \
  -v $(pwd)/sg/reports:/app/reports \
  sg-provisioner:latest \
  --config my-config.yaml \
  --action list-scenarios

Use show-scenario to review the rules of a candidate scenario:

docker run --rm \
  -v ~/.aws:/home/sguser/.aws:ro \
  -v $(pwd)/sg/configs:/app/configs:ro \
  -v $(pwd)/sg/reports:/app/reports \
  sg-provisioner:latest \
  --config my-config.yaml \
  --action show-scenario

Step 3: Create Configuration File¶

Map your existing security groups to a SG Provisioner YAML configuration. Use overrides to capture any custom rules that differ from the base scenario:

client:
  company_name: Global Bank
  company_prefix: globalbank
  account_id: "123456789012"
  tenant_id: "c001"

environment:
  env: prod
  region: us-west-2

security_groups:
  scenario: 3-tier-web           # Closest matching scenario
  vpc_source: direct
  vpc_id: vpc-0abc123def456      # Your existing VPC
  sg_name_override: ""
  workload: ""

  overrides:
    app:
      port_overrides:
        - protocol: tcp
          old_port: 8080
          new_port: 3000         # Your custom app port
      additional_ingress:
        - protocol: tcp
          port: 9090
          source_tier: web
          description: Prometheus metrics

tags:
  cost_center: Engineering
  project: Main Platform
  owner: platform-team

Step 4: Validate Configuration¶

docker run --rm \
  -v ~/.aws:/home/sguser/.aws:ro \
  -v $(pwd)/sg/configs:/app/configs:ro \
  -v $(pwd)/sg/reports:/app/reports \
  sg-provisioner:latest \
  --config globalbank-prod-c001-us-west-2-sg.yaml \
  --action validate-config

Step 5: Generate and Review Template¶

# Generate CloudFormation template
docker run --rm \
  -v ~/.aws:/home/sguser/.aws:ro \
  -v $(pwd)/sg/configs:/app/configs:ro \
  -v $(pwd)/sg/templates:/app/templates \
  -v $(pwd)/sg/reports:/app/reports \
  sg-provisioner:latest \
  --config globalbank-prod-c001-us-west-2-sg.yaml \
  --action create-prov-template

# Generate review report
docker run --rm \
  -v ~/.aws:/home/sguser/.aws:ro \
  -v $(pwd)/sg/configs:/app/configs:ro \
  -v $(pwd)/sg/templates:/app/templates \
  -v $(pwd)/sg/reports:/app/reports \
  sg-provisioner:latest \
  --config globalbank-prod-c001-us-west-2-sg.yaml \
  --action create-review-report

Review the generated HTML report and compare the rules against your existing security groups.

Step 6: Test Deploy¶

Deploy the new security groups with a test suffix to verify they work correctly without affecting production:

docker run --rm \
  -v ~/.aws:/home/sguser/.aws:ro \
  -v $(pwd)/sg/configs:/app/configs:ro \
  -v $(pwd)/sg/reports:/app/reports \
  sg-provisioner:latest \
  --config globalbank-prod-c001-us-west-2-sg.yaml \
  --action test-deploy

Step 7: Migrate Workloads¶

Once the new security groups are validated:

Update your EC2 instances, RDS databases, Lambda functions, and other resources to use the new security group IDs
Verify connectivity is maintained
Monitor for any issues

Step 8: Decommission Old Security Groups¶

After all workloads are migrated and validated:

# Verify no resources are using the old security groups
aws ec2 describe-network-interfaces \
  --filters "Name=group-id,Values=sg-old-web,sg-old-app,sg-old-db" \
  --region us-west-2 \
  --query 'NetworkInterfaces[].{Id:NetworkInterfaceId,Description:Description}'

# Delete old security groups manually (not managed by CloudFormation)
aws ec2 delete-security-group --group-id sg-old-web --region us-west-2
aws ec2 delete-security-group --group-id sg-old-app --region us-west-2
aws ec2 delete-security-group --group-id sg-old-db --region us-west-2

Migrating from Terraform¶

Note: The following steps are based on standard Terraform practices. Adapt commands to match your specific configuration.

Step 1: Export Terraform State¶

# List security group resources in Terraform state
terraform state list | grep aws_security_group

# Export security group details
terraform state show aws_security_group.web
terraform state show aws_security_group.app
terraform state show aws_security_group.db

Step 2: Map to YAML Configuration¶

Translate Terraform resource attributes to SG Provisioner YAML:

Terraform	SG Provisioner YAML
`aws_security_group.ingress[].from_port`	`overrides.<tier>.additional_ingress[].port`
`aws_security_group.ingress[].cidr_blocks`	`overrides.<tier>.additional_ingress[].source`
`aws_security_group.ingress[].security_groups`	`overrides.<tier>.additional_ingress[].source_tier`
`aws_security_group.tags`	`tags` section

Step 3: Deploy and Migrate¶

Follow Steps 3-8 from the manual migration above.

Step 4: Remove from Terraform State¶

After migration, remove old resources from Terraform state to prevent accidental deletion:

terraform state rm aws_security_group.web
terraform state rm aws_security_group.app
terraform state rm aws_security_group.db
# Remove all associated ingress/egress rules

Migrating from AWS CDK¶

Note: The following steps are based on standard AWS CDK practices. Adapt commands to match your specific configuration.

Step 1: Review Synthesized Template¶

cdk synth > existing-template.yaml

Step 2: Map to YAML Configuration¶

Review the CloudFormation template and map security group resources to SG Provisioner YAML. Focus on:

Ingress and egress rules per security group
Cross-security group references
Tags

Step 3: Deploy and Migrate¶

Follow Steps 3-8 from the manual migration above.

Step 4: Destroy CDK Stack¶

After migration, destroy the CDK stack:

cdk destroy

Migrating from CloudFormation (Manual Templates)¶

Step 1: Export Existing Template¶

aws cloudformation get-template \
  --stack-name your-existing-sg-stack \
  --region us-west-2 \
  --query 'TemplateBody' > existing-template.json

Step 2: Map to YAML Configuration¶

Review the existing CloudFormation template and map AWS::EC2::SecurityGroup resources to SG Provisioner YAML. Select the closest matching scenario and use overrides for any custom rules.

Step 3: Deploy and Migrate¶

Follow Steps 3-8 from the manual migration above.

Step 4: Delete Old Stack¶

After migration:

aws cloudformation delete-stack \
  --stack-name your-existing-sg-stack \
  --region us-west-2

Parallel Deployment Strategy¶

For zero-downtime migration, run old and new security groups in parallel:

Week 1: Deploy new SGs via SG Provisioner, test connectivity
Week 2: Migrate non-critical workloads to new SGs
Week 3: Migrate critical workloads to new SGs
Week 4: Monitor, validate, decommission old SGs

Use the workload discriminator to avoid naming collisions during parallel deployment:

# Temporary workload name during migration
security_groups:
  workload: "new"
  # Result: globalbank-prod-c001-us-west-2-new-sg

Once migration is complete, redeploy without the workload discriminator and decommission the temporary stack.

Rollback Procedures¶

CloudFormation Automatic Rollback¶

If deployment fails, CloudFormation automatically rolls back all resources:

# Check stack events for failure reason
aws cloudformation describe-stack-events \
  --stack-name globalbank-prod-c001-us-west-2-sg-stack \
  --query 'StackEvents[?ResourceStatus==`CREATE_FAILED`].[LogicalResourceId,ResourceStatusReason]' \
  --output table \
  --region us-west-2

Manual Rollback¶

If you need to revert after a successful deployment:

# Delete the new SG stack
docker run --rm \
  -v ~/.aws:/home/sguser/.aws:ro \
  -v $(pwd)/sg/configs:/app/configs:ro \
  -v $(pwd)/sg/reports:/app/reports \
  sg-provisioner:latest \
  --config globalbank-prod-c001-us-west-2-sg.yaml \
  --action delete-security-groups --force

Your old security groups remain untouched — the SG Provisioner only manages resources it created.

Workload Rollback¶

If workloads were migrated to new security groups:

Update resources to use old security group IDs
Verify connectivity is restored
Delete new SGs when ready

See LICENSE.txt for terms and conditions.