1. Using Oracle API Platform Cloud Service
  2. Manage Gateways
  3. Create a Gateway Node on Oracle Cloud Infrastructure

Create a Gateway Node on Oracle Cloud Infrastructure

You can use Terraform to create a new gateway node on Oracle Cloud Infrastructure.

Topics:

Before You Begin Creating a Gateway on Oracle Cloud Infrastructure

Before you create API Platform Cloud Service Gateway on Oracle Cloud Infrastructure, complete the prerequisites.

Decide whether to encrypt your passwords. Oracle strongly recommends encrypting passwords for security purposes, especially for production. Encrypting passwords prevents users who have access to resource manager stacks from seeing the passwords. If you want to create a gateway quickly for testing purposes only, providing plain text passwords requires fewer prerequisites.

Complete the following prerequisites whether or not you encrypt passwords:

Complete the following additional prerequisites if you want to encrypt passwords:

Understand Service Requirements

Learn the service requirements for creating a gateway.

You must fulfill certain requirements before you complete setup prerequisites and use Terraform to create the API Platform Cloud Service gateway instance on Oracle Cloud Infrastructure.

Basic Essentials

You require the following basic Oracle Cloud Infrastructure essentials:

  • Tenancy

  • User

  • Group

  • Compartment

Create a compartment in Oracle Cloud Infrastructure for your API Platform Cloud Service gateway resources, or use an existing compartment.

Required Access

You require permissions to access to several Oracle Cloud Infrastructure components and services in order to use API Platform Cloud Service Gateway setup.

  • Compute

  • Resource Manager

  • Load Balancing

  • Virtual Cloud Networks

  • Custom Images

  • Block Volumes

If you want to encrypt passwords, you must also have permissions to access to the following:

  • Key Management

  • Dynamic Groups

Check the service limits for these components in your Oracle Cloud Infrastructure tenancy and, if necessary, request a service limit increase. See Service Limits in the Oracle Cloud Infrastructure documentation.

Encrypt Passwords

Note:

Encryption is strongly recommended, especially for production, but is not required.

Encrypt the following passwords that you will supply to the Terraform package for setting up the API Platform Cloud Service gateway using a key from the Oracle Cloud Infrastructure Key Management service:

  • Gateway Weblogic Administrator Password

  • Client Secret associated with desired API Management Platform

  • Gateway Runtime User Password

  • Gateway Manager User Password

See Key Management FAQ and Encrypt Passwords.

Authorization

This prerequisite is required if you encrypt passwords.

Note:

Encryption is strongly recommended, especially for production, but is not required.

Authorize the compute instance to use Oracle Cloud Infrastructure services.

Provide Access to Required Oracle Cloud Infrastructure Resources in a Compartment

Provide access to Oracle Cloud Infrastructure resources in a compartment through policies.

Note:

You must complete this prerequisite regardless of whether you encrypt passwords.

When you create API Platform Cloud Service Gateway setup in Oracle Cloud Infrastructure, by default the compute instance, block storage volume, virtual cloud network, subnets, security lists, route tables, load balancer, and so on, are all created within a single compartment.

Access to Oracle Cloud Infrastructure resources in a compartment are controlled through policies. Your Oracle Cloud Infrastructure user must have management access to the these resources. The policies are written with respect to the group in which the user belongs.

The following examples show how to create the policies you need:
Allow group MyGroup to manage instance-family in compartment
    MyCompartment
Allow group MyGroup to manage virtual-network-family in compartment
    MyCompartment
Allow group MyGroup to manage volume-family in compartment
    MyCompartment
Allow group MyGroup to manage load-balancers in compartment
    MyCompartment
Allow group MyGroup to manage orm-stacks in compartment
    MyCompartment
Allow group MyGroup to manage orm-jobs in compartment
    MyCompartment
Allow group MyGroup to manage app-catalog-listing in compartment
    MyCompartment

If you plan to encrypt keys, you also need the following policies:

Allow group MyGroup to manage vaults in compartment
    MyCompartment
Allow group MyGroup to manage keys in compartment
    MyCompartment

As an alternative to creating individual policies, you can use one manage all-rources policy: 

Allow group MyGroup to manage all-resources in compartment
    MyCompartment

Create an Encryption Key

Create an encryption key in Oracle Cloud Infrastructure Key Management. This will allow you to encrypt and decrypt the various passwords required for APICS Gateway setup.

Note:

Encryption is strongly recommended, especially for production, but is not required.

An encryption key created in Oracle Cloud Infrastructure Key Management enables you to encrypt and decrypt the passwords required for API Platform Cloud Service Gateway setup.

First, create a vault and encryption key in Key Management, or use an existing vault and key.

After you create the key, note the following information:

  • Cryptographic Endpoint of the vault
  • OCID of the key

