4 Getting Started with Oracle GoldenGate Microservices

After deploying Oracle GoldenGate Microservices on the Oracle Cloud Marketplace, you can access the latest release of Oracle GoldenGate.

Connecting to the Oracle GoldenGate Compute Node

To access the new Oracle GoldenGate deployment, log in to the compute node using the following steps. For this, you need to identify the IP address of the compute node where Oracle GoldenGate is running.

Note:

If the instance has a public IP address, you can use it to connect using SSH. If the instance only has a private IP address, then use the bastion service to start a bastion session to SSH to the instance.

To identify the IP address:

  1. Log in to your Oracle Cloud Console.
  2. Select Compute -> Instances.
  3. Select the hyperlink name of the compute node. The IP Address is listed under Instance Access.
  4. To access the compute node where Oracle GoldenGate is running, connect as the opc account using SSH. For more information on how to access a node using the opc account, see Connecting to an Instance.
A public SSH key is specified as a part of the deployment process and you can use the private key when you are connecting to the Oracle GoldenGate instance. The following example illustrates how you connect to the Oracle GoldenGate compute node:
ssh -i private-key-filename opc@public-id-address

Next you need the Administrator Password before you connect to the Service Manager.

Setting up Oracle GoldenGate Microservices for Your Database

Before you can start using Oracle GoldenGate Microservices, there are a few tasks that you must perform, depending on your database platform, to ensure that your environment is complete and ready to replicate your data.

Setting up for DB2 z/OS

The required DB2 connection drivers are not pre-installed in Oracle GoldenGate on Microservices for Non-Oracle (DB2 z/OS) compute node. You have to install one of the following DB2 connection drivers before using Oracle GoldenGate (listed from lightest to heaviest):
  • IBM Data Server Driver for ODBC and CLI v10.5 or later
  • IBM Data Server Runtime Client v10.5 or later
  • IBM Data Server Client v10.5 or later
  • DB2 Connect v10.5 or later

For more information on these drivers, see DB2 z/OS - Choosing an Installation Operating System in Oracle GoldenGate Microservices Documentation.

Setting up Environment Variables

After provisioning the Oracle GoldenGate Microservices instance and installing the connection drivers, follow these instructions to edit the deployment's environment variables restart the services.

To set the environment variables:
  1. Open a browser and connect to the Oracle GoldenGate Service Manager. The URL is similar to http://host:port, where host is the name of the server or IP of the server that is running the Service Manager and port is the port number of the Service Manager. For a secure deployment, the URL is similar to https://public_ip_address.
  2. Enter the Oracle GoldenGate Administration user name and password and sign in to display the Service Manager home page.
  3. In the Deployments page of the Service Manager home page, locate the deployment.
  4. Click the Deployment name and then click Configuration.
  5. Ensure that you see both PATH and LD_LIBRARY_PATH variables in the list on the Deployment page. If the variables are not set, then set them as shown in the following example, and the values of these variables should typically, reflect the path where the ODBC driver is installed.
    PATH: /home/opc/odbc_cli/clidriver/bin:/home/opc/odbc_cli/clidriver/adm:$PATH
    LD_LIBRARY_PATH: /home/opc/odbc_cli/clidriver/lib:$LD_LIBRARY_PATH
  6. In the Action column of the Deployment page, click Start to restart the deployment.
  7. In the Service Manager home page, identify the Administration service you want to start and click Start to start the Administration service.
For more information about using the Service Manager, see Manage Deployments from the Service Manager in Oracle GoldenGate Microservices Documentation.

Topic:

Setting up for Oracle

The Oracle GoldenGate image on Oracle Cloud Marketplace contains the latest Oracle GoldenGate release along with Oracle Database Client software for all supported versions of the Oracle database.

For supported Oracle Database platforms for Oracle GoldenGate, see the latest certification matrix.

For more information about setting up the environment variables, such as LD_LIBRARY_PATH andTNS_ADMIN to the instant client directories, see OGGCA User Deployment in Oracle GoldenGate Microservices Documentation.

Setting up for MySQL

Before you can begin replicating data, for a MySQL database, review the instance, database and user requirements available in Prepare MySQL for Oracle GoldenGate and MySQL: Understanding What’s Supported in Oracle GoldenGate Microservices Documentation.

Setting up for PostgreSQL

