Update Procedures¶

Procedures for safely updating the VPC 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, 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 vpc-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¶

Pull New Version¶

# Pull latest from AWS Marketplace registry
docker pull public.ecr.aws/<marketplace-id>/vpc-provisioner:latest

# Or pull specific version
docker pull public.ecr.aws/<marketplace-id>/vpc-provisioner:1.2.3

# Tag locally
docker tag public.ecr.aws/<marketplace-id>/vpc-provisioner:latest vpc-provisioner:latest

Note: Replace <marketplace-id> with the actual registry path from your AWS Marketplace subscription.

Verify New Version¶

# Check image details
docker images vpc-provisioner

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

# Validate existing config against new version
docker run --rm \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-b001-us-west-2-vpc.yaml \
  --action validate-config

Test Before Production¶

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

docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-b001-us-west-2-vpc.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:

# Re-tag previous version
docker tag public.ecr.aws/<marketplace-id>/vpc-provisioner:1.2.2 vpc-provisioner:latest

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

# Validate config with previous version
docker run --rm \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-b001-us-west-2-vpc.yaml \
  --action validate-config

Keep Multiple Versions¶

Tag versions explicitly so you can switch between them:

docker tag public.ecr.aws/<marketplace-id>/vpc-provisioner:1.2.2 vpc-provisioner:1.2.2
docker tag public.ecr.aws/<marketplace-id>/vpc-provisioner:1.2.3 vpc-provisioner:1.2.3

# Use specific version
docker run --rm \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:1.2.2 \
  --config edge-prod-b001-us-west-2-vpc.yaml \
  --action validate-config

Configuration Updates¶

Modifying an Existing Configuration¶

When you need to change VPC settings (CIDR blocks, subnets, NAT gateway, tags):

# 1. Edit configuration file
vi configs/edge-prod-b001-us-west-2-vpc.yaml

# 2. Validate changes
docker run --rm \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-b001-us-west-2-vpc.yaml \
  --action validate-config

# 3. Regenerate CloudFormation template
docker run --rm \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/templates:/app/templates \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-b001-us-west-2-vpc.yaml \
  --action create-prov-template

# 4. Validate the template
docker run --rm \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/templates:/app/templates \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-b001-us-west-2-vpc.yaml \
  --action validate-prov-template

# 5. Preview what will change
docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/templates:/app/templates \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-b001-us-west-2-vpc.yaml \
  --action show-changes

# 6. Regenerate IAM policy (if permissions changed)
docker run --rm \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/policies:/app/policies \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-b001-us-west-2-vpc.yaml \
  --action create-policy

Updating Tags¶

To update tags on an existing VPC, 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 Subnets¶

When adding new subnets to an existing VPC:

Add the new subnet definitions to your configuration
Ensure CIDRs don’t overlap with existing subnets
Regenerate the template and preview changes with show-changes
Verify the changes are additive (no replacements of existing subnets)

Infrastructure Maintenance¶

Drift Detection¶

Check if deployed infrastructure has been modified outside of CloudFormation:

docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-b001-us-west-2-vpc.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 VPC deployment:

# 1. Tear down existing infrastructure
docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-b001-us-west-2-vpc.yaml \
  --action delete-vpc \
  --force

# 2. Redeploy with updated configuration
docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/templates:/app/templates \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-b001-us-west-2-vpc.yaml \
  --action create-vpc \
  --force

Warning: delete-vpc removes the VPC and all its resources (subnets, NAT gateways, route tables, internet gateway). Ensure no EC2 instances, RDS databases, or other services are running in the VPC before proceeding.

Monitoring After Update¶

Verify Deployed Infrastructure¶

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

# Check VPC exists
aws ec2 describe-vpcs \
  --filters "Name=tag:Name,Values=edge-prod-b001-us-west-2-vpc" \
  --region us-west-2

# Check subnets
aws ec2 describe-subnets \
  --filters "Name=tag:Name,Values=edge-prod-b001-us-west-2-*" \
  --region us-west-2 \
  --query 'Subnets[].{Name:Tags[?Key==`Name`].Value|[0],CIDR:CidrBlock,AZ:AvailabilityZone}'

# Run drift detection
docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-b001-us-west-2-vpc.yaml \
  --action check-drift

Review Logs¶

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

# Check for errors in logs
grep -i error 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.