Manage Gateways

Create, view, and edit Gateways

Overview

A Gateway represents the initial network entry point of application and/or API traffic into an NGINX instance in the traffic data path. You can share the same Gateway for both application and API traffic.

In a Gateway, you will define a group of ingress URIs and Certificates that can then be used by Application Components. Adding these definitions at the Gateway level means you don’t have to define the URIs and certificates for each individual Component. Instead, you can opt to inherit these settings from the Gateway, and only configure the relative path(s) for each Component. Alternatively, you can fully define the URI in the Component; doing so will override any settings defined for the Gateway.

Supported Component Types

Gateways support both HTTP/HTTPS (commonly referred to as “web”) components and TCP/UDP components.

There are settings in the Gateway, like web URIs, that apply only to web components. Likewise, there are settings in the Gateway that only apply to TCP/UDP components, like TCP/UDP URIs.

Gateways also have common settings – that is, neither web- nor TCP/UDP-specific – that can apply to either type of Component. Components of either type will inherit these settings unless they are overridden in the Component definition. Component settings can only inherit or override Gateway settings if they are of the same type or common. (In other words, a TCP/UDP Component’s settings won’t override or inherit a Web URI configured in the Gateway.)

TLS

For HTTPS URIs in a Gateway, you can add custom TLS Settings associated with a specific URI (and its associated hostname), or you can add Shared TLS Settings. Web components can also have their own custom TLS Settings and Shared TLS Settings.

Web Components that do not have any custom TLS Settings or shared TLS settings can inherit either the custom TLS Settings or the shared TLS Settings from the Gateway.

For TCP/UDP URIs in a Gateway, you can add custom TLS Settings associated with a specific URI (IP address and port range), or you can add Shared TLS Settings. TCP/UDP Components that do not have any custom TLS Settings or shared TLS Settings can inherit the custom TLS Settings or shared TLS Settings from the Gateway.

Web Components that do not have any custom TLS settings can inherit TLS settings from the following sources in this order:

  • Shared TLS settings for the Component
  • Custom TLS settings for the Gateway (the URI host and port for the Component and Gateway must match)
  • Shared TLS settings for the Gateway

TCP/UDP Components that do not have any custom TLS settings can inherit TLS settings from the following sources in this order:

  • Shared TLS settings for the Component
  • Custom TLS settings for the Gateway (the IP address in the Component URI must match or be contained in the IP address in the Gateway URI, and the port/port range in the Component URI must match or be contained in the port/port range in the GW URI)
  • Shared TLS settings for the Gateway

Examples

Let’s say we created a Gateway with an ingress URI definition that contains our application’s FQDN and the associated TLS Settings needed to secure traffic.

In the App Component’s ingress settings, we define a Web URI that uses a relative path. Together, the Gateway URI – “app.acme.com” – and the Component URIs – “/widgets” – form the absolute URI for our application: “app.acme.com/widgets”. The Component uses the cert configured at the Gateway level to secure traffic.

Object Name URIs TLS Setting
Gateway acme-app-gw https://app.acme.com acme-cert-1
(custom TLS setting for this URI)
Web Component acme-app-widgets /widgets acme-cert-1
(inherited from acme-app-gw)

Next, we will add some TCP/UDP settings.

In the Gateway, we add the TCP/UDP URI noted earlier: tcp+tls://192.168.1.5:100-104 and a custom TLS setting of acme-cert-2 for this URI. Then, we add a new TCP/UDP Component with the URI tcp+tls://192.168.1.5:100.

Object Name URIs TLS Setting
Gateway acme-app-gw https://app.acme.com,
tcp+tls://192.168.1.5:100-104
acme-cert-1
acme-cert-2
Web Component acme-app-widgets /widgets acme-cert-1
(inherited from acme-app-gw)
TCP/UDP Component acme-app-tcp-udp tcp+tls://192.168.1.5:100 acme-cert-2
(inherited from acme-app-gw)

In this configuration:

  • The Web Component will continue to inherit the Web URI and cert from the Gateway.
  • The TCP/UDP Component will inherit the TLS setting from the Gateway URI.
  • The TCP/UDP Component will not inherit the Web URI setting from the Gateway.

Placements