The required PostgreSQL client libraries are not pre-installed in the Oracle GoldenGate Microservices for Non-Oracle (PostgreSQL) compute node and will need to be manually installed and configured before using the Microservices installation of Oracle GoldenGate for PostgreSQL on OCI Marketplace.

Required packages are available at https://www.postgresql.org/download/. Select the Linux operating system family and Red Hat/Rocky/CentOS distribution, then follow the instructions to integrate with the PostgreSQL Yum Repository. When selecting a PostgreSQL version, choose the version based on the version of the source or target PostgreSQL database. For platform, choose Red Hat Enterprise, CentOS, Scientific or Oracle version 7, and select x86_64 for the architecture.

Install the postgresqlversion#-libs module of the Linux installation package.

For example:

# Install the repository RPM:
sudo yum install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm 
# Install PostgreSQL:
sudo yum install -y postgresql13-libs
Setting up Environment Variables

After provisioning the instance for PostgreSQL and installing the connection drivers, follow these instructions to edit the deployment's environment variables restart the services.

To set the environment variables:

  1. Open a browser and connect to the Oracle GoldenGate Service Manager. The URL for OCI Marketplace is in the following format: https://public_ip_address

  2. Enter the Oracle GoldenGate Administration User Name and Password and sign in to display the Service Manager home page.

  3. In the Deployments page of the Service Manager home page, locate the deployment.

  4. Click the Deployment name and then click Configuration.

  5. Click the + sign next to Environment Variables and create a new Name entry called LD_LIBRARY_PATH with a Value of the PostgreSQL client libraries installation lib folder and of the Oracle GoldenGate’s installation lib folder.

    For example:

    /usr/pgsql-13/lib:/u01/app/ogg/lib

  6. Click Add and Save Changes.

  7. Repeat the previous step and add another Name entry called ODBCINI with the value of /etc/odbc.ini.

  8. Click Add and Save Changes.

  9. Return to the Overview page of the Service Manager and in the Action drop-down of the Deployment, click Start or Restart, depending on its status, in order for the new variables to take effect.

Upgrading from Oracle GoldenGate for PostgreSQL version 21.14

When upgrading from Oracle GoldenGate for PostgreSQL release 21.14 to a higher version for a cloud database as source and target databases, the environment variables, such as ODBCINI and LD_LIBRARY_PATH need to be set again.

Perform the following steps to set the environment variables after an upgrade:

  1. Create a JSON file to list the environment variables and their values.

    For example:

    {
        "environment": [    
          {
            "name": "ODBCINI",      
            "value": "/home/opc/odbc.ini"    
          },
          {      
            "name": "LD_LIBRARY_PATH",
            "value": "/u01/app/ogg/lib/:/usr/pgsql-11/lib:$LD_LIBRARY_PATH"    
          }
          ]}

  2. Run the following curl command to set the environment variables: 

    curl -o output.json
        --request
        PATCH 'https://ogg instance name/services/v2/deployments/MarketPlace?root=deployments&deployment=deploymentInfo&name=MarketPlace' -u 'ogg username':'ogg password'
        --header
        'Content-Type: application/json' -d@JSON file
        --insecure

Starting the Administration Service

For some installations of Oracle GoldenGate Microservices, such as for DB2 and SQL Server, you were instructed in previous steps to install the client drivers for the database on the compute node. After they are installed, you must then manually start the Administration service for your instance.

To start the Administration Service:

  1. Navigate to the Service Manager login page. You can reach the Service Manager page by using the public IP address that you obtained when you performed a look up of the compute node information for the environment: https://public_ip_address
  2. Under Services, use the Action drop-down for the Administration Service, and select Start.

Creating User Accounts

To secure your Oracle GoldenGate Microservices deployment, you should consider creating new user accounts for your Oracle GoldenGate users and assign each account to the functional role that they are expected to perform. These roles are as follows:

  • Security
  • Administrator
  • Operator
  • User

Oracle GoldenGate users only have access permissions according to their defined access levels. For more information on how Oracle GoldenGate Security Framework is used, refer to Authentication and Authorization in Oracle GoldenGate in Oracle GoldenGate Microservices Documentation.

Topics:

Creating Users in the Service Manager

After you log in to the Service Manager as Administrator, you can create users with the different roles such as Administrator, Operator, or User. Users with the Security role can administer all Microservices.

