Container Service for Kubernetes:Basics of NGINX Ingress O&M

The following content describes the structure of the NGINX configuration file.

The following code shows a sample nginx.conf file, including some common directives and directive blocks:

# the number of worker processes to use
worker_processes 4;

# include additional configuration files
include /etc/nginx/conf.d/*.conf;

http {
  # HTTP server settings
  server {
    # listen on port 80
    listen 80;

    # server name
    server_name www.example.com;

    # default location
    location / {
      # root directory
      root /var/www/html;

      # index file
      index index.html;
    }
  }
}

In this example:

• worker_processes: a directive that specifies the number of worker processes to be used by NGINX.

• include: a directive that specifies other configuration files to include.

• server: a block that configures the settings of a specific server.

• location: a block that configures the settings of the default location, which is the root URL of the NGINX server.

For more information, see NGINX official documentation.

The following sections describe the most critical parts of the NGINX configuration file.

Directive blocks

HTTP block

The HTTP block configures the global parameters of the HTTP server. The parameters include the number of worker processes to run, maximum number of connections allowed, and log settings. The following code shows a sample HTTP block:

http {
    worker_processes 4;  
    worker_rlimit_nofile 8192; 
    client_max_body_size 128m; 

    access_log /var/log/nginx/access.log; 
    error_log /var/log/nginx/error.log; 

    server {
        ...
    }
}

In this example, the HTTP block specifies the number of worker processes, maximum number of file descriptors allowed, maximum body size allowed for client requests, and locations of the access log file and error log file. A Server block is nested under the HTTP block, specifying the configurations of a specific web server.

Server block

A Server block defines the processing rules of traffic requests for a specific domain name or a group of domain names. You can configure different settings and behaviors for multiple websites and applications hosted on the same server.

The following code shows a sample Server block:

server {
    listen 80;
    server_name www.example.com;

    location / {
        root /var/www/html/example;
        index index.html index.htm;
    }

    location /app {
        proxy_pass http://localhost:3000;
    }

    error_page 500 502 503 504 /50x.html;
    location = /50x.html {
        root /usr/share/nginx/html;
    }
}

In this example, the server processes only unencrypted traffic of the domain name www.example.com on port 80.

• listen specifies that the server listens for inbound connections on port 80.

• server_name specifies the domain name that the Server block processes.

• listen and server_name are used together to specify the domain name and port based on which the server listens for and processes traffic.

server_name

This directive specifies the domain name of a virtual host.

server_name name1 name2 name3

# example:
server_name www.example.com;

The following four matching modes are supported to specify a domain name:

• Exact match: server_name www.example.com

• Wildcard match (with a wildcard used to indicate the subdomain): server_name *.example.com

• Wildcard match (with a wildcard used to indicate the top-level domain): server_name www.example.*

• Regular expression match: server_name ~^www\.example\.*$

The four matching modes in the list are prioritized in descending order.

Location block

A Location block configures the request processing rules of the server for a specific URL path or URL pattern. You can define different behaviors based on different parts of a website or an application, such as providing static files for specific directories or proxying requests to another server.

The following code shows some sample Location blocks:

server {
    ...

    location / {
        root /var/www/html/example;
        index index.html index.htm;
    }

    location /app {
        proxy_pass http://localhost:3000;
    }

    error_page 500 502 503 504 /50x.html;
    location = /50x.html {
        root /usr/share/nginx/html;
    }
}

In this example:

• The / Location block specifies that requests to the root URL of the website are processed by providing files in the /var/www/html/example directory.

• The /app Location block specifies that requests to the /app URL are proxied to localhost on port 3000.

• The /50x.html Location block specifies how the server handles server errors by serving specific files.

When multiple Location blocks exist, requests are captured and processed by the Location block that is first matched based on the Location block matching rules and priority.

Syntax of matching rule concatenation:

• location [ = | ~ | ~* | ^~ ] uri { ... }

• location @name { ... }

The priority of the matching rules is in the following descending order: = > ^~ > ~ > ~* > No character used.

Example:

# Default general match. This matching rule applies to a request with no Location block hitting other matching rules.
location = / {
}
# Prefix match.
location ^~ /xx/ {
     # If a request prefixed with /xx/ is matched, the search is stopped. 
}
# Prefix match without a regular expression.
location  /uri {
}

location / {
     # Match all requests because all requests start with /. However, Location blocks defined by using regular expressions and those with longer prefix matches are prioritized to be matched. 
}

# Regular expression match.
location ~*.(gif|jpg|jpeg)$ {
     # Match any request that ends with gif, jpg, or jpeg. 
}

An NGINX Ingress sorts multiple Ingress paths of a host in descending order of length. For more information, see Ingress Path Matching and Understanding Nginx Server and Location Block Selection Algorithms.

Directive inheritance and override

In NGINX configuration, directives follow an inheritance mechanism from the outer to the inner contexts. An inner child context inherits configuration directives from its outer parent context. For example, the directives specified in the http{} context are inherited by all nested server{} and location{} contexts. Similarly, the directives specified in the server{} context are inherited by all nested location{} contexts. Take note that if a directive is specified in both a parent context and a child context, the configuration in the child context overrides, rather than combining with, that in the parent context.

Example:

http {
    add_header X-HTTP-LEVEL-HEADER 1;
    add_header X-ANOTHER-HTTP-LEVEL-HEADER 1;

    server {
        listen 8080;
        location / {
            return 200 "OK";
        } 
    }

    server {
        listen 8081;
        add_header X-SERVER-LEVEL-HEADER 1;

        location / {
            return 200 "OK";
        }

        location /test {
            add_header X-LOCATION-LEVEL-HEADER 1;
            return 200 "OK";
        }

        location /correct {
            add_header X-HTTP-LEVEL-HEADER 1;
            add_header X-ANOTHER-HTTP-LEVEL-HEADER 1;

            add_header X-SERVER-LEVEL-HEADER 1;
            add_header X-LOCATION-LEVEL-HEADER 1;
            return 200 "OK";
        } 
    }
}

Reverse proxy configurations of NGINX

proxy_pass

The reverse proxy configurations of NGINX allow NGINX to operate as a proxy server that listens for client requests and forwards them to one or more backend servers. This enables NGINX to receive and route requests to appropriate backend servers for processing. To configure NGINX as a reverse proxy, you can use the proxy_pass directive in a Location block in the NGINX configuration file.

Example:

server {
    listen 80;
    server_name www.example.com;

    location / {
        proxy_pass http://localhost:3000;
    }
}

In this example, the / Location block specifies that all requests to the domain name www.example.com are proxied to the local host on port 3000. This means that NGINX receives and forwards requests to the server that runs on port 3000 on the local host.

proxy_set_header

You can use the proxy_set_header directive to specify additional headers to add to the proxy request.

Example:

server {
    listen 80;
    server_name www.example.com;

    location / {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_pass http://localhost:3000;
    }
}

In this example, the proxy_set_header directive adds the Host and X-Real-IP headers to the proxy request, setting the hostname of the incoming request and the IP address to their respective values. These headers are useful for ensuring that the upstream server receives accurate information about the request.

Common NGINX directives

Common NGINX commands