HTTP Proxy Usage

HTTPServer
Pipelines

Creating an HTTP Proxy allows for traffic routing and management. You can set one up using the egctl create httpproxy command. For comprehensive instructions, refer to egctl create httpproxy. For more advanced features, you might consider setting up HTTPServer and Pipelines.

HTTPServer

An HTTPServer acts as a listening server on a specified port, directing traffic to designated Pipelines. Below is a basic configuration example:

name: demo
kind: HTTPServer

port: 10080     # Listening port
http3: false    # HTTP3 usage; default is false
keepAlive: true # Keep the connection alive; default is true

---
title: Use HTTPS; default is false.
linkTitle: Use HTTPS; default is false.
weight: 2
---
---
title: If true, set autocert or provide certs and keys.
linkTitle: If true, set autocert or provide certs and keys.
weight: 2
---
https: false

---
title: Automated certificate management.
linkTitle: Automated certificate management.
weight: 2
---
---
title: More info in AutoCertManager
linkTitle: More info in AutoCertManager
weight: 2
---
autoCert: false

---
title: Public keys in PEM base64 format
linkTitle: Public keys in PEM base64 format
weight: 2
---
certs:
  cert1: <public-key-data>
  cert2: <public-key-data>
---
title: Corresponding private keys
linkTitle: Corresponding private keys
weight: 2
---
keys: 
  cert1: <private-key-data>
  cert2: <private-key-data>

---
title: Max request body size; default is 4MB
linkTitle: Max request body size; default is 4MB
weight: 2
---
clientMaxBodySize: 4 * 1024 * 1024

---
title: Max connections with clients, default 10240
linkTitle: Max connections with clients, default 10240
weight: 2
---
maxConnections: 10240

---
title: Root certificate authorities
linkTitle: Root certificate authorities
weight: 2
---
caCertBase64: <your-ca-cert>

---
title: Special pipeline that can be executed
linkTitle: Special pipeline that can be executed
weight: 2
---
---
title: before or/and after all pipelines in a serve.
linkTitle: before or/and after all pipelines in a serve.
weight: 2
---
globalFilter: global-filter-name

---
title: Distributed tracing settings
linkTitle: Distributed tracing settings
weight: 2
---
tracing: {}

---
title: IP Filter for all traffic under the server
linkTitle: IP Filter for all traffic under the server
weight: 2
---
ipFilter:
  blockIPs: []
  allowIPs: []
  blockByDefault: false

---
title: Traffic routing rules
linkTitle: Traffic routing rules
weight: 2
---
rules:
    - host: <your-host>
      paths:
        - path: /pipeline
          backend: demo-0

You can create, update, edit, or delete HTTPServer with egctl commands. More details in egctl.

For managing HTTPServer (create, update, edit, delete, check), use egctl commands. Further details can be found in the egctl section.

For a deep dive into available parameters, consult:

Exploring Rules in Depth

Within an HTTPServer configuration, the rules section enables precise traffic routing based on various conditions, such as host names, IP addresses, paths, methods, headers, and query parameters.

Here’s a more concise and structured breakdown of the rules section:

name: demo
kind: HTTPServer
port: 10080
...

rules:
---
title: Rules for host matching.
linkTitle: Rules for host matching.
weight: 2
---
---
title: If not match, HTTPServer will check next rule.
linkTitle: If not match, HTTPServer will check next rule.
weight: 2
---
- host: <your-host>
  hosts: [<your-host1>, <your-host2>]
  hostRegexp: <your-host-regexp>

  # IP-based filtering.
  ipFilter: {}

  # Path-based routing.
  paths: 
  - path: /abc # Exact path match
    backend: abc-pipeline

  - pathPrefix: /xyz # Matches any path with the given prefix
    backend: xyz-pipeline

  - path: /efg
    methods: [PUT] # Path and HTTP method condition
    backend: efg-pipeline
  
  - pathRegexp: /[a-z]+ # Path and HTTP method condition
    backend: az-pipeline

  # for path, rewriteTarget replace original path
  # for pathPrefix, rewriteTarget replace prefix
  # for pathRegexp, rewriteTarget use re.ReplaceAllString(path, rewriteTarget)
  - path: /hig
    backend: newhig-pipeline
    rewriteTarget: /newhig

  # Header-based routing.
  - path: /headers
    headers:
    - key: "X-Test"
      values: [test1, test2] # Matches if any of these values are found
    - key: "AllMatch"
      regexp: "^true$"       # Matches the exact regular expression
    matchAllHeader: false    # If true, all header conditions must match
    backend: headers-pipeline

  # Query parameter-based routing.
  - path: /query
    matchAllQuery: false     # If true, all query conditions must match
    queries:
    - key: "q"
      values: ["v1", "v2"]
    - key: "q2"
      values: ["v3", "v4"]
    backend: query-pipeline

---
title: next rule
linkTitle: next rule
weight: 2
---
- host: ...
  ...

Order Matters

Rules are checked sequentially. Place frequently matched rules at the top to optimize performance.
Similarly, within each rule, path conditions are also checked in order. Prioritize commonly used paths.

By carefully structuring the rules section, you can ensure optimal and precise traffic management within Easegress.

Examples

With the provided configuration,

1. Path Routing

When a request is made to http://127.0.0.1:10080/abc, it gets directed to the `abc-pipeline`` based on the path-based routing rule:

- path: /abc
  backend: abc-pipeline

2. Path Prefix Routing

A request to any URL with the prefix /xyz, like http://127.0.0.1:10080/xyz123, will be directed to xyz-pipeline due to:

- pathPrefix: /xyz
  backend: xyz-pipeline

3. Method-based Routing

Only PUT requests to http://127.0.0.1:10080/efg will be routed to efg-pipeline:

- path: /efg
  methods: [PUT]
  backend: efg-pipeline

4. Regular Expression Routing

Requests with paths that match the regular expression, like http://127.0.0.1:10080/abcd, get routed to az-pipeline:

- pathRegexp: /[a-z]+
  backend: az-pipeline

5. Header-based Routing:

If a request has the header X-Test with values test1 or test2, it will be directed to headers-pipeline. For instance, a request to http://127.0.0.1:10080/headers with the header X-Test: test1 will match:

- path: /headers
  headers:
  - key: "X-Test"
    values: [test1, test2]
  backend: headers-pipeline

6. Query Parameter Routing

A request to http://127.0.0.1:10080/query?q=v1 matches the condition and will be routed to query-pipeline:

- path: /query
  queries:
  - key: "q"
    values: ["v1", "v2"]
  backend: query-pipeline

Pipelines

In Easegress, Pipelines are fundamental constructs that enable the arrangement and execution of filters in a sequence to process incoming requests. Think of it as a production line in a factory; each filter can alter or process the request in a specific way before passing it to the next filter (or the final destination).

Here’s a simple pipeline configuration:

name: pipeline-demo
kind: Pipeline
flow:
  - filter: proxy
filters:
  - name: proxy
    kind: Proxy
    pools:
    - servers:
      - url: http://127.0.0.1:9095
      - url: http://127.0.0.1:9096
      loadBalance:
        policy: roundRobin

Explanation:

flow: Defines the order in which filters are executed. In this case, we only have one filter named “proxy”.
filters: Contains configurations for each filter. Here, we have:
- name: The filter’s identifier.
- kind: The type of filter, which is “Proxy” in this case.
- other spec details: The configuration details and settings will differ and be specific to the chosen filter type. This means each filter has its unique parameters and settings based on its functionality and role.

In this example, incoming requests to the pipeline are simply proxied to either http://127.0.0.1:9095 or http://127.0.0.1:9096 in a round-robin fashion.