GoldenGate Cloud Service (GGCS): How to provision GGCS in Oracle Public Cloud (OPC) via RESTful API

Introduction

This document will walk you through how to provision GoldenGate Cloud Service (GGCS) in Oracle Public Cloud (OPC) via RESTful application programming interface (API).

For the purpose of this article, it will be using “cURL” as the RESTful client software to demonstrate the RESTful API calls for provisioning GGCS. For checking the progress of the provisioning, it will use the command line JSON (JavaScript Object Notation) processor “jq” for processing the JSON output file during provisioning.

The following topics are not included in the scope of this article:

  • Installation of “cURL” RESTful client software
  • Installation of “jq” JSON Command Line processor software
  • Provisioning of Oracle Database Cloud Service (DBCS) instance

It is assumed that “cURL” and “jq” software together with Oracle DBCS have been installed and provisioned. An Oracle DBCS instance is required during GGCS provisioning to house the data repository of the GoldenGate Cloud Control (GGCC) software which uses Weblogic Server software and an essential part of the GGCS to provide online monitoring of its processes.

The scripts and information provided in this article are for educational purposes only. They are not supported by Oracle Development or Support, and come with no guarantee or warrant for functionality in any environment other than the test system used to prepare this article.

For details on provisioning of Oracle DBCS, please check the following Oracle Documentation link:

For details on installing “cURL” and “jq” software, please check the following links:

Prerequisites

Before you can provision GGCS, certain prerequisites needs to be in-place for the provisioning to be successful; such as the right OPC subscription services, correct OPC user roles and enough OPC resource quotas, and other services or software as needed.

For this article, the following are at least the minimum prerequisites needed to provision GGCS:

  • Oracle GGCS Enterprise Edition Subscription
  • A minimum of one Oracle DBCS Instance – To be used for GGCC Data Repository
  • Oracle Storage Cloud Service Subscription
  • Domain User account with the Compute_Operations Role
  • cURL-  RESTful client software
  • jq – JSON Command Line processor software

Main Article

For this article, the following examples or assumptions were used for the provisioning process:

  • Identity Domain Name – ateamoggdom
  • User Name with Compute_Operations Role – john.doe@oracle.com
  • DBCS Service Name – ateam-ogg-dbcs-cURL
  • DBCS SYSDBA User – sys
  • Weblogic User – weblogic
  • GGCS Service Name – ateam-ogg-ggcs-cURL
  • GGCS Backup Storage Container Name – BKPGGURL
  • GGCS Create Input JSON File – ateam-ogg-ggcs-cURL-create.json

High Level Steps of GGCS provisioning via RESTful API

The following are the high-level steps for provisioning GGCS via RESTful API:

  • Find the RESTful API / REST Endpoint for GGCS
  • Create a JSON input file to be used by cURL which contains all the necessary GGCS provisioning parameters
  • Create a Storage Container to be used for running GGCS Backup process
  • Create the GGCS instance via cURL using the JSON input file
  • Check for the completion of the GGCS creation via cURL and jq software

Find the REST Endpoint for GGCS

To find the REST endpoint for GGCS, you need to login to the OPC domain and go the the “Service Details” page of the GoldenGate Cloud Service.

Here are the steps to get the REST endpoint from the GGCS Service Details page:

  • Login to the OPC Domain as the OPC user with Compute_Operations Role.
  • Click the Dashboard Icon OPC_Dashboard_Icon.
  • On the GoldenGate Dashboard/Widget, click the Action Menu  and Click the “View Details” as shown in this example.

  • On the GGCS details page, select and copy or take a note of the URL address on the REST Endpoint as shown in this example, this will be the URL address that will be used by cURL to provision the GGCS instance.

