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.

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.

   

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!

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: