Configure Reverse Proxy with NGINX to Access Oracle GoldenGate Microservices
Learn how to configure reverse proxy service using NGINX for accessing Oracle GoldenGate Microservices without using port numbers.
Reverse proxy enables accessing microservices using one single port (443) in a deployment. This enables encapsulation of the URL for microservices over an unsecure deployment.
Note:
Reverse proxy is optional, however, Oracle recommends that you ensure easy access to microservices and provide enhanced security.You can run microservices in an unsecure deployment on loopback address and front it with an HTTP reverse proxy using the NGINX installation.
When sending trail files from Oracle GoldenGate Classic to Microservices
environment that is configured with a reverse proxy, use a pump Extract from Oracle GoldenGate
Classic with SOCKSPROXY
option. When sending trail files from Oracle
GoldenGate Microservices to Classic Architecture use the ogg
protocol in the
Distribution Service configuration.
See Connecting Classic to MA and Connecting MA to Classic in Administering Oracle GoldenGate.
You can configure Oracle GoldenGate
Microservices Architecture to use a reverse proxy. Oracle GoldenGate
MA includes a script called ReverseProxySettings
that generates configuration file for only the NGINX reverse proxy server.
For example, the Administration Service is available on
http://goldengate.example.com:9001
and the Distribution Service is on
http://goldengate.example.com:9002
. With reverse proxy, each of the
microservices can simply be accessed from the single address. For example,
http://goldengate.example.com/distsrvr
for the Distribution Service.
The URL is different for each service and is by name instead of by port.
You can use these options by running the ReverseProxySettings
utility. Here are the options available with this utility:
-
-o
or--output
-
The output file name. The default file name is
ogg.conf
. -
-P
or--password
-
A password for a Service Manager account.
-
-l
or--log
-
Log file name and initiates logging. The default is no logging.
-
--trailOnly
-
Configure only for inbound trail data.
-
-t
or--type
-
The proxy server type. The default is Nginx.
-
-s
or--no-ssl
-
Configure without SSL.
-
-h
or--host
-
The virtual host name for reverse proxy.
-
-p
or--port
-
The reverse proxy port number. The defaults are 80 or 443.
-
-?
or--help
-
Display usage information.
-
-u
or--user
-
Name of the Service Manager account to use.
-
-v
or--version
-
Displays the version.
These values are used when connecting to the Service Manager and are required when authentication is enabled.
Topics:
Prerequisites for Using ReverseProxySettings
You can use any reverse proxy service with MA. The following example provides a process that you can follow to configure other reverse proxy services in conjunction with the documentation for your proxy server.
The following prerequisites provide details on the minimum requirements to configure an NGINX Reverse Proxy. Similar requirements may be required for your environment and reverse proxy, if you are using a different utility for proxy configuration.
-
Install NGINX, see Install the NGINX Web Server and Proxy on Oracle Linux. For Oracle Linux, the command to install NGINX is:
yum -y install nginx
-
Check the JRE version to be JRE 8 or higher.
-
Install Oracle GoldenGate MA.
-
Create one or more active MA deployments.
-
Ensure that the Oracle user has
sudo
permissions. -
Configure the
PATH
environment variable to include the NGINX installation directory path.
Configure Reverse Proxy with NGINX on Linux
An Oracle GoldenGate MA installation includes the
ReverseProxySettings
utility. The ReverseProxySettings
utility is located in the $OGG_HOME/lib/utl/reverseproxy
directory.
To identify additional commands that can be used with the
ReverseProxySettings
utility, run the utility with the
--help
option:
$OGG_HOME/lib/utl/reverseproxy/ReverseProxySettings --help
To add the NGINX certificate to the Distribution Service’s client wallet as a trusted certificate, see Set Up Trusted Certificates.
-
To generate a configuration file for NGINX reverse proxy, navigate to the location of the
ReverseProxySettings
utility:cd $OGG_HOME/lib/utl/reverseproxy
-
Run the ReverseProxySetting utility:
ReverseProxySettings -u adminuser -P adminpwd -o ogg.conf http://localhost:9100
In this code snippet,
adminuser
is the deployment user name andadminpwd
is the deployment user password used to login to the deployment. -
Replace the existing NGINX configuration with the configuration that was generated using the
ReverseProxySetting
utility for your MA deployment:sudo mv ogg.conf /etc/nginx/conf.d/nginx.conf
However, this NGINX configuration isn't complete without the
events
section, and enclosing themap
andserver
sections inhttp
.Optionally, you can use the default
nginx.conf
file and add the generatedogg.conf
by adding aninclude
statement similar to this:include /etc/nginx/conf.d/ogg.conf;
In this case, you must comment out the other
servers
section. -
Generate a self-signed certificate for NGINX:
sudo sh /etc/ssl/certs/make-dummy-cert /etc/nginx/ogg.pem
For distribution paths to go through the reverse proxy, you need to use a valid certificate. It's better to specify the same certificate that the deployment is using to process incoming requests, otherwise, starting the path will fail with the next error in Distribution Service:
2019-03-26T11:26:00.324-0700 ERROR| ERROR OGG-10351 Oracle GoldenGate Distribution Service for Oracle: Generic error -1 noticed. Error description - Certificate validation error: Unacceptable certificate from test00abc: application verification failure. (A4)
-
Validate the NGINX configuration:
sudo nginx -t
The output would show the following, if the command is successful:NGINX: the configuration file /etc/NGINX/NGINX.conf syntax is ok NGINX: configuration file /etc/NGINX/NGINX.conf test is successful
-
Reload NGINX with the new configuration:
sudo nginx -s reload
If the changes for the configuration file are not loaded, stop and restart the proxy.
-
To test if you can access the microservices after NGINX is set up successfully, open the web browser.
-
Enter the proxy URL for the Service Manager using port number 443, similar to the following:
http://dc.example.com:443
This would open the Service Manager login page, from where you can access the other microservices also. If you want to directly access a microservice, you can enter the proxy URL for that microservice, as given in the
ogg.conf
file, generated previously.
Also see this video on configuring the NGINX reverse proxy.
SSL Termination
When there is an unsecure connection between the reverse proxy, which uses a TLS-based connection, and the origin server, it is referred to as reverse proxy SSL-termination.
Note:
In SSL-Termination the connections between the reverse proxy and the origin servers are unsecure.
However, SSL-bridging is also supported where the connections between the client and reverse proxy is secured and the connection between the reverse proxy and the origin server is also secured.