WMS ID: 11512 (#462)

* New folder for a new LiveLab Created a new folder with placeholder text for a new LiveLab * Added instructions to integrate MicroTx lib files * Instructions Updated image, instructions to run the sample app, integrate TMM files with sample app, and update the YAML file. * Updated tags and tasks Restructured the content. * Changes to manifest file * Purchase and sale of stocks * replaced XA sample app with Banking and Trading app * updated intro * uncomment lines without going through details * incorporated feedback * Updated images for ATP instances * Self QA Fixed issues that were identified during self QA. * updated links to tasks within page * Self QA checks * More self QA changes * added lab 2 * MTRM-1123 Incorporated feedback received from the QA team. * Incorporated feedback Incorporated feedback received from the LiveLabs team * Update screenshots for Lab 4 Added screenshots for Lab 4: ATP-S instance from the latest OCI console * Chunked data and incorporated feedback Broke down the long lab of running the app into two smaller labs and incorporated feedback received from Anoosha. * Minor change in Lab number * minor updates to the prerequisites * Update link to common image * Optional task to enable txn history * resized images resized images and minor text updates * Updated link to the ZIP file * Updated a link * Updated a link * Updates for changes to the image Bharath has made changes to the image. I have updated the text accordingly. * changes for updated image * Changes to the stock broker app * Comments incorporated to Lab 1 * Incorporated review comments and updated images * Changes to the Stock Broker app * Incorporated feedback rxd from Bharath * Incorporated Shivanshu's feedback * Update integrate-microtx-lib-files.md * Update integrate-microtx-lib-files.md * Specify shape to select A specific shape has to be selected. * minor change * LiveLabs content for ORDS apps First draft of LiveLabs content for ORDS apps * Draft 2 Ready for review * QA review comments incorporated Self QA completed QA review comments incorporated --------- Co-authored-by: ZackaryRice <128171922+ZackaryRice@users.noreply.github.com>
oracle-livelabs · Feb 1, 2024 · c8f731f · c8f731f
1 parent ea45d6c
commit c8f731f
Show file tree

Hide file tree

Showing 108 changed files with 2,170 additions and 0 deletions.
diff --git a/...tx-ords-data-consistency/introduction/images/ords-microtx-bank-transfer-app.png b/...tx-ords-data-consistency/introduction/images/ords-microtx-bank-transfer-app.png
diff --git a/microtx-ords-data-consistency/introduction/introduction.md b/microtx-ords-data-consistency/introduction/introduction.md
@@ -0,0 +1,59 @@
+# Introduction
+
+## About this Workshop
+
+As organizations rush to adopt microservices architecture, they often run into problems associated with data consistency as each microservice typically has its own database. In monolithic applications, local transactions were enough as there were no other sources of data that needed to be consistent with the database. An application would start a local transaction, perform some updates, and then commit the local transaction to ensure the application moved from one consistent state to another. Once the application’s state is spread across multiple sources of data, some factors need to be considered. What happens if the updates succeed in one microservice, but fails in another microservice as part of the same request? One solution is to use a distributed transaction that spans across the sources of data used by the microservices involved in a request. To maintain consistency in the state of all microservices participating in a distributed transaction, Oracle Transaction Manager for Microservices (MicroTx) provides a transaction coordination microservice and client libraries.
+
+In this workshop, you will learn how to use MicroTx to maintain data consistency across multiple Oracle REST Data Services (ORDS) applications by deploying and running a Bank Transfer application. You will also integrate MicroTx with the Kubernetes ecosystem by using tools, such as Kiali and Jaeger, to visualize the flow of requests between MicroTx and the microservices.
+
+### About the Bank Transfer Application
+
+The Bank Transfer application is created in PL/SQL and deployed using ORDS in Oracle Database. It demonstrates how you can develop ORDS applications that participate in a distributed transaction while using MicroTx to coordinate the transaction. You can use the Bank Transfer application to withdraw or deposit an amount. Since financial applications that move funds require strong global consistency, the application uses the XA transaction protocol.
+
+The following figure shows the various microservices in the Bank Transfer application. Some microservices connect to a resource manager. Resource managers manage stateful resources such as databases, queuing or messaging systems, and caches.
+![Microservices in Bank Transfer application](./images/ords-microtx-bank-transfer-app.png)
+
+* The MicroTx coordinator manages transactions amongst the participant services.
+
+* Teller microservice, a Java microservice, initiates the transactions. It is called an XA transaction initiator service. The user interacts with this microservice to transfer money from Department One to Department Two. It exposes a REST API method to transfer funds. This method defines the transaction boundary and initiates the distributed transaction. When a new request is created, MicroTx starts an XA transaction at the Teller microservice. This microservice also contains the business logic to issue the XA commit and roll back calls.
+
+* Department One and Department Two are ORDS applications. They participate in the transactions, so they are called as XA participant services. Two PDBs, FREEPDB1 and FREEPDB2, are created in a standalone instance of Oracle Database 23c Free to simulate the distributed transaction.  The standalone ORDS APEX service instance, runs on port 8080, and it is configured with two database pools that connect to FREEPDB1 and FREEPDB2. The ORDS service creates database pool for each PDB and exposes the REST endpoint. A single ORDS standalone service has two database connection pools connecting to different PDBs: FREEPDB1 and FREEPDB2. Department One and Department 2 connect to individual PDBs and the ORDS participant services expose three REST APIs, namely withdraw, deposit and get balance. The MicroTx library includes headers that enable the participant services to automatically enlist in the transaction. These microservices expose REST APIs to get the account balance and to withdraw or deposit money from a specified account. They also use resources from resource manager.
+
+The service must meet ACID requirements, so an XA transaction is initiated, and both withdraw and deposit are called in the context of this transaction.
+
+When you run the Bank Transfer application, the Teller microservice calls the exposed `transfer` REST API call to initiate the transaction to withdraw an amount from Department 1, an ORDS service, which is connected to FREEPDB1. After the amount is successfully withdrawn, the Teller service receives HTTP 200. Then the Teller calls the `deposit` REST API from Department 2, an ORDS service, which is connected to FREEPDB2. After the amount is successfully deposited, the Teller service receives HTTP 200, and then the Teller commits the transaction. MicroTx coordinates this distributed transaction. Within the XA transaction, all actions such as withdraw and deposit either succeed, or they all are rolled back in case of a failure of any one or more actions.
+
+During a transaction, the microservices also update the associated resource manager to track the change in the amount. When you run the Bank Transfer application, you will see how MicroTx ensures consistency of transactions across the distributed microservices and their resource managers.
+
+Participant microservices must use the MicroTx client libraries which registers callback and provides implementation of the callback for the resource manager. As shown in the image, MicroTx communicates with the resource managers to commit or roll back the transaction. MicroTx connects with each resource manager involved in the transaction to prepare, commit, or rollback the transaction. The participant service provides the credentials to the coordinator to access the resource manager.
+
+Estimated Workshop Time: 50 minutes
+
+### Objectives
+
+In this workshop, you will learn how to:
+
+* Set up various microservices. A Java service, Teller, is the transaction initiator application. The ORDS instances, Department 1 and Department 2 participate in the service. MicroTx is connected to all the resource managers and microservices so that it can coordinate the transaction.
+* Run the Bank Transfer application to transfer an amount from one account to another.
+* Use tools, such as Kiali and Jaeger, to visualize the flow of requests between MicroTx and the microservices.
+
+### Prerequisites
+
+This lab assumes you have:
+
+* An Oracle Cloud account
+
+* At least 4 OCPUs, 24 GB memory, and 128 GB of bootable storage volume is available in your Oracle Cloud Infrastructure tenancy to run the Bank Transfer application.
+
+Let's begin! If you need to create an Oracle Cloud account, click **Get Started** in the **Contents** menu on the left. Otherwise, if you have an existing account, click **Lab 1**.
+
+## Learn More
+
+* [Oracle® Transaction Manager for Microservices Developer Guide](http://docs.oracle.com/en/database/oracle/transaction-manager-for-microservices/23.4.1/tmmdg/index.html)
+* [Oracle® Transaction Manager for Microservices Quick Start Guide](http://docs.oracle.com/en/database/oracle/transaction-manager-for-microservices/23.4.1/tmmqs/index.html)
+
+## Acknowledgements
+
+* **Author** - Sylaja Kannan, Consulting User Assistance Developer
+* **Contributors** - Brijesh Kumar Deo and Bharath MC
+* **Last Updated By/Date** - Sylaja Kannan, February 2024
diff --git a/microtx-ords-data-consistency/ords-provision/images/click-sql.png b/microtx-ords-data-consistency/ords-provision/images/click-sql.png
diff --git a/...otx-ords-data-consistency/ords-provision/images/db-actions-sign-in-complete.png b/...otx-ords-data-consistency/ords-provision/images/db-actions-sign-in-complete.png
diff --git a/microtx-ords-data-consistency/ords-provision/images/run-sql-script.png b/microtx-ords-data-consistency/ords-provision/images/run-sql-script.png
diff --git a/microtx-ords-data-consistency/ords-provision/ords-provision.md b/microtx-ords-data-consistency/ords-provision/ords-provision.md
@@ -0,0 +1,334 @@
+# Set Up the ORDS Instances
+
+## Introduction
+
+This lab walks you through the steps to set up two Oracle REST Data Services (ORDS) applications, Department 1 and Department 2. These applications are created in PL/SQL and deployed using ORDS in Oracle Database. These applications participate in the XA transaction, so they are called transaction participant services.
+
+There are 2 PDBs (pluggable database) and a catalog database running in a standalone instance of Oracle Database 23c Free to simulate the distributed transaction. Here are the details about the PDBs:
+
+* FREE: A catalog database that the `sysdba` user can access.
+* FREEPDB1: A pluggable database that contains the OTMM schema. This is connected to Department 1, an ORDS service.
+* FREEPDB2 : A pluggable database that contains the OTMM schema. This is connected to Department 2, an ORDS service.
+
+The standalone ORDS APEX service instance, runs on port 8080, and it is configured with two database pools that connect to FREEPDB1 and FREEPDB2. The ORDS service creates database pool for each PDB and exposes the REST endpoint. A single ORDS standalone service has two database connection pools connecting to different PDBs: FREEPDB1 and FREEPDB2. Department 1 and Department 2 connect to individual PDBs and the ORDS participant services expose three REST APIs, namely withdraw, deposit and get balance. The MicroTx library includes headers that enable the participant services to automatically enlist in the transaction. These microservices expose REST APIs to get the account balance and to withdraw or deposit money from a specified account. They also use resources from resource manager.
+
+Estimated Time: 15 minutes
+
+### Objectives
+
+In this lab, you will:
+
+* Start the Database service and ORDS service instances
+* Grant privileges to the database schema
+* Set Up Department 1 and Department 2 applications
+* Test access to the applications
+
+### Prerequisites
+
+This lab assumes you have:
+
+* An Oracle Cloud account.
+* Successfully completed the previous labs:
+  * Get Started
+  * Lab 1: Prepare setup
+  * Lab 2: Environment setup
+* Logged in using remote desktop URL as an `oracle` user. If you have connected to your instance as an `opc` user through an SSH terminal using auto-generated SSH Keys, then you must switch to the `oracle` user before proceeding with the next step.
+
+ ```text
+  <copy>
+  sudo su - oracle
+  </copy>
+  ```
+
+## Task 1: Start the Database Service and ORDS Service Instances
+
+1. Run the following command to verify that the Oracle Database 23c Free service instance is running.
+
+    ```text
+    <copy>
+    sudo /etc/init.d/oracle-free-23c status
+    </copy>
+    ```
+
+   **Example output**
+
+    ```text
+    Status of the Oracle FREE 23c service:
+    LISTENER status: RUNNING
+    FREE Database status: RUNNING
+    ```
+
+   If the Oracle Database 23c Free service instance is not in the `RUNNING` state, then run the following command to restart the service.
+
+    ```text
+    <copy>
+    sudo systemctl restart oracle-free-23c
+    </copy>
+    ```
+
+2. Run the following commands in a new terminal to start the Oracle REST Data Services (ORDS) standalone service. Keep this terminal window open throughout the lab.
+
+    ```text
+    <copy>
+    export _JAVA_OPTIONS="-Xms8192M -Xmx8192M"
+    ords --config ${ORDS_CONFIG} serve
+    </copy>
+    ```
+
+3. Reset the password for the `SYS` user by logging into the catalog database with the default password.
+
+    ```SQL
+    <copy>
+    sql sys/Passw0rd@FREE as sysdba
+    SQL> ALTER USER SYS IDENTIFIED BY [new-user-password];
+    SQL> ALTER USER SYSTEM IDENTIFIED BY [new-user-password];
+    SQL> commit;
+    SQL> exit;
+    </copy>
+    ```
+
+    Where, `[new-user-password]` is the new password that you specify for FREE, a catalog database.
+
+## Task 2: Grant Privileges to the Schema in FREEPDB1
+
+1. Login to FREEPDB1 using the default username and password.
+
+    ```SQL
+    <copy>
+    sql sys/Passw0rd@FREEPDB1 as sysdba
+    </copy>
+    ```
+
+2. Change the default password.
+
+    ```SQL
+    <copy>
+    ALTER USER OTMM IDENTIFIED BY [<new-freepdb1-password>]; 
+    commit;
+    exit;
+    </copy>
+    ```
+
+    Where, `<new-freepdb1-password>` is the new password that you want to set.
+
+3. Run the following commands to grant privileges to the schema.
+
+    ```SQL
+    <copy>
+    DECLARE
+        l_principal VARCHAR2(20) := 'OTMM';
+    begin
+        DBMS_NETWORK_ACL_ADMIN.append_host_ace (
+            host => '*',
+            lower_port => null,
+            upper_port => null,
+            ace => xs$ace_type(privilege_list => xs$name_list('http'),
+            principal_name => l_principal,
+            principal_type => xs_acl.ptype_db));
+    end;
+    /
+ 
+    DECLARE
+        l_principal VARCHAR2(20) := 'OTMM';
+    begin
+        DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
+            host => '*',
+            ace  =>  xs$ace_type(privilege_list => xs$name_list('connect', 'resolve'),
+            principal_name => l_principal,
+            principal_type => xs_acl.ptype_db));
+    end;
+    /
+    </copy>
+    ```
+
+    Where, `OTMM` is the username that can access the schema.
+
+4. Commit the changes and exit from SQL prompt.
+
+    ```SQL
+    <copy>
+    SQL> commit;
+    SQL> exit;
+    </copy>
+    ```
+
+## Task 3: Grant Privileges to the Schema in FREEPDB2
+
+1. Login to FREEPDB2 using the default username and password.
+
+    ```SQL
+    <copy>
+    sql sys/Passw0rd@FREEPDB2 as sysdba
+    </copy>
+    ```
+
+2. Change the default password.
+
+    ```SQL
+    <copy>
+    ALTER USER OTMM IDENTIFIED BY [<new-freepdb2-password>]; 
+    commit;
+    exit;
+    </copy>
+    ```
+
+    Where, `<new-freepdb2-password>` is the new password that you want to set.
+
+3. Run the following commands to grant privileges to the schema.
+
+    ```SQL
+    <copy>
+    DECLARE
+        l_principal VARCHAR2(20) := 'OTMM';
+    begin
+        DBMS_NETWORK_ACL_ADMIN.append_host_ace (
+            host => '*',
+            lower_port => null,
+            upper_port => null,
+            ace => xs$ace_type(privilege_list => xs$name_list('http'),
+            principal_name => l_principal,
+            principal_type => xs_acl.ptype_db));
+    end;
+    /
+ 
+    DECLARE
+        l_principal VARCHAR2(20) := 'OTMM';
+    begin
+        DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
+            host => '*',
+            ace  =>  xs$ace_type(privilege_list => xs$name_list('connect', 'resolve'),
+            principal_name => l_principal,
+            principal_type => xs_acl.ptype_db));
+    end;
+    /
+    </copy>
+    ```
+
+    Where, `OTMM` is the username that can access the schema.
+
+4. Commit the changes and exit from SQL prompt.
+
+    ```SQL
+    <copy>
+    SQL> commit;
+    SQL> exit;
+    </copy>
+    ```
+
+## Task 4: Set Up Department 1
+
+1. Enter the SQL Developer web URL, `http://localhost:8080/ords/sql-developer`, to access Department 1 database.
+    A sign-in page for Database Actions is displayed.
+
+2. Enter the new password to access the FREE database as `sysdba` user.
+
+    The Database Actions page is displayed.
+
+3. In the **Development** box, click **SQL**.
+
+    ![Click on SQL](./images/click-sql.png)
+
+4. Open the `tmmxa.sql` SQL script file which is located at `/home/oracle/OTMM/otmm-23.4.1/samples/xa/plsql/lib`.
+
+5. Click **Run as SQL script** to run the `tmmxa.sql` SQL script file.
+
+    ![Click Run as SQL script](./images/run-sql-script.png)
+
+6. Open the `ordsapp.sql` SQL script file which is located at `/home/oracle/OTMM/otmm-23.4.1/samples/xa/plsql/databaseapp`.
+
+7. In the script, search for `resManagerId` and enter a unique resource manager ID to identify the database in both the `deposit` and `withdraw` handlers.
+
+    **Example Code**
+
+    ```text
+    <copy>
+    resManagerId VARCHAR2(256):= ''DEPT1-RM''; 
+    </copy>
+    ```
+
+    ```text
+    <copy>
+    resManagerId VARCHAR2(256):= ''DEPT1-RM'';
+    </copy>
+    ```
+
+7. Click **Run as SQL script** to run the `ordsapp.sql` SQL script file.
+
+    ![Click Run as SQL script](./images/run-sql-script.png)
+
+8. Log out from SQL Developer.
+
+## Task 5: Set Up Department 2
+
+1. Enter the SQL Developer web URL, `http://localhost:8080/ords/pool2/sql-developer`, to access Department 2 database.
+    A sign-in page for Database Actions is displayed.
+
+2. Enter the schema username and password that you have specified in the previous tasks.
+
+    The Database Actions page is displayed.
+
+3. In the **Development** box, click **SQL**.
+
+    ![Click on SQL](./images/click-sql.png)
+
+4. Open the `tmmxa.sql` SQL script file which is located at `/home/oracle/OTMM/otmm-23.4.1/samples/xa/plsql/lib`.
+
+5. Click **Run as SQL script** to run the script file.
+
+    ![Click Run as SQL script](./images/run-sql-script.png)
+
+6. Open the `ordsapp.sql` SQL script file which is located at `/home/oracle/OTMM/otmm-23.4.1/samples/xa/plsql/databaseapp`.
+
+7. In the script, search for `resManagerId` and enter a unique resource manager ID to identify the database in both the `deposit` and `withdraw` handlers.
+
+    **Example Code**
+
+    ```text
+    <copy>
+    resManagerId VARCHAR2(256):= ''DEPT2-RM''; 
+    </copy>
+    ```
+
+    ```text
+    <copy>
+    resManagerId VARCHAR2(256):= ''DEPT2-RM'';
+    </copy>
+    ```
+
+8. Click **Run as SQL script** to run the script file.
+
+    ![Click Run as SQL script](./images/run-sql-script.png)
+
+9. Log out from SQL Developer.
+
+## Task 6: Test Access to Department 1 and Department 2
+
+Run the following commands to test access and verify that REST API calls to Department 1 and Department 2 are executed successfully.
+
+1. Run the following command to retrieve the balance in account 1 of Department 1.
+
+    ```text
+    <copy>
+    curl --location --request GET 'http://localhost:8080/ords/otmm/accounts/account1'
+    </copy>
+    ```
+
+2. Run the following command to retrieve the balance in account 2 of Department 2.
+
+    ```text
+    <copy>
+    curl --location --request GET 'http://localhost:8080/ords/pool2/otmm/accounts/account2'
+    </copy>
+    ```
+
+You may now **proceed to the next lab.**
+
+## Learn More
+
+* [REST Data Services Developer's Guide](https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/)
+
+## Acknowledgements
+
+* **Author** - Sylaja Kannan
+* **Contributors** - Brijesh Kumar Deo and Bharath MC
+* **Last Updated By/Date** - Sylaja Kannan, February 2024