Chapter 2. Getting Started with Red Hat Data Grid for OpenShift

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

Template	Description	Requires OpenShift Secrets
datagrid72-image-stream	Provides a jboss-datagrid72-openshift image stream for JBoss Data Grid.	No
datagrid72-basic	Configures the image so you can run JBoss Data Grid on Red Hat OpenShift without the need to create OpenShift Secrets.	No
datagrid72-https	Configures the image to create an HTTPS route that requires authentication to access JBoss Data Grid.	Yes. Requires OpenShift Secrets for an SSL keystore and JGroups configurations.
datagrid72-mysql	Configures the image so you can run JBoss Data Grid with a MySQL database that provides an ephemeral cache store.	Yes. Requires OpenShift Secrets for an SSL keystore and JGroups configurations.
datagrid72-mysql-persistent	Configures the image so you can run JBoss Data Grid with a MySQL database that provides a persistent cache store.	Yes. Requires OpenShift Secrets for an SSL keystore and JGroups configurations.
datagrid72-postgresql	Configures the image so you can run JBoss Data Grid with a PostgreSQL database that provides an ephemeral cache store.	Yes. Requires OpenShift Secrets for an SSL keystore and JGroups configurations.
datagrid72-postgresql-persistent	Configures the image so you can run JBoss Data Grid with a PostgreSQL database that provides a persistent cache store.	Yes. Requires OpenShift Secrets for an SSL keystore and JGroups configurations.
datagrid72-partition	Configures the image so you can run JBoss Data Grid with a partitioned data directory. This enables the Data Grid for OpenShift deployment to preserve metadata for cache entries when the pod restarts with the DATAGRID_SPLIT environment variable. For more information, see Configuration Environment Variables.	No

2.1. Importing Data Grid for OpenShift Image Templates

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

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
```

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.2/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.2/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.

Verify the templates are available on OpenShift.

$ oc get templates -n openshift | grep datagrid72

2.1.1. Working with the Data Grid for OpenShift Image

Importing the 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.

2.1.1.1. Viewing Information about the Data Grid for OpenShift Image

Run the following command after you import the image templates to view the available image streams for 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 at registry.redhat.io.

2.1.1.2. Importing the Data Grid for OpenShift Image

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

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

$ oc -n openshift import-image jboss-datagrid72-openshift:1.2

Note

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.

2.2. Configuring Data Grid for OpenShift Deployments

You configure 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.

2.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.

2.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 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.

2.2.2.1. Instantiating the Template

Create a new project.

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

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
```
Check the application status.
```
$ oc status
```

2.2.2.2. Listing Environment Variables

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

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
...

2.2.2.3. Changing Environment Variables

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.

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

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
...

2.2.3. Modifying 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.

2.2.3.1. Exporting the Template

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
```
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
```

2.2.3.2. Modifying the Template

Open the exported datagrid72-extended file with any text editor.
Tip
Templates define the deployment configuration in yaml or json format.
In the labels section, change the template label to datagrid72-extended.
```
labels:
  template: datagrid72-extended
```
In the metadata section, change the template name to datagrid72-extended.
```
metadata:
  name: datagrid72-extended
```

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

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}
```
Save and close the datagrid72-extended file.

2.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
...

2.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.

2.3.1. Creating a Project and Instantiate a Template

Create a new project.

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

Instantiate the datagrid72-basic template.

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

2.3.2. Examining Deployed Services

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.2
    deployment

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

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.

2.3.3. Invoking a Get Operation on the Cache

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

2.3.4. Inserting and Retrieving an Entry in the Cache

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

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\"}"

2.3.5. Deleting the Entry from the Cache

Delete the key named a.

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

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.

Where did the comment section go?

Red Hat's documentation publication system recently went through an upgrade to enable speedier, more mobile-friendly content. We decided to re-evaluate our commenting platform to ensure that it meets your expectations and serves as an optimal feedback mechanism. During this redesign, we invite your input on providing feedback on Red Hat documentation via the discussion platform.

Log in to Your Red Hat Account

Red Hat Account

Customer Portal

Select Your Language

Infrastructure and Management

Cloud Computing

Storage

JBoss Development and Management

JBoss Integration and Automation

Mobile

Services

Tools

Red Hat Product Security Center

Security Updates

Resources

Customer Portal Community

Customer Events

Stories

Chapter 2. Getting Started with Red Hat Data Grid for OpenShift

2.1. Importing Data Grid for OpenShift Image Templates

2.1.1. Working with the Data Grid for OpenShift Image

2.1.1.1. Viewing Information about the Data Grid for OpenShift Image

2.1.1.2. Importing the Data Grid for OpenShift Image

2.2. Configuring Data Grid for OpenShift Deployments

2.2.1. Getting Started with Image Configuration

2.2.2. Setting Parameters on the Command Line

2.2.2.1. Instantiating the Template

2.2.2.2. Listing Environment Variables

2.2.2.3. Changing Environment Variables

2.2.3. Modifying Data Grid for OpenShift Image Templates

2.2.3.1. Exporting the Template

2.2.3.2. Modifying the Template

2.2.3.3. Importing and Instantiating the Modified Template

2.3. Invoking Cache Operations Through the REST Endpoint

2.3.1. Creating a Project and Instantiate a Template

2.3.2. Examining Deployed Services

2.3.3. Invoking a Get Operation on the Cache

2.3.4. Inserting and Retrieving an Entry in the Cache

2.3.5. Deleting the Entry from the Cache

Where did the comment section go?