Skip to content

Latest commit

 

History

History
342 lines (289 loc) · 7.54 KB

3.13.Nginx.md

File metadata and controls

342 lines (289 loc) · 7.54 KB
Raw

Nginx Configuration Conversion to Easegress YAML

This document serves as a guide for converting Nginx configurations to Easegress YAML format using the egctl convert nginx command.

egctl convert nginx -f <nginx.conf> -o <output.yaml> --prefix <prefix>

Nginx Configurations Supported for Conversion

listen

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;

server_name

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$

location

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)$

proxy_pass and upstream

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:https://user.example.com

proxy_pass http:backend

upstream backend {
    server 127.0.0.1:8080;
    server 127.0.0.2:9090 weight=10;
}

websocket

Settings recognized as WebSocket configurations correspond to an Easegress Pipeline with a WebsocketProxy filter.

location /websocket {
    proxy_pass http:https://wsbackend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
}

HTTPS

HTTPS configurations are supported as per Easegress HTTPServer settings.

listen 443 ssl;

ssl_certificate        you-cert.crt;
ssl_certificate_key    your-cert-key.key;

ssl_certificate        you-cert2.crt;
ssl_certificate_key    your-cert-key2.key;

ssl_client_certificate your-client-cert.crt;

proxy_set_header

Translates to an Easegress Pipeline with a RequestAdaptor filter.

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:

proxy_set_header Host $host

gzip

Corresponds to an Easegress Pipeline with a Proxy filter, including compression settings.

gzip on;
gzip_min_length 1000;

Example

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 {
            proxy_set_header X-Path "apis";
            proxy_pass http:https://localhost:8880;

            location /apis/v1 {
                proxy_set_header X-Path "apis/v1";
                proxy_pass http:https://localhost:8888;
            }
        }

        location /upstream {
            gzip on;
            gzip_min_length 1000;
            proxy_pass http:https://backend;
        }

        location /websocket {
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $connection_upgrade;
            proxy_pass http:https://localhost:9090;
        }
    }

    server {
        listen 127.0.0.1:443 ssl;
        ssl_client_certificate <your-client-cert>;
        ssl_certificate <your-cert>;
        ssl_certificate_key <your-key>;

        location = /user {
            proxy_pass http:https://localhost:9999;
        }
    }
}

then run

egctl convert ngxin -f nginx.conf -o nginx.yaml --prefix convert-nginx

will generate following Easegress 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:https://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:https://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:https://localhost:1234
              weight: 1
            - url: http:https://localhost:2345
              weight: 10

---
name: convert-nginx-websocket
kind: Pipeline
flow: []
filters:
    - kind: WebSocketProxy
      name: websocket
      pools:
        - loadBalance:
            policy: roundRobin
          servers:
            - url: ws:https://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:https://localhost:9999
              weight: 1