See Managing Keys in the Oracle Cloud Infrastructure documentation.

Encrypt Passwords

Use Oracle Cloud Infrastructure Key Management to encrypt the passwords that you need to create and join a API Platform Cloud Service Gateway Node.

Note:

Encryption is strongly recommended, especially for production, but is not required.

You can encrypt the following passwords:

  • Gateway Weblogic Admin Password

  • Client Secret associated with desired API Management Platform

  • Gateway Runtime User Password

  • Gateway Manager User Password

You cannot use the console to encrypt or decrypt sensitive data in Key Management. You must use the Oracle Cloud Infrastructure command line interface (CLI) or API.

See CLI Quickstart in the Oracle Cloud Infrastructure documentation to setup the Oracle Cloud Infrastructure CLI or API.

To encrypt passwords:
  1. Identify the Cryptographic Endpoint of your vault in Key Management.
  2. Identify the OCID of your encryption key in Key Management
  3. Encode the passwords in base64 format. For example, on Linux:
     echo -n 'Your_Password' | base64
  4. Use the CLI or API to encrypt your passwords:
    oci kms crypto encrypt --key-id Key_OCID --endpoint Crypto_Endpoint --plaintext Base64_Password

See Using Keys in the Oracle Cloud Infrastructure documentation.

Create a Dynamic Group

Create a group in Oracle Cloud Infrastructure whose members are the compute instances that you will create with API Platform Cloud Service Gateway Node setup.

Note:

Dynamic groups are needed only if you encrypt passwords. Encryption is strongly recommended, especially for production, but is not required.

To create a dynamic group:

  1. Access the Oracle Cloud Infrastructure console.
  2. From the navigation menu, select Identity, and then click Compartments.
  3. Copy the OCID for the compartment that you plan to use for the APICS Gateway Node compute instances.
  4. Click Dynamic Groups.
  5. Click Create Dynamic Group.
  6. Enter a Name and Description.
  7. For Rule 1, create a rule that includes all instances in the selected compartment in this group.
    ALL {instance.compartment.id = 'Compartment_OCID'}
  8. Provide the OCID for the compartment.
  9. Click Create Dynamic Group.

Create a Policy for the Dynamic Group

Create a policy in Oracle Cloud Infrastructure so that the compute instances in the API Platform Cloud Service gateway node can access your encryption key.

Note:

Dynamic groups and policies are needed only if you encrypt passwords. Encryption is strongly recommended, especially for production, but is not required.

To create a policy:

  1. Access the Oracle Cloud Infrastructure console.
  2. From the Navigation Menu, select Identity, and then click Policies.
  3. Select the Compartment in which you want to create the policies.
  4. Click Create Policy.
  5. Enter a Name and Description.
  6. For Statement, enter the following statement in the given format:
    Allow dynamic-group Group_Name to use keys in compartment
    Vault_Compartment_Name

    Provide the name of the dynamic group and the name of the compartment where your encryption key is located. For example:

     Allow dynamic-group MyInstancesDynamicGroup to use keys in compartment
    MyCompartment
You are now ready to create the gateway instance.

Create the Gateway Instance on Oracle Cloud Infrastructure

Use a Terraform project you download from Oracle to create the logical gateway instance on Oracle Cloud Infrastructure.

Prerequisites: You must complete the required steps in Before You Begin Creating a Gateway on Oracle Cloud Infrastructure.

