Update the solution

This section describes how to update the Spatial Data Management Application to a newer version.

Update Overview

Updates are performed using AWS CloudFormation stack updates, which modify existing resources in place where possible. Most updates can be performed with minimal downtime.

Before You Update

1. Review Release Notes

Check the release notes for the new version:

2. Backup Critical Data

Although Amazon DynamoDB has Point-in-Time Recovery enabled, create explicit backups:

# Backup DynamoDB tables (replace <STACK-NAME> with your stack name)
for table in $(aws dynamodb list-tables --query 'TableNames[?contains(@, `<STACK-NAME>`)]' --output text); do
  aws dynamodb create-backup \
    --table-name $table \
    --backup-name "${table}-pre-update-$(date +%Y%m%d)"
done

3. Review Current Configuration

Export current stack parameters:

# Replace <STACK-NAME> with your CloudFormation stack name
aws cloudformation get-template \
  --stack-name <STACK-NAME> \
  --query 'TemplateBody' > current-template.json

aws cloudformation describe-stacks \
  --stack-name <STACK-NAME> \
  --query 'Stacks[0].Parameters' > current-parameters.json

4. Test in Non-Production Environment

Always test updates in a development or staging environment first.

Update Procedures

The following steps guide you through updating the solution using AWS CloudFormation change sets. You can also perform these steps through the AWS CloudFormation console. For detailed information about CloudFormation update processes, see Updating stacks using change sets in the AWS CloudFormation User Guide.

Standard Update (No Breaking Changes)

Step 0: Get Your Stack Name

If you don’t know your stack name, list all CloudFormation stacks to find it:

# List all stacks
aws cloudformation list-stacks \
  --stack-status-filter CREATE_COMPLETE UPDATE_COMPLETE \
  --query 'StackSummaries[*].[StackName,StackStatus]' \
  --output table

Look for your Spatial Data Management stack (for example, SpatialDataManagement). Use this stack name in the following steps by replacing <STACK-NAME> with your actual stack name.

Step 1: Download New Template

Download the latest CloudFormation template for the new version. For download instructions, see Step 1: Launch stack in the Deploy the solution section.

Step 2: Review Changes

Create a change set to preview changes before applying the update. Replace <CHANGE-SET-NAME> with a descriptive name based on the version you’re updating to (for example, update-to-v1-1-0). Refer to the Document revisions section or the version from the downloaded template to determine the appropriate version number.

# Create change set to preview changes
aws cloudformation create-change-set \
  --stack-name <STACK-NAME> \
  --change-set-name <CHANGE-SET-NAME> \
  --template-body file://new-template.json \
  --parameters file://current-parameters.json \
  --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM

Step 3: Review Change Set

# Review the change set (use the same change set name from Step 2)
aws cloudformation describe-change-set \
  --stack-name <STACK-NAME> \
  --change-set-name <CHANGE-SET-NAME> \
  --query 'Changes[*].[Type,ResourceChange.Action,ResourceChange.LogicalResourceId,ResourceChange.ResourceType]' \
  --output table

Step 4: Execute Update

aws cloudformation execute-change-set \
  --stack-name SpatialDataManagement \
  --change-set-name update-to-v1-1-0

Step 5: Monitor Update Progress

aws cloudformation describe-stack-events \
  --stack-name SpatialDataManagement \
  --query 'StackEvents[*].[Timestamp,ResourceStatus,ResourceType,LogicalResourceId]' \
  --output table

Update Impact by Component

Lambda Functions

DynamoDB Tables

API Gateway

OpenSearch Serverless

CloudFront Distribution

VPC Changes

Post-Update Validation

1. Verify Stack Status

aws cloudformation describe-stacks \
  --stack-name SpatialDataManagement \
  --query 'Stacks[0].StackStatus'

Expected: UPDATE_COMPLETE

2. Test API Functionality

API_ENDPOINT=$(aws cloudformation describe-stacks \
  --stack-name SpatialDataManagement \
  --query 'Stacks[0].Outputs[?OutputKey==`ApiEndpoint`].OutputValue' \
  --output text)

# Test health endpoint
curl $API_ENDPOINT/health

# Test authenticated endpoint (requires token)
curl -H "Authorization: Bearer $TOKEN" $API_ENDPOINT/api/v1/libraries

3. Check Lambda Function Versions

aws lambda list-functions \
  --query 'Functions[?contains(FunctionName, `SpatialDataManagement`)].[FunctionName,LastModified,State]' \
  --output table

Rollback Procedures

Automatic Rollback

CloudFormation automatically rolls back if update fails. Monitor rollback:

aws cloudformation describe-stack-events \
  --stack-name SpatialDataManagement \
  --query 'StackEvents[?contains(ResourceStatus, `ROLLBACK`)]'

Manual Rollback

If you need to manually rollback to previous version:

Option 1: Use Previous Template

aws cloudformation update-stack \
  --stack-name SpatialDataManagement \
  --template-body file://current-template.json \
  --parameters file://current-parameters.json \
  --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM

Update Best Practices

1. Maintenance Window

Schedule updates during low-usage periods:

2. Incremental Updates

Update one major version at a time:

3. Monitoring During Update

Set up CloudWatch alarms to monitor:

4. Communication Plan

Version-Specific Update Notes

Before updating, refer to the Document revisions section for version-specific information. Review the release notes to determine if there are any special deployment sequences, breaking changes, or client update requirements for your target version.

Next Steps

After successful update: