Configuration as code

What the file holds

• Routes, as the route dialog shows them: hostnames, path, where they go (upstreams of their own or an upstream of the list), HTTPS, every switch (cache, firewall, rate limit, password, sign-in, address list, custom headers, upload limits, under attack, waiting room, web application firewall), the redirect and the group. Routes set up under YAML or the dialog’s Matching come along with their conditions, priority and entry points. TCP and UDP routes are routes too.
• Upstreams and middlewares the routes use, by name, with each upstream’s connection settings (transport). Both are every proxy’s: changing one in the file changes it on every proxy that uses it, and the plan says which. Files from before upstreams, with services: and service:, still apply.
• Route defaults of a DNZ Proxy: redirect to https://, compression, security headers, the firewall on every route, upload limits.

version: 2
proxy: edge
kind: dnz-proxy
defaults:
  redirect_https: true
  compress: true
  security_headers: false
routes:
- name: app-example-com
  hosts:
  - app.example.com
  servers:
  - http://10.0.1.20:3000
  - url: http://10.0.1.21:3000
    weight: 3
  - url: https://10.0.1.22:3443
    weight: 1
    skip_tls_verify: true   # any certificate from this server
  https: true
  group: Web app
  cache: 10m
  basic_auth:
  - admin
- name: api
  hosts:
  - api.example.com
  path: /v1
  upstream: backend
  https: true
  rate_limit:
    average: 50
    burst: 100
upstreams:
- name: backend
  servers:
  - http://10.0.2.11:8080
  health_check:
    path: /health
    interval: 10
  transport:
    serverName: backend.internal
    forwardingTimeouts:
      dialTimeout: 5s

Servers from a DNS name

upstreams:
- name: swarm
  from_dns:
    mode: dns
    name: swarm-nodes.example.local
    port: 8080
    scheme: http          # https or h2c; TCP upstreams take tls: true instead
    family: v4            # v6 or both
    resolve_on: dnz       # proxy: each DNZ Proxy node and Caddy look it up (tasks.<service>)
    min_interval_secs: 30

TCP and UDP routes

routes:
- name: db
  protocol: tcp
  entry_points: [pg]
  hosts: [db.example.com]   # by TLS hostname (SNI); left out: every connection on the port
  tls: passthrough          # or terminate (the proxy holds the certificate); left out: no TLS
  servers: [10.0.0.7:5432]
  client_ips: [10.0.0.0/8]
  middlewares: [office-only]
- name: resolvers
  protocol: udp
  entry_points: [dns]
  upstream: resolvers
upstreams:
- name: resolvers
  protocol: udp
  servers: [10.0.0.53:53]
middlewares:
- name: office-only
  protocol: tcp
  kind: ipAllowList
  config:
    ipAllowList:
      sourceRange: [10.0.0.0/8]

Export and import in the dashboard

From the CLI

dnz proxy export edge > edge.yaml           # one proxy
dnz proxy export --all > proxies.yaml       # every proxy, --- between them
dnz proxy plan -f edge.yaml                 # what would change; nothing is written
dnz proxy apply -f edge.yaml                # apply it
dnz proxy apply -f edge.yaml --prune        # and remove what the file doesn't have
dnz proxy apply -f edge.yaml --proxy edge-2 # the same routes on another proxy

edge: 1 to add, 1 to change, 0 to remove.

+ route shop-example-com
    hosts: ["shop.example.com"]
    servers: ["http://10.0.3.5:8080"]
    https: true
~ route app-example-com
    cache: 10m → 1h
+ dns shop.example.com
    a new record pointing at edge

How applying works

• Nothing half applied. Every check the route dialog makes runs first: hostnames in your zones, one route per hostname, upstreams and middlewares that exist, sign-in providers, switches the proxy’s kind runs. An error names the route and its line, for example route shop-example-com (line 14): unknown key cahce, and nothing changes.
• Nothing removed unless you ask. Routes, services and middlewares the file leaves out stay; --prune (or Remove what the file doesn’t have) deletes them, and their hostnames stop going through the proxy. An upstream or middleware a route still uses (on any proxy) is never removed.
• DNS follows. A new route’s hostnames go through the proxy, with a new record pointing at it when a name has none. dns_record: false on a route leaves DNS alone.
• Applying twice changes nothing.
• History kept. Each route a file adds, changes or removes gets a version in route history, and every apply is in the audit log.

Secrets

GitOps with GitHub Actions

name: proxies
on:
  pull_request:
    paths: ["proxies/**"]
  push:
    branches: [main]
    paths: ["proxies/**"]
jobs:
  apply:
    runs-on: ubuntu-latest
    env:
      DNZ_SERVER: https://dnz.example.com
      DNZ_TOKEN: ${{ secrets.DNZ_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - name: Install dnz
        run: curl -fsSL https://raw.githubusercontent.com/terrific-ci/dnz/main/install.sh | sudo sh
      - name: Plan
        run: for f in proxies/*.yaml; do dnz proxy plan -f "$f"; done
      - name: Apply
        if: github.event_name == 'push'
        run: for f in proxies/*.yaml; do dnz proxy apply -f "$f"; done

API