SupportConsoleDevelopersStart a trialContact

Chapter 3. Getting Started with Red Hat JBoss Data Grid for OpenShift

JBoss Data Grid provides an JBoss Data Grid for OpenShift image stream and set of templates to help you quickly get up and running with JBoss Data Grid deployments on Red Hat OpenShift.

datagrid72-image-stream
Image stream for JBoss Data Grid.
datagrid72-basic
Run JBoss Data Grid for OpenShift without the need to create OpenShift Secrets.
datagrid72-https
Run JBoss Data Grid for OpenShift with an HTTPS route to securely access caches. Requires a JKS keystore in an OpenShift secret.
datagrid72-mysql
Run JBoss Data Grid for OpenShift with a MySQL database as an ephemeral cache store. Requires a JKS keystore in an OpenShift secret.
datagrid72-mysql-persistent
Run JBoss Data Grid for OpenShift with a MySQL database as a persistent cache store. Requires a JKS keystore in an OpenShift secret.
datagrid72-postgresql
Run JBoss Data Grid for OpenShift with a PostgreSQL database as an ephemeral cache store. Requires a JKS keystore in an OpenShift secret.
datagrid72-postgresql-persistent
Run JBoss Data Grid for OpenShift with a PostgreSQL database as a persistent cache store. Requires a JKS keystore in an OpenShift secret.
datagrid72-partition
Run JBoss Data Grid for OpenShift with a partitioned data directory that preserves metadata for cache entries when the pod restarts. Requires the DATAGRID_SPLIT environment variable. See Configuration Environment Variables.

3.1. Importing JBoss Data Grid for OpenShift Image Templates

The first step to using the JBoss Data Grid for OpenShift image templates is to import them into OpenShift as follows:

  1. On your master host(s), log in as a cluster administrator or a user with project administrator access to the openshift namespace. 

    $ oc login -u system:admin

  2. Import a specific template or all templates.

    • Import a specific template: 

      $ oc create -n openshift -f \
https://raw.githubusercontent.com/jboss-container-images/jboss-datagrid-7-openshift-image/1.3/templates/datagrid72-mysql.json

    • Import all templates: 

      $ for resource in datagrid72-image-stream.json \
  datagrid72-basic.json \
  datagrid72-https.json \
  datagrid72-mysql-persistent.json \
  datagrid72-mysql.json \
  datagrid72-partition.json \
  datagrid72-postgresql.json \
  datagrid72-postgresql-persistent.json
do
  oc create -n openshift -f \
  https://raw.githubusercontent.com/jboss-container-images/jboss-datagrid-7-openshift-image/1.3/templates/${resource}
done
      Tip

      Use the oc create command to import a new template. Use the oc replace --force command to overwrite an existing template.

  3. Verify the templates are available on OpenShift. 

    $ oc get templates -n openshift | grep datagrid72

3.1.1. Working with the JBoss Data Grid for OpenShift Image

Importing the JBoss Data Grid for OpenShift image templates also imports the jboss-datagrid72-openshift image. When you create a new application from a template, or instantiate a template, you deploy the image in a pod that uses the configuration settings from the template.

In this way, the jboss-datagrid72-openshift image is a general purpose build of JBoss Data Grid. Each template configures the image for specific purposes.

3.1.1.1. Viewing Information about the JBoss Data Grid for OpenShift Image

Run the following command after you import the image templates to view the available image streams for JBoss Data Grid for OpenShift: 

$ oc get is -n openshift | grep datagrid

The oc get command shows the jboss-datagrid72-openshift image stream is available in the openshift namespace. This image stream defines the JBoss Data Grid container image as an available resource for creating deployments.

Run the following command to view information about the jboss-datagrid72-openshift image stream: 

$ oc describe is jboss-datagrid72-openshift -n openshift

The oc describe command shows the tags for the jboss-datagrid72-openshift image stream as well as the location for the container image in the registry.

3.1.1.2. Importing the JBoss Data Grid for OpenShift Image

You can optionally import the JBoss Data Grid for OpenShift image into the openshift namespace separately to the templates.

To import the JBoss Data Grid for OpenShift image, run the following command: 

