# Redirect website requests

Redirect pages of a bucket's static website with routing rules, or send every request to another host.

Replace _example-site_ with your bucket's name.

## Prerequisites

- Permission for `s3:PutBucketWebsite` on the bucket.
- In the console, also `s3:GetBucket` on the bucket to open it (without it the bucket's page says
  "Access denied").
- The bucket is not one the platform manages.

## Add redirect rules

The first rule whose condition matches wins. Up to 50 rules. Rules belong to a website that
serves the bucket's files: in the console, **Redirect rules** appears once the website is on.

**Console**
1. Open the bucket, then choose **Website**. The website serves the bucket's files.
2. Under **Redirect rules**, choose **Add rule** (the sheet is **Add a redirect rule**).
3. Under **When**, for **The key starts with**, enter `docs/v1/`, or for **The page would
   answer**, enter `404`.
4. Under **Then redirect**, choose **Replace the prefix** and for **New prefix** enter `docs/v2/`;
   or choose **Send to one key** or **Keep the key**.
5. (Optional) Fill in **Host**, **Protocol** and **Status code**.
6. Choose **Add rule**.

Each added, edited, moved or deleted rule is saved at once.

**CLI**
```sh
dcloud s3 bucket-access set-website example-site --index-document index.html \
  --routing-rules '{"condition":{"keyPrefixEquals":"docs/v1/"},"redirect":{"replaceKeyPrefixWith":"docs/v2/"}}'
```

**API**
```http
PUT /s3/api/buckets/example-site/website
{ "indexDocument": "index.html", "routingRules": [{ "condition": { "keyPrefixEquals": "docs/v1/" }, "redirect": { "replaceKeyPrefixWith": "docs/v2/" } }, { "condition": { "httpErrorCodeReturnedEquals": "404", "keyPrefixEquals": "blog/" }, "redirect": { "hostName": "blog.example.com", "replaceKeyPrefixWith": "" } }] }
```

**Terraform**
```hcl
resource "dcloud_bucket_website" "site" {
  bucket         = dcloud_bucket.site.id
  index_document = "index.html"
  routing_rules = jsonencode([{
    condition = { keyPrefixEquals = "docs/v1/" }
    redirect  = { replaceKeyPrefixWith = "docs/v2/" }
  }])
}
```

The CLI, API and Terraform set the whole website configuration at once: name the error document
and every rule you keep, or they are removed. Over S3, `aws s3api put-bucket-website` with a
`RoutingRules` list does the same.

| Field                                   | Meaning                                                                                                                                                                         |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `condition.keyPrefixEquals`             | The request path (without the leading `/`) starts with this                                                                                                                     |
| `condition.httpErrorCodeReturnedEquals` | Only when the page would answer this code; checked after the lookup. A page answers `403` when it is not public and `404` when it is missing, so those are the codes that match |
| `redirect.hostName`                     | Another host; the request's own host otherwise                                                                                                                                  |
| `redirect.protocol`                     | `https` (default) or `http`                                                                                                                                                     |
| `redirect.replaceKeyPrefixWith`         | Replace the matched prefix; the rest of the path is kept                                                                                                                        |
| `redirect.replaceKeyWith`               | Replace the whole path                                                                                                                                                          |
| `redirect.httpRedirectCode`             | `301` (default), `302`, `303`, `307`, `308`                                                                                                                                     |

The query string is kept, except with `replaceKeyWith`. A rule has `replaceKeyPrefixWith` or
`replaceKeyWith`, not both.

## Redirect every request

To send every request to another host, for example a bare domain to `www.`:

**Console**
1. On the **Website** tab, choose **Redirect every request**.
2. For **Redirect to host**, enter `www.example.com`.
3. Choose **Turn on website**, or **Save** when the website is on.

**CLI**
```sh
dcloud s3 bucket-access set-website example-site --redirect-all-requests-to '{"hostName":"www.example.com"}'
```

**API**
```http
PUT /s3/api/buckets/example-site/website
{ "redirectAllRequestsTo": { "hostName": "www.example.com" } }
```

**Terraform**
```hcl
resource "dcloud_bucket_website" "apex" {
  bucket                   = dcloud_bucket.apex.id
  redirect_all_requests_to = jsonencode({ hostName = "www.example.com" })
}
```

Every request is answered with `301` to the host, path and query kept, `https` unless you set
`protocol`. The bucket then serves no files and needs no public policy. Turning this on replaces
the index document, the error document and the redirect rules.

## If it is refused

- 400 `routingRules: At most 50 routing rules`.
- 400 `RedirectAllRequestsTo stands alone: no index document, error document or routing rules with it`.
- 400 `… ReplaceKeyPrefixWith and ReplaceKeyWith cannot both be set`.
- 400 `… HttpRedirectCode is 301, 302, 303, 307 or 308`.
- 403 `This bucket is managed by the platform; its access cannot be changed`.

## Related

- [Host a static website](host-a-static-website.md)
- `s3.bucket-access.set-website` · `dcloud s3 bucket-access set-website` · `dcloud_bucket_website`
