Documentation

Policies Reference

Proxy

Description

The Proxy policy forwards the request to a service endpoint.

This type of policy should generally be placed last in the policies list within a pipeline.

Usage

To enable the Proxy policy, add proxy in gateway.config.yml in the policies section.


policies:
  - proxy

Example


http:
  port: 9091

apiEndpoints:
  api:
    path: '*'

serviceEndpoints:
  example: # will be referenced in proxy policy
    url: 'http://example.com'

pipelines:
  example-pipeline:
    apiEndpoints:   # process all request matching "api" apiEndpoint
      - api
    policies:
      proxy: # name of the policy
        -   # list of actions
          condition:
            name: pathExact
            path: /admin
          action:
            serviceEndpoint: example # reference to serviceEndpoints Section

Options Reference

serviceEndpoint:
- the name of the service endpoint to forward to
- the path of the API endpoint is appended to the path of the serviceEndpoint host and path automatically
- example: API endpoint - “http://api.foobar.com/api” proxied to a service endpoint defined as “http://internal.api.lan:8080/” will have “/api” appended to it to become “http://internal.api.lan:8080/api”
strategy:
- Assigns a load-balancing strategy for serviceEndpoint declarations that have more than one URL, defaults to round-robin.
proxyUrl:
- Address of the intermediate proxy. Example: http://corporate.proxy:3128. See more details below.
ws:
- true/false, if you want to proxy websockets
xfwd:
- true/false, adds x-forward headers
secure:
- true/false, if you want to verify the SSL Certs
toProxy:
- true/false, passes the absolute URL as the path (useful for proxying to proxies)
prependPath:
- true/false, Default: true - specify whether you want to prepend the target’s path to the proxy path. See more details below.
ignorePath:
- true/false, Default: false - specify whether you want to ignore the proxy path of the incoming request. See more details below.
stripPath
- true/false, Default: false — specify whether you want to strip the apiEndpoint path from the final URL. See more details below.
localAddress:
- Local interface string to bind for outgoing connections
changeOrigin:
- true/false, Default: true - changes the origin of the host header to the target URL
preserveHeaderKeyCase:
- true/false, Default: false - specify whether you want to keep letter case of response header key
auth:
- Basic authentication i.e. ‘user:password’ to compute an Authorization header.
hostRewrite:
- rewrites the location hostname on (201/301/302/307/308) redirects.
autoRewrite:
- rewrites the location host/port on (201/301/302/307/308) redirects based on requested host/port. Default: false.
protocolRewrite:
- rewrites the location protocol on (201/301/302/307/308) redirects to ‘http’ or ‘https’. Default: null.
cookieDomainRewrite:
- rewrites domain of set-cookie headers. Possible values:
  - false (default): disable cookie rewriting
  - String: new domain, for example cookieDomainRewrite: "new.domain". To remove the domain, use cookieDomainRewrite: "".
  - Object: mapping of domains to new domains, use "*" to match all domains. For example keep one domain unchanged, rewrite one domain and remove other domains:
```
cookieDomainRewrite: {
  "unchanged.domain": "unchanged.domain",
  "old.domain": "new.domain",
  "*": ""
}
```
headers:
- object with extra headers to be added to target requests.
timeout:
- timeout (in millis) when proxy receives no response from target

Load balancing strategies

round-robin: This strategy routes each client request to a URL assigned in the urls array for a serviceEndpoint, starting at the first URL, moving through the last URL, and finally looping back to the start.

serviceEndpoints:
  backend: # will be referenced in proxy policy
    urls:
      - http://srv1.example.com
      - http://srv2.example.com

pipelines:
  example-pipeline:
    apiEndpoints:
      - api
    policies:
      proxy:
        - action:
            serviceEndpoint: backend

Path management

You probably noticed there are 3 options that concern the path: prependPath, ignorePath and stripPath. They might be a little bit confusing so here’s a breakdown on how they work with the most common cases.

Let’s assume we have an Express Gateway instance listening on port 80 and exposed on an IP that has a CNAME of https://myCompanyName.io

With:

An apiEndpoint /public/api/billing*
A serviceEndpoint http://internalBillingMicroservice/anything

and launching

curl https://myCompanyName.io/public/api/billing/byName?name=Clark

According to the options you will get different results:

prependPath:  false
ignorePath:   false
stripPath:    false

Resulting upstream service path: /public/api/billing/byName?name=Clark

prependPath:  true
ignorePath:   false
stripPath:    false

Resulting upstream service path: /anything/public/api/billing/byName?name=Clark

prependPath:  true
ignorePath:   true
stripPath:    false

Resulting upstream service path: /anything

prependPath:  false
ignorePath:   true
stripPath:    false

Resulting proxied URL: /

prependPath:  true
ignorePath:   false
stripPath:    true

Resulting proxied URL: /anything/byName?name=Clark

Service Endpoints options

There might be cases where a set of Proxy options is valid for an entire service endpoint. If you have, for example, a service endpoint on an host and then multiple pipelines based on a path — you might end up setting the same options per each pipeline. In that case, you can either use yaml references, or set the proxyOptions parameter on the serviceEndpoint directly.

serviceEndpoints:             # downstream microservices
  cats:                       # name, used as a reference in pipeline
    url: "http://cats1.example.com"
    proxyOptions:
      changeOrigin: false
      xfwd: true

The proxyOptions object will be forwarded to the node-http-proxy middleware.

Service Endpoints behind intermediate proxy

Some corporation allow access to internet only through proxy. In this case you need to specifically tell Express-Gateway to use proxy to forward requests

Request flow will look like this:

Request -> Express Gateway with Proxy policy -> Corporate proxy -> Target Service Endpoint

This can be done done using http_proxy or HTTP_PROXY env variable.

http_proxy=http://corporate.proxy:3128 npm start

Another way is to set proxyUrl in the proxy policy itself

pipelines:
  example-pipeline:
    apiEndpoints:   # process all request matching "api" apiEndpoint
      - api
    policies:
      proxy: # name of the policy
        - action:
            serviceEndpoint: example
            proxyUrl: http://corporate.proxy:3128