$ oc -n openshift import-image jboss-datagrid72-openshift:1.3
Note

JBoss Data Grid for OpenShift templates use the global openshift namespace as the default for the jboss-datagrid72-openshift image stream. You can set the IMAGE_STREAM_NAMESPACE environment variable to import templates in a different namespace or project. However you must also ensure that an image stream is available in that namespace.

3.1.2. Importing OpenShift Secrets

You must import or create OpenShift secrets that contain HTTPS and JGroups keystores before you can instantiate templates that require authentication.

JBoss Data Grid for OpenShift provides an example HTTPS and JGroups keystore that you can import as an OpenShift secret. However, this secret is intended for evaluation purposes only. You should not use it in production environments.

Do the following to import the example secret into your project namespace: 

$ oc create \
  -f https://raw.githubusercontent.com/jboss-openshift/application-templates/master/secrets/datagrid-app-secret.json

For more information about creating secrets to secure network traffic, see Securing Network Traffic.

3.2. Configuring JBoss Data Grid for OpenShift Deployments

You configure JBoss Data Grid for OpenShift deployments with environment variables that you can set:

  • on the command line when you create new applications from templates.
  • in templates that you import into OpenShift projects. You can then create pre-configured deployments from those templates.

You can also set environment variables through the OpenShift Web Console. See the relevant OpenShift documentation.

3.2.1. Getting Started with Image Configuration

Run the following command to show the datagrid72-basic template: 

$ oc describe template datagrid72-basic -n openshift

The output of the oc describe command shows information about the template as well as the parameters that are set in the template. When you instantiate the datagrid72-basic template, those parameters configure the following objects:

  • Service defines a logical set of pods and access policies.
  • Route exposes services externally to pods.
  • Deployment Configuration configures triggers and replicas for the replication controller; also configures pod templates that contain exposed ports for services, environment variables for the image, and so on.

As an example, the output of the oc describe command shows the following template parameters that set credentials and name caches: 

Parameters:

  Name:		USERNAME
  Display Name:	Username
  Description:	Data Grid username.
  Required:	false
  Value:	<none>

  Name:		PASSWORD
  Display Name:	Password
  Description:	Password for the Data Grid user.
  Required:	false
  Value:	<none>

  Name:		CACHE_NAMES
  Display Name:	Cache Names
  Description:	Comma-separated list of caches to create.
  Required:	false
  Value:	<none>

The output of the oc describe command shows the services, routes, and deployment configuration that the datagrid72-basic template configures: 

Objects:
    Service		${APPLICATION_NAME}
    Service		${APPLICATION_NAME}-memcached
    Service		${APPLICATION_NAME}-hotrod
    Service		${APPLICATION_NAME}-ping
    Route		${APPLICATION_NAME}
    DeploymentConfig	${APPLICATION_NAME}

When you instantiate the datagrid72-basic template, the launch script sets those parameters as environment variables for the image in the deployment configuration.

3.2.2. Setting Parameters on the Command Line

Learn how to set parameters for JBoss Data Grid deployments on the command line.

Complete the following steps to:

  • Instantiate the datagrid72-basic template to create a new JBoss Data Grid for OpenShift deployment.

  • Set parameters that:

    • Define credentials to access the cache over HTTPS and Hot Rod.
    • Create a cache named mycache.
    • Configure the cache to start eagerly.

3.2.2.1. Instantiating the Template

  1. Create a new project. 

    $ oc new-project datagrid-env --display-name="Setting Environment Variables"

  2. Deploy a new application with the datagrid72-basic template. Use the -e option to pass parameter and value pairs.

    1. Specify a username: -e USERNAME=developer

    2. Specify a password: -e PASSWORD=<value>

      The password cannot be the same as the username or root, admin, or, administrator. It must contain at least 8 characters, 1 alphabetic character(s), 1 digit(s), and 1 non-alphanumeric symbol(s).

    3. Create a cache named 'mycache': -e CACHE_NAMES=mycache

    4. Configure the cache to start eagerly: -e MYCACHE_CACHE_START=EAGER 

      $ oc new-app --template=datagrid72-basic --name=rhdg \
  -e USERNAME=developer -e PASSWORD=******** \
  -e CACHE_NAMES=mycache -e MYCACHE_CACHE_START=EAGER

  3. Check the application status. 

    $ oc status

3.2.2.2. Listing Environment Variables

  1. Retrieve the available pods in the project. 

    $ oc get pods

NAME                    READY     STATUS    RESTARTS   AGE
datagrid-app-1-<id>     0/1       Running   1          1m
datagrid-app-1-deploy   1/1       Running   0          1m

  2. List environment variables for the pod named datagrid-app-1-<id>. Where <id> is a randomly generated string such as 67q5h. 

    $ oc env pods/datagrid-app-1-<id> --list

# pods datagrid-app-1-<id>, container datagrid-app
CACHE_NAMES=mycache
MYCACHE_CACHE_START=EAGER
PASSWORD=********
USERNAME=developer
...

3.2.2.3. Changing Environment Variables

  1. Change the deployment configuration so that the cache starts lazily. 

    $ oc env dc/datagrid-app -e MYCACHE_CACHE_START=LAZY

    This command triggers the replication controller to deploys a new version of the application.

  2. Retrieve the updated list of pods. 

    $ oc get pods

NAME                    READY     STATUS    RESTARTS   AGE
datagrid-app-2-<id>     0/1       Running   0          58s
datagrid-app-2-deploy   1/1       Running   0          59s

  3. List environment variables for the pod named datagrid-app-2-<id>. 

    $ oc env pods/datagrid-app-2-<id> --list

# pods datagrid-app-2-<id>, container datagrid-app
CACHE_NAMES=mycache
MYCACHE_CACHE_START=LAZY
PASSWORD=********
USERNAME=developer
...

3.2.3. Modifying JBoss Data Grid for OpenShift Image Templates

Learn how to set parameters for JBoss Data Grid deployments in reusable image templates.

Complete the following steps to:

  • Export the datagrid72-basic template from Red Hat OpenShift.

  • Modify the datagrid72-basic template to set parameters that:

    • Define credentials to access the cache over HTTPS and Hot Rod.
    • Create a cache named mycache.
    • Configure the cache to start eagerly.
  • Import the modified template and instantiate it.

3.2.3.1. Exporting the Template

  1. On your master host(s), log in as a cluster administrator or a user with project administrator access to the openshift namespace. 

    $ oc login -u system:admin

  2. Export the datagrid72-basic template to a file named datagrid72-extended.

    Tip

    You can export templates with any filename to your home (~/) directory. 

    $ oc export template datagrid72-basic -n openshift > datagrid72-extended

3.2.3.2. Modifying the Template

  1. Open the exported datagrid72-extended file with any text editor.

    Tip

    Templates define the deployment configuration in yaml or json format.

  2. In the labels section, change the template label to datagrid72-extended. 

    labels:
  template: datagrid72-extended

  3. In the metadata section, change the template name to datagrid72-extended. 

    metadata:
  name: datagrid72-extended

  4. In the parameters section, add values for the USERNAME, PASSWORD, CACHE_NAMES, and <CACHE_NAME>_CACHE_START environment variables. 

    parameters:
- description: Data Grid username.
  displayName: Username
  name: USERNAME
  value: developer

- description: Password for the Data Grid user.
  displayName: Password
  name: PASSWORD
  value: ********

- description: Comma-separated list of caches to configure.
  displayName: Cache Names
  name: CACHE_NAMES
  value: mycache

- description: Configures the cache to start eagerly or lazily.
  displayName: Cache Start
  name: MYCACHE_CACHE_START
  required: false
  value: EAGER

  5. Add an 'env' definition for the <CACHE_NAME>_CACHE_START environment variable to the deployment configuration. 

    spec:
  containers:
    -env:
      -name: MYCACHE_CACHE_START
       value: ${MYCACHE_CACHE_START}
  6. Save and close the datagrid72-extended file.

3.2.3.3. Importing and Instantiating the Modified Template

Import the modified template into the openshift namespace. 

$ oc create -n openshift -f datagrid72-extended

After you import the modified template, instantiate it and then list environment variables for the deployed pod. 

$ oc new-app --template=datagrid72-extended

$ oc status

