coherence-operator

Quick Start Guide

The Quick Start guide provides a simple tutorial to help you get the operator up and running quickly. The Coherence Operator (the “operator”) manages Coherence through Kubernetes, monitors MBean attributes through Prometheus, and server logs through Elasticsearch and Kibana.

Note: Use of Prometheus and Grafana is available only when using the operator with Oracle Coherence 12.2.1.4.

Introduction

Use this Quick Start guide to deploy Coherence applications in a Kubernetes cluster managed by the operator. Note that this guide is for demonstration purposes only, and not sufficiently prescriptive or thorough for a production environment.

These instructions assume that you are already familiar with Kubernetes and Helm. If you want to learn more about these two technologies, refer to the Kubernetes and Helm documentation.

For more advanced actions, such as accessing Kibana for viewing server logs, see the User Guide.

Note: If you have an older version of the operator installed on your cluster, you must remove it before installing the current version.

Before You Begin

Software Requirements

The operator has the following requirements:

Runtime Environment Requirements

Configure the Environment

Add the Helm Repository for Coherence

Create a coherence helm repository:

$ helm repo add coherence https://oracle.github.io/coherence-operator/charts

$ helm repo update

If you want to build the operator from source, refer to the Developer Guide and ensure that you replace the coherence Helm repository prefix in all samples with the fully qualified directory as described at the end of the guide.

Install the Operator

  1. Use helm to install the operator:
$ helm --debug install coherence/coherence-operator \
    --name sample-coherence-operator \
    --set "targetNamespaces={}" \
    --set imagePullSecrets=sample-coherence-secret

Note: For all helm install commands, you can leave the --version option off if you want the latest version of the chart to be retrieved. However, if you want to use a specific version, such as 0.9.8, add --version 0.9.8 to all installs for the coherence-operator and coherence charts.

Note: Remove the --debug option if you do not want verbose output. Refer to the values.yaml in the chart for more information about the --set targetNamespaces argument.

When the operation completes successfully, the Helm installation produces an output similar to the following:

NOTES:
Coherence Operator successfully installed.

Monitoring namespaces:
  ""
  1. Use helm ls to view the installed releases.
$ helm ls

NAME                     	REVISION	UPDATED                 	STATUS  	CHART                   	APP VERSION	NAMESPACE
sample-coherence-operator	1       	Thu May  9 13:59:22 2019	DEPLOYED	coherence-operator-0.9.8	0.9.8      	default
  1. Verify the status of the operator using helm status:
$ helm status sample-coherence-operator

A successful deployment displays an output similar to the following:

LAST DEPLOYED: Thu Feb  7 14:11:17 2019
STATUS: DEPLOYED

[...]

Install Coherence

Obtain Images from Oracle Container Registry

By default, the Helm chart pulls the Oracle Coherence Docker image from the Oracle Container Registry. To pull the image correctly for the first time, you must perform the following steps:

  1. In a web browser, navigate to Oracle Container Registry and click Sign In.
  2. Enter your Oracle credentials or create an account if you don’t have one.
  3. Search for coherence in the Search Oracle Container Registry field.
  4. Click coherence in the search result list.
  5. On the Oracle Coherence page, select the language from the drop-down list and click Continue.
  6. Click Accept on the Oracle Standard Terms and Conditions page.

Subsequently, the image will be pulled automatically using the Kubernetes secret.

This action is required to pull the image correctly for the first time. After this, the image will be pulled automatically using the Kubernetes secret.

Set Up Secrets to Access the Oracle Container Registry

Create a Kubernetes secret with the Oracle Container Registry credentials:

 $ kubectl create secret docker-registry oracle-container-registry-secret \
     --docker-server=container-registry.oracle.com \
     --docker-username='<username>' --docker-password='<password>' \
     --docker-email=`<emailid>`

When installing Coherence, refer to the secret and Kubernetes will use that secret when pulling the image.

Note: Kubernetes secrets are not global. Any Kubernetes secret will be scoped to a namespace. If a namespace is not specified, the secret will be created in the default namespace. So, if you are installing coherence cluster in a specific namespace then you also need to create docker-registry secret in that namespace by passing –namespace option to kubectl create secret command shown above.

Use Helm to Install Coherence

Install the coherence helm chart using the secret ‘oracle-container-registry-secret’ which was created using the kubectl create secret command.

$ helm --debug install coherence/coherence \
    --name sample-coherence \
    --set imagePullSecrets=oracle-container-registry-secret

Note: If you want to use a different version of Coherence than the one specified in the coherence Helm chart, supply a --set argument for the coherence.image value:

