New backward compatible multiport syntax for VIRTUAL_PORT variable

[pini-gh]

This pull request is intended to support containers exposing more than one entrypoint through different ports. I've discussed this topic in issue #1504.

New VIRTUAL_PORT syntax

VIRTUAL_PORT = [ <virtual_port> | <multiport> ];
multiport    = port, { ",",  port };
port         = <virtual_port> [ ":", <virtual_path> [ ":", <virtual_dest> ]];

As many nginx upstream definitions are created as specified ports. The same goes for location blocks. Routing is performed based on the virtual path specified for each port.

Example

VIRTUAL_HOST: "multiport.example.com"
VIRTUAL_PORT: "9220:~ ^/(admin|fonts?|images|webmin)/,10901,20901:/ws2p,30901:/gva/playground"

would produce one nginx upstream definition per port, and as many location blocs:

# multiport.example.com:10901
upstream multiport.example.com-10901 {
        ## Can be connected with "docker-gen-bridge" network
        # blah
        server 172.29.0.5:10901;
}
# multiport.example.com:20901/ws2p
upstream multiport.example.com-5c7ebef820fe004e45e3af1d0c47971594d028b2-20901 {
        ## Can be connected with "docker-gen-bridge" network
        # blah
        server 172.29.0.5:20901;
}
# multiport.example.com:30901/gva/playground
upstream multiport.example.com-1f02ce2421b17d828edaabfc3014360891bb0be3-30901 {
        ## Can be connected with "docker-gen-bridge" network
        # blah
        server 172.29.0.5:30901;
}
# multiport.example.com:9220~ ^/(admin|fonts?|images|webmin)/
upstream multiport.example.com-cae8bfc2ea1fe6bb6fda08727ab065e8fed98aa2-9220 {
        ## Can be connected with "docker-gen-bridge" network
        # blah
        server 172.29.0.5:9220;
}
server {
        server_name multiport.example.com;
        listen 80 ;
        access_log /var/log/nginx/access.log vhost;
        location / {
                proxy_pass http://multiport.example.com-10901;
        }
        location /ws2p {
                proxy_pass http://multiport.example.com-5c7ebef820fe004e45e3af1d0c47971594d028b2-20901;
        }
        location /gva/playground {
                proxy_pass http://multiport.example.com-1f02ce2421b17d828edaabfc3014360891bb0be3-30901;
        }
        location ~ ^/(admin|fonts?|images|webmin)/ {
                proxy_pass http://multiport.example.com-cae8bfc2ea1fe6bb6fda08727ab065e8fed98aa2-9220;
        }
}

Backward compatible

Legacy VIRTUAL_PORT syntax with only one port still works the very same way. I've ran the full test suite with only 3 unrelated errors (which I reproduce with version 1.0.4 as well):

FAILED test/test_ssl/test_dhparam.py::test_custom_dhparam_is_supported_per_site - Exception: Failed to process CLI request:
ERROR test/test_raw-ip-vhost.py::test_raw_ipv4_vhost_forwards_to_web1
ERROR test/test_raw-ip-vhost.py::test_raw_ipv6_vhost_forwards_to_web2

Added related documentation

See section 'Multiport Syntax' of the README.

Specific test case

I've added a test case in folder test/test_multiport_syntax. It features a web server exposing 4 ports. All these ports are reachable through different paths. This test case runs successfully on my box.

[pini-gh]

Hi @buchdag, I thin this PR is ready for review now. Thanks in advance.

[rhansen]

I'm having trouble parsing the proposed syntax. Can you express it in ABNF?

Also, see my comment in #1504.

[pini-gh]

@rhansen:

I'm having trouble parsing the proposed syntax. Can you express it in ABNF?

This is EBNF but for the leaf items <virtual_port>, <virtual_path>, and <virtual_dest> which accept the same values as the legacy VIRTUAL_PORT, VIRTUAL_PATH, and VIRTUAL_DEST variables.

Here is how I would put it in ABNF:

VIRTUAL_PORT = [<virtual_port> / <multiport>]
multiport    = port *("," port)
port         = <virtual_port> [":" <virtual_path> [":" <virtual_dest>]]

[rhansen]

Apologies, I somehow misread the colon separator as a comma which confused me greatly. I understand now.

[pini-gh]

Rebased on 'main'.

[buchdag]

@pini-gh I like this. I'll try to review it this week-end. Do you remember (of the top of your head, I'll search myself later) issues that would be solved by this PR or other PR that implements the same feature ?

[pini-gh]

@buchdag Thanks

Browsing the issues I've found these ones : #560, #911, #939, #1042, #1066, #1112, #1382, #1463, #1504, #2050.
Please double-check; I may have misinterpreted some of them.

Some of them ask explicitly for accessing the same container through different vhosts / vports. I think this PR is relevant for them as well because it brings a different solution for the very same problem: one container exposing several ports.

EDIT: I forgot to answer about other PRs. Here they are: #259, #1405. And I know @rhansen is working on something similar. See his comments in #1504.

[VincentSC]

What is the status for this? Any help needed?

[rhansen]

What is the status for this? Any help needed?

@VincentSC See the discussion in #1504. Two things need to happen: the dust needs to settle on the desired syntax, and the code needs infrastructure changes to support whatever syntax we end up with. I've been slowly chipping away at the prerequisite code changes in separate pull requests.

[ironrai]

Is there hope that this will be resumed in the near future? I need it a lot

[pini-gh]

Is there hope that this will be resumed in the near future? I need it a lot

You can use image pinidh/nginx-proxy:1.3.1-pini2.

[buchdag]

Superseded by #2434

[pini-gh]

Closing this PR now that #2434 is merged.