Create the JSON input file to be used by cURL which contains all the necessary GGCS provisioning parameters

  1. Here’s the content of the JSON file (ateam-ogg-ggcs-cURL-create.json) which was created and used by cURL in this article to provision GGCS instance

    {
    “serviceParameters”: {
    “serviceName”: “ateam-ogg-ggcs-cURL“,
    “vmPublicKeyText”: “ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC8nBPI2qMQkvyPYCg8SyxsXzshvvsmIEWH2xsSVusVZIdgVoTlab55q1ey6q+OAJ9y+Qc73bng9QcIfgtzdIv0vSfOW001nWALn4sgzBYcBne9xi411JEdKOZjfcloYbRAEwKtThB3xHIyJpvskOMha1WZ+Wk3zfPsfNVHt7iiNGVQnf5P/p6mEwpxglgisKiYAhbMRqy98Sdw9Fd482Ghegl3V0hzS1uIQc8ZguDKjIaYdqo3AbhN2VEJBX20EK9yHo8rThELOsrqXX9X4hYrPSfDmyiZmsRnLXb9aN3ALRnpJenYn1yosCXsJ66PSX9ZBMzLDtO0FzHkCfwL4C/r A-Team Test Key File”,
    “ggProvType”:”GGCCALSO”,
    “cloudStorageContainer” : “Storage-ateamoggdom\/BKPGGURL“,
    “cloudStorageUser” : “john.doe@oracle.com“,
    “cloudStoragePassword” : “Welcome1”,
    },
    “componentParameters”: {
    “GGCSRep”: {
    “shape”: “oc3”,
    “repodbcsName” : “ateam-ogg-dbcs-cURL“,
    “repodbUserName” : “sys“,
    “repodbPassword” : “Welcome2”,
    “wlsUserName”: “weblogic“,
    “wlsPassword”: “Welcome3”
    }
    }
    }

Create a Storage Container for GGCS Backup via the REST API – to be used for running GGCS Backup process

Before you can create a storage container via REST API, you would need to find and get the REST and AUTH endpoints of the Storage Cloud Service form its “Service Details” page.

Here are the steps to get the REST and AUTH  endpoints from the Storage Cloud Service Details page:

  • Login to the OPC Domain as the OPC user with Compute_Operations Role.
  • Click the Dashboard Icon OPC_Dashboard_Icon.
  • On the Storage Dashboard/Widget, click the Action Menu  and Click the “View Details” as shown in this example.

  • On the Storage Cloud Service details page, select and copy or take a note of the URL addresses for the REST and AUTH Endpoints as shown in this example, this will be the URL addresses that will be used by cURL to create a storage container.

The steps to create a storage container via REST API are as follows:

  1. 1. Get an authorization token (X-Auth-Token) to be used for authentication in creating the storage container via the cURL command using the URL for the AUTH endpoint of the Storage Cloud Service.

curl -v -s -X GET \
-H “X-Storage-User: Storage-ateamoggdom:john.doe@oracle.com” \
-H “X-Storage-Pass: Welcome1” \
https://ateamoggdom.storage.oraclecloud.com/auth/v1.0

From the curl command output, look for the value of the X-AUTH-Token and use that value for the authorization token for the curl command to create the storage. Here’s that snippet of the command output with the X-AUTH-Token value.

.
.
.
< date: 1504143195801
< X-Auth-Token: AUTH_tk880a43e8752c43bd0d21097d21c274cc
< X-Storage-Token: AUTH_tk880a43e8752c43bd0d21097d21c274cc
< X-Storage-Url: https://uscom-central-1.storage.oraclecloud.com/v1/Storage-ateamoggdom
< Content-Length: 0
.
.
.

  1. 2. Create the Storage Container via cURL command using the Authorization token, in this example it is AUTH_tk880a43e8752c43bd0d21097d21c274cc and the name of the GGCS Backup container is BKPGGURL. The URL address to use for the storage creation is the REST endpoint for the Storage Cloud Service.

curl -v -s -X PUT \
-H “X-Auth-Token:AUTH_tk880a43e8752c43bd0d21097d21c274cc” \
https://ateamoggdom.storage.oraclecloud.com/v1/Storage-ateamoggdom/BKPGGURL

