Under the hood
Replacing a CDN secret in Laravel without a gap
How to rotate the shared secret between bunny.net and a Laravel app without a moment where the two disagree, and how Brewless does it in two releases.
In this post
Put a CDN in front of a Laravel app and sooner or later you need a secret that only the CDN knows. Replacing that secret looks like a two-minute job: a new value at the CDN, a new value on the server. Done in that order, though, every request between the two changes goes wrong.
This post is about that window: why the secret exists, why it cannot change in one step, and how Brewless replaces it without a gap.
Can you rotate a CDN secret without downtime?
Yes, as long as your app accepts two secrets for a while. First give the app the new secret next to the old one, then move the CDN to the new one, and only then take the old one off the app. At no point do the two sides disagree.
The rest is about doing those three moves in the right order, and about what can go wrong in between.
Why there is a secret between the edge and your app
On Brewless, visitors reach bunny.net, and bunny.net forwards the request to your Serverless Container at Scaleway. Scaleway routes a request on its Host header and only knows the container's own domain, so the edge sends that domain as Host and carries the hostname the visitor asked for in a header of its own. The visitor's address travels in X-Forwarded-For.
Both of those headers can be written by anyone. The container also has a public address at Scaleway, and a request sent straight there could claim to be for any hostname and from any address. On an app that gives every customer a subdomain, that is a request claiming to be for a customer's subdomain. And X-Forwarded-For is what rate limits and your logs count.
So the edge adds a secret to every request, and brewless/laravel only believes the hostname header when that secret is present, and only for the domains of the environment. With the secret, only the entry the edge appended to X-Forwarded-For counts; without it, the header is dropped altogether. Once the secret has done its job, the package takes its header off the request, so nothing further down sees it.
Note
The edge secret is not a lock on the container. A request without it is still answered, as the container's own host. What the secret decides is which hostname and which visitor address your app believes. More on the setup in Putting bunny.net in front of a Laravel app.
It is a shared secret, not a strong one. The pull zone at bunny.net holds it in an edge rule, where anyone with the bunny.net key of that account can read it. That is the main reason you might one day want to replace it.
When to replace it
Not on a timer. Replace it when it may have been seen by someone it should not have been:
- a bunny.net API key that leaked or was shared too widely;
- a provider that reports an incident;
- someone with access to the bunny.net account who left.
Why the obvious way leaves a gap
The secret lives in two places that cannot change in the same instant:
| Side | Where the secret is | How it changes |
|---|---|---|
| Edge | An edge rule on the bunny.net pull zone | An API call to bunny.net |
| Container | BREWLESS_EDGE_SECRET on the web container |
A new rollout of the container |
A container learns a new variable by rolling out, and a rollout takes a while. Change the edge first, and the containers still hold the old secret while the edge already sends the new one. Change the containers first, and they wait for a secret the edge does not send yet. Either way, every request in between arrives without a secret the app believes: it is answered as the container's own host, and the visitor's address is lost.
On a single-site app that may mean wrong redirects and generated URLs for a few minutes. On a multi-tenant app that finds the tenant by its hostname, nobody's subdomain resolves to their tenant until both sides agree.
The overlap: hold two secrets for a few minutes
The fix is the pattern you may know from rotating signing keys: accept the old and the new value at once, for as long as the move takes.
brewless/laravel 1.2 and later read a second secret from BREWLESS_EDGE_SECRET_PREVIOUS. While both are set, a request carrying either one is believed. The comparison is constant-time and checks every secret it holds, so the answer costs the same work whichever one matched. Holding two is meant to last minutes, not to stay as a setting.
With that, the replacement becomes a sequence in which every step is safe on its own:
- Give the containers the new secret next to the old one. The edge still sends the old one, and it is still believed.
- Point the edge at the new secret. The containers hold it already, so nothing changes for a visitor.
- Take the old secret off the containers.
- Delete the old secret.
How Brewless does it
On Brewless that is one command:
brewless edge:rotate-secret production
Behind it, Brewless runs the sequence above as six steps, documented on The edge secret:
- It checks that your application can hold two secrets at once. The application says so itself on its ops route, which the worker or release container answers.
- It writes a new secret to your own Scaleway Secret Manager, as a new version of the one that is there.
- It puts the image that is live now live again, and gives the containers the new secret together with the one the edge still sends.
- It points the rule at bunny.net to the new secret.
- It puts the live image live once more, now with the new secret alone.
- It deletes the version of the secret the edge sent before, value and all.
That is two releases of the image that is live. Nothing is built and nothing is rolled back, and your site keeps answering throughout. The new secret is generated in your Secret Manager and goes from there to the edge rule and the containers; you never see it.
Every step first reads what is actually true at Scaleway and at bunny.net. A replacement that stopped halfway carries on where it left off, and one that is asked for twice replaces the secret once. Wherever it stops, the environment answers: either the containers accept both secrets, or the two sides agree on one. A deploy in between hands the containers the pair as well, and never moves the edge behind the replacement's back.
Warning
Each of the two releases empties the edge cache, as every release does. Pages come from your container once more before the edge keeps them again, so expect a short burst of container requests after a replacement.
What it needs
Three things, and Brewless checks them rather than guessing:
brewless/laravel1.2 or later. An older version holds one secret at a time. Brewless says so and changes nothing, instead of leaving your site answering as the wrong host.- Variables kept through Brewless. The new secret reaches the containers as a variable, so the environment needs
brewless env:pushto have run at least once. See Laravel secrets without a .env file in production. - A worker or release container, because that is the container that answers whether the application can hold two secrets.
There is one case Brewless refuses outright: an environment that sets BREWLESS_EDGE_SECRET in its own variables. That value wins, and Brewless then leaves the edge rule alone, so the secret is yours to keep in step on both sides. Moving the rule would point the edge at a secret your containers do not have. To hand it back, take the line out of your variables and deploy:
brewless env:pull production
# remove the BREWLESS_EDGE_SECRET line from the file
brewless env:push production
After the next deploy, Brewless keeps the secret in your Secret Manager and can replace it.
The same pattern elsewhere in your app
The overlap is not specific to CDNs. Anything that is checked on one side and sent from another, such as a webhook signing secret or a key between two of your own services, can be replaced the same way: accept both, move the sender, drop the old one. Laravel itself does this for APP_KEY with APP_PREVIOUS_KEYS, so encrypted values and cookies made with the old key keep working after you change it.
What makes the edge secret worth a command of its own is that both sides sit in accounts you own, at two different providers, and one of them only changes by rolling out a container. Brewless knows both sides and the order, so the replacement is a single line instead of a checklist at an inconvenient moment.
Frequently asked questions
Why does a Laravel app behind a CDN need a shared secret at all?
Because the headers that carry the visitor's hostname and address can be written by anyone who reaches the container directly. A secret only the CDN sends lets the app believe those headers from the edge and ignore them from everyone else.
Can I not just change the secret at the CDN and then on the server?
Not without a gap. Between the two changes the edge sends a secret the container does not hold, or the other way round, and every request in that window is answered as the container's own host, with the visitor's address dropped.
When should I replace the edge secret?
When it may have been seen by someone who should not have seen it, such as a leaked bunny.net key, an incident at a provider, or someone with access who left. It is not a value that has to change on a timer.
Does replacing the edge secret on Brewless cause downtime?
No. The containers hold both secrets while the edge moves over, so the site keeps answering. Each of the two releases does empty the edge cache, as every release does, so pages come from the container once more before the edge keeps them again.
What if I set BREWLESS_EDGE_SECRET in my own variables?
Then that value is yours to keep in step on both sides, and Brewless refuses to replace it. Remove the variable with brewless env:pull and brewless env:push, deploy, and Brewless keeps the secret in your Secret Manager from then on.