Bug 1253726 - [DOCS] Provide details about EAP6 clustering
[DOCS] Provide details about EAP6 clustering
Status: CLOSED CURRENTRELEASE
Product: Red Hat xPaaS
Classification: Red Hat
Component: Documentation (Show other bugs)
unspecified
Unspecified Unspecified
high Severity urgent
: ---
: ---
Assigned To: Andrew Burden
Radek Koubsky
Vikram Goyal
:
Depends On:
Blocks: 1293988
  Show dependency treegraph
 
Reported: 2015-08-14 10:03 EDT by Ricardo Martinelli de Oliveira
Modified: 2017-07-04 02:05 EDT (History)
15 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
: 1293988 1376871 (view as bug list)
Environment:
Last Closed: 2017-07-04 02:05:16 EDT
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Ricardo Martinelli de Oliveira 2015-08-14 10:03:13 EDT
Document URL: 
https://docs.openshift.com/enterprise/3.0/using_images/xpaas_images/eap.html

Section Number and Name: 
No section. I'm suggesting a new one.

Describe the issue: 
Provide details about how EAP 6 clustering works in v3 as well provide ways to test if clustering is working.

Suggestions for improvement: 

Additional information:
Comment 12 Miheer Salunke 2015-12-18 10:30:24 EST
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
Comment 13 Eric Rich 2015-12-21 16:02:24 EST
(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!
Comment 14 Josep 'Pep' Turro Mauri 2016-01-13 11:31:14 EST
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)
Comment 17 Travis Rogers 2016-06-22 17:59:54 EDT
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
Comment 18 Andrew Burden 2016-09-16 13:46:39 EDT
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.
Comment 20 Vikram Goyal 2016-09-19 04:49:52 EDT
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
Comment 21 Radek Koubsky 2016-10-14 05:53:23 EDT
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"
Comment 26 Frederic Giloux 2017-04-16 13:15:33 EDT
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>

Note You need to log in before you can comment on or make changes to this bug.