Best Practices from Oracle Development's A‑Team

Setup Oracle API Gateway on OCI-Classic in Oracle Public Cloud

Gaurav Gupta
Principal Solutions Architect (A-team)

This blog provides steps to get Oracle API Gateway up and running on Oracle cloud- OCI Classic VM

We will see following steps:
1. Create compute instance on Oracle Cloud Infrastructure Classic (OCI-classic)
2. Create Logical gateway in API management console and Assign grants to add nodes
3. Connect OCI-classic instance using SSH and copy setup files
4. Configure user, Entropy value on Linux OS
5. API Physical Gateway setup (gateway node setup)
6. Security rules changes in OCI-classic
7. Test API deployment


1. Oracle API Platform 18.1.3+ instance provisioned
2. api-manager-user and api-runtime-user created and assigned to relevant groups in API Platform WebLogic realm
3. You have admin credentials on API management console
4. Basic knowledge of Linux & Oracle API Platform

Let's begin. . .

1. Create compute instance on Oracle Cloud Infrastructure Classic (OCI-classic)

In this step we will provision a compute instance (VM) with Oracle Linux and associate network, storage, OCPU. Later We will install physical gateway on this VM.
- Login to OPC, go to services->compute classic. You will see list of all compute instances

- Click on “Create Instance” button to create a new instance. It will show list of available images. Click on “Show All Images” to look for image of your choice. (You can check supported OS on this link - https://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/system-requirements-premise-gateway-installation.html#GUID-45E866FB-A8E3-4DF3-A031-21ADBADC674D. Here I have selected OL 6.7 from the list. Select image and click on Next button.

- Select shape based on your workload. Here I have selected General purpose single OCPU shape as shown below.

- Select shape and click next. It will give option to name your instance. And provide SSH key. You can generate new key or use existing SSH public key. Later we will need SSH key to connect compute instance.

- Click next. You will get option for network and security configuration as shown below

- Select persistent public IP Reservation. To create persistent public IP click on Create IP Reservation button. (If public IP is not selected as persistent it may change if VM is shut down & started again).

- Once PublicIP configured it will look like shown below. We will configure security rules later. You can configure vNIC interface if you want to configure & access API gateway over VPN from your on-prem datacenter.

- Click next. You will need to attach storage to the compute. You can create new volume or use existing volume if already available

- I will create new Volume. So click on “Add new Volume” button and provide storage information. Gateway needs minimum 30 GB disk space available before installation. I have assigned 120 GB and configured volume as “boot drive”.

- Add storage. And click on next. Review summary.

- If everything is correct click “create” button. Wait for few minutes and check Instances tab. You should see a new instance added in the list, with status as “Running”.

Our instance is ready for API Gateway installation. We will need Public IP while configuring gateway

2. Create Logical gateway in API management console and Assign grants to add nodes

A Logical Gateway (a Gateway in the Management Portal) comprises multiple physical gateways registered with it. Once logical gateway created, we can download installer (of physical gateway) and get access to wizard to generate 'gateway-props.json', file used during the installation.

- Login to API management portal and go to gateways tab.

- Click on Create Gateway. Provide gateway name & description. Once created you will get to see a new logical gateway in list.

- Click on gateway you just created. And goto nodes as shown below.

- Currently no node is attached to this logical gateway. We need to download setup file. Click on “Download Gateway Installer” button. It will download zip file “ApicsGatewayInstaller.zip”.

- We need to provide gateway configuration information in a file called “gateway-props.json”. to generate this file click on another button “Open Installation Wizard”. It will start wizard where we need to fill-in value for various parameters. At the end we will get to download gatewa-props.json. Later we will copy this file into gateway installation directory.

(1) keep the defaults (it will show Logical gateway ID & management service URL)

(2) Provide following detail:
(2.1) Gateway node name & description
(2.2) Listen IP address: This is HOST name of of your compute instance. Do not provide privateIP here. As privateIP may change on vm reboot, and gateway will fail to start. You can provide any value for now. Once we access VM we can get hostname and update this parameter.
(2.3) Publish IP address: This is public IP address of your compute instance.
(2.4) Management Service connection Proxy: this property is required at runtime if the gateway node needs a proxy to connect to the management service, as defined in the managementServiceUrl property
(2.5) Gateway node proxy: this property is required at runtime if the gateway node needs a proxy to pass client requests to backend services
(2.6) Installation directory: /u01/gateway (gateway will be installed in this directory on compute instance)
(2.7) Installation Archive location: /u01/gw_archive

(3) Optional additional configuration: keep default and click next.
(4) Download file and click on done.

- We also need to assign grants to respective users/groups to allow node registration. Because we will use these users while installing gateway. Here I will use 3 users : weblogic (administrator), gateway-manager-user, gateway-runtime-user. So click on grants tab of your gateway

- You will see 5 tabs under Grants. We have to click each tab and add grantee.
(1) You can add grant for ‘weblogic’ user in all tabs.
(2) Grant ‘gateway-manager-user’ in first 3 tabs.
(3) In ‘Request deployment to gateway’ tab you should add API Managers users/group. This is for users with API manager role. Which you can create later. For now I have granted only weblogic user in this tab.
(4) And in last tab ‘Node Service account’ grant user ‘gateway-runtime-user’.

3. Connect OCI-classic instance using SSH and copy setup files

- Lets connect to compute instance we had created. You can use tool like putty or SSH from your linux machine.
- While creating compute instance we had used SSH public key. We will use respective private key to connect remote host.
- (To connect on SSH copy private key file in a directory. Go to that directory from linux terminal and use command ssh -i privateKey opc@publicIP).
- To connect using putty, Open new session in putty. Provide public ip address, connection type SSH. Let the default port be 22. (don’t press connect/open yet. We need to first provide SSH key)

- To configure SSH key, Click on SSH->Auth option and browser your private key. (Putty needs file in .ppk format for private key. You should be able to generate ppk file for your private key)

- Click on “Open” button to start the session. You will see following popup. Click on “Yes”.

- You should see terminal asking “login as :”. Provide value opc.

- You will get terminal access on successful login. Before proceeding further please copy “ApicsGatewayInstaller.zip” & “gateway-props.json” in compute node. I have copied installer in /home/opc. You will also need to download JDK (JDK 8 preferably),copy and install. Check supported JDK versions in URL shared earlier.

- Switch to root user with command: sudo su -
- Install JDK.
- Unzip ApicsGatewayInstaller.zip into /u01/ apigateway-installer directory.
- Inside installer directory apigateway-installer open file gateway-props.json. replace content of this file with the one we had created & downloaded using wizard. This is how my gateway-props.json looks like as shown below. If you want to change any parameter it can directly be changed in this file. I have updated listenIpAddress to the hostname of my VM. (Use command hostname to check the host name of your instance)

4. Configure user, Entropy value on Linux OS

- Check Entropy value of your OS. If it is low, API Gateway installer will stuck in later stage. (Most cloud platform could have entropy issue) entropy is the randomness needed by OS/application for use in cryptography or other uses that require random data. A lack of entropy can have a negative impact on performance and security (Source entropy_wiki)
(1) Check Entropy with command - cat /proc/sys/kernel/random/entropy_avail. If it is less than 1000, use following commands to increase it.
(1.1) yum install rng-tools
(1.2) rngd -r /dev/urandom -o /dev/random
(1.3) Now check entropy again. You should get higher value
NOTE:: Sometime you may not have access (or do not want) to download rng-tools, as it needs root permission. In that case you can set following JVM config before starting configure:
export CONFIG_JVM_ARGS=-Djava.security.egd=file:/dev/urandom

- Create user oracle using command: useradd oracle
- Switch to user oracle: sudo su - oracle

- make sure 'oracle' user has permissions to access and execute scripts inside apigateway-installer directory. (Because in previous steps we created this directory as root user and unzipped installer in it.)
- Set JAVA_HOME and PATH variables. Below is how my PATH and JAVA_HOME looks like.

5. API Physical Gateway setup

- We are ready to install physical gateway on the compute instance. After installation we will also associate physical gateway (gateway node) with the logical gateway created earlier in step-2
- Switch to user oracle if not already.
- Go inside directory /u01/apigateway-installer
- We need to run command “./APIGateway -f gateway-props.json -a install-configure-start-join” but we will run these commands one by one in sequence. This generally helps in troubleshooting if we get stuck at any particular step.

- Run first command: ./APIGateway -f gateway-props.json -a install.
(1) It will ask for credentials you want to set for weblogic server to be installed on node. I have used gwweblogic/welcome1. (Note:- Please don’t use $ sign in password. There seems some parsing issue with WLST for $ sign). On successful completion of this command you will see directory /u01/gateway got created.

- Run 2nd command: ./APIGateway -f gateway-props.json -a configure to create WebLogic domain for gateway. (Note- you can tail to /u01/gateway/logs/ gatewayInstall.log to check log during this stage).

- Run 3rd command: ./APIGateway -f gateway-props.json -a start to start gateway managed servers. . (Note- you can tail to /u01/gateway/logs/gatewayDomainCreation.log to check log during this stage).

- Run last command: ./APIGateway -f gateway-props.json -a join. This will register gateway node in logical gateway we had created earlier. It will ask for gateway manager & runtime user credentials. Provide same users we had assigned grant in logical gateway tab.

- Gateway installation is complete. Go to API management console -> gateway -> Nodes tab to approve node. Currently node is under “Requesting” tab. Once node is approved you will see it under ‘Active’ tab.
Note: When a new node (physical gateway) is registered, default polling interval is 2 mins. But sometimes first poll may take little more time as gateway does various activities like registration/synch-up/uprade with internal components & management tier. so please wait couple of minutes for polling or deployments to reflect. A popular practice is setting interval to 5 seconds to make sure changes are indeed being deployed correctly. Once proved that the polling is working, you can increase the value back to 2 mins. ( How to change polling interval )

- Define Loadbalancer info as well. Here to keep this blog simple we haven’t used any LB. so provide Gateway node public IP & port in Settings->Loadbalancer URL.

6. Security rules changes in OCI-classic

- Gateway setup is complete. But to access API on gateway URL we need to open ports 8011 and 9022 on compute node.
NOTE: It is not recommended to make gateway ports accessible on public Internet. In real implementation You should alway route request to API gateway through load balancer. In this blog load balancer is not used just to keep focus on gateway setup.
- Go back to the OCI – Compute Classic console. And click on “Network” tab

- Goto “Security Application” and click on “Create Security Application” button. Provide port 8011 detail and click on “Create” button. Similarly do for 9022 port

- You will get to see security application created

- Now got to “Security Lists” tab and click on “Create Security List” to create security list.

- Once created it will appear in list

- Now goto “Security Rules” tab, click on “Create security rule” button. Associate Security application & List we created for port 8011, with the rule. As shown below. It also says source of API request can be from public internet. If you are expecting specific IP addresses that can also be mentioned. Do this for port 9022 as well

- Final step is to bind security policy with our compute node. Go to instances -> your GW compute -> click on “Add to Security List” button -> associate “apigw_seclist”. (Don’t remove ‘default’ security list). So finally this is how it will look like:

- Our gateway is ready to accept requests

7. Test API deployment

- Get a REST service that you want to expose as API on Oracle API platform and deploy on gateway. (You can create mock service in Apiary or look for a simple REST service from Internet) . Login to API management console -> Go to API tab

- Click on Create API and create a TestAPI.

- In API Request policy, Provide API URI that should be used to access API

- Provide backend service URL that is being exposed as API in Service Request.

- This is how API implementation looks like. Save the changes.

- Goto deployment tab and deploy API to the gateway. It may take few seconds to deploy API on gateway.

- API deployment is successful on OCI-classic compute node.
- Go to your browser and invoke API on URL https://{publicIP}:9022/testapi

Join the discussion

Comments ( 1 )
  • Stefan Wednesday, June 19, 2019
    There are a couple of errors in this walkthrough: In step 4 you don't set the Java_home and path, you just echo it.
    You create the directory ApicsGatewayInstaller and later use apigateway-installer as directory name.
    When you unzip ApicsGatewayInstaller.zip as user root, you cannot run the APIGateway commands as user oracle because the files are owned by root.
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha