Red Hat Training

A Red Hat training course is available for Red Hat JBoss Data Virtualization

Chapter 5. Tutorials

These tutorials build on from the environment created in the OpenShift Primer and from the information in the previous chapter.

For a different end-to-end demonstration for deploying JDV for OpenShift, see the four-part Red Hat JBoss Data Virtualization on OpenShift article series on the Red Hat Developer Program Blog:

5.1. Example Workflow: Deploying a JDV Project Using the JDV for OpenShift Image

This Example Worfklow downloads and deploys the dynamicvdb-datafederation quickstart available in the jboss-openshift GitHub. This quickstart federates data from a relational data source (H2, Derby, MySQL, or PostgreSQL) and an EXCEL file. H2 and Derby data sources are embedded in the JDV for OpenShift pod; MySQL and PostgreSQL data sources deploy in separate pods. The default quickstart deploys a H2 data source.

After deployment, this example will demonstrate how to use the QS-DB-TYPE environment variable to define an alternate data source. This variable is only applicable to the quickstart and is not valid for other deployments.

5.1.1. Preparing Red Hat JBoss Data Virtualization for OpenShift Deployment

  1. Create a new project: 

    $ oc new-project jdv-app-demo

  2. Create a service account to be used for the Red Hat JBoss Data Virtualization for OpenShift deployment: 

    $ oc create serviceaccount datavirt-service-account

  3. Add the view role to the service account. This enables the service account to view all the resources in the jdv-app-demo namespace, which is necessary for managing the cluster. 

    $ oc policy add-role-to-user view system:serviceaccount:jdv-app-demo:datavirt-service-account

  4. The Red Hat JBoss Data Virtualization for OpenShift template requires an SSL keystore and a JGroups keystore.
    These keystores are expected even if the application will not use https.
    This example uses ‘keytool’, a package included with the Java Development Kit, to generate self-signed certificates for these keystores. The following commands will prompt for passwords.

    1. Generate a secure key for the SSL keystore: 

      $ keytool -genkeypair -alias https -storetype JKS -keystore keystore.jks

    2. Generate a secure key for the JGroups keystore: 

      $ keytool -genseckey -alias jgroups -storetype JCEKS -keystore jgroups.jceks

  5. Use the SSL and JGroup keystore files to create the keystore secret for the project: 

    $ oc secret new datavirt-app-secret keystore.jks jgroups.jceks

  6. Create a secret with the datasources.env file, an environment file containing the data sources and necessary resource adapters. This file needs to be stored locally. Either clone the jboss-openshift/openshift-quickstarts repository from GitHub, or download the environment file from:
    https://github.com/jboss-openshift/openshift-quickstarts/blob/master/datavirt/dynamicvdb-datafederation/datasources.env 

    $ oc secrets new datavirt-app-config datasources.env

  7. Link the keystore and environment secrets to the service account created earlier: 

    $ oc secrets link datavirt-service-account datavirt-app-secret datavirt-app-config

5.1.2. Deployment

Use the OpenShift web console to configure a JDV for OpenShift application template with the quickstart details.

  1. Log in to the OpenShift web console and select the jdv-app-demo project space.
  2. Click Add to Project to list all of the default image streams and templates.
  3. Use the Filter by keyword search bar to limit the list to those that match datavirt and select datavirt63-secure-s2i.
  4. Specify the following:
    SOURCE_REPOSITORY_URL: https://github.com/jboss-openshift/openshift-quickstarts
    SOURCE_REPOSITORY_REF: master
    CONTEXT_DIR: datavirt/dynamicvdb-datafederation/app
  5. Click Deploy.

5.1.3. Defining Alternate Data Sources

The dynamicvdb-datafederation quickstart uses the QS_DB_TYPE environment variable to determine the data source to use. This value is set to h2 by default. After the quickstart has been deployed, this variable can be added to the deployment configuration and modified so that an alternate data source is used.
For example, to modify the deployment configuration so that the deployment uses a MySQL data source: 

$ oc env dc/datavirt-app QS_DB_TYPE=mysql5

The dynamicvdb-datafederation quickstart has been prepared with H2, Derby, MySQL, and PostgreSQL data sources.

5.2. Example Workflow: Deploying the JDG for OpenShift as a Materialization Target Quickstart

This Example Worfklow continues from Example Workflow: Deploying a JDV Project Using the JDV for OpenShift Image, and presumes that the dynamicvdb-datafederation quickstart has been successfully deployed. In this example, a JDG for OpenShift instance will be prepared and deployed so that JDV for OpenShift can use it as a materialization target.

5.2.1. Preparing the Project to Deploy JDG for OpenShift

  1. Ensure you are in the jdv-app-demo project: 

    $ oc project jdv-app-demo

  2. Create a service account for JDG for OpenShift: 

    $ oc create serviceaccount datagrid-service-account

  3. Add the view role to the service account. This enables the service account to view all the resources in the jdv-app-demo namespace, which is necessary for managing the cluster. 

    $ oc policy add-role-to-user view system:serviceaccount:jdv-app-demo:datagrid-service-account

  4. Use the JGroup keystore file (created in Example Workflow: Deploying a JDV Project Using the JDV for OpenShift Image to create the keystore secret for the project: 

    $ oc secret new datagrid-app-secret jgroups.jceks

  5. Link the keystore secret to the service account created earlier: 

    $ oc secrets link datagrid-service-account datagrid-app-secret

5.2.2. Deploying JDG for OpenShift

A JDG for OpenShift instance needs to be deployed, with necessary caches specified, so that JDV for OpenShift can use it as a materialization target for the databases. Any of the JDG for OpenShift templates can be used, however non-persistent templates are recommended to gain clustering and high availability benefits. This example uses the datagrid65-https template to take advantage of SSL.

  1. Log in to the OpenShift web console and select the jdv-app-demo project space.
  2. Click Add to Project to list all of the default image streams and templates.
  3. Use the Filter by keyword search bar to limit the list to those that match datagrid. You may need to click See all to show the desired application template.

  4. Select the datagrid65-https template.

    1. In the DATAVIRT_CACHE_NAMES environment variable field, enter addressbook. This configures the three caches required (addressbook, addressbook_staging, and addressbook_alias) for addressbook to be used as a materialization cache for the database.
    2. Ensure the CACHE_TYPE_DEFAULT environment variable is set to replicated.
  5. Click Deploy

5.2.3. Configure JDV for OpenShift to use JDG for OpenShift as a Materialization Target

After the JDG for OpenShift instance is running, modify the JDV for OpenShift deployment so that it uses JDG as a materialization target. Add the DATAGRID_MATERIALIZATION environment variable to the build configuration: 

$ oc env bc/datavirt-app DATAGRID_MATERIALIZATION=true