Update Procedures¶

Procedures for safely updating the SG Provisioner tool and maintaining deployed infrastructure.

Table of Contents¶

Version Strategy
Pre-Update Checklist
Updating the Docker Image
Rollback Procedures
Configuration Updates
Infrastructure Maintenance
Monitoring After Update
Update Schedule

Version Strategy¶

Semantic Versioning¶

We follow Semantic Versioning 2.0.0:

MAJOR (1.x.x): Breaking changes, incompatible configuration format changes
MINOR (x.1.x): New features, new actions, new scenarios, backward compatible
PATCH (x.x.1): Bug fixes, backward compatible

Example: 1.2.3 → Major: 1, Minor: 2, Patch: 3

Image Tags¶

latest: Most recent stable release
1.2.3: Specific version (recommended for production)
1.2: Latest patch for minor version

Pre-Update Checklist¶

Before updating:

Review RELEASE_NOTES.md for breaking changes
Backup current configuration files
Document current image version: docker images sg-provisioner
Test new version against a non-production config first
Schedule maintenance window for production updates
Notify stakeholders
Prepare rollback plan (keep previous image tag)

Updating the Docker Image¶

Get New Version from AWS Marketplace¶

When a new version is available, you will be notified via AWS Marketplace. To update:

Log into AWS Console
Navigate to AWS Marketplace → Manage Subscriptions
Select SG Provisioner
Follow the instructions to pull the latest image

Verify New Version¶

# Check image details
docker images sg-provisioner

# Verify tool runs
docker run --rm sg-provisioner:latest --help

# Validate existing config against new version
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

Test Before Production¶

Run a test deployment with the new image to verify compatibility:

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

This creates an isolated test stack with a random suffix — no impact on production resources. Delete the test stack when done:

aws cloudformation delete-stack \
  --stack-name <test-stack-name> \
  --region us-west-2

Rollback Procedures¶

Quick Rollback¶

If the new version causes issues, revert to the previous image. Contact AWS Marketplace support to obtain the previous version, then tag it locally:

# Re-tag previous version as latest
docker tag sg-provisioner:1.2.2 sg-provisioner:latest

# Verify rollback
docker run --rm sg-provisioner:latest --help

# Validate config with previous version
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

Keep Multiple Versions¶

Tag versions explicitly so you can switch between them:

docker tag sg-provisioner:latest sg-provisioner:1.2.3

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

Configuration Updates¶

Modifying an Existing Configuration¶

When you need to change security group settings (port overrides, additional rules, tags):

# 1. Edit configuration file
vi sg/configs/globalbank-prod-c001-us-west-2-sg.yaml

# 2. Validate changes
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

# 3. Regenerate 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

# 4. Validate the 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 validate-prov-template

# 5. Preview what will change
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 show-changes

# 6. 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

# 7. Redeploy with updated configuration
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-security-groups --force

Updating Tags¶

To update tags on existing security groups, modify the tags section in your config and follow the configuration update workflow above. The show-changes action will display the tag modifications before they are applied.

Adding Override Rules¶

When adding new ingress/egress rules via overrides:

Add the new rules to the overrides section in your configuration
Validate and regenerate the template
Use show-changes to verify only the expected rules are being added
Redeploy with create-security-groups --force

Infrastructure Maintenance¶

Drift Detection¶

Check if deployed security groups have been modified outside of CloudFormation:

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 check-drift

If drift is detected, review the changes and decide whether to:

Update the configuration to match the current state
Redeploy to restore the intended state

Replacing a Deployment¶

To fully replace an existing SG deployment:

# 1. Delete existing security groups
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

# 2. Redeploy with updated configuration
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-security-groups --force

Warning: delete-security-groups removes the CloudFormation stack and all security groups. Ensure no EC2 instances, RDS databases, Lambda functions, or other resources are using these security groups before proceeding.

Monitoring After Update¶

Verify Deployed Infrastructure¶

# Check CloudFormation stack status
aws cloudformation describe-stacks \
  --stack-name globalbank-prod-c001-us-west-2-sg-stack \
  --region us-west-2 \
  --query 'Stacks[0].StackStatus'

# Check security groups exist
aws ec2 describe-security-groups \
  --filters "Name=tag:ManagedBy,Values=sg-provisioner-tool" \
  --region us-west-2 \
  --query 'SecurityGroups[].{Name:GroupName,Id:GroupId}'

# Check SSM parameters
aws ssm get-parameters-by-path \
  --path /sg/globalbank-prod-c001-us-west-2-sg/ \
  --region us-west-2

# Run drift detection
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 check-drift

Review Logs¶

# Check recent execution logs
ls -lt sg/reports/*.log | head -5

# Check for errors in logs
grep -i error sg/reports/*.log

Update Schedule¶

Recommended Schedule¶

Security patches: Within 24 hours of release
Bug fixes: Within 1 week
Minor updates: Monthly
Major updates: Quarterly (after thorough testing)

Maintenance Windows¶

Development: Anytime
Staging: Business hours (for immediate feedback)
Production: Scheduled maintenance window with stakeholder notification

See LICENSE.txt for terms and conditions.