PaaS - How to install Oracle API Gateway and register with Oracle API Platform Cloud Service (Part 2)

In a previous post, I covered the steps to create an Oracle API Platform Cloud Service instance: PaaS - How to setup Oracle API Platform Cloud Service (Part 1).

To continue with the Oracle API Platform setup, an API Gateway node must be installed and registered with the Oracle API Platform Cloud instance. The API Gateway node can be installed on-premise or on any other vendor cloud instance.

In this post (Part 2), I will cover the steps involved with installing and registering the API Gateway. The Gateway installation can be downloaded from the API Management Portal or by using wget.

I will be installing the API Gateway on an Oracle Linux Virtual Machine instance (version 6.4) on my local machine. This will be the equivalent of installing the API Gateway on-premise. Finally, I will show the API Gateway registered with the Oracle API Platform instance already running in Oracle Cloud.

Oracle Documentation for installing the API Gateway can also be found here.

1. Download the API Gateway installer from the API Management Portal via the Oracle API Platform Cloud Service you have set up (URL https://API_PLATFORM_IP:PORT/apiplatform/gateways):

The API Gateway can also be downloaded using wget:

wget --keep-session-cookies --save-cookies cookies.txt --post-data='j_username=API_USERNAME&j_password=API_USER_PASSWORD' --no-check-certificate https://API_PLATFORM_IP/apiplatform/public/j_security_check

wget --load-cookies cookies.txt --no-check-certificate https://API_PLATFORM_IP/apiplatform/downloads/ApicsGatewayInstaller.zip

2. The downloaded archive 'ApicsGatewayInstaller.zip' contains installation and configuration files. The archive is just over 1GB:

3. My installation of the API Gateway will mimic an On-Premise installation, therefore the System Requirements from the Oracle Documentation is as follows:

Operating Systems

Oracle Linux and Red Hat Enterprise Linux 7.2, 6.7, and 6.4.

Microsoft Windows 10 supported for development and testing only

Microsoft Windows Server 2016 supported for production

CPU

Dual core, 2 GHz or more per CPU

Disk Space

30 GB

Memory

6 GB

JDK version

Oracle-Certified Java SE JDK 8. OpenJDK is not supported.

Python version (With OpenSLL Support)

2.7.10+

Note: This is required only for Windows installs. If installing on Linux, the version of Python bundled with the installer is used.

Open SSL version

1.0.0+

Note: This is required only for Windows installs. If installing on Linux, the version of Open SSL bundled with the installer is used.

4. The machine for the API Gateway to be installed on is a pre-built Oracle Linux 6.4 Virtual Machine. 

Initially, I built an Oracle Linux 7.2 Virtual Machine from scratch but my API Gateway installation faced installation issues, most likely due to missing configuration of the VM itself, I needed to spend more time setting it up. In the end, to save time and continue with the progress, I decided to use a pre-built Oracle VM (containing Oracle Fusion Middleware components such as WebLogic, WebCenter Portal etc - Oracle WebCenter Portal 12.2.1 - Virtual Machine. List of pre-built VM's here).

The 6.4 version of the VM satisfied the minimum OS requirement. The VM was loaded into VirtualBox and ready to be used as an environment for the API Gateway to be installed on:

5. Boot up the VM and copy/migrate ApicsGatewayInstaller.zip to a local folder:

6. Before progressing with the installation, we need to satisfy other minimum requirements:

• Oracle JDK 8+

• Python 2.7.10+ (with OpenSSL support)

7. The VM I am using comes with OpenJDK by default, this needs to be replaced with Oracle JDK. Follow one of my previous blogposts if you are in this situation OR do what you got to do to satisfy the Oracle JDK 8+ requirement. I installed Oracle JDK 8 update 77:

8. Check what version of Python you have (if installed) 'python --version'. 

We want to ensure 2.7.10 is installed. The Oracle VM's and Linux Machines will most likely be installed with Python 2.6 - This is used by the operating system and tools such as yum. DO NOT uninstall the existing Python as it may result in the OS malfunctioning due to dependencies!

Follow the steps at How to Compile and Install Python with OpenSSL Support. Steps are clear and easy to follow. (The steps are based on installing Python 3.5.1, but replace with 2.7.10 instead).

9. After the install, to run Python 2.7.10, it can be accessed from '/usr/local/bin/python2.7'. When we run commands for the API Gateway, we will run the with an absolute path Python from that directory to ensure the correct version of Python is utilised:

10. Change directory to where you copied ApicsGatewayInstaller.zip and unzip it:

11. Within the extracted files is the important json file that contains configuration properties used by the API Gateway installation - 'gateway-props.son'. By default, it looks like:

12. We need to update the 'gateway-props.json' to match respective requirements such as the API Management Portal IP/Port etc. It is important that you get these properties correct, refer to the Oracle Documentation for an indepth explanation of each mandatory/optional property that can be entered.

My 'gateway-props.son' on my VM instance looks like the following:

{

   "gatewayInstallDir" : "/u01/app/oracle/gateway/run",
   "installationArchiveLocation" : "/u01/app/oracle/gateway-installer/archived-install/archive1",
   "prevInstallCleanupAction" : "clean",
   "gatewayNodeName"   : "OS-GatewaynNode1",
   "managementServerHost"    : "https://144.21.72.78",
   "managementServerPort"    : "443",
   "nonProxyHosts"           : "localhost",
   "listenIpAddress"         : "10.0.2.15",
   "publishAddress"      :  "10.0.2.15",
   "gatewayExecutionMode": "Development",
   "gatewayNodeDescription" : "wcp12cr2",
   "gatewayDomainName" : "gateway1",
   "logicalGateway" : "OS-LogicalGateway1",
   "opatchesFolder" : "/u01/app/oracle/gateway-patches",
   "gatewayMServerPort" : "8000",
   "gatewayMServerSSLPort" : "8443"
}

13. Oracle Documentation guides the installation in a way for multiple commands to be run at once resulting in the Gateway installed all the way up to joining the API Platform in one command: 'install-configure-start-creategateway-join'. 

We do NOT want to run all commands at once, we will run these commands separately and verify at each step. This ensures that if there are any errors, we know at exactly what command there was a problem. A total of 5 steps will be run in the following order:

• install - Installs API Gateway binaries.

• configure - Configures the API Gateway Weblogic domain.

• start - Starts the API Gateway Admin server, Managed server and a lightweight Java DB.

• creategateway - Connects to the Management Portal and creates a Logical Gateway. A unique Gateway ID is returned and will be used in the join step.

• join - Requests for the API Gateway Node to join the Logical Gateway. This requires approval from an API Gateway Manager user on the Management Portal to allow successful pairing.

14. Set JAVA Home: Before running the commands, ensure the JAVA_HOME is set:

$ export JAVA_HOME=/usr/java/jdk1.8.0_77/

15. Set Low Entropy (Non Prod environments): Ensure low entropy is set (see Useful Notes at the end of the post for more information):

$ export CONFIG_JVM_ARGS=-Djava.security.egd=file:/dev/./urandom

Note: The above command should not be run on Production environments. If the low entropy issue occurs on Production, then involve the OS administrators!

16. Before running the next command, ensure the root folder /u01 is initially created and make sure your user has atleast RW permissions to it, else you will face Permission Denied errors.

17. install: Run the following command: 

$ /usr/local/bin/python2.7 APIGateway.py -f gateway-props.json -a install

Note: Running the install command will ask you for a weblogic username and password. This step creates the admin user and is granted weblogic rights. Keep a note of the credentials, going forward with other commands, you must enter the same credentials else changes will not be possible:

18. configure: Run the following command:

$ /usr/local/bin/python2.7 APIGateway.py -f gateway-props.json -a configure

Enter the weblogic credentials when prompted:

19. start: Run the following command:

$ /usr/local/bin/python2.7 APIGateway.py -f gateway-props.json -a start

Enter the weblogic credentials when prompted and wait for the servers to start. I initially encountered the low entropy issue which caused the servers to take forever booting up. I found that the request to start the servers automatically ends after about 10 minutes or so, if they still have not started:

20.1 Confirm that the servers have successfully started by accessing WebLogic Console and logging in with the credentials created during the install step:

http://listenerIPAddress:8001/console

20.2 Take a look at the Managed servers that have been created (An Admin server and a Gateway Node server):

20.3 Click on the Gateway Node managedServer1 and see the Listen Address, Listen Port and SSL Listen Port. They match the properties from the gateway-props.json used to configure the Gateway:

21. creategateway: Run the following command:

$ /usr/local/bin/python2.7 APIGateway.py -f gateway-props.json -a creategateway

Enter the weblogic credentils when prompted.

Enter the Gateway Manager user when prompted (set up in the API Management Portal - you can use the main user that was used to create the API Platform if needed).

Enter the Gateway Manager Runtime user (same as above).

Note: For the simplicity of this blogpost, I am using the Administrator Weblogic user for all credentials. Ideally, we would have multiple users each assigned with the respective Gateway role. This can be managed through the Roles tab in the API Management Portal.

If the logical Gateway is created successfully, it will return a Gateway ID. Make a note of this ID (we can see the ID returned is 101):

22. To verify the logical Gateway is created, log into the API Management Portal, click Gateways and check the newly created Gateway and also compare it's ID:

23. Before joining the logical Gateway, the 'gateway-props.json' must be updated with the gatewayId property:

24. join: Run the following command:  

$ /usr/local/bin/python2.7 APIGateway.py -f gateway-props.json -a joingateway

Enter the weblogic credentils when prompted.

Enter the Gateway Manager user when prompted (set up in the API Management Portal - you can use the main user that was used to create the API Platform if needed).

Enter the Gateway Manager Runtime user (same as above).

If successful, one of the last messages will be 'Join request sent, please login to the APICS portal as gateway manager to approve the request':

25. Log back into the API Management Portal, click Gateways, click the Nodes icon, click the Requesting tab and we should see our Gateway Node trying to join:

26. Hover over the Gateway Node name and Approve, Reject, Dismiss options should appear on the right:

27. Click Approve and a description for your action (useful if you are Rejecting the Join request):

28. Now, we will see the Gateway Node under the Active tab:

29. One final look to check our API Gateway Node status and confirm all is as expected:

That's it folks, well done! The fundamentals of the API Platform Cloud Service are complete. In Part 3, I will create and deploy a sample API Application and show the Platform working end to end.

Useful Things to know:

1. Logs: If you encounter failures or issues, inspect the Gateway logs that are created. These will contain more information than what is displayed in the terminal when configuring the Gateway.

2. Starting the servers taking too long: This can be due to there not being enough entropy (randomness) in the OS. This can be resolved with the following command:

$ export CONFIG_JVM_ARGS=-Djava.security.egd=file:/dev/./urandom

3. Domain Administrator validation: Initially, when I tried to install the gateway, it failed. After investigating the logs, my domain administrator username/password vailed validation checks. (I set the password as 'welcome1'). The validation checks are:

3. Polling: The API Gateway Node will poll the Logical Gateway on the cloud or 'phone home' every X minutes to update it self with the latest deployed API's, policies etc. This value can be modified on the API Management Portal - Gateway Node page. The interval value or interval type can be changed:

4. API Gateway Status - Make use of the status command to get a summary of the Statuses and other Useful information. I ran the status command before I created and joined the Logical Gateway:

5. Best practises & Lessons learnt: Luis Weir has posted a helpful presentation covering these aspects, view the presentation on Slide Share here.