Sunday, 27 May 2018

Oracle API Physical Gateway installation and register with Oracle API CS

In the previous blog, we have covered how to provision Oracle API Cloud Service instance: Creating an Oracle API Platform Cloud Service (CS) Instance 

To deploy the service on Oracle API CS instance, Oracle API physical gateway must be installed and should be registered with Oracle API Logical Gateway.

In this post, we'll cover the step by step process which will help to install Oracle API physical gateway.

Physical Gateway installation roadmap

Step-1 Virtual Machine Setup
Step-2 Create Logical Gateway in Oracle API CS
Step-3 Install Oracle jdk-8u171
Step-4 Installation of Oracle Physical Gateway
Step-5 Deploy Service on Physical Gateway

Let's go step by step

Step-1 Virtual Machine Setup

For this blog, we'll create the compute instance on Oracle Cloud Infrastructure (OCI)
Below is the requirement for physical gateway installation:

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

Dual core, 2 GHz or more per CPU
Disk Space
30 GB
4 GB
JDK Version
Oracle-Certified Java SE JDK 8+. OpenJDK is not supported
In one of the blow, we have showcased step by step procedure on how to provision compute instance on OCI. Please cover the blog before we move forward

Step-2 Create Logical Gateway in Oracle API CS instance

A Logical Gateway comprises multiple physical gateways registered with it. Once logical gateway created, physical gateway installer can be downloaded. To Create the Logical Gateway, we should have API CS instance provisioned. The blog shows, how to provision API CS instance.

Below are the steps to create Logical Gateway in API CS.
  • Login to API CS https://<API_CS_IP>/apiplatform/
  • Go to the Gateway tab

  • Click on Create button

  • Provide name, description and click Create button

  • Click on the Gateway, we just created

  • Click on the Nodes tab

  • Download the Physical Gateway installer by clicking the Download Gateway Installer button. It will download zip file “” file.
  • Create the gateway configuration file which will be used while installing the physical gateway. Click on the Open Installation Wizard button to create the configuration file.

  • The configuration wizard will get open. Click on the Next button

  • In the next screen, provide information as below and click Next butto
    • Gateway Node Name: Keep the default value
    • Gateway Node Description: Keep the default value
    • Listen IP Address: Provide hostname of the host machine where physical gateway will be installed
    • Publish Address: Provide IP address of the host machine where physical gateway will be installed
    • Management Service Connection Proxy: This property is required at runtime if the gateway node needs the proxy to connect to the management service
    • Gateway Node Proxy: This property is required at runtime if the gateway node needs the proxy to pass client requests to backend services
    • Node Installation Directory: Gateway installation directory for example (/home/gateway)
    • Installation Archive Location: Gateway installation archive directory for example (/home/gateway_archive)
  • In the next screen, keep the default values and click Next button
  • In the Next screen, click Download File button. Downloaded file name would be gateway-props.json. Save the file at some place as it would be required during physical gateway installation. Below is the structure of gateway-props.json file
    "logicalGatewayId" : "106",
    "managementServiceUrl" : "",
    "gatewayNodeName" : "APICSDevGateway Node 1",
    "gatewayNodeDescription" : "APICSDevGateway Node 1",
    "listenIpAddress" : "hostname",
    "publishAddress" : "",
    "nodeInstallDir" : "/home/gateway",
    "installationArchiveLocation" : "/home/gateway_archive",
    "gatewayExecutionMode" : "Development",
    "heapSizeGb" : "2",
    "maximumHeapSizeGb" : "4",
    "gatewayMServerPort" : "8011",
    "gatewayMServerSSLPort" : "9022",
    "nodeManagerPort" : "5556",
    "coherencePort" : "8088",
    "gatewayDBPort" : "1527",
    "gatewayAdminServerPort" : "8001",
    "gatewayAdminServerSSLPort" : "9021"
  • Create below two users from API CS weblogic console using http://<API_CS_IP>:7001/console and assing the respective group
  • Click the Assign tab of the created Gateway
  • There is five Grants tab. Assign the users as per below table. Use Add Grantee button to add users
Grant Tab
User / Group
Manage Gateway
View all details
Deploy to Gateway
Request Deployment to Gateway
API Managers users/group
Node service account