--set coherence.image="<prefix>/coherence:<version>"

Use the command helm inspect readme <chart name> to print out the README.md of the chart. For example, helm inspect readme coherence/coherence prints out the README.md for the operator chart. This includes documentation on all the possible values that can be configured with --set options to helm. Refer to the Configuration section of README.

When the operation completes successfully, you see output similar to the following.

NOTES:
1. Get the application URLs by running these commands:

  export POD_NAME=$(kubectl get pods -l "app=coherence,release=sample-coherence" -o jsonpath="{.items[0].metadata.name}")

  To forward a local port to the Pod Coherence*Extend port run:

      kubectl port-forward $POD_NAME 20000:20000

  then access the Coherence*Extend endpoint at 127.0.0.1:20000

  To forward a local port to the Pod Http port run:

      kubectl port-forward $POD_NAME 30000:30000

  then access the http endpoint at http://127.0.0.1:30000

You can also query the status of the installed Coherence using helm status:

$ helm status sample-coherence
LAST DEPLOYED: Wed Feb 13 14:51:38 2019
STATUS: DEPLOYED
[...]

Running helm install creates a helm release. See the Helm Glossary for the definition of Release.

Access the Installed Coherence

You can access the installed Coherence running within your Kubernetes using the default Coherence*Extend feature.

When starting Coherence with no options, the created Coherence cluster has three nodes, and exposes a Coherence*Extend proxy server on port 20000 in the cluster. You must forward this port so that it is available outside the cluster. You can use the kubectl command by supplying the name of the Kubernetes pod that is running the Coherence.

Query the Kubernetes cluster to get the name of the first of the three nodes in the Coherence cluster.

$ export POD_NAME=$(kubectl get pods -l "app=coherence,release=sample-coherence" -o jsonpath="{.items[0].metadata.name}")

The name of the cluster will be similar to sample-coherence-65f558c987-5bdxr. Then, map the port 20000 inside the cluster to port 20000 outside the cluster.

$ kubectl port-forward $POD_NAME 20000:20000

With this information, you can write a Coherence*Extend client configuration to access the cluster. Save the following XML in a file called example-client-config.xml:

<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config
   coherence-cache-config.xsd">
   <caching-scheme-mapping>
      <cache-mapping>
         <cache-name>*</cache-name>
         <scheme-name>thin-remote</scheme-name>
      </cache-mapping>
   </caching-scheme-mapping>

   <caching-schemes>
       <remote-cache-scheme>
           <scheme-name>thin-remote</scheme-name>
           <service-name>Proxy</service-name>
           <initiator-config>
               <tcp-initiator>
                  <remote-addresses>
                      <socket-address>
                          <address>127.0.0.1</address>
                          <port>20000</port>
                      </socket-address>
                  </remote-addresses>
               </tcp-initiator>
           </initiator-config>
       </remote-cache-scheme>
   </caching-schemes>
</cache-config>

Write a simple Java program to interact with the Coherence cluster. Save this file as HelloCoherence.javain the same directory as the XML file.

import com.tangosol.net.CacheFactory;
import com.tangosol.net.NamedCache;

public class HelloCoherence {
  public static void main(String[] asArgs) throws Throwable {
    NamedCache<String, Integer> cache = CacheFactory.getCache("HelloCoherence");
    Integer IValue = (Integer) cache.get("key");
    IValue = (null == IValue) ? Integer.valueOf(1) : Integer.valueOf(IValue + 1);
    cache.put("key", IValue);
    System.out.println("The value of the key is " + IValue);
  }
}

With the XML and Java source files in the same directory, and the coherence.jar at ${COHERENCE_HOME}/lib/coherence.jar, compile and run the program:

$ javac -cp .:${COHERENCE_HOME}/lib/coherence.jar HelloCoherence.java
$ java -cp .:${COHERENCE_HOME}/lib/coherence.jar \
       -Dcoherence.cacheconfig=$PWD/example-client-config.xml HelloCoherence

The program produces an output similar to the following:

The value of the key is 1

Run the program again to get an output similar to the following:

The value of the key is 2

Note: If you are using JDK 11 or later, you can omit the javac command and simply run the program as:

$ java -cp $${COHERENCE_HOME}/lib/coherence.jar \
  -Dcoherence.cacheconfig=$PWD/example-client-config.xml  HelloCoherence.java

Remove Coherence and Coherence Operator

Remove the coherence release:

$ helm delete --purge sample-coherence sample-coherence-operator
This site is open source. Improve this page.