To create the gateway instance:

  1. Import the hardened image from the PAR URL.
    1. In Oracle Cloud Infrastructure Console, click the Navigation menu, select Core Infrastructure, then Compute, and then Custom Images.
    2. Select the compartment where you want to create the gateway.
    3. Click Import Image.
    4. For Name, enter an image name.
      Oracle recommends that you use the image name from the PAR URL for example, hardened-2.11.01-OL7-master, but you can specify any name.
      You will use this name later for the GATEWAY_IMAGE_NAME Resource Manager variable.
    5. For the image PAR URL enter the most recent URL, for example: 
      https://objectstorage.us-phoenix-1.oraclecloud.com/p/Um0Ipf9TLJ1Crs7si2h9u0X2ygcWBKW3lxB2yfOnw3o/n/idlybogdd5kn/b/ics_images/o/hardened-2.11.01-OL7-master-d61e4a32-65a7-412c-8cc2-cc25c82a51b8
    6. For Image Type, specify OCI.
    7. Click Import Image.
  2. Download the Terraform project to your local machine from the most recent Terraform PAR URL, for example:
    https://objectstorage.us-phoenix-1.oraclecloud.com/p/dDbfaMa1xu6hVpCHhaqQeVmKsRo_MAhznvtKxDYB7Aw/n/paasdevapics/b/apip-gw/o/api_platform_gw_for_oci.025.tf.zip

    To obtain the most recent Terraform PAR URL, go to the same site where you obtained the image PAR URL: https://objectstorage.us-phoenix-1.oraclecloud.com/p/685VvkxH6CTe8HEacvPd6uSz4cFOmEJcK9syhbaC8i0/n/paasdevapics/b/apip-gw/o/latest_par_urls.html.

  3. In Oracle Cloud Infrastructure console, click the Navigation menu, select Solutions and Platform, then Resource Manager, and then Stacks. Select your compartment and click Create Stack.
  4. Browse or drag and drop the downloaded Terraform project, and then click Next.
  5. On the Variables page, configure the Terraform variables, and then click Next.

    Table 3-1 Configure the Variables

    Variable Information
    PREFIX Change these arbitrary characters to a prefix of your choice. Use only English characters and a dash. Keep the prefix short.
    LOGICAL_GATEWAY_PREFIX Change these arbitrary characters to a prefix of your choice. Use only English characters and a dash. Keep the prefix short.
    MANAGEMENT_SERVICE_URL Enter the management service URL.

    To locate this URL, on the Management Portal, select Gateway, click the Node icon, and then click Open Installation Wizard.
    IDCS_URL Enter the Oracle Identity Cloud Service URL.

    To locate this URL, on the Mangement Portal, select Gateway, click the Node icon, and then click Open Installation Wizard.
    PLAINTEXT_SECRETS

    Check this box if you plan to enter the secrets in plain text format. If you have encrypted your secrets, leave this box unchecked.

    Note: For security, encryption is strongly recommended, especially for production, but is not required.

    The four secrets are:

    • CLIENT_SECRET
    • GATEWAY_RUNTIME_PASSWORD
    • GATEWAY_MANAGER_PASSWORD
    • GATEWAY_ADMIN_PASSWORD
    CRYPTOGRAPHIC_ENDPOINT

    This is the endpoint information you noted when you created the encryption key. The endpoint is necessary for decryption. See Create an Encryption Key. If you did not encrypt secrets, leave this variable blank.

    Note: For security, encryption is strongly recommended, especially for production, but is not required.

    CRYPTOGRAPHIC_KEY_ID This is the OCID for the encryption key you created. This OCID is necessary for decryption. See Create an Encryption Key. If you did not encrypt secrets, leave this variable blank.

    Note: For security, encryption is strongly recommended, especially for production, but is not required.

    GATEWAYADMIN_NAME Enter a name for the new gateway administrator. This user is created in the gateway WebLogic Server only.
    GATEWAYADMIN_PASSWORD

    Enter the encrypted password or enter the password in plain text format. See Encrypt Passwords.

    Note: For security, encryption is strongly recommended, especially for production, but is not required.

    CLIENT_ID Enter the Client ID associated with your API Platform instance.

    To locate your Client ID, see View Security Settings.

    CLIENT_SECRET

    Enter the Client Secret associated with your API Platform instance. Enter the encrypted secret, or enter the secret in plain text format.

    To locate your Client Secret, see View Security Settings.

    Note: For security, encryption is strongly recommended, especially for production, but is not required.

    GATEWAY_RUNTIME_USER Enter the name of the existing gateway runtime user with the correct role.

    Available users are listed on the Management Portal. Select Roles, and then Gateway Runtime.
    GATEWAY_RUNTIME_PASSWORD

    Enter the encrypted password or enter the password in plain text format. See Encrypt Passwords.

    Note: For security, encryption is strongly recommended, especially for production, but is not required.

    GATEWAY_MANAGER_USER Enter the name of the existing gateway manager with the correct role.

    Available users are listed on the Management Portal. Select Roles, and then Gateway Manager.
    GATEWAY_MANAGER_PASSWORD

    Enter the encrypted password, or enter the password in plain text format. See Encrypt Passwords.

    Note: For security, encryption is strongly recommended, especially for production, but is not required.

    GATEWAY_IMAGE_NAME Enter the name of the gateway image you noted in Step 1.
    INSTANCE_SHAPE Enter a shape for the gateway instance.

    To find available shapes, on the Oracle Cloud Infrastructure Console, click the Navigation menu, select Government and Administration, then Administration, then Tenancy Details, then Service Limits, and then Compute.

    SSH_PUBLIC_KEY Enter your public key.

    After the gateway instance is created, you can ssh to the gateway instance:

    ssh -i private_key_file opc@compute_instance_public_ip
  6. On the Summary page, click Create.
    The stack is created, and its details page opens automatically.
  7. From Terraform Actions, click Plan.
  8. Wait for the job to complete.
    To see the job status, look under Jobs on the Stack Details page.
  9. From Terraform Actions, click Apply.
    After about 15 minutes, you will see the newly created logical gateway in API Platform.
  10. Navigate to the newly created gateway node and click Approve.
