serverless-redirect

CloudFormation stack that redirects every request on OldDomainName, and optionally www.OldDomainName, to NewDomainName, keeping scheme, path and query string unchanged. http:// goes to http://, https:// to https://. NewDomainName decides whether to upgrade to HTTPS. A CloudFront Function builds the response, so no origin is called.

Resources: CloudFront Function, origin request policy that exposes CloudFront-Forwarded-Proto to the function, CloudFront distribution, Route 53 A and AAAA alias records, and an ACM certificate unless AcmCertificateArn is set.

TLS Certificate

You can either provide your own certificate ARN and deploy anywhere, or deploy to us-east-1, provide a Route53 hosted zone ID, and let this stack manage the cert for you.

If you manage the cert yourself, it must cover the OldDomainName, and www.OldDomainName if IncludeWww=true, either directly, or via a wildcard. The stack never requests a wildcard certificate.

Requirements

• Public Route 53 hosted zone for OldDomainName in the same account. With IncludeWww=true, www.OldDomainName must be in the same zone.
• No A or AAAA record for OldDomainName (and www.OldDomainName) in that zone.
• OldDomainName (and www.OldDomainName) must not be an alternate domain name on another CloudFront distribution.

Parameters

Name	Default	Value
OldDomainName		Hostname to redirect from, for example old.example.com. Lowercase, no wildcard.
IncludeWww	false	true also redirects www.OldDomainName to the same target
NewDomainName		Hostname to redirect to, for example new.example.com
HostedZoneId		Hosted zone ID of OldDomainName, for example Z111111QQQQQQQ
RedirectType	permanent	permanent returns 308, temporary returns 307
AcmCertificateArn	empty	See TLS Certificate

Deploy

aws cloudformation deploy \
  --region us-east-1 \
  --template-file template.yaml \
  --stack-name old-example-com-redirect \
  --parameter-overrides \
    OldDomainName=old.example.com \
    NewDomainName=new.example.com \
    HostedZoneId=Z111111QQQQQQQ \
    IncludeWww=false \
    RedirectType=permanent

The command returns after ACM issues the certificate and CloudFront deploys the distribution.

With your own certificate, add AcmCertificateArn=arn:aws:acm:us-east-1:111122223333:certificate/... to --parameter-overrides and set --region as needed.

To change RedirectType or IncludeWww, run the same command with the new value. Changing IncludeWww replaces the stack-managed certificate.

Verify

curl -sI 'https://old.example.com/a/b?x=1&y'
curl -sI 'http://old.example.com/a/b?x=1&y'

Expected: status 308 (or 307) and location: https://new.example.com/a/b?x=1&y for the first request, location: http://new.example.com/a/b?x=1&y for the second. With IncludeWww=true, repeat with www.old.example.com; the location is the same.

Remove

aws cloudformation delete-stack --region us-east-1 --stack-name old-example-com-redirect

Use the region the stack was deployed in.

Scope

One hostname per stack, plus www. with IncludeWww=true. The hosted zone is not managed by this stack.

QA

.github/workflows/qa.yaml runs on every push. No AWS access.

pip install cfn-lint==1.57.0 checkov==3.3.19
cfn-lint template.yaml
checkov --file template.yaml --framework cloudformation --compact --quiet
npm ci
npm test
actionlint

npm test parses template.yaml and runs the function code in Node, with !Sub variables resolved from Mappings. It does not check CloudFront Functions runtime restrictions.

Contributions

Non-LLM-slop contributions and issues are most definitely welcome.

License

MIT. See LICENSE.

One more thing

This package is brought to you by Tactic Media, a South Australian software development business.

We love to help businesses become more efficient by automating tasks that shouldn't have been done by a human in the first place.

Head over to our website to check out what we do, and if you think we can help you give your employees more time to spend on something more creative, let's talk