From the curl command output, look for the lines that contains the PUT command for the storage container name and the line that states “HTTP …. Created“. This is an indication that the create storage command was successful.

.
.
.
> PUT /v1/Storage-ateamoggdom/BKPGGURL HTTP/1.1
> User-Agent: curl/7.35.0
> Host: ateamoggdom.storage.oraclecloud.com
> Accept: */*
> X-Auth-Token:AUTH_tk880a43e8752c43bd0d21097d21c274cc
>
< HTTP/1.1 201 Created
< X-Trans-Id: tx015f09e9ba834dfd98e26-0059a76944ga
.
.
.

Create the GGCS instance via cURL using the JSON input file

In this step, we need to use a JSON file as an input or payload for the cURL command. In this example, the JSON file ateam-ogg-ggcs-cURL-create.json was used for the following cURL command to create the GGCS instance:

curl -s -i -X POST \
-u john.doe@oracle.com:Welcome1 \
-d @ateam-ogg-ggcs-cURL-create.json \
-H “Content-Type:application/vnd.com.oracle.oracloud.provisioning.Service+json” \
-H “X-ID-TENANT-NAME:ateamoggdom” \
https://psm.us.oraclecloud.com:443/paas/api/v1.1/instancemgmt/ateamoggdom/services/ggcs/instances -k -m 89

From the curl command output, look for the lines that states “HTTP …. Accepted” and “…Submitted job to create service…”. This is an indication that the GGCS instance provisioning job was successfully submitted.

HTTP/1.1 202 Accepted
Server: Oracle-Application-Server-11g
Strict-Transport-Security: max-age=31536000;includeSubDomains
Location: https://psm.us.oraclecloud.com:443/paas/api/v1.1/activitylog/ateamoggdom/job/14983556
.
.
Access-Control-Allow-Methods: GET, POST, DELETE, PUT, OPTIONS, HEAD
.
.
Service-URI: https://psm.us.oraclecloud.com:443/paas/api/v1.1/instancemgmt/ateamoggdom/services/ggcs/instances/ateam-ogg-ggcs-cURL
.
.
Connection: close
{“details”:{“message”:”Submitted job to create service [ateam-ogg-ggcs-cURL] in domain [ateamoggdom].”,”jobId”:”14983556″}}

 

Check for the successful completion of the GGCS provisioning process via cURL and jq software

In this step, we will invoke the “jq” command line JSON processor to process the JSON output file from the curl command when checking the progress of the GGCS provisioning process. Use the GGCS service name that was used in the provisioning as part of the URL address, in this example it is ateam-ogg-ggcs-cURL.

curl -X GET -u john.doe@oracle.com:Welcome1 \
-m 150 \
-H “Content-Type: application/vnd.com.oracle.oracloud.provisioning.Service+json” \
-H “X-ID-TENANT-NAME:ateamoggdom” \
https://psm.us.oraclecloud.com:443/paas/api/v1.1/instancemgmt/ateamoggdom/services/ggcs/instances/ateam-ogg-ggcs-cURL -k | \
jq ‘.state’

From the curl | jq command output, this should return at least a starting value of “INITIALIZING”. This means that the provisioning process is going in it’s initialization phase, and this value will change overtime until it completes the provisioning process and the successful end result value of the state would be in “READY” state. The normal time to provision a GGCS instance is around 15 – 30 minutes.

.
.
.
“INITIALIZING”

After about 15-30 minutes, repeat the same curl | jq command to check final status of the proviosning process making sure that the final status is in “READY” state,

.
.
.
“READY”

The “READY” state indicates that the provisioning process was successfully completed and the GGCS VM instance is up and running.

Summary

This article walked through the steps to on how to provision GGCS in OPC via RESTful API.

Additional Resources:

Oracle Database Cloud Service (DBCS) 

Oracle GoldenGate Cloud Service (GGCS)

GGCS User Guide Documentation

GGCS Tutorial Section

Add Your Comment