Containerized HTTP redirect and rewrite service with automatic Let's Encrypt SSL certs

• SRE_INFO
• Refractr Architecture

Refractr at Mozilla runs in our itse-apps cluster. It is installed via a HelmRelease in the it-sre-apps github repo.

See the helm chart

This is the refractr (redirects|rewrites) spec file. First let's talk about the values that do not have to be specified and have sane defaults.

This is the destination that the redirect or rewrite will send the request. In most cases this is a single url. These never have http(s):// schemes. But in the more complicated redirects (Ex3) and rewrites (Ex4) it can have path logic or rewrite condtinals, respectively.

This is the list of domains that requests will be redirected or rewritten from. These never have the http(s):// schemes. In the simple case (Ex1) they can be single scalar string value. But they can also be an array of strings as well (Ex2).

One thing to remember all refractr entires is that they default to: status: 301 for doing redirects. Therefore, if not specified with status key, it will be 301. The status key can be added to any of the four examples: Ex1, Ex2, Ex3 or Ex4.

These are the key: value pairs that will be used during testing prior to deploy. They are written src: dst. The tests will be generated by default via product of dsts * srcs. If the tests key is specified, the autogenerate feature will be disabled in favor of the user-specified tests. The tests key can be added to any of the four examples: Ex1, Ex2, Ex3 or Ex4. In all instances, specifying the tests will override the default test generation behavior.

There are several ways to input a refractr. All entries will be preceeded with - because they are items in the refractr list (top level key).

Often the need is a simple redirect from one domain to another. A simple refract can be specified as single key: value pair item in the refracts list of items. The key: value pair in this case is: destination: source(s). The destination is a single web url complete with the https:// scheme. Note that http:// are not valid desitinations. Whereas the source(s) can be a single source domain or list of multiples.

• Ex1 Simple: Single Source

spec:

- destination(dsts): source(srcs)

example:

- wiki.mozilla.org/: wiki.mozilla.com

• Ex2 Simple: Multiple Sources

spec:

- destination(dsts):
  - source1
  - source2

example:

- www.mozillalabs.com/:
  - labs.mozilla.org
  - labs.mozilla.com

Sometimes the refract requires more control and input, especially when specifying a rewrite which requires this format. The handling of status and tests is exactly as above, but often you will want to specify the tests key: value src: dst pairs because rewrites can't deduce what would be good tests.

Sometimes for a redirect, you want to redirect paths on the domain to different destinations. This is done via key: value path: dst under the dsts key. The sources will be the product of paths * srcs

• Ex3 Complex: Redirect, Paths -> Destinations

spec:

- dsts:
    path1: dst1
    path2: dst2
  srcs: src(s)

example:

- dsts:
  - /faq.html: https://support.mozilla.org/products/firefox-lockwise/
  - /addon/updates.json: https://mozilla-lockwise.github.io/addon/updates.json
  - /: https://www.mozilla.org/firefox/lockwise/
  srcs: lockwise.firefox.com

Note: redirects (Ex4) and rewrites (Ex5) can and often are combined in a refract spec.

• Ex4 Complex: Rewrite

spec:

- dsts:
  - match1: dst1
  - match2: dst2
  srcs: src(s)
  tests:
    # must specify tests for each rewrite, because they won't be generated
  - src1: dst1
  - src2: dst2

example:

 - dsts:
  - /tree.php/: people.mozilla.org/o
  - ^/search/(.*): 'people.mozilla.org/s?query=$1&who=staff'
  - /: people.mozilla.org/
  srcs: phonebook.mozilla.org
  status: 302
  tests:
    # this test must be specified because rewrites `^/(.*)` will not generate a test
  - http://phonebook.mozilla.org/search/test: https://people.mozilla.org/s?query=test&who=staff

Note: redirects (Ex4) and rewrites (Ex5) can and often are combined in a refract spec.

• Ex5 Complex: Rewrite with If and Redirect Directives

spec:

- dsts:
  - if <some-valid-nginx-predicate>
    ^: <rewrite>
  - redirect: (optional) <catchall-redirect> (used when the 'if' condtional fails)
  srcs: src(s)

example:

- dsts:
  - if: '$http_host ~ "^(?<lang>[a-z]{2,3}(-[a-z]{2})?)?\.(start.*)$"'
    ^: https://start.mozilla.org/$lang$request_uri
  - redirect: https://start.mozilla.org/
  srcs:
  - '*.start.mozilla.com'
  - '*.start2.mozilla.com'
  - '*.start3.mozilla.com'
  - '*.start-prod.mozilla.com'
  tests:
  - http://ca.start.mozilla.com: https://start.mozilla.org/ca/
  - http://en-us.start.mozilla.com: https://start.mozilla.org/en-us/
  - http://en-uk.start.mozilla.com: https://start.mozilla.org/en-uk/

• Ex6 Raw Nginx

spec:

- nginx: |
    server {
        server_name name1 name2;

        etc
    }
  tests:
  - src: dst

example:

- nginx: |
    server {
        server_name example.com;
        return 301 https://www.example.com;
    }
  tests:
  - http://example.com: https://www.example.com/