Project: Easegress (Orchestration & Management / API Gateway)
File: 3.13.Nginx.md

- - - - - This document serves as a guide for converting Nginx configurations to Easegress YAML format using the `egctl convert nginx` command. ```bash egctl convert nginx -f <nginx.conf> -o <output.yaml> --prefix <prefix> ``` The `listen` directive supports `port`, `address:port`, and `ssl` configurations. It corresponds to the `port` and `address` properties of an Easegress `HTTPServer`. ``` listen: 80; listen: 127.0.0.1:80; listen: 443 ssl; ``` Supports exact hostnames, prefixed hostnames, suffixed hostnames, and regular expressions. Translates to the `hosts` attribute in Easegress `HTTPServer`. ``` server_name www.example.com *.example.com; server_name www.example.* ~^(?<user>.+)\.example\.net$ ``` Handles `location` with prefix paths, exact paths, and regular expression paths (case-insensitive included). The ordering in Easegress follows Nginx's precedence: exact paths first, prefix paths next (sorted by length), and regex paths last. Nested locations are also supported. This translates to `rules` and `paths` in an Easegress `HTTPServer`. ``` location /apis { location /apis/v1 { ... } ... } location = /user { ... } location ~* \.(gif|jpg|jpeg)$ { ... } location ^~ /admin/ { ... } ``` The resulting path order in Easegress would be: ``` path: /user pathPrefix: /apis/v1 pathPrefix: /admin/ pathPrefix: /apis pathRegexp: \.(gif|jpg|jpeg)$ ``` Currently, only reverse proxy functionalities are supported. For `upstream`, the default load-balancing strategy is `roundRobin`. If a server weight is specified, `weightRandom` is used for load balancing. Equal to Easegress `Pipeline` with `Proxy` filter. ``` proxy_pass http://user.example.com proxy_pass http:backend upstream backend { server 127.0.0.1:8080; server 127.0.0.2:9090 weight=10; } ``` Settings recognized as `WebSocket` configurations correspond to an Easegress `Pipeline` with a `WebsocketProxy` filter. ``` location /websocket { proxy_pass http://wsbackend; proxyhttpversion 1.1; proxysetheader Upgrade $http_upgrade; proxysetheader Connection "Upgrade"; } ``` HTTPS configurations are supported as per Easegress `HTTPServer` settings. ``` listen 443 ssl; ssl_certificate you-cert.crt; sslcertificatekey your-cert-key.key; ssl_certificate you-cert2.crt; sslcertificatekey your-cert-key2.key; sslclientcertificate your-client-cert.crt; ``` Translates to an Easegress `Pipeline` with a `RequestAdaptor`

The following Nginx embedded variables are supported: `$host` `$hostname` `$content_length` `$content_type` `$remote_addr` `$remote_user` `$request_body` `$request_method` `$request_uri` `$scheme` For example: ``` proxysetheader Host $host ``` Corresponds to an Easegress `Pipeline` with a `Proxy` filter, including `compression` settings. ``` gzip on; gzipminlength 1000; ``` Given following nginx configuration: ``` events {} http { upstream backend { server localhost:1234; server localhost:2345 weight=10; } server { listen 80; server_name www.example.com *.example.com; location /apis { proxysetheader X-Path "apis"; proxy_pass http://localhost:8880; location /apis/v1 { proxysetheader X-Path "apis/v1"; proxy_pass http://localhost:8888; } } location /upstream { gzip on; gzipminlength 1000; proxy_pass http://backend; } location /websocket { proxyhttpversion 1.1; proxysetheader Upgrade $http_upgrade; proxysetheader Connection $connection_upgrade; proxy_pass http://localhost:9090; } } server { listen 127.0.0.1:443 ssl; sslclientcertificate <your-client-cert>; ssl_certificate <your-cert>; sslcertificatekey <your-key>; location = /user { proxy_pass http://localhost:9999; } } } ``` then run ```bash egctl convert ngxin -f nginx.conf -o nginx.yaml --prefix convert-nginx ``` will generate following Easegress YAML: ```yaml name: convert-nginx-80 kind: HTTPServer address: "" port: 80 keepAliveTimeout: 60s maxConnections: 10240 rules: hosts: isRegexp: false value: www.example.com isRegexp: false value: '*.example.com' paths: pathPrefix: /websocket backend: convert-nginx-websocket clientMaxBodySize: -1 pathPrefix: /upstream backend: convert-nginx-upstream pathPrefix: /apis/v1 backend: convert-nginx-apisv1 pathPrefix: /apis backend: convert-nginx-apis name: convert-nginx-443 kind: HTTPServer https: true address: 127.0.0.1 port: 443 caCertBase64: <your-client-cert-data> certs: <your-cert>: <your-cert-data> keys: <your-cert>: <your-key-data> rules: paths: path: /user backend: convert-nginx-user name: convert-nginx-apis kind: Pipeline flow: [] filters: kind: RequestAdaptor name: request-adaptor template: | header: set: X-Path: apis kind: Proxy maxIdleConns: 10240 maxIdleConnsPerHost: 1024 name: proxy pools: loadBalance: policy: roundRobin servers: url: http://localhost:8880 weight: 1 name: convert-nginx-apisv1 kind: Pipeline flow: [] filters: kind: RequestAdaptor name: request-adaptor template: | header: set: X-Path: apis/v1 version: "" kind: Proxy maxIdleConns: 10240 maxIdleConnsPerHost: 1024 name: proxy pools: loadBalance: policy: roundRobin servers: url: http://localhost:8888 weight: 1 name: convert-nginx-upstream kind: Pipeline flow: [] filters: compression: minLength: 1000 kind: Proxy maxIdleConns: 10240 maxIdleConnsPerHost: 1024 name: proxy pools: loadBalance: policy: weightedRandom servers: url: http://localhost:1234 weight: 1 url: http://localhost:2345 weight: 10 name: convert-nginx-websocket kind: Pipeline flow: [] filters: kind: WebSocketProxy name: websocket pools: loadBalance: policy: roundRobin servers: url: ws://localhost:9090 weight: 1 name: convert-nginx-user kind: Pipeline flow: [] filters: kind: Proxy maxIdleConns: 10240 maxIdleConnsPerHost: 1024 name: proxy pools: loadBalance: policy: roundRobin servers: url: http://localhost:9999 weight: 1 ```