tilegroxy docs
GitHub Issues Get tilegroxy
Edit this page Report an issue

Overview

TLS profiles hold the certificates, keys, and trusted CAs used for HTTPS.

Description

They’re defined once and referenced by ID wherever they’re needed, both for requests to upstream servers and for the server itself.

Like other entities, a profile uses a parameter called name to dictate its type which controls the list of parameters available. Every profile must also have an id, which can be any string except system.

Profiles do nothing until they’re referenced:

Where profiles are referenced
Parameter Purpose Profile parameters used

client.tls

Validating the certificates of upstream servers

CA, CAFile, SystemCAs, MinVersion

client.mtls

The certificate presented to upstream servers that require mutual TLS (mTLS)

Certificate, CertificateFile, Key, KeyFile, AllowedHosts

server.encrypt.tls

The certificate served to clients

Certificate, CertificateFile, Key, KeyFile, MinVersion, Hosts, or an acme or selfsigned profile

server.encrypt.mtls

Validating the certificates of incoming clients

CA, CAFile

Parameters that don’t apply to a reference are ignored, so a single profile can be used for several of these. Any parameter in a profile that isn’t used by a reference is logged at warn level on startup. A reference to an unknown ID, or to a profile missing what that reference needs, prevents the application from starting up.

The client and server.encrypt sections don’t fall back to each other. A section only uses the profiles it references, so the server’s certificate is never presented to an upstream unless client references that profile as well.

Everything that uses the client configuration picks up its profiles: the proxy, url template, and pmtiles providers, custom providers calling GetTile, and passthrough authentication. Datastores, caches, analytics, telemetry, and the JWKS download for JWT authentication make their own connections and don’t use profiles.

A layer’s client overrides the top-level client piecemeal, so different layers can trust different CAs or present different certificates. To combine upstreams that need different profiles, give each its own layer and pull them together with ref providers, since a ref uses the client of the layer it refers to.

Profiles can be reloaded without downtime. See Reloading.

Choosing a profile

Goal Profile Notes

Use certificates, keys, or CAs you already have

PEM

Supplied as file paths or text. Usable by every reference

Obtain and renew certificates automatically via Let’s Encrypt

ACME

Only usable for server.encrypt.tls. Requires server.encrypt.httpport

Run HTTPS locally for development or testing

Self-Signed

Only usable for server.encrypt.tls. Generates a certificate clients won’t trust by default

Example

The mesh profile is used by default, but its certificate is only presented to hosts matching its allowedHosts. The remaining layers override the client to validate the upstream a different way.

  • YAML

  • JSON

tls:
  - name: pem
    id: mesh
    certificateFile: /var/run/certs/tls.crt
    keyFile: /var/run/certs/tls.key
    caFile: /var/run/certs/ca.crt
    allowedHosts:
      - "*.svc.cluster.local"
  - name: pem
    id: partner
    certificate: secret.partner-cert
    key: secret.partner-key
    allowedHosts:
      - wmts.partner.example.net
  - name: pem
    id: corp-ca
    caFile: /etc/pki/corp-root.pem

client:
  tls: mesh
  mtls: mesh

layers:
  - id: buildings
    provider:
      name: pmtiles
      url: https://tiles.storage.svc.cluster.local/buildings.pmtiles
  - id: partner_imagery
    client:
      tls: system
      mtls: partner
    provider:
      name: proxy
      url: https://wmts.partner.example.net/imagery/{z}/{x}/{y}.jpg
  - id: archive
    client:
      tls: corp-ca
    provider:
      name: proxy
      url: https://archive.corp.example.com/{z}/{x}/{y}.png
  - id: osm
    client:
      tls: system
    provider:
      name: proxy
      url: https://tile.openstreetmap.org/{z}/{x}/{y}.png
{
  "tls": [
    {
      "name": "pem",
      "id": "mesh",
      "certificateFile": "/var/run/certs/tls.crt",
      "keyFile": "/var/run/certs/tls.key",
      "caFile": "/var/run/certs/ca.crt",
      "allowedHosts": [
        "*.svc.cluster.local"
      ]
    },
    {
      "name": "pem",
      "id": "partner",
      "certificate": "secret.partner-cert",
      "key": "secret.partner-key",
      "allowedHosts": [
        "wmts.partner.example.net"
      ]
    },
    {
      "name": "pem",
      "id": "corp-ca",
      "caFile": "/etc/pki/corp-root.pem"
    }
  ],
  "client": {
    "tls": "mesh",
    "mtls": "mesh"
  },
  "layers": [
    {
      "id": "buildings",
      "provider": {
        "name": "pmtiles",
        "url": "https://tiles.storage.svc.cluster.local/buildings.pmtiles"
      }
    },
    {
      "id": "partner_imagery",
      "client": {
        "tls": "system",
        "mtls": "partner"
      },
      "provider": {
        "name": "proxy",
        "url": "https://wmts.partner.example.net/imagery/{z}/{x}/{y}.jpg"
      }
    },
    {
      "id": "archive",
      "client": {
        "tls": "corp-ca"
      },
      "provider": {
        "name": "proxy",
        "url": "https://archive.corp.example.com/{z}/{x}/{y}.png"
      }
    },
    {
      "id": "osm",
      "client": {
        "tls": "system"
      },
      "provider": {
        "name": "proxy",
        "url": "https://tile.openstreetmap.org/{z}/{x}/{y}.png"
      }
    }
  ]
}

See Encryption for an example of using profiles to serve HTTPS.

Edit this page Report an issue