Redirect an entire website using AWS Lambda and API Gateway, packaged with CloudFormation and deployed with Serverless Application Model (SAM).
If you've migrated from one domain to another and you want to redirect all incoming requests from the old domain to the new one, you'd typically do the following:
- Create a webserver with either Apache or NGINX that listens to incoming requests.
- Rewrite all requests to the new domain while passing appropriate headers (
301/302HTTP status with aLocationheader).
This works fine except you have to run a whole webserver just to manage this.
We could use API Gateway as an entrypoint for requests and map those requests to our Lambda function. This way, we utilize a resource only when it's needed. Lambda is ideal for this use case since this is not a long lived process and it's also very specialized and the behaviour well defined.
We've used CloudFormation to define our Lambda functions and in the function definition, we've specified that requests coming into API Gateway would act as a trigger for our Lambda functions. We've also specified that GET requests are handled by one function and all other HTTP methods are handled by another.
Finally, we use AWS SAM to package and deploy our code.
Assumptions:
- MyRedirectorBucket is the name of the bucket we'll be uploading our packaged Lambda code to.
- Redirector is the name of our CloudFormation stack.
- http://example.org/ is the new domain we are redirecting to.
Make sure our S3 bucket exists, if not, create it
aws s3 ls s3://MyRedirectorBucket/ > /dev/null 2>&1 || aws s3 mb s3://MyRedirectorBucket
Validate our CloudFormation template to make sure there are no errors
aws cloudformation validate-template --template-body file://./app_spec.yml
Package and upload local artifacts to S3
aws cloudformation package \
--template-file app_spec.yml \
--output-template-file packaged.yml \
--s3-bucket MyRedirectorBucket
Deploys the CloudFormation template by creating and executing a changeset.
aws cloudformation deploy \
--template-file packaged.yml \
--stack-name Redirector \
--capabilities CAPABILITY_IAM \
--parameter-overrides \
NewDomain=http://example.org \
HTTPResponse=301
Note: Ensure that NewDomain is prefixed with either http:// or https:// or you will get a chain of redirects to a never-ending path on the source domain. It will be amusing but will not meet your goal.
Note: This redirector has a special feature where if you specify either a query parameter or a non-slash-terminated string in the NewDomain URL (e.g. ``https://www.example.com/snafu` or `https://www.example.com/some/path?foo=bar") it will disregard the path and any query parameters passed in by the user and will redirect strictly to the NewDomain URL.
| Parameters | Type | Description |
|---|---|---|
| HTTPResponse | Number |
The HTTP response to redirect with. Only 301 and 302 are allowed. |
| NewDomain | String |
New domain to redirect to. |
While testing, you may need to delete a stack
aws cloudformation delete-stack --stack-name Redirector
In order to fully configure a target domain for redirection, first establish a Redirector API Gateway through the CloudFormation Stack as described above. Then add a Custom Domain Mapping through the AWS Console. You can add a Custom Domain Name through the console, give it a DNS name, tell it to use an Edge Optimized endpoint configuration, and give it a valid ACM certificate for the domain you are targeting. This can be a wildcard certificate, which might make things simpler for you if you are configuring multiple domains. Then Edit the custom domain name and do an Add mapping operation to add a Base Path Mapping to map / to the Redirector Prod stage.
Once this is configured, look for the Target Domain Name under the Custom Domain Name / Endpoint Configuration in the console and chnage that to the DNS name you want to redirect from.
The first version of this software had the same issue as SAM bug #191. If you look at the Stages in your API Gateway, you may find a stage named Stage. As of 2019-11-15 this issue is resolved and new deployments of lambda-redirector should not have a Stage stage defined.
See: http://www.contribution-guide.org/
Copyright 2018 by Modus Create, Inc.
This software is licensed under the permissive MIT License.
