S3 website redirects aren’t just about sending users to a different URL; they’re a powerful, albeit often misunderstood, way to manage traffic flow and serve content dynamically from static storage.
Let’s see this in action. Imagine you have an S3 bucket configured for static website hosting, and you want to redirect all requests for /old-path to /new-path.
{
"RedirectRules": [
{
"Condition": {
"KeyPrefixEquals": "old-path"
},
"Redirect": {
"ReplaceKeyPrefixWith": "new-path"
}
}
]
}
This JSON, when applied to your bucket’s redirect rules, tells S3: "If the request path starts with old-path, rewrite it to start with new-path before serving." This isn’t a separate server doing the work; S3 itself handles this rewrite at the edge.
The core problem S3 website redirects solve is managing URL changes without breaking existing links or SEO. When you move content, rename pages, or consolidate sites, you need a way to ensure users and search engines hitting old URLs still find the new ones. S3’s static website hosting feature provides this capability directly within the object storage layer, eliminating the need for a separate web server or proxy just for redirects.
Internally, when a request hits your S3 website endpoint, S3 first checks if the requested object exists. If it doesn’t, it then consults the configured redirect rules. These rules are evaluated in order. If a Condition matches the request, the corresponding Redirect action is applied. This can involve replacing a prefix, replacing the entire key, or issuing a specific HTTP status code (like 301 for permanent or 302 for temporary redirects). The rewritten or redirected request is then processed.
You control this behavior through two primary mechanisms:
-
Bucket-level Redirect Rules: Applied to all requests for the bucket. This is where you’d put your broad redirect strategies, like redirecting an entire old domain to a new one or handling
index.htmlto root path rewrites. -
Object-level Redirects: Applied only to a specific object. When you upload an object, you can configure its metadata to specify a redirect. This is useful for individual page moves or when you want a single file to act as a redirect.
Consider a scenario where you’ve migrated from an old domain old-example.com to new-example.com. You can configure your S3 bucket for new-example.com to handle redirects from the old domain.
{
"WebsiteConfiguration": {
"RedirectAllRequestsTo": {
"HostName": "new-example.com",
"Protocol": "https"
}
}
}
This RedirectAllRequestsTo rule, applied at the bucket level, will send every request that hits the old-example.com S3 website endpoint to https://new-example.com, preserving the original path and query string.
A common, yet often overlooked, aspect is how S3 prioritizes object existence over redirect rules. If an object named about.html exists in your bucket, a redirect rule targeting /about.html will not be triggered for requests to about.html. The existing object will be served instead. This means your redirect rules are only consulted when an object isn’t found. This behavior is crucial for understanding why a redirect might not be firing as expected; you might have an object with a conflicting name.
The next step in mastering S3 website configurations is understanding how to combine prefix-based redirects with specific object redirects for complex routing scenarios and implementing custom error pages.