Containerized HTTP redirect and rewrite service with automatic Let's Encrypt SSL certs
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.
spec:
- destination(dsts): source(srcs)
example:
- wiki.mozilla.org/: wiki.mozilla.com
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
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.
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.
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/
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/