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: pomerium/pomerium:latest
    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: 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:
Feedback