To create users in the Service Manager:
  1. Navigate to the Service Manager log in page. You can reach the Service Manager page by using the public IP address that you obtained when you looked up the compute node information for the environment: https://public_ip_address.
  2. Log in using the oggadmin user and the password credentials located in the /home/opc/ogg_credentials.json file.
  3. Click the menu icon present on the top left corner to open the menu section.
  4. Select the User Administration option from the menu.
  5. On the Users screen, select the plus (+) icon to add a new user.
  6. Fill in all the required fields.
  7. Click Submit to create the new user.

Creating Users in the Administration Service

After logging in to the Oracle GoldenGate Microservices Administration Service as the Administrator, for the specified deployment, you can create a new user with the role of Administrator, Operator, or User to administer the deployment.

To create Users in the Administration Service:

  1. Log in to the Administration Service using the Security Role User (oggadmin) credentials.
  2. Click the menu icon present in the top left corner to open the menu.
  3. From the menu, select the User Administration option.
  4. From the Users screen, select the plus (+) icon, to create a new user.
  5. Fill in the details for all the required fields and click Submit.

Note:

Passwords must be 8 to 30 characters long and contain at least 1 uppercase, 1 lowercase, 1 numeric, and 1 special character. Special characters such as ‘$’, ‘^’, or ‘?’are not allowed.

Changing Default Administrator Password

Changing passwords for critical accounts, such as oggadmin, is the first priority in securing your Oracle GoldenGate Microservices deployment. To change the password for oggadmin, you must first change it in the Service Manager and then in Administration Service.

This topic describes the following:

Changing the Administrator Password for the Service Manager

To change the Administrator password for the Service Manager:

  1. Navigate to the Service Manager login page. You can reach the Service Manager page by using the public IP address that you obtained when you performed a look up of the compute node information for the environment.
    https://public_ip_address
  2. Log in using the oggadmin user and password credentials located in the /home/opc/ogg-credentials.json file.
  3. Select the menu icon present on the top left corner to open the menu.
  4. Select User Administration option from the menu.
  5. From the Users screen, select the Pencil icon under Actions column.
  6. Update the password for the oggadmin user and click Submit.

    When the password is successfully reset, the current user is logged out.

  7. Log in again to the Service Manager by using the new password.

Note:

Passwords must be 8 to 30 characters long and must contain at least 1 uppercase, 1 lowercase, 1 numeric, and 1 special character. Special characters such as ‘$’, ‘^’, or ‘?’ are not allowed.

Changing the Administrator Password for the Administration Service

After changing the Oracle GoldenGate Microservices Service Manager security role user password, you should change the password of the security role user in the underlying deployments.

To change the Administrator password for the Administration Service:

  1. From the Service Manager left-navigation pane, click Deployments and then select the deployment name.
  2. Click Administration Service from the Deployments page to open the Administration Service web interface for the deployment.
  3. Log in using the oggadmin user credentials available in the following location:
    /home/opc/ogg_credentials.json
  4. Select the menu icon present on the top left corner to open the menu.
  5. Select User Administration option from the menu.
  6. From the Users screen, select the Pencil icon under Actions column.
  7. Update the essential details for password and info sections for the oggadmin user and click Submit.

    When the password is successfully reset, the current user is logged out.

  8. Log in again to the Administration Service by using the new password.
See Edit Users in Oracle GoldenGate Microservices Documentation.

Note:

Passwords must be 8 to 30 characters long and contain at least 1 uppercase, 1 lowercase, 1 numeric, and 1 special character. Special characters such as ‘$’, ‘^’, or ‘?’ are not allowed.

Changing the Default GGSCHEMA Value

By default, Oracle GoldenGate Microservices deployments on OCI Marketplace creates a default GGSCHEMA of ggadmin.

Note:

Oracle GoldenGate display error if the schema value for the SQLServer database is not ggadmin.

When connecting deployments to source and target databases, for some databases, such as SQL Server, Oracle GoldenGate needs to create objects in the database. These are created objects using the ggadmin schema, unless otherwise specified.

This means that in the source or target databases, that a schema called ggadmin needs to be created in advance of adding supplemental logging (TRANDATA), creating heartbeat tables, and creating checkpoint tables.

If you prefer to use a different schema instead of the default ggadmin schema, then you can manually modify the value, following the steps listed in the Creating a Parameter File in Oracle GoldenGate Microservices Documentation guide.

After you have modified the GGSCHEMA value, for these processes to recognize the new schema, you need to restart the Administration service and any existing Extracts and Replicats.