Gateways include placements that reference physical NGINX instances or instance groups (for example, an AWS cloud autoscale group).
Placements define the physical machines that are used to manifest a particular path associated with a Component.
When multiple placements are defined within a Gateway, each placement represents a resilient path for any Component that references that Gateway.

Before You Begin

Objectives

  • Create a Gateway
  • View, edit, and delete Gateways

Create a Gateway

To create a Gateway:

  1. Open the NGINX Controller user interface and log in.

  2. Select the NGINX Controller menu icon, then select Services > Gateways.

  3. Select Create Gateway.

  4. Complete each of the configuration sections:

  5. When ready, review the API Spec and then select Submit to create the Gateway.

General Configuration

On the Gateways > Create Gateway > Configuration page:

  1. Provide the name for your Gateway.
  2. (Optional) Provide a Display Name.
  3. (Optional) Provide a Description.
  4. (Optional) Add any desired tags.
  5. (Optional) Select the error response format.
  6. Select the Environment that will contain the Gateway resource.
  7. Select Next.

Placements

  1. In the Instance Refs box, select the NGINX instance(s) that you want to deploy the Gateway on.

  2. In the Listen IPs box, add the IP address(es) on which the server listens for and accepts requests.

    • To use non-local Listen IPs, you must enable net.ipv4.ip_nonlocal_bind on the instance.
    • When High Availability Mode is enabled, Virtual Router Redundancy Protocol (VRRP ) is configured for the Listen IP address(es).
  3. To enable high-availability mode for your data paths, select Use High Availability Mode.

Hostnames

On the Gateways > Create Gateway > Hostnames page:

  1. Specify the hostname of the gateway using the following URI format. Include the protocol and port (if non-standard):

    • http://<fqdn>
    • https//<fqdn>
    • http://<fqdn>:<port>
    • https://<fqdn>:<port>
    • tcp[+tls]://<fqdn>:<port>
    • udp://<fqdn>:<port>
  2. (Optional) In the Cert Reference list, select a certificate that you want the Gateway to reference or select Create New to add a certificate.

Methods

On the Gateways > Create Gateway > Methods page:

  1. (Optional) Select the HTTP method(s) to use in requests.

Advanced

On the Gateways > Create Gateway > Advanced page:

  1. (Optional) In the Receive Buffer Size box, set the buffer size to use for reading client requests. The default buffer size is 16k.
  2. (Optional) In the Send Buffer Size box, set the buffer size to use for reading a response from a disk. The default buffer size is 32k.
  3. (Optional) In the Client Max Body Size box, set the maximum size allowed for the client request body, specified in the Content-Length request header field. The default max body size is 1 MB.
  4. (Optional) Select the Allow Underscores in Headers toggle to allows the use of underscores in client request header fields. When set to disabled (the default setting), request headers with names that contain underscores are considered invalid and are ignored.
  5. (Optional) Select the Allow TCP Keep Alive toggle to configure the idle, interval, and count settings for keep alive probes.

View, edit, and delete Gateways

To view, edit, and delete Gateways:

  1. Open the NGINX Controller user interface and log in.

  2. Select the NGINX Controller menu icon, then select Services.

  3. On the Services menu, select Gateways.

  4. On the Gateways menu, select Overview. The Gateways Overview page is displayed and shows a list of your Gateways.

  5. To view the details for a Gateway, choose the Gateway from the list. This opens a side panel where you can view the Gateway’s linked Components, Certs, and Placements.

  6. To edit a Gateway, choose the Gateway from the list, then select Edit (pencil icon).

  7. To delete a Gateway, choose the Gateway from the list, then select Delete (trash icon).

    Note:
    If your Gateway has external references, such as Components that reference the Gateway, you’ll need to delete or reconfigure the external references before removing the Gateway. Refer to Manage Apps & Components to learn how to edit and delete Components.

Troubleshooting

Timeouts

Timeouts are commonly reported when an Instance doesn’t report back to NGINX Controller within 60 seconds. A timeout can occur if one or more Instances are under load or lose connectivity to NGINX Controller. If you experience timeouts when configuring a Gateway, check your network connection as well as the status of the Instance on which you’re deploying the Gateway.

What’s Next


This documentation applies to the following versions of NGINX Controller Documentation: 3.0, 3.1, 3.2, 3.3, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9, 3.10, 3.12, 3.13, 3.14, 3.15, 3.16.1, 3.17 and 3.18.