Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart 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.

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
    Copy to Clipboard Toggle word wrap

  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
      Copy to Clipboard Toggle word wrap

    • 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
      Copy to Clipboard Toggle word wrap
      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
    Copy to Clipboard Toggle word wrap

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.

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
Copy to Clipboard Toggle word wrap

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
Copy to Clipboard Toggle word wrap

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.

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
Copy to Clipboard Toggle word wrap
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
Copy link

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
Copy to Clipboard Toggle word wrap

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

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
Copy link

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

$ oc describe template datagrid72-basic -n openshift
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap

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}
Copy to Clipboard Toggle word wrap

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
Copy link

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
Copy link

  1. Create a new project. 

    $ oc new-project datagrid-env --display-name="Setting Environment Variables"
    Copy to Clipboard Toggle word wrap

  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
      Copy to Clipboard Toggle word wrap

  3. Check the application status. 

    $ oc status
    Copy to Clipboard Toggle word wrap

3.2.2.2. Listing Environment Variables
Copy link

  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
    Copy to Clipboard Toggle word wrap

  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
...
    Copy to Clipboard Toggle word wrap

3.2.2.3. Changing Environment Variables
Copy link

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

    $ oc env dc/datagrid-app -e MYCACHE_CACHE_START=LAZY
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

  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
...
    Copy to Clipboard Toggle word wrap

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
Copy link

  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
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

3.2.3.2. Modifying the Template
Copy link

  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
    Copy to Clipboard Toggle word wrap

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

    metadata:
  name: datagrid72-extended
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

  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}
    Copy to Clipboard Toggle word wrap
  6. Save and close the datagrid72-extended file.

Import the modified template into the openshift namespace. 

$ oc create -n openshift -f datagrid72-extended
Copy to Clipboard Toggle word wrap

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
...
Copy to Clipboard Toggle word wrap

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.

  1. Log in to OpenShift. 

    $ oc login -u developer
    Copy to Clipboard Toggle word wrap

  2. Create a new project. 

    $ $ oc new-project datagrid --display-name="RHDG REST Example"
    Copy to Clipboard Toggle word wrap

  3. Instantiate the datagrid72-basic template. 

    $ oc new-app --template=datagrid72-basic --name=rhdg
    Copy to Clipboard Toggle word wrap

3.3.2. Examining Deployed Services
Copy link

  1. View the deployment status. 

    $ oc status
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

  2. Show details about the datagrid-app route. 

    $ oc describe route datagrid-app
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap
  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
Copy link

  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
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

    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\"}"
    Copy to Clipboard Toggle word wrap

3.3.5. Deleting the Entry from the Cache
Copy link

  1. Delete the key named a. 

    $ curl -X DELETE -i \
http://rhdgroute-datagrid.192.0.2.0.nip.io/rest/default/a
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

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

Back to top
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. Explore our recent updates.

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.

Theme

© 2025 Red Hat