5 Quick Start with Minikube

Follow the instructions in this section to configure Minikube, install Transaction Manager for Microservices (MicroTx), and then run a sample application.

Caution:

The instructions provided in this section are specific to test or development environments. Do not use these instructions to set up and use MicroTx in production environments.

The runme.sh script runs the microservices in a non-secure mode.

Note:

As you run the runme.sh script only in test or development environments, you do not need to provide any authentication details.

The runme.sh script installs MicroTx, builds the Docker images, and then installs the sample application. You can also run the sample applications without automating these steps using the runme.sh script file. See Deploy Sample Applications in Transaction Manager for Microservices Developer Guide.

• Set Up the Required Software
  Before you begin, ensure that the following software is available on your local system.
• Run XA Sample Applications
  Run the XA sample application to transfer an amount from one department to another and to understand how you can use MicroTx to coordinate XA transactions. The MicroTx library files are already integrated with the sample application code.
• Run Saga Sample Applications
  Run the Saga sample application to book a trip and understand how you can use MicroTx to coordinate the transactions. The MicroTx library files are already integrated with the sample application code.
• Run TCC Sample Applications
  Run the TCC sample application to book a trip and understand how you can use MicroTx to coordinate the transactions. The MicroTx library files are already integrated with the sample application code.

5.1 Set Up the Required Software

Before you begin, ensure that the following software is available on your local system.

1. Install Docker version 20.10.x. See https://docs.docker.com/engine/install/.
2. After installing Docker, install Minikube. See https://minikube.sigs.k8s.io/docs/start/.
3. Run the following command to download Istio.

   curl -sL https://istio.io/downloadIstioctl | sh -

   When you run the runme.sh script, it installs Istio.

4. Add the istioctl client tool to the PATH environment variable of your local system. The following example specifies the a sample value. Provide the path based on your environment.

   export PATH=$HOME/.istioctl/bin:$PATH

5. Install the following required software.
   • npm version 7.x or later. See https://nodejs.org/en/download/.
   • Maven version 3.6 or later. See https://maven.apache.org/download.cgi.
   • Java JDK version 11 or later. See https://www.oracle.com/java/technologies/downloads/.
   • cURL. See https://curl.se/download.html.
   • jq. See https://stedolan.github.io/jq/download/.
6. Install and configure Kubernetes command-line interface (Kubectl), 1.21.x or later versions, to work with your Kubernetes cluster. See https://kubernetes.io/docs/tasks/tools/.
   Use Kubectl to create and manage your deployments. Kubectl uses the Kubernetes APIs to interact with the cluster.
7. Install the latest version of Helm 3.x on your local machine. For more information, see https://helm.sh/docs/intro/install/.
   Use Helm to make deployments easier as you can run a single command to install applications and resources into Kubernetes clusters. Helm interacts with the Kubernetes API server to install, upgrade, query, and remove Kubernetes resources.
8. Ensure that Java Development Kit (JDK) is installed on your local system, and then run the following commands in the Bash shell to set the following environment variables.

   export JAVA_HOME=jdk-install-dir
   export PATH=$JAVA_HOME/bin:$PATH

5.2 Run XA Sample Applications

Run the XA sample application to transfer an amount from one department to another and to understand how you can use MicroTx to coordinate XA transactions. The MicroTx library files are already integrated with the sample application code.

The sample application demonstrates how you can develop microservices that participate in XA transactions while using MicroTx to coordinate the transactions. When you run the Teller application, it withdraws money from one department and deposits it to another department by creating an XA 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. For details about the sample XA application, see About the Sample XA Application in Transaction Manager for Microservices Developer Guide.

Before you begin, complete the following tasks:

• Complete the prerequisites and set up the required software. See Prerequisites.
• Set up resource managers for the two transaction participant services to run XA applications. Set up Oracle Database as the resource manager. See Set Up XA-Compliant Resource Managers.
• Note down the details required to connect to the database, such as credentials and connection string.

To run the sample XA application using the runme.sh script file:

1. Enter the following commands in a bash shell to run the runme.sh script file.

   cd installation_directory/otmm-<version>
   sh runme.sh

2. Type 2 to run sample applications in the Minikube environment.
   The script sets up Minikube, configures Istio service mesh, loads the Docker image of MicroTx, and then installs MicroTx. After completing the installation, the script runs the transaction coordinator and provides the URL of the transaction coordinator.
3. Type 1 to run sample applications and MicroTx in non-secure mode in your test environment.

   You may have to wait for a few seconds while the script loads the images of the sample applications, and then installs it.

   When the script displays the full path that you must set for the KUBECONFIG environment variable, you can perform the next step.

4. Copy the command returned by the script, and then run the command in a new terminal. Set KUBECONFIG to configure Kubectl to run commands on Minikube.

   The script displays the actual command which you can copy and run as it is in a new terminal. The following is a sample command. The actual command that the script returns depends on the value of the $HOME variable.

   export KUBECONFIG=$HOME/.kube/minikube

5. Run the following command in a new terminal to start a tunnel between Minikube and the Istio ingress gateway.

   $ minikube tunnel

   If prompted, enter the password to access your local system, and then press any key to continue running the script.

6. Type 1 to run the sample application that uses the XA transaction protocol.
7. Provide details for the Department One application to connect with its resource manager.

   1. If you use Oracle Autonomous Database as the resource manager, enter the path to the Oracle Autonomous Database wallet that you have previously downloaded and extracted to your local machine. For example, installation_directory/xa/java/department-helidon/Database_Wallet.

      If you are using another Oracle Database, press Enter as you don't need to provide details of the wallet.

   2. Enter the connection string to the data store in Oracle Database.
      • If you are using a non-autonomous Oracle Database (a database that does not use a credential wallet), use the following format to enter the connection string:

        jdbc:oracle:thin:@<publicIP>:<portNumber>/<database unique name>.<host domain name>

        For example:

        jdbc:oracle:thin:@123.213.85.123:1521/CustDB_iad1vm.sub05031027070.customervcnwith.oraclevcn.com

      • If you are using Oracle Database Cloud Service with Oracle Cloud Infrastructure, see Create the Oracle Database Classic Cloud Service Connection String in Using Oracle Blockchain Platform.
      • If you are using Oracle Autonomous Transaction Processing, use the following format to enter the connection string:

        jdbc:oracle:thin:@tcps://<host>:<port>/<service_name>?wallet_location=<wallet_dir>

        You can find the required details, such as host, port, and service name in the tnsnames.ora file, which is located in folder where you have extracted the wallet.

        For example:

        jdbc:oracle:thin:@tcps://adb.us-phoenix-1.oraclecloud.com:7777/unique_connection_string_low.adb.oraclecloud.com?wallet_location=Database_Wallet

   3. Enter the user name to access the Oracle Database, such as SYS.
   4. Enter the password for the Oracle Database user.
   The script installs and runs the Department One application.
8. Provide details for the Department Two application to connect with its resource manager.

   1. If you use Oracle Autonomous Database as the resource manager, enter the path to the Oracle Autonomous Database wallet that you have previously downloaded and extracted to your local machine. For example, installation_directory/xa/java/department-helidon/Database_Wallet.

      If you are using another Oracle Database, press Enter as you don't need to provide details of the wallet.

   2. Enter the connection string to the data store in Oracle Database.
      • If you are using a non-autonomous Oracle Database (a database that does not use a credential wallet), use the following format to enter the connection string:

        jdbc:oracle:thin:@<publicIP>:<portNumber>/<database unique name>.<host domain name>

        For example:

        jdbc:oracle:thin:@123.213.85.123:1521/CustDB_iad1vm.sub05031027070.customervcnwith.oraclevcn.com

      • If you are using Oracle Database Cloud Service with Oracle Cloud Infrastructure, see Create the Oracle Database Classic Cloud Service Connection String in Using Oracle Blockchain Platform.
      • If you are using Oracle Autonomous Transaction Processing, use the following format to enter the connection string:

        jdbc:oracle:thin:@tcps://<host>:<port>/<service_name>?wallet_location=<wallet_dir>

        You can find the required details, such as host, port, and service name in the tnsnames.ora file, which is located in folder where you have extracted the wallet.

        For example:

        jdbc:oracle:thin:@tcps://adb.us-phoenix-1.oraclecloud.com:7777/unique_connection_string_low.adb.oraclecloud.com?wallet_location=Database_Wallet

   3. Enter the user name to access the Oracle Database, such as SYS.
   4. Enter the password for the Oracle Database user.
   The script installs and runs the Department Two application.
