Headless Configuration

The proxy-config.yaml file is used to configure Qpoint Proxy, defining global settings, endpoint-specific rules, and optional middleware stacks.

Configuration File Structure

The proxy-config.yaml file consists of three main sections:

1. Global Proxy Settings

2. Endpoints

3. Stacks (Optional)

proxy: # Global Proxy Settings
  jwt_hmac_key: "qwertyuiopasdfghjklzxcvbnm123456"  # Key for HMAC to validate JWTs
  tls_ca_crt: "PEM or file://global_ca_cert.pem"  # Path or inline CA certificate
  tls_ca_key: "PEM or file://global_ca_key.pem"  # Path or inline CA key
  default_domain_action: ALLOW  # Default action for unspecified domains

  endpoints:  # Specific Endpoint Settings
    
    # Endpoint with ACL, without SSL/TLS Termination, & without Stack
    - domain: "api.github.com"
      action: DENY
      allow:
        - ip: 172.17.0.1
        - id: dog
    
    # Endpoint with ACL, with SSL/TLS Termination & with Stack
    - domain: "api.example.com"
      action: DENY
      allow:
        - ip: 172.17.0.1
        - http-user: user2:password2
        - tag: admin    
      stack: complete # Reference to the 'complete' stack

stacks:
  complete:
    middlewares:
      - name: duration-micro
        config: "us"
        wasm: "docker://us-docker.pkg.dev/qpoint-edge/public/middleware/http_duration:0bb591c"
      - name: local-metrics
        config: "metrics-config"
        wasm: "/path/to/local/metrics.wasm"
 

Global Settings

These settings apply across the entire proxy configuration.

proxy:
  jwt_hmac_key: "qwertyuiopasdfghjklzxcvbnm123456"  # Key for HMAC to validate JWTs
  tls_ca_crt: "PEM or file://"  # Path or inline CA certificate
  tls_ca_key: "PEM or file://"  # Path or inline CA key
  default_domain_action: ALLOW  # Default action for unspecified domains

• jwt_hmac_key (optional): Key used for HMAC to validate JWTs for Access Control.

• tls_ca_crt (optional): Path or inline CA certificate for optional SSL/TLS termination.

• tls_ca_key (optional): Path or inline CA key for optional SSL/TLS termination

• default_domain_action: Sets the default action for domain requests not explicitly defined in the endpoints section.

Endpoints

Controls traffic based on the requested domain, with specific rules for each domain.

proxy:
  ... # Global Settings
  endpoints:
    - domain: "api.example.com"
      action: DENY
      allow:
        - ip: 172.17.0.1
      cert:
        ca: "PEM or file://"  # Inline or path to CA certificate
        crt: "PEM or file://"  # Inline or path to domain certificate
        key: "PEM or file://"  # Inline or path to private key
      stack: complete  # Reference to a stack for middleware processing

• domain: The specific domain to which the rule applies.

• action: Default action for this domain (ALLOW or DENY).

• allow/deny: Conditions to override the default action based on IP addresses, user credentials, or JWT claims.

• cert: SSL/TLS certificate configurations for the endpoint.

  • ca: Path or inline CA certificate.

  • crt: Path or inline server certificate.

  • key: Path or inline private key.

• stack: Name of a middleware stack to apply additional inline processing (optional).

Stacks (Optional)

Defines groups of middleware modules for enhanced traffic processing. See more detailed information in Stacks

stacks:
  default:
    middlewares:
      - name: duration-micro
        config: "us"
        wasm: "docker://us-docker.pkg.dev/qpoint-edge/public/middleware/http_duration:0bb591c"
      - name: report
        wasm: "/path/to/local/report.wasm"

• stacks: Top-level section defining all middleware stacks.

• default: Name of the stack.

• middlewares: List of middleware modules in each stack.

  • name: Descriptive name of the middleware.

  • config: Configuration parameters for the middleware.

  • wasm: Path to the WebAssembly module, either a local path or a remote URI.

Examples of Endpoint Configurations

Without SSL/TLS Termination & Without Stack

endpoints:
  - domain: "api.github.com"
    action: DENY
    allow:
      - ip: 172.17.0.1

With SSL/TLS Termination & With Stack

proxy:
  tls_ca_crt: "PEM or file://"  # Path or inline CA certificate
  tls_ca_key: "PEM or file://"  # Path or inline CA key
  default_domain_action: ALLOW
  endpoints:
    - domain: "api.example.com"
      action: DENY
      allow:
        - ip: 172.17.0.1
      stack: complete # Reference to a stack for middleware processing