template.adoc.in

= {template}
:toc:
:toc-placement!:
:toclevels: 5

{description}

toc::[]

{#parameters}
== Parameters

Templates allow you to define parameters which take on a value. That value is then substituted wherever the parameter is referenced.
References can be defined in any text field in the objects list field. Refer to the
https://docs.openshift.org/latest/architecture/core_concepts/templates.html#parameters[Openshift documentation] for more information.

|=======================================================================
|Variable name |Image Environment Variable |Description |Example value |Required
{parametertable}
|=======================================================================
{/parameters}

{#objects}
== Objects

The CLI supports various object types. A list of these object types as well as their abbreviations
can be found in the https://docs.openshift.org/latest/cli_reference/basic_cli_operations.html#object-types[Openshift documentation].

{#Service}
=== Services

A service is an abstraction which defines a logical set of pods and a policy by which to access them. Refer to the
https://cloud.google.com/container-engine/docs/services/[container-engine documentation] for more information.

|=============
|Service        |Port  |Name | Description
{table}
|=============
{/Service}

{#Route}
=== Routes

A route is a way to expose a service by giving it an externally-reachable hostname such as `www.example.com`. A defined route and the endpoints
identified by its service can be consumed by a router to provide named connectivity from external clients to your applications. Each route consists
of a route name, service selector, and (optionally) security configuration. Refer to the
https://docs.openshift.com/enterprise/3.0/architecture/core_concepts/routes.html[Openshift documentation] for more information.

|=============
| Service    | Security | Hostname
{table}
|=============
{/Route}

{#BuildConfig}
=== Build Configurations

A `buildConfig` describes a single build definition and a set of triggers for when a new build should be created.
A `buildConfig` is a REST object, which can be used in a POST to the API server to create a new instance. Refer to
the https://docs.openshift.com/enterprise/3.0/dev_guide/builds.html#defining-a-buildconfig[Openshift documentation]
for more information.

|=============
| S2I image  | link | Build output | BuildTriggers and Settings
{table}
|=============
{/BuildConfig}

=== Deployment Configurations

A deployment in OpenShift is a replication controller based on a user defined template called a deployment configuration. Deployments are created manually or in response to triggered events.
Refer to the https://docs.openshift.com/enterprise/3.0/dev_guide/deployments.html#creating-a-deployment-configuration[Openshift documentation] for more information.

{#triggers}
==== Triggers

A trigger drives the creation of new deployments in response to events, both inside and outside OpenShift. Refer to the
https://access.redhat.com/beta/documentation/en/openshift-enterprise-30-developer-guide#triggers[Openshift documentation] for more information.

|============
|Deployment | Triggers
{table}
|============
{/triggers}

{#replicas}
==== Replicas

A replication controller ensures that a specified number of pod "replicas" are running at any one time.
If there are too many, the replication controller kills some pods. If there are too few, it starts more.
Refer to the https://cloud.google.com/container-engine/docs/replicationcontrollers/[container-engine documentation]
for more information.

|============
|Deployment | Replicas
{table}
|============
{/replicas}

==== Pod Template

{#serviceAccountName}
===== Service Accounts

Service accounts are API objects that exist within each project. They can be created or deleted like any other API object. Refer to the
https://docs.openshift.com/enterprise/3.0/dev_guide/service_accounts.html#managing-service-accounts[Openshift documentation] for more
information.

|============
|Deployment | Service Account
{table}
|============
{/serviceAccountName}

{#image}
===== Image

|============
|Deployment | Image
{table}
|============
{/image}

{#readinessProbe}
===== Readiness Probe

{table}
{/readinessProbe}

{#ports}
===== Exposed Ports

|=============
|Deployments | Name  | Port  | Protocol
{table}
|=============
{/ports}

{#env}
===== Image Environment Variables

|=======================================================================
|Deployment |Variable name |Description |Example value
{table}
|=======================================================================
{/env}

{#volumes}
=====  Volumes

|=============
|Deployment |Name  | mountPath | Purpose | readOnly 
{table}
|=============
{/volumes}

=== External Dependencies

{#PersistentVolumeClaim}
==== Volume Claims

A `PersistentVolume` object is a storage resource in an OpenShift cluster. Storage is provisioned by an administrator
by creating `PersistentVolume` objects from sources such as GCE Persistent Disks, AWS Elastic Block Stores (EBS), and NFS mounts.
Refer to the https://docs.openshift.com/enterprise/3.0/dev_guide/persistent_volumes.html#overview[Openshift documentation] for
more information.

|=============
|Name | Access Mode
{table}
|=============

{/PersistentVolumeClaim}

{#secrets}
==== Secrets

This template requires link:../secrets/{secretName}.adoc[{secretFile}]
to be installed for the application to run.
{/secrets}

{#clustering}
[[clustering]]
==== Clustering

Clustering in OpenShift EAP is achieved through one of two discovery mechanisms:
Kubernetes or DNS. This is done by configuring the JGroups protocol stack in
standalone-openshift.xml with either the `<openshift.KUBE_PING/>` or `<openshift.DNS_PING/>`
elements. The templates are configured to use `DNS_PING`, however `KUBE_PING`is
the default used by the image.

The discovery mechanism used is specified by the `JGROUPS_PING_PROTOCOL` environment
variable which can be set to either `openshift.DNS_PING` or `openshift.KUBE_PING`.
`openshift.KUBE_PING` is the default used by the image if no value is specified
for `JGROUPS_PING_PROTOCOL`.

For DNS_PING to work, the following steps must be taken:

. The `OPENSHIFT_DNS_PING_SERVICE_NAME` environment variable must be set to the
  name of the ping service for the cluster (see table above).  If not set, the
  server will act as if it is a single-node cluster (a "cluster of one").
. The `OPENSHIFT_DNS_PING_SERVICE_PORT` environment variables should be set to
  the port number on which the ping service is exposed (see table above).  The
  `DNS_PING` protocol will attempt to discern the port from the SRV records, if
  it can, otherwise it will default to 8888.
. A ping service which exposes the ping port must be defined.  This service
  should be "headless" (ClusterIP=None) and must have the following:
.. The port must be named for port discovery to work.
.. It must be annotated with `service.alpha.kubernetes.io/tolerate-unready-endpoints`
   set to `"true"`.  Omitting this annotation will result in each node forming
   their own "cluster of one" during startup, then merging their cluster into
   the other nodes' clusters after startup (as the other nodes are not detected
   until after they have started).

.Example ping service for use with DNS_PING
[source,yaml]
----
kind: Service
apiVersion: v1
spec:
    clusterIP: None
    ports:
    - name: ping
      port: 8888
    selector:
        deploymentConfig: eap-app
metadata:
    name: eap-app-ping
    annotations:
        service.alpha.kubernetes.io/tolerate-unready-endpoints: "true"
        description: "The JGroups ping port for clustering."
----

For `KUBE_PING` to work, the following steps must be taken:

. The `OPENSHIFT_KUBE_PING_NAMESPACE` environment variable must be set (see table above).
  If not set, the server will act as if it is a single-node cluster (a "cluster of one").
. The `OPENSHIFT_KUBE_PING_LABELS` environment variables should be set (see table above).
  If not set, pods outside of your application (albeit in your namespace) will try to join.
. Authorization must be granted to the service account the pod is running under to be
  allowed to access Kubernetes' REST api. This is done on the command line.

.Policy commands
====
Using the default service account in the myproject namespace:
....
oc policy add-role-to-user view system:serviceaccount:myproject:default -n myproject
....
Using the eap-service-account in the myproject namespace:
....
oc policy add-role-to-user view system:serviceaccount:myproject:eap-service-account -n myproject
....
====
{/clustering}
{/objects}

[[tls]]
== TLS/SSL configuration

Red Hat Single Sign-On server can be configured to use TLS for handling incoming connections (also known as Key Store) and outgoing connections (also known as Trust Store). The configuration uses an automated script to convert a key or a certificate from PEM format into JKS, which is then consumed by Red Hat Single Sign-On.

The Key Store configuration requires a secret (or a volume), containing the key in PEM format, mounted at `/etc/x509/https`. The name of the file that holds the key is `tls.key` by default. Typically, a key is link:https://docs.openshift.com/container-platform/3.11/dev_guide/secrets.html#service-serving-certificate-secrets[created by OpenShift and mounted as a secret.] The `sso-*-x509-https.json` template contains a example of such a configuration.

The Trust Store configuration uses certificates in PEM format. They should be mounted somewhere in the Pod and `X509_CA_BUNDLE` variable should point to them. A typical example is using the CA bundle provided by OpenShift - `/var/run/secrets/kubernetes.io/serviceaccount/ca.crt`. The `X509_CA_BUNDLE` variable might be configured to point to a custom file system path within the Pod, containing the set of CA certificates to use. The space (` `) character is used as a separator for specifying multiple CA bundles.

TIP: With the current implementation it is possible to use `X509_CA_BUNDLE` along with `SSO_TRUSTSTORE_*`. However, the current implementation favors the `X509_CA_BUNDLE` variable and in some cases, `SSO_TRUSTSTORE_*` might be ignored. This behavior is implementation dependent and may change in the future.