Hi Kevin,

Can you please give us the detailed steps for clustering using xpaas images like EAP 6 ?

I came across http://ce-docs.usersys.redhat.com/openshift/eap/6.4/clustering.html where the first and the second point consists of "(see table above)" but the table with values for OPENSHIFT_KUBE_PING_NAMESPACE and OPENSHIFT_KUBE_PING_LABELS is missing.

Thanks and regards,
Miheer Salunke

(In reply to Miheer Salunke from comment #12)
> Hi Kevin,
> 
> Can you please give us the detailed steps for clustering using xpaas images
> like EAP 6 ?
> 
> I came across
> http://ce-docs.usersys.redhat.com/openshift/eap/6.4/clustering.html where
> the first and the second point consists of "(see table above)" but the table
> with values for OPENSHIFT_KUBE_PING_NAMESPACE and OPENSHIFT_KUBE_PING_LABELS
> is missing.
> 
> Thanks and regards,
> Miheer Salunke

I think the default clustering for EAP 6.4 (with 3.1 xPaaS images) uses the kube ping clustering model, and does so be default. 

However your request miheer brings up a good point about why the information in http://ce-docs.usersys.redhat.com/openshift/eap/6/clustering.html is not part of the public docs. Adding Vikrim for clarification and privatization!

A potential suggestion for these docs: the OPENSHIFT_KUBE_PING_NAMESPACE env var sounds like a good candidate to be populated using the downward API:

https://docs.openshift.com/enterprise/3.1/dev_guide/downward_api.html

I believe that in the typical use case you would be clustering with pods in the same namespace, so adding something like this to the deployment config should populate that env var automatically for this use case:

      containers:
      - env:
        - name: OPENSHIFT_KUBE_PING_NAMESPACE
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace

Doing the same automagically for OPENSHIFT_KUBE_PING_LABELS is a bit more tricky because you can't use the env-based downward API (only static metadata can be referenced that way)

Can we add some additional information into section 3.2 [1] covering clustering with the xPaaS EAP image?

Might be good to provide example values for the environment variables:
OPENSHIFT_KUBE_PING_NAMESPACE=project_name
OPENSHIFT_KUBE_PING_LABELS=application=app_name

Also, an example CLI setting the environment variable in a deployment config:
oc env dc/my-test-app -e OPENSHIFT_KUBE_PING_NAMESPACE=project_name
OPENSHIFT_KUBE_PING_LABELS=application=app_name


Also the text "Example 3.1. Policy commands" should be "Example 3.2.1. Policy commands".


[1]
https://access.redhat.com/documentation/en/red-hat-xpaas/0/red-hat-xpaas-eap-image/chapter-3-reference-information

Thanks for the suggestions everyone. 
I've updated the xPaaS content to include the examples provided by Travis, and cleaned it up the topic somewhat to make it  

The testing of clustering is more complex so I've cloned this bug (BZ#1376871) to track that aspect, and so that doesn't impede publication of the examples.

Thanks Andrew.
 
Travis - can you review Andrew's changes [1] for KUBE_PING? If they are ok, I will go ahead and publish.

Moving this bug to ON_QA.

[1] https://doc-stage.usersys.redhat.com/documentation/en/red-hat-xpaas/0/single/red-hat-xpaas-eap-image#clustering

One suggestion from me:
Would be nice to provide some kind of verification of clustering (KUBE_PING) to users. For example, if clustering is enabled, one can see the following logs from within a pod:

"Service account has sufficient permissions to view pods in kubernetes (HTTP 200). Clustering will be available."

"05:00:24,017 INFO  [org.jgroups.protocols.openshift.KUBE_PING] (MSC service thread 1-7) namespace [rkoubsky] set; clustering enabled"

The following part of the documentation is lacking some information:

"The OPENSHIFT_KUBE_PING_LABELS environment variables should be set. If not set, pods outside of your application (albeit in your namespace) will try to join.
For example:

OPENSHIFT_KUBE_PING_LABELS=application=<app_name>"

This should make clearer that the label should match what has been set at the service level. Also "oc new-app" with later versions of OpenShift default to app=<app_name> and not application=<app_name>

This update has been published and is available on the Portal:
https://access.redhat.com/documentation/en-us/red_hat_jboss_middleware_for_openshift/3/html-single/red_hat_jboss_enterprise_application_platform_for_openshift/#clustering