Skip to main content

Zero Fundamentals: Build Routes

This guide shows you how to build a route to Grafana in Pomerium Zero. Watch the video to see the steps in action, or read the guide below.

note

This guide assumes you've completed the Pomerium Zero Quickstart.

Routing in Pomerium

In Pomerium, Routing makes it possible for the Proxy service to manage requests and responses between a client and an upstream service.

To route requests and responses to the correct locations, the Proxy service requires two URLs:

  • The From URL. This URL defines the external, publicly accessible URL of a proxied request. It tells the Proxy service to listen for requests from this location.
  • The To URL. This URL defines the destination of the request, and can be an internal or external resource. It tells Pomerium where to proxy the request to.

A diagram demonstrating how Pomerium proxies requests with the From and To URLs in a route block

How to build routes in Pomerium Zero

To learn how to build routes, you'll follow these steps:

  1. Configure a service in Docker Compose
  2. Build a route to the service
  3. Access your secured service behind Pomerium

Configure Grafana

The service you'll secure is Grafana, an open-source observability platform. In the same docker-compose.yaml file where you're running Pomerium Zero, add the Grafana configuration below:

grafana:
image: grafana/grafana:latest
ports:
- 3000:3000
networks:
main: {}
volumes:
- ./grafana-storage:/var/lib/grafana

Build a route

In the Routes:

  1. Select Routes from the sidebar, create a new route, and name it something obvious, like Grafana.

  2. In the From field, select https:// from the protocol dropdown. In the next field, enter the external URL. It should follow this format:

    grafana.<CLUSTER_STARTER_DOMAIN>.pomerium.app

  3. In the To field, enter the destination URL: http://grafana:3000

  4. In the Policies field, select Any Authenticated User.

    Building your first route in the Zero Console

Save your route and apply the changeset.

Access the route

Now, in your browser, navigate to the external From URL you just saved. You'll notice you're accessing Grafana over the external URL. This means you've successfully configured Pomerium to proxy requests to Grafana.

If you look at the route's TLS certificate, you'll notice the certificate was issued by ZeroSSL on behalf of your cluster domain. This means the connection between the client and Grafana is secured over TLS!

Reviewing the service&#39;s TLS certificate

Up Next: Build Policies

Great job! You successfully built a route in Pomerium Zero. Next, you'll learn how to build authorization policies.

Go to Build Policies.

Configuration file state

At this point, your Docker Compose file should look like this:

docker-compose.yaml
services:
pomerium:
image: cr.pomerium.com/pomerium/pomerium:v0.26.0
ports:
- 443:443
restart: always
environment:
POMERIUM_ZERO_TOKEN: <YOUR_CLUSTER_TOKEN>
XDG_CACHE_HOME: /var/cache
volumes:
- pomerium-cache:/var/cache
networks:
main:
aliases:
- verify.<YOUR_CLUSTER_SUBDOMAIN>.pomerium.app
verify:
image: cr.pomerium.com/pomerium/verify:latest
networks:
main:
aliases:
- verify
grafana:
image: grafana/grafana:latest
ports:
- 3000:3000
networks:
main: {}
volumes:
- ./grafana-storage:/var/lib/grafana

networks:
main: {}

volumes:
pomerium-cache: