Proxy Configuration Examples

Each YAML block is a complete configuration for one proxy process. Replace DNS names, identity patterns, and socket paths with values from your deployment. The paired client and server examples run beside their respective applications; networking and Services must route each target hostname to the receiving proxy’s listener port.

See the Proxy Config Reference for loading instructions, field definitions, and defaults. For Kubernetes manifests, see the manual sidecar deployment guide or the TCP deployment example.

HTTP client

The calling application sends plaintext HTTP to http://127.0.0.1:8081. This proxy connects with mTLS to the server proxy’s port 8443 and accepts only the api-server workload identity pattern.

spiffe:
  workload_socket_path: unix:///spiffe-workload-api/agent.sock
metricsAddr: "127.0.0.1:7600"
listeners:
  - name: api-client
    address: "127.0.0.1:8081"
    mode: client
    protocol: http
    target:
      url: https://api-server.example.svc.cluster.local:8443
      spiffe_ids:
        - '^spiffe://example\.org/ns/example/sa/api-server/.*$'
    timeouts:
      read: 30s
      write: 90s
      idle: 3m
    connection:
      disable_keepalive: true

HTTP server

This proxy accepts mTLS connections from the api-client workloads and forwards HTTP to the receiving application on loopback port 8080. For a central topology, change the source pattern to the central proxy’s identity.

spiffe:
  workload_socket_path: unix:///spiffe-workload-api/agent.sock
listeners:
  - name: api-server
    address: ":8443"
    mode: server
    protocol: http
    source:
      spiffe_ids:
        - '^spiffe://example\.org/ns/example/sa/api-client/.*$'
    target:
      url: http://127.0.0.1:8080

HTTP central notary

The client proxy connects to this central proxy using mTLS. The central proxy then connects to the server proxy using its own identity. Configure the client proxy’s target URL and identity pattern for this central proxy, and configure the server proxy to allow the notary service account.

The receiving application must support nonstreaming POST /v1/chat/completions requests, and the calling application must use that endpoint through its client proxy. Other application endpoints are blocked by the OpenAI middleware in this example. The central proxy also needs the Kubernetes permissions and database mount described in Notary.

spiffe:
  workload_socket_path: unix:///spiffe-workload-api/agent.sock
notary:
  enable: true
  database:
    path: /var/lib/qhx/notary.db
listeners:
  - name: central-notary
    address: ":8443"
    mode: central
    protocol: http
    source:
      spiffe_ids:
        - '^spiffe://example\.org/ns/example/sa/api-client/.*$'
    target:
      url: https://api-server.example.svc.cluster.local:8443
      spiffe_ids:
        - '^spiffe://example\.org/ns/example/sa/api-server/.*$'
    middlewares:
      - type: notary-query
      - type: openai
        allowUnknown: false
    timeouts:
      read: 30s
      write: 5m
      idle: 3m

TCP client

The calling application connects to loopback port 15432. This proxy carries the TCP stream over mTLS to the database server proxy on port 9443.

spiffe:
  workload_socket_path: unix:///spiffe-workload-api/agent.sock
listeners:
  - name: database-client
    address: "127.0.0.1:15432"
    mode: client
    protocol: tcp
    target:
      url: tls://database.example.svc.cluster.local:9443
      spiffe_ids:
        - '^spiffe://example\.org/ns/example/sa/database/.*$'

TCP server

This proxy accepts the client proxy’s mTLS connection and forwards its byte stream to the database on loopback port 5432.

spiffe:
  workload_socket_path: unix:///spiffe-workload-api/agent.sock
listeners:
  - name: database-server
    address: ":9443"
    mode: server
    protocol: tcp
    source:
      spiffe_ids:
        - '^spiffe://example\.org/ns/example/sa/database-client/.*$'
    target:
      url: tcp://127.0.0.1:5432

MQTT buffered publisher

The publishing application connects to loopback port 1883. This proxy buffers publishes and connects over mTLS to the broker proxy on port 8883. It permits up to 1,000 queued messages within the 32 MiB payload limit. Use a separate, unbuffered connection for subscriptions.

Message expiry is disabled in this example. Read the buffering limits and delivery semantics before choosing queue limits, an overflow policy, or max-ttl.

spiffe:
  workload_socket_path: unix:///spiffe-workload-api/agent.sock
listeners:
  - name: mqtt-publisher
    address: "127.0.0.1:1883"
    mode: client
    protocol: mqtt
    target:
      url: mqtts://broker.example.svc.cluster.local:8883
      spiffe_ids:
        - '^spiffe://example\.org/ns/example/sa/broker/.*$'
    middlewares:
      - type: buffer
        storage:
          type: in-memory
          max-bytes: 33554432
          max-messages: 1000
          max-ttl: 0s
        overflow-policy: reject
        reconnect-backoff:
          initial: 2s
          max: 1m
    timeouts:
      idle: 3m

MQTT server

This proxy accepts mTLS connections from publisher proxies and forwards MQTT to the broker on loopback port 1883. The broker remains responsible for its own MQTT authentication and topic authorization.

spiffe:
  workload_socket_path: unix:///spiffe-workload-api/agent.sock
listeners:
  - name: mqtt-server
    address: ":8883"
    mode: server
    protocol: mqtt
    source:
      spiffe_ids:
        - '^spiffe://example\.org/ns/example/sa/mqtt-publisher/.*$'
    target:
      url: mqtt://127.0.0.1:1883