$ oc get pods

$ oc env pods/datagrid-app-1-<id> --list

# pods datagrid-app-1-<id>, container datagrid-app
CACHE_NAMES=mycache
MYCACHE_CACHE_START=EAGER
PASSWORD=********
USERNAME=developer
...

3.3. Invoking Cache Operations Through the REST Endpoint

JBoss Data Grid provides a REST endpoint through which you can invoke cache operations using standard HTTP methods. The REST endpoint is available by default without the need for configuration.

Complete the following steps to:

  • Create a new project and instantiate the datagrid72-basic template.
  • Invoke cache operations with the HTTP GET, POST, and DELETE methods.

3.3.1. Creating a Project and Instantiate a Template

  1. Log in to OpenShift. 

    $ oc login -u developer

  2. Create a new project. 

    $ $ oc new-project datagrid --display-name="RHDG REST Example"

  3. Instantiate the datagrid72-basic template. 

    $ oc new-app --template=datagrid72-basic --name=rhdg

3.3.2. Examining Deployed Services

  1. View the deployment status. 

    $ oc status

    The oc status command shows a datagrid-app HTTP service. 

    In project RHDG REST Example (datagrid) on server https://192.0.2.0:8443

http://datagrid-app-datagrid.192.0.2.0.nip.io (svc/datagrid-app)
  dc/datagrid-app deploys openshift/jboss-datagrid72-openshift:1.3
    deployment

  2. Show details about the datagrid-app route. 

    $ oc describe route datagrid-app

    The oc describe route command shows the route where the HTTP service is exposed. 

    Name:			datagrid-app
Namespace:		datagrid
Created:		4 minutes ago
Labels:			app=rhdg
			application=datagrid-app
			template=datagrid72-basic
			xpaas=<version>
Description:		Route for application's HTTP service.
Annotations:		openshift.io/generated-by=OpenShiftNewApp
			openshift.io/host.generated=true
Requested Host:		datagrid-app-datagrid.192.0.2.0.nip.io
			  exposed on router router 4 minutes ago
  3. Note the hostname and IP address for the route. In the following command examples, you must substitute 192.0.2.0 with the correct IP address for your route to the REST endpoint.

3.3.3. Invoking a Get Operation on the Cache

  1. Attempt to get a value for a key named a from a cache named default. 

    $ curl -i -H "Accept:application/json" \
http://rhdgroute-datagrid.192.0.2.0.nip.io/rest/default/a

    The key named a does not exist in the cache named default. As a result, you get an HTTP 404 error. 

    HTTP/1.1 404 Not Found
content-length: 0
Set-Cookie: 3abf86065a054efa9e7658b871f83223=b78127f864341eb60be6916d847b8b06; path=/; HttpOnly
Cache-control: private

3.3.4. Inserting and Retrieving an Entry in the Cache

  1. Insert a JSON formatted entry in a key named a into the cache named default. 

    $ curl -X POST -i -H "Content-type:application/json" \
-d "{\"name\":\"Red Hat Data Grid\"}" \
http://rhdgroute-datagrid.192.0.2.0.nip.io/rest/default/a

  2. Get the value of the key that you inserted. 

    $ curl -i -H "Accept:application/json" \
http://rhdgroute-datagrid.192.0.2.0.nip.io/rest/default/a

    You get an HTTP 200 response that contains the key value you set. 

    HTTP/1.1 200 OK
etag: 1187661430
last-modified: <time-stamp>
content-type: application/json
content-length: 34
Set-Cookie: 3abf86065a054efa9e7658b871f83223=b78127f864341eb60be6916d847b8b06; path=/; HttpOnly
Cache-control: private

"{\"name\":\"Red Hat Data Grid\"}"

3.3.5. Deleting the Entry from the Cache

  1. Delete the key named a. 

    $ curl -X DELETE -i \
http://rhdgroute-datagrid.192.0.2.0.nip.io/rest/default/a

  2. Attempt to retrieve the key value again. 

    $ curl -i -H "Accept:application/json" \
http://rhdgroute-datagrid.192.0.2.0.nip.io/rest/default/a

    You get an HTTP 404 error because you deleted the key.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.