How to Add a Custom Response Header in OpenResty Edge (No Reload)

In this tutorial, we will show how to add custom response headers in OpenResty Edge without restarting or reloading servers.

To add a custom response header in OpenResty Edge:

1. Open the Edge web console and enter your application.
2. Go to Page Rules and add a new rule.
3. Add the “Add response header” action.
4. Enter the header name (e.g. X-TEST-EXTRA-HEADER) and a value—either a static string or a built-in variable (System Hostname or a named Request Header).
5. Create a release to push the rule to all gateway clusters.

The change takes effect without any server reload, restart, or binary upgrade. If you also need to rewrite the headers sent to your upstreams, see Set Different Host Headers for Upstream Requests in OpenResty Edge.

The full walkthrough with screenshots follows below.

How to Add a Response Header with a String Value

First, go to the OpenResty Edge web console. This is our demo deployment of the console. Each user would have their own deployment. We will use our sample application for the “test-edge.com” domain.

Enter the application.

First go to “Page Rules” page.

Click here to add a new rule.

Let’s add an action.

We will choose “Add response header”.

The header have two parts, the name and the value.

Name the header as “X-TEST-EXTRA-HEADER”.

For the value, you can use string or built-in variable, we try the string first.

Type in “hello world”.

Make sure this rule runs before any existing normal ones.

Save it.

To push out the new rule, we need to create a new release.

Ship it!

It is fully synchronized.

Now the new page rule has been pushed to all the gateway clusters and servers.

Our configuration changes do NOT require server reload, restart, or binary upgrade. So it’s very efficient and scalable.

Let’s test it out on a gateway server.

We copy the IP address of this San Francisco gateway server.

Then test it on the terminal.

The “X-TEST-EXTRA-HEADER” is here.

How to Use a Built-in Variable as the Header Value

Next let’s try built-in variable for value of response header.

Edit this rule.

Let’s choose built-in variable for header value.

Here we provide two options for built-in variable currently. One is “Request Header”, which means you can retrieve the request information. You need to specify the “Request Header” by name like “Origin”, “Referer” etc.

Another one is “System Hostname”, which is just the gateway server’s name we set.

Let’s try “System Hostname” here.

Save it.

Again, we need to create a new release.

Ship it!

It is fully synchronized now.

First we can check the hostname for the previous server.

The hostname for this gateway server is like this.

Then switch to terminal.

The value of “X-TEST-EXTRA-HEADER” has changed to the hostname.

Try another gateway server, like this one in Frankfurt, the hostname is like this.

Switch to terminal again.

The value is now the Frankfurt server’s hostname.

FAQ: Adding Response Headers in OpenResty Edge

Do I need to restart the server to add a response header in OpenResty Edge?

No. OpenResty Edge pushes the page rule to all gateway clusters with no reload, restart, or binary upgrade, and the change takes effect immediately.

Can the response header value be dynamic in OpenResty Edge?

Yes. Besides a static string, you can use a built-in variable as the value: System Hostname (the gateway server’s name) or a named Request Header such as Origin or Referer.

How do I apply the same response header across all gateway servers in OpenResty Edge?

Create a release in the OpenResty Edge console. The page rule synchronizes to every gateway cluster and server automatically—no per-server configuration.

What is the difference between “Add response header” and “Set response header” in OpenResty Edge?

Add response header appends a header and keeps any existing header of the same name; Set response header overrides an existing header of the same name. Use the former to add, the latter to force-rewrite. See the official Response Header Actions documentation for the full action list.

What is OpenResty Edge

OpenResty Edge is our all-in-one gateway software for microservices and distributed traffic architectures. It combines traffic management, private CDN construction, API gateway, security, and more to help you easily build, manage, and protect modern applications. OpenResty Edge delivers industry-leading performance and scalability to meet the demanding needs of high concurrency, high load scenarios. It supports scheduling containerized application traffic such as K8s and manages massive domains, making it easy to meet the needs of large websites and complex applications.

If you like this tutorial, please subscribe to this blog site and/or our YouTube channel. Thank you!

About The Author

Yichun Zhang (Github handle: agentzh), is the original creator of the OpenResty^® open-source project and the CEO of OpenResty Inc..

Yichun is one of the earliest advocates and leaders of “open-source technology”. He worked at many internationally renowned tech companies, such as Cloudflare, Yahoo!. He is a pioneer of “edge computing”, “dynamic tracing” and “machine coding”, with over 22 years of programming and 16 years of open source experience. Yichun is well-known in the open-source space as the project leader of OpenResty^®, adopted by more than 40 million global website domains.

OpenResty Inc., the enterprise software start-up founded by Yichun in 2017, has customers from some of the biggest companies in the world. Its flagship product, OpenResty XRay, is a non-invasive profiling and troubleshooting tool that significantly enhances and utilizes dynamic tracing technology. And its OpenResty Edge product is a powerful distributed traffic management and private CDN software product.

As an avid open-source contributor, Yichun has contributed more than a million lines of code to numerous open-source projects, including Linux kernel, Nginx, LuaJIT, GDB, SystemTap, LLVM, Perl, etc. He has also authored more than 60 open-source software libraries.