Backend - nginx (be-gateway-nginx)
What files / which architecture is generated?
├── docker - Contains Dockerfile for the build │ ├── lua - Directory for custom Lua modules │ │ └── server-error.lua - Example of server error response module with Lua │ ├── Dockerfile - Definition of your nginx gateway container │ ├── entrypoint.sh - Enables runtime configurations and runs openresty │ └── nginx.conf - The nginx configuration ├── Jenkinsfile - Contains Jenkins build configuration ├── .pre-commit-config.yaml ├── metadata.yml - Component metadata └── release-manager.yml - Configuration file for the Release Manager
Usage - how do you start after you provisioned this quickstarter
Simply start to configure your nginx.conf to fit your needs. Also, you can develop and/or use different Lua modules.
Routing to your services
In order to route/proxy to services in the same namespace you do not need to define environment variables for their ports and/or hosts.
OpenShift already loads them into the container’s environment by following a convention like <DEPLOYMENT_CONFIG>_SERVICE_HOST and <DEPLOYMENT_CONFIG>_SERVICE_PORT. Please, follow the example provided and comments in the nginx.conf file.
Adding offical Lua modules
One can add official Lua modules by using opm.
In the following code snipped one can see how to add an official Lua module through docker build stage. Inside your Dockerfile:
RUN opm install zmartzone/lua-resty-openidcThen, one can load such module dependency in new modules like:
local http = require("resty.openidc")
lua-resty-openidc module is already provided with the default Dockerfile.
|
Using Lua modules
Lua integration in nginx requires following the Directives provided in its architecture. Notice the importance of the execution order of the directives. Most of the directives require being defined inside your server locations. See next some possibilities one can make use of
1 - Managing access with access_by_lua_block
With this directive one can integrate with Identity Providers via different auth/z standars, such as simple HTTP Basic Auth, OAuth, OIDC:
access_by_lua_block {
require("your-auth-module").authenticate()
}2 - Managing content with content_by_lua_block
This directive handles content definition. See the provided server-error.lua module example; by loading the right ENV variables in nginx.conf, you can add in your error location block a custom server error handling:
location = /50x.html {
content_by_lua_block {
require("server-error").make_error()
}
}3 - Handle incoming requests with rewrite_by_lua_block
One can also make use of the rewrite directive, for example, for filtering/rewriting incoming requests coming from your clients:
rewrite_by_lua_block {
require("filter-requests-headers").run_filter()
}4 - Handle body responses with body_filter_by_lua_block
Filter the body responses comming from your Backend services. For example, one could filter any error response, so to assure filtering stack traces from a JSON object response when running on production:
body_filter_by_lua_block {
require("filter-error-response").filter_stack_traces()
}Metadata
The following are typical metadata values that can be used for components based on this quickstarter: Note that the OpenShift resources will be labeled based on this metadata.
name: nginx
description: "Enhanced nginx with Lua embeded. nginx [engine x] is an HTTP and reverse proxy server, a mail proxy server, and a generic TCP/UDP proxy server. Technologies: OpenResty/nginx 1.25.3.2-0"
supplier: https://openresty.org
version: 1.25.3.2-0
type: ods-service
role: integrationHow this quickstarter is built through Jenkins
There are two steps:
-
Build the container image.
-
Deploy.
include::partials$secret-scanning-with-gitleaks.adoc
Builder agent used
This quickstarter uses jenkins-agent-base