9. Type 1 to run the Teller application to transfer an amount from Department One to Department Two by creating an XA transaction.
10. Enter the account number from which you want to withdraw an amount. The sample table contains the following account numbers: account1 to account5. If you do not enter an account number and press enter, the default value is account1.
    The account balance is displayed.
11. Enter the name of the account to which you want to deposit the amount. The sample table contains the following account numbers: account1 to account5. If you do not enter an account number and press enter, the default value is account2.
    The account balance is displayed.
12. Enter the amount that you want to transfer. For example, 300. If you do not enter an amount and press enter, the default value is 100.
    The account balance of both accounts after the transaction are displayed on the screen. You can compare the earlier account balance with the current balance to ensure that the amount has been transferred.
13. Press any key to exit.
14. Type 1 to stop running all the microservices in the sample application and uninstall it.
15. Type 1 to uninstall MicroTx. If you want use the existing installation to run other sample applications, type 2.
16. Type 1 to uninstall Istio. If you want use the existing installation to run other sample applications, type 2.

What's next?

• Use the Kiali dashboard to view how the MicroTx handles the flow of requests between the sample microservices.
• Perform distributed tracing using Jaeger to trace the entire transaction. See Perform Distributed Tracing with Jaeger.
• Run another sample application.
• View the source files of the sample application.
• View the log files to find more details about the transactions.
• Create and run your own application using MicroTx.

5.3 Run Saga Sample Applications

Run the Saga sample application to book a trip and understand how you can use MicroTx to coordinate the transactions. The MicroTx library files are already integrated with the sample application code.

The sample application demonstrates how you can develop microservices that participate in Saga transactions while using MicroTx to coordinate the transactions. When you run the application, it makes a provisional booking by reserving a hotel room and flight ticket. Only when you provide approval to confirm the booking, the booking of the hotel room and flight ticket is confirmed. If you cancel the provisional booking, the hotel room and flight ticket that was blocked is released and the booking is canceled. By default, the hotel and flight service permits only three confirmed bookings. To enable you to test the failure scenario, the services reject any additional booking requests that are made after three confirmed bookings. This leads to the cancellation (compensation) of a provisionally booked hotel or flight within the trip and the trip is not booked. For details about the sample Saga application, see About the Sample Saga Application in Transaction Manager for Microservices Developer Guide.

To run the sample Saga application using the runme.sh script file:

1. Enter the following commands in a bash shell to run the runme.sh script file.

   cd installation_directory/otmm-<version>
   sh runme.sh

2. Type 2 to run sample applications in the Minikube environment.
   The script sets up Minikube, configures Istio service mesh, loads the Docker image of MicroTx, and then installs MicroTx. After completing the installation, the script runs the transaction coordinator and provides the URL of the transaction coordinator.
3. Type 1 to run sample applications and MicroTx in non-secure mode in your test environment.

   You may have to wait for a few seconds while the script loads the images of the sample applications, and then installs it.

   When the script displays the full path that you must set for the KUBECONFIG environment variable, you can perform the next step.

4. Copy the command returned by the script, and then run the command in a new terminal. Set KUBECONFIG to configure Kubectl to run commands on Minikube.

   The script displays the actual command which you can copy and run as it is in a new terminal. The following is a sample command. The actual command that the script returns depends on the value of the $HOME variable.

   export KUBECONFIG=$HOME/.kube/minikube

5. Run the following command in a new terminal to start a tunnel between Minikube and the Istio ingress gateway.

   $ minikube tunnel

   If prompted, enter the password to access your local system, and then press any key to continue running the script.

6. Type 2 to run the sample application that uses the Saga transaction protocol.

   The script installs the sample application.

7. Type 1 to confirm that you want to run the Saga sample application, and then press Enter.
   The sample application provisionally books a hotel room and a flight ticket and displays the details of the provisional booking. In case of any issues, the provisional booking is not made and the status displayed is Failed Trip Booking.