You have successfully created a logical gateway node on Oracle Cloud Infrastructure.

Resolve Issues with the New Gateway Node

Resources are available to you to help you resolve any issues you may have with the new gateway node.

Topics:

About Login Basics

Learn how to log in to the gateway compute instance and change users.

Log In to the Gateway Node Compute Instance

Open a command window and enter the following:

ssh -i private_key opc@public_ip_address

For example:

ssh -i opc_private_key opc@192.0.2.254

You are logged in as the opc user.

Change Users

After you have logged in as the opc user, you can switch users if needed.

To switch to the oracle user: 

sudo su - oracle

To switch back to the opc user before switching to a different user: 

exit

To switch to the root user: 

sudo su -

Locate Log Files

Locate the log files that are available to help you in debugging and troubleshooting.

Gateway Actions Log Files

Check the gateway actions log files first when you are debugging an issue.

Location:

/u01/gateway/install/logs

Log files:

checkJavaDbStatus.log
gatewayDomainCreation.log
gatewayInstall.log
java_version_check.log
main.log
scsgPatch.log
registerNode.log
status.log

Administration Server and Managed Server Log Files

You can access log files that are related to starting and stopping the Adminstration Server, Managed Server, and Node Manger.

Location:

/u01/gateway/install/domain/gateway1

Log files:

startDb.out
startMServer.out
startNodeManager.out
startWls.out
stopDb.out
stopMServer.out
stopNodeManager.out
stopWls.out

You can also use diagnostic and access log files for the Administration Server and Managed Server.

Administration Server log location:

/u01/gateway/install/domain/gateway1/servers/AdminServer/logs

Managed Server log location:

/u01/gateway/install/domain/gateway1/servers/managedServer1/logs

APICS Log Files

The APICS log files are related to the APICS controller (deployment, polling, and analytics, for example).

Location:

/u01/gateway/install/domain/gateway1/apics/logs

Log files:

apics.log
analytics.log

Customize the Hostname Verifier for Gateway Restart

You can customize the Hostname Verifier before you restart the gateway.

Note:

Terraform sets the Hostname Verifier automatically, so you are not required to customize it yourself.

To customize the Hostname Verifier:

  1. Log into the WebLogic Administration Console.
  2. In the Change Center of the Administration Console, click Lock & Edit.
  3. In the left pane of the Console, expand Environment and select Servers.
  4. In the Servers table, click the Managed Server name.
  5. In the Settings for Managed page, select SSL.
  6. Click Advanced.
  7. In the Hostname Verification list, select Custom Hostname Verification.
  8. In the Custom Hostname Verifier, enter string :
    weblogic.security.utils.SSLWLSWildcardHostnameVerifier
  9. Click Save.
  10. In the Change Center of the Administration Console, click Activate Changes.
  11. Stop and then restart WebLogic Server.

Enable and Customize the HTTP Access Log

Learn how to enable and customize the HTTP access log to provide detailed information for the gateway.

  1. Log into the WebLogic Administration Console.
  2. In the Change Center of the Administration Console, click Lock & Edit.
  3. In the Servers table, click the Administration Server/Managed Server name.
  4. In the Settings for Adminion Server/Managed page, select Logging, and then HTTP.
  5. On the Logging - HTTP page, ensure that the HTTP access log file enabled check box is checked.
  6. Click Advanced.
  7. On the Advanced pane, in the Format list box, select Extended.
  8. In the Extended Logging Format Fields, enter the following space-delimited string:
    c-ip date time time-taken cs-method cs-uri sc-status
  9. Click Save.
  10. In the Change Center of the Administration Console, click Activate Changes.
  11. Stop and then re-start WebLogic Server.
    The access.log file will appear in the following directory: 
    install_location/domain/gateway1/servers/server/logs

Stop, Start, or Check the Status of the Gateway Node

Learn how to stop, start, or check the status of the gateway.

  1. First, ssh into the gateway node compute instance:
    ssh -i private_key opc@public_ip
  2. Switch to oracle user:
    sudo su - oracle
  3. Navigate to the installer directory:
    cd /u01/installer

    The JSON property file SilentInstall.json is located inside the installer directory.

    Note:

    For security reasons, you can delete the SilentInstall.json file, then recreate later. To learn about the contents of the SilentInstall.json file, see the information about the gateway-props.json file in Install a Gateway Node.

Use the JSON file when you check the status of the gateway, or stop or start the Administration Server and Managed Servers.

  • To check the current status:
    ./APIGateway -f SilentInstall.json -a status
  • To stop the gateway Administration Server and Managed Servers:
    ./APIGateway -f SilentInstall.json -a stop
  • To start the gateway Administration Server and Managed Servers:
    ./APIGateway -f SilentInstall.json -a start