Step-3 Install Oracle jdk-8u171
  • Download Oracle jdk-8u171-linux-i586.tar.gz from Oracle Site
  • Log in to the VM which is created in Step-1 via SSH client like putty
  • Copy the jdk to /usr directoy
  • Extract Oracle jdk-8u171-linux-i586.tar.gz using blow command
    • tar -zxvf jdk-8u171-linux-i586.tar.gz
Step-4 Installation of Oracle Physical Gateway
  • Log in to the VM which is created in Step-1 via SSH client like putty
  • Create three folders into the /home directory
    • gateway
    • gateway_archive
    • GWinsalller
  • Copy the into GWinsalller directory
  • Go to /home/GWinsalller unzip the file
  • Notice that gateway-props.json under /home/GWinsalller directory
  • Replace the existing gateway-props.json file with the file which was downloaded in the Step-2
  • Set JAVA_HOME and PATH variables as below:
    • export JAVA_HOME=/usr/jdk1.8.0_171
    • export PATH=$PATH:$JAVA_HOME/bin
  • Go to the /home/GWinsalller directory
  • Run below command to install API Gateway binaries. It will ask for credentials you want to set for WebLogic Server to be installed on the node. We kept weblogic/Welcome1
    • ./APIGateway -f gateway-props.json -a install
  • Run below command to Configure the API Gateway Weblogic domain
    • ./APIGateway -f gateway-props.json -a configure

  • Run below command to Start the API Gateway Admin server, Managed server, and a lightweight Java DB
    • ./APIGateway -f gateway-props.json -a start

Note: Gateway startup logs are written in startWls.out, startMServer.out files which is under
/home/gateway/domain/gateway1 the directory
  • Run below command to Request 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. It will ask for gateway manager & runtime user credentials. Provide same users we had assigned grant in logical gateway tab
    • ./APIGateway -f gateway-props.json -a join
  • Gateway installation is complete now. Go to API management console -> Gateway -> Nodes tab to approve node. Currently, the node is under “Requesting” tab

  • Once approved, the node will be shown under "Active" tab
  • Port 8011 & 9022 port should be added to security list so that the API CS service can be accessed from public network too. Without the ports opened, API CS service would not be accessible from the open network.
NOTE: It is not recommended to make gateway ports accessible on the public Internet. In a real implementation, we should always route the request to API gateway through the load balancer.

Step-5 Deploy Service on Physical Gateway

To make this blog shorter, we wrote another blog which will show how to configure backend service in API CS and deploy on the physical gateway.

Note: Service logs are written in the apics.log log file under /home/gateway/domain/gateway1/apics/logs directory

Sunday, 13 May 2018

Create an Oracle Linux instance on Oracle Cloud Infrastructure Compute Classic (OCI)

This blog will help us to create an Oracle Linux in Compute Classic. In this article, we'll create an instance from an Oracle provided Oracle Linux image and boot the instance from a persistent disk.

To complete this blog, we must have the subscription to Compute Classic.