8. Confirm or cancel the provisional booking. Type 1 to confirm a successful provisional booking or type 2 to cancel a provisional booking, and then press Enter.
   If you type 1, your booking is confirmed and information about your confirmed booking is displayed.
9. Press any key to exit.
10. Type 1 to stop running all the microservices in the sample application and uninstall it.
11. Type 1 to uninstall MicroTx. If you want use the existing installation to run other sample applications, type 2.
12. Type 1 to uninstall Istio. If you want use the existing installation to run other sample applications, type 2.

What's next?

• Use the Kiali dashboard to view how the MicroTx handles the flow of requests between the sample microservices.
• Perform distributed tracing using Jaeger to trace the entire transaction. See Perform Distributed Tracing with Jaeger.
• Run another sample application.
• View the source files of the sample application.
• View the log files to find more details about the transactions.
• Create and run your own application using MicroTx.

5.4 Run TCC Sample Applications

Run the TCC sample application to book a trip and understand how you can use MicroTx to coordinate the transactions. The MicroTx library files are already integrated with the sample application code.

The sample TCC application implements a scenario where the travel agent microservice books a trip, flight booking service books a flight, and the hotel booking microservice books a hotel. The travel agent service accesses both the flight and hotel booking services. When a customer books a flight and a hotel, the booking is reserved until either the customer completes the payment and confirms the booking. In case of any failure, the reserved resources are canceled and the resources are returned back to the inventory. For details about the sample TCC application, see About the Sample TCC Application in Transaction Manager for Microservices Developer Guide.

To run the sample TCC application using the runme.sh script file:

1. Enter the following commands in a bash shell to run the runme.sh script file.

   cd installation_directory/otmm-<version>
   sh runme.sh

2. Type 2 to run sample applications in the Minikube environment.
   The script sets up Minikube, configures Istio service mesh, loads the Docker image of MicroTx, and then installs MicroTx. After completing the installation, the script runs the transaction coordinator and provides the URL of the transaction coordinator.
3. Type 1 to run sample applications and MicroTx in non-secure mode in your test environment.

   You may have to wait for a few seconds while the script loads the images of the sample applications, and then installs it.

   When the script displays the full path that you must set for the KUBECONFIG environment variable, you can perform the next step.

4. Copy the command returned by the script, and then run the command in a new terminal. Set KUBECONFIG to configure Kubectl to run commands on Minikube.

   The script displays the actual command which you can copy and run as it is in a new terminal. The following is a sample command. The actual command that the script returns depends on the value of the $HOME variable.

   export KUBECONFIG=$HOME/.kube/minikube

5. Run the following command in a new terminal to start a tunnel between Minikube and the Istio ingress gateway.

   $ minikube tunnel

   If prompted, enter the password to access your local system, and then press any key to continue running the script.

6. Type 3 to run the sample application that uses the TCC transaction protocol.
7. Type 1 to run Java applications or type 2 to run Node.js applications.
   The script installs and then runs the three sample microservices: Flight booking, Hotel booking, and Travel agent.
8. Type y to confirm that you want to run the TCC sample application, and then press Enter.
   The sample application reserves a hotel room and a flight ticket and displays the reservation details.
9. Confirm or cancel the booking. Type y to confirm the booking or type n to cancel the booking, and then press Enter.

   If you type y, the booking is confirmed and details about the confirmed booking are displayed.

   If you type n, the Travel Agent microservice cancels the reserved resources and returns the resources back to the inventory.

10. Press any key to exit.
11. Type 1 to stop running all the microservices in the sample application and uninstall it.
12. Type 1 to uninstall MicroTx. If you want use the existing installation to run other sample applications, type 2.
13. Type 1 to uninstall Istio. If you want use the existing installation to run other sample applications, type 2.

What's next?

• Use the Kiali dashboard to view how the MicroTx handles the flow of requests between the sample microservices.
• Perform distributed tracing using Jaeger to trace the entire transaction. See Perform Distributed Tracing with Jaeger.
• Run another sample application.
• View the source files of the sample application.
• View the log files to find more details about the transactions.
• Create and run your own application using MicroTx.