Update Procedures¶

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

Table of Contents¶

Version Strategy
Pre-Update Checklist
Updating the Docker Image
Rollback Procedures
Configuration Updates
Infrastructure Maintenance
Tier Upgrades
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¶

Each tier has its own image tag:

startup-5: Startup tier (5 groups)
medium-10: Medium tier (10 groups)
enterprise-12: Enterprise tier (12 groups)

Pre-Update Checklist¶

Before updating:

Review Release Notes for breaking changes
Backup current configuration files
Document current image versions: docker images sec-provisioner
Export current groups, roles, and policies for comparison
Test new version against a non-production config first
Schedule maintenance window for production updates
Notify stakeholders

Updating the Docker Image¶

Pull New Version¶

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

# Tag locally
docker tag public.ecr.aws/<marketplace-id>/sec-provisioner:medium-10 sec-provisioner:medium-10

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

Verify New Version¶

# Check image details
docker images sec-provisioner

# Verify tool runs
docker run --rm sec-provisioner:medium-10 --help

# Validate existing config against new version
docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action validate-config

Test Before Production¶

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

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

Compare Exports¶

Export groups, roles, and policies with the new version and compare against previous exports:

# Export with new version
docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/groups:/app/groups \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action export-groups

# Compare with previous exports
diff sec/groups/previous/ sec/groups/

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>/sec-provisioner:medium-10-prev sec-provisioner:medium-10

# Verify rollback
docker run --rm sec-provisioner:medium-10 --help

# Validate config with previous version
docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action validate-config

Keep Multiple Versions¶

Tag versions explicitly so you can switch between them:

docker tag public.ecr.aws/<marketplace-id>/sec-provisioner:medium-10 sec-provisioner:medium-10-v1.0.0
docker tag public.ecr.aws/<marketplace-id>/sec-provisioner:medium-10 sec-provisioner:medium-10-v1.1.0

Configuration Updates¶

Modifying Groups or Roles¶

When you need to change group permissions, add roles, or modify policy assignments:

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

# 2. Validate changes
docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action validate-config

# 3. Export and review updated definitions
docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/groups:/app/groups \
  -v $(pwd)/sec/roles:/app/roles \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action export-groups

docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/groups:/app/groups \
  -v $(pwd)/sec/roles:/app/roles \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action export-roles

# 4. Regenerate template
docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/templates:/app/templates \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action create-prov-template

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

# 6. Deploy update
docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action deploy \
  --force

Adding a New Group¶

Add the group definition under security.iam_groups in your config
Add the group name to security_profiles.<profile>.enabled_groups
Follow the modification workflow above

Adding a New Assumable Role¶

Add the role definition under security.assumable_roles
Add the role name to security_profiles.<profile>.enabled_assumable_roles
Add the role name to the appropriate group’s assumable_roles list
Follow the modification workflow above

Infrastructure Maintenance¶

Drift Detection¶

Check if deployed infrastructure has been modified outside of CloudFormation:

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

Note: CloudFormation does not support drift detection for IAM Groups. Only IAM Roles and Policies are checked.

Replacing a Deployment¶

To fully replace an existing deployment:

# 1. Delete existing stack
docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action delete-stack \
  --force

# 2. Redeploy
docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action deploy \
  --force

Warning: delete-stack removes all IAM groups, roles, and policies managed by the stack. Users assigned to groups will lose their permissions immediately.

Tier Upgrades¶

When upgrading from a lower tier to a higher tier (e.g., startup → medium):

Purchase the new tier via AWS Marketplace
Pull the new tier image: docker pull public.ecr.aws/<marketplace-id>/sec-provisioner:medium-10
Create a new config based on the medium master config template
Migrate your customizations from the startup config to the medium config (client, environment, deployment, tags sections carry over directly)
Add new groups and roles available in the medium tier to your security profile
Delete the startup stack: --action delete-stack --force with the startup image
Deploy the medium stack: --action deploy --force with the medium image

Important: Your existing IAM users will need to be re-added to the new groups after the tier upgrade, as the group names change with the new stack.

Monitoring After Update¶

Verify Deployed Infrastructure¶

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

# Check IAM groups
aws iam list-groups \
  --query 'Groups[?starts_with(GroupName, `edge-prod-b001`)].GroupName'

# Check IAM roles
aws iam list-roles \
  --query 'Roles[?starts_with(RoleName, `edge-prod-b001`)].RoleName'

# Check SSM parameters
aws ssm get-parameters-by-path \
  --path /security/edge-prod-b001-us-west-1-medium-sec/ \
  --region us-west-1 \
  --query 'Parameters[].Name'

# Run drift detection
docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action check-drift

Review Logs¶

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

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