Let's begin and create an Oracle Linux instance.

  • Log in to Oracle Cloud my service application at Upon successful login, my services page would be displayed
  • Click the menu from the upper left corner of the page and Select Compute Classic
  • Click Create Instance button
  • Click on Show All Images
  • On the Image page, select an image depending on the choice. For now, we are selecting  OL_6.7_UEKR4_x86_64 and click Next
  • On the Shape page, select an appropriate shape for the instance. The shape determines the number of CPUs and RAM that the instance will have. For the purpose of this tutorial, select oc3 (OCPUs: 1, Memory: 7.5 GB). Click the button to go to the next page

  • On the Instance page, select or enter the following, and then click the button to go to the next page
    • Persistent: Select true, if you want to persist the instance when the orchestration is suspended
    • Placement: Select the domain where the instance would be created. Let it be the default(Auto) for now
    • Name: Enter a unique name, or retain the default
    • Label: Enter a unique label to help identify the instance, or retain the default. The label is used to list the instance on the Instances page
    • Description(Optional): Enter a description, if required
    • Tags(Optional):  Specify a tag to help identify the instance
    • SSH Keys: Click this field or start typing to see a list of available SSH public keys. To add a new SSH public key:
      • Click Add SSH Public Key button
      • Enter a name for the SSH public key
      • Click Select File and navigate to the folder where the SSH public key is saved, or paste the public key in the Value field
      • Click Add

    • The SSH public key is added and appears in the list of SSH keys that we want to associate with the instance
    • Custom Attributes(Optional): This field allows us to customize the instance by providing additional information specific to each instance
  • On the Network page, enter or select the following. Once done, click the button to go to the next page
    • DNS Hostname Prefix: Enter a string that will be used as a prefix in the domain hostname for the instance.
    • Network Options: Select whether you want to configure an interface on the shared network or one or more interfaces on IP networks. Select both options.
    • IP Network Options
    • Click Configure Interface button. In the Configure IP Network Interface dialog box, select or enter the following and then click Save
      • Interface: Select the interface that you want to add to the specified IP network. We can select any interface from eth0 to eth7. After we select all the interfaces that we want to add to IP networks, the first available interface is assigned to the shared network. We can't add, delete, or modify interface allocations after an instance is created. Let's select eth0
      • vNIC Name: Retain the default vNIC name
      • IP Network: Specify the IP network that we want to add this interface to. When we add an instance to an IP network, the specified interface of the instance is assigned an IP address on the specified IP network. To create new IP Network Click Create IP Network and enter below details
        • Name:  Name for the IP network. 
        • IP address prefix: It should be in Classless inter-domain routing(CIDR) format. For example, enter
      • Static IP Address: We can specify a private IP address for this interface. The private IP address must be unused and it must belong to the subnet of the selected IP network. For this blog, leave the blank
      • Public IP Address: We can select an available public IP address for this interface. When the instance is created, we can configure security rules and access control lists for your IP network to enable access to this IP address over the public Internet. If we don't select an IP reservation now, we can associate a public IP address with this interface later by creating or updating an IP reservation. Let's leave this field blank for now
      • Cloud IP Address: We can select an available cloud IP reservation for this interface. When the instance is created, this IP address can be accessed by other Oracle Cloud services without being accessible over the public Internet. If we don't select a cloud IP address now, we can associate a cloud IP address with this interface later by creating or updating an IP reservation. Let's leave this field blank for now
      • MAC Address: Specify the MAC address if it required. Let's leave this field blank for now
      • Virtual NIC Sets: We can select the Virtual NIC (vNIC) sets to which to add this interface. Let's leave this field blank for now
      • DNS: We can specify DNS A record names for the instance. Let's leave this field blank for now
      • Name Servers: You can enter the name servers that are sent through DHCP as option 6. Let's leave this field blank for now
      • Search Domains: You can enter the search domains that should be sent through DHCP. Let's leave this field blank for now
      • Default Gateway: We can select this option if we want to use this interface as the default gateway
    • Shared Network Options
      • Public IP Address: To associate a permanent public IP address with the instance, select Persistent Public IP Reservation. If we select an Auto-Generated public IP address, the IP address persists while the instance is running, but will change every time on reboot. If we have already created an IP address reservation, select it from the list. Otherwise, create one using below steps:
        • Click Create IP Reservation button
        • In the Create Public IP Reservation dialog box, enter a name for the IP reservation and then click Create
        • The IP reservation will be created and selected
      • Security Lists: We can add the instance to one or more security lists. When we add an instance to a security list, we can control access to or from that instance by creating security rules that use the specified security list as a source or destination. For now, leave this field set to the "default" security list
  • On the Storage page, to use a persistent boot disk, accept the default settings and click the button to go to the next page.
If some extra storage is required to the instance, we can do the following:
    • We can attach the existing volume using Attach Existing Volume. 
    •  We can create new volume by clicking Add New Volume.  Click Add New Volume to create the new volume and do the following:
      • Name: Enter Name of the volume
      • Size: Enter the disk size in GB
      • Storage property: For storage volumes that require low latency and high IOPS, such as for storing database files, select storage/latency. For all other storage volumes, select storage/default
      • Attach as Disk: Accept the default disk number or enter a higher number. The disk number that specified determines the device name. The disk attached at index 1 is named /dev/xvdb, the disk at index 2 is /dev/xvdc, the disk at index 3 is /dev/xvdd, and so on
      • Boot Drive: Select this option to use the specified storage volume as the boot disk. When this option selected, the disk number is automatically set to 1
  • On the Review page, verify the information that we have entered if satisfied then click Create

