add doc

cmd/client/commandv2/convert/nginx/cmd.go

@@ -41,9 +41,16 @@ type Options struct {
 func Cmd() *cobra.Command {
  flags := &Options{}
  flags.init()
+ examples := []general.Example{
+ {
+ Desc: "Convert nginx config to easegress yamls",
+ Command: "egctl convert nginx -f <nginx.conf> -o <output.yaml> --prefix <prefix>",
+ },
+ }
  cmd := &cobra.Command{
- Use: "nginx",
- Short: "Convert nginx.conf to easegress yaml file",
+ Use: "nginx",
+ Short: "Convert nginx.conf to easegress yaml file",
+ Example: general.CreateMultiExample(examples),
  Args: func(cmd *cobra.Command, args []string) error {
  if flags.NginxConf == "" {
  return fmt.Errorf("nginx.conf file path is required")

docs/02.Tutorials/2.2.HTTP-Proxy-Usage.md

@@ -98,9 +98,14 @@ port: 10080
 rules:
 # Rules for host matching.
 # If not match, HTTPServer will check next rule.
+# wildcard is supported in front or end of hostnames.
 - host: <your-host>
- hosts: [<your-host1>, <your-host2>]
  hostRegexp: <your-host-regexp>
+ hosts:
+ - value: *.example.com 
+ isRegexp: false
+ - value: www.example.* 
+ isRegexp: false
 
  # IP-based filtering.
  ipFilter: {}

docs/03.Advanced-Cookbook/3.13.Nginx.md

@@ -0,0 +1,342 @@
+# Nginx Configuration Conversion to Easegress YAML
+
+- [Nginx Configuration Conversion to Easegress YAML](#nginx-configuration-conversion-to-easegress-yaml)
+ - [Nginx Configurations Supported for Conversion](#nginx-configurations-supported-for-conversion)
+ - [listen](#listen)
+ - [server\_name](#server_name)
+ - [location](#location)
+ - [proxy\_pass and upstream](#proxy_pass-and-upstream)
+ - [websocket](#websocket)
+ - [HTTPS](#https)
+ - [proxy\_set\_header](#proxy_set_header)
+ - [gzip](#gzip)
+ - [Example](#example)
+
+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>
+```
+
+## 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 
+
+```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: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
+```

docs/03.Advanced-Cookbook/README.md

@@ -12,3 +12,4 @@
 ### [Workflow](3.10.Workflow.md)
 ### [Performance](3.11.Performance.md)
 ### [Migrate v1.x Filter To v2.x](3.12.Migrate.md)
+### [Nginx Configuration Conversion to Easegress YAML](3.13.Nginx.md)