Caddy: Named Routes

Welcome back! We're going to examine an experimental Caddy feature: Named Routes

What are Named Routes?

Named routes are similar to Snippets which we briefly covered in a previous post about Imports. Snippets allow you to import a repeatable portion of your Caddyfile by defining the code block to repeat and then using import my-code-block to use it. Named routes are similar but are more specifically used for implementing reusable reverse proxy handlers.

Example: Hosting Agency

Let's say that you run a hosting agency with 100s of different websites and a few identical web servers. You want to set up Caddy to sit in front of your web servers and load-balance traffic between them.

In the Caddyfile, we have a straightforward configuration:

client-site-1.com {
	reverse_proxy {
		to 10.0.0.3 10.0.0.4 10.0.0.5
		lb_policy random
		lb_retries 30
		max_fails 10
		unhealthy_latency 5000ms
	}
}

client-site-2.com {
	reverse_proxy {
		to 10.0.0.3 10.0.0.4 10.0.0.5
		lb_policy random
		lb_retries 30
		max_fails 10
		unhealthy_latency 5000ms
	}
}

This configuration works fine, but you could cut a few lines of config out. Instead of writing the reverse proxy directives multiple times, you could use a snippet.

Snippets: Simplifying configuration

(upstream) {
		reverse_proxy {
		to 10.0.0.3 10.0.0.4 10.0.0.5
		lb_policy random
		lb_retries 30
		max_fails 10
		unhealthy_latency 5000ms
	}
}
client-site-1.com {
	import upstream
}

client-site-2.com {
	import upstream
}

This is fine and good but let's take this one step further and convert our Snippet into a Named Route. Each time you import a snippet, the directives inside are treated as separate parts of the configuration. If you're importing a snippet with a reverse_proxy directive many times, then many instances of the reverse_proxy are created in-memory to handle load balancing and health checks.

Converting Snippets to Named Routes

This is really easy - all we need to do is add an ampersand '&' in front of our snippet declaration and replace the word "import" with "invoke":

&(upstream) {
		reverse_proxy {
		to 10.0.0.3 10.0.0.4 10.0.0.5
		lb_policy random
		lb_retries 30
		max_fails 10
		unhealthy_latency 5000ms
	}
}
client-site-1.com {
	invoke upstream
}

client-site-2.com {
	invoke upstream
}

This final configuration is the most efficient, creating a single Named Route instance for proxying requests upstream. All sites that use this named route will share the same upstream routing information. This feature is even more powerful when combined with passive health checks. If proxied requests for one site begin to the fail, the load balancer will automatically fail over to the next one for all sites at once.

Continue Reading

Read more about Named Routes in Caddy's official documentation.

Wrapping up

Named Routes help conserve resources and maintain consistency when using Caddy server for reverse proxying multiple different sites to the same upstream. This experimental feature is a natural choice for having many sites at scale.

Want to learn more about Caddy?

Visit their official website at caddyserver.com Read through the docs at caddyserver.com/docs If you use it, sponsor the project (we do!) caddyserver.com/sponsor

This post is one of a series of tutorials about Caddy Server. You can view all relevant posts here.

Learn about Skip2

Get Started