Update Procedures¶

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

Table of Contents¶

Version Strategy
Pre-Update Checklist
Updating the Docker Image
Rollback Procedures
Configuration Updates
Infrastructure Maintenance
Adding Solutions to Existing Buckets
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 s3-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>/s3-provisioner:latest

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

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

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

Verify New Version¶

# Check image details
docker images s3-provisioner

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

# Validate existing config against new version
docker run --rm \
  -v $(pwd)/s3/configs:/app/configs:ro \
  -v $(pwd)/s3/reports:/app/reports \
  s3-provisioner:latest \
  --config your-config.yaml \
  --action validate-config

Test Before Production¶

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

docker run --rm \
  -v ~/.aws:/home/s3user/.aws:ro \
  -v $(pwd)/s3/configs:/app/configs:ro \
  -v $(pwd)/s3/reports:/app/reports \
  s3-provisioner:latest \
  --config your-config.yaml \
  --action test-deploy \
  --solution master-solution

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-1

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>/s3-provisioner:1.2.2 s3-provisioner:latest

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

# Validate config with previous version
docker run --rm \
  -v $(pwd)/s3/configs:/app/configs:ro \
  -v $(pwd)/s3/reports:/app/reports \
  s3-provisioner:latest \
  --config your-config.yaml \
  --action validate-config

Keep Multiple Versions¶

Tag versions explicitly so you can switch between them:

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

# Use specific version
docker run --rm \
  -v $(pwd)/s3/configs:/app/configs:ro \
  -v $(pwd)/s3/reports:/app/reports \
  s3-provisioner:1.2.2 \
  --config your-config.yaml \
  --action validate-config

Configuration Updates¶

Modifying an Existing Configuration¶

When you need to change bucket settings (versioning, lifecycle policy, tags):

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

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

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

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

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

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

Updating Tags¶

To update tags on an existing bucket, 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.

Changing Lifecycle Policy¶

# Before
s3:
  lifecycle_policy: development

# After
s3:
  lifecycle_policy: ml-optimized

After changing, regenerate the template and preview changes with show-changes before applying.

Infrastructure Maintenance¶

Drift Detection¶

Check if deployed infrastructure has been modified outside of CloudFormation:

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

Uploading Updated Templates¶

After regenerating a template, upload it to S3 for reference:

docker run --rm \
  -v ~/.aws:/home/s3user/.aws:ro \
  -v $(pwd)/s3/configs:/app/configs:ro \
  -v $(pwd)/s3/templates:/app/templates \
  -v $(pwd)/s3/reports:/app/reports \
  s3-provisioner:latest \
  --config edge-prod-b001-us-west-1-s3.yaml \
  --action upload-template \
  --solution master-solution

Replacing a Deployment¶

To fully replace an existing deployment:

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

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

Warning: tear-down deletes the bucket and all its contents. Ensure you have backups before proceeding.

Adding Solutions to Existing Buckets¶

Pattern A: Shared Bucket¶

Add a new ML solution to an existing shared bucket:

docker run --rm \
  -v ~/.aws:/home/s3user/.aws:ro \
  -v $(pwd)/s3/configs:/app/configs:ro \
  -v $(pwd)/s3/reports:/app/reports \
  s3-provisioner:latest \
  --config edge-prod-b001-us-west-1-s3.yaml \
  --action deploy-solution \
  --solution recommendation-engine

Pattern B: Dedicated Bucket¶

Create a new config file for the new solution and deploy:

# 1. Create config with bucket_name_override
# configs/edge-prod-b001-us-west-1-recommendation-engine-s3.yaml

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

# 3. Deploy
docker run --rm \
  -v ~/.aws:/home/s3user/.aws:ro \
  -v $(pwd)/s3/configs:/app/configs:ro \
  -v $(pwd)/s3/templates:/app/templates \
  -v $(pwd)/s3/reports:/app/reports \
  s3-provisioner:latest \
  --config edge-prod-b001-us-west-1-recommendation-engine-s3.yaml \
  --action create-bucket \
  --solution recommendation-engine \
  --force

Monitoring After Update¶

Verify Deployed Infrastructure¶

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

# Check bucket exists
aws s3 ls s3://edge-prod-b001-us-west-1-s3/

# List solution folders
aws s3 ls s3://edge-prod-b001-us-west-1-s3/solutions/

# Run drift detection
docker run --rm \
  -v ~/.aws:/home/s3user/.aws:ro \
  -v $(pwd)/s3/configs:/app/configs:ro \
  -v $(pwd)/s3/reports:/app/reports \
  s3-provisioner:latest \
  --config edge-prod-b001-us-west-1-s3.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.