Compute Classic instances are provisioned and managed using orchestrations. Provisioning an instance will take approximately 30 minutes.

Once created successfully, VM would be visible on the Compute Classic page

Friday, 11 May 2018

Creating an API in Oracle API Platform Cloud Service (API CS)

Oracle API Platform Cloud Service offers an easy way to manage, secure, and publish services for application developers. It facilitates the creation of APIs that expose the functionality of organization's back-end systems or other services.

In this article, we'll show how to create an API using existing backend service. We must have backend REST API endpoint up and running before beginning this article.

Let's assume our backend service is running on below endpoint:

We'll manage the above REST endpoint in API CS

Below are the steps to manage REST endpoint in API CS

  • Log in to Oracle API Portal Console using http://hostname:port/apiplatform

  • Click on Create API button
  • On the Create API page, enter the following values, and then click Create:
    • Name: Enter API name TestAPI
    • Version: Enter version as v1.0
  • Click on TestAPI
  • Click on API Implementation tab
  • In the API Request section, Click on Edit button

  • On the Edit Policy Page, enter API EndPoint URL. Let say test and click Apply button

  • In the Service Request section, Click on Edit button

  • Enter base URI( of the REST API Endpoint. If the service is Basic Auth or OAuth, then select Service Account.  As of now service is not secured so simply click Apply button

  • Click on Save button
  • Configuration is complete. Let's deploy the service on Physical Gateway
  • Click on Deployments tab
  • Click on Deploy API
  • Select Gateway and Click on Deploy button
  • The API deployment appears on the Waiting tab as the API in the WAITING deployment state
  • Once Deployed, API will appear under the Deployed tab

  • The API has been created and deployed. This is the time to test the API. If, Physical Gateway API is not remembered, click on Deployments tab and Expand the bar 
  • Copy the URL from Nodes section

  • Paste the copied URL in the browser URL and append the relative URL(/portal/employee?id=1234) of REST API

Wednesday, 9 May 2018

Service Account in Oracle API Cloud Service(CS)

Service Account is an authentication feature provided by Oracle API CS. In other words, Service Account is a resource containing credentials. Service Account can be used when a back-end service require authentication (Basic or OAuth).

Below two authentication schemes can be used with Service Account:
  • Basic Authentication
  • OAuth
Basic Authentication requires only two properties:
  • User Name
  • Password
OAuth requires properties to be configured:
  • Token Endpoint URL: The OAuth Token Provider endpoint where the access token is available
  • Scope: The scope(s) of the access request
  • Client ID: The ID which identifies the client application
  • Client Secret: The secret password associated with the client ID
  • Grant Type: Either Client Credentials or Resource Owner Password Credentials
  • Token Transfer: Transfer the token via URL or Header
Creating a Service Account

A user must be having admin privileges to create a Service Account

Below are the steps to create Service Account
  • Login to API Portal Console
  • Click on the Service Accounts from the menu
  • Click on Create button

  • Enter information as below to create Service Account
    • Service Account Name: Enter the unique service account name
    • Description(Optional): Enter a brief description of the service account
    • Account Type: Either Basic Auth or OAuth 2.0 depending on the backend service authentication mechanism
      • If Basic Auth selected, enter User Name and Password
      • If OAuth 2.0 selected, enter required information as below
        • Token Endpoint URL: Enter the URL for the OAuth token provider endpoint where the access token is available
        • Use Gateway Node Proxy((Optional) ): Click if a proxy is required to reach the token endpoint URL
        • Scope: Enter a scope, such as.READ. Separate multiple scopes with a blank space
        • Client ID: Enter the client ID.
        • Client Secret: Enter the client secret
        • Grant Type: Select Client Credentials or Resource Owner Password Credentials If Resource Owner Password Credentials selected, enter the appropriate username and password
        • Token Transfer: Click Pass Token via URL or Pass Token via Header
For now, Select Basic Auth and click on Create button

Once created, the service account will be displayed on the Service Account page