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.okd.io/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.okd.io/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.okd.io/latest/architecture/networking/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.okd.io/latest/dev_guide/builds/index.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.okd.io/latest/dev_guide/deployments/how_deployments_work.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://docs.okd.io/latest/dev_guide/builds/triggering_builds.html#config-change-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.okd.io/latest/dev_guide/service_accounts.html#dev-managing-service-accounts[Openshift documentation] for more
information.

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

{#image}
===== Image

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

{#readinessProbe}
===== Readiness Probe

{table}
{/readinessProbe}

{#livenessProbe}
===== Liveness Probe

{table}
{/livenessProbe}

{#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.okd.io/latest/dev_guide/persistent_volumes.html[Openshift documentation] for
more information.

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

{/PersistentVolumeClaim}
{#secrets}
==== Secrets

This template requires the following secrets to be installed for the application to run.

{secretNames}
{/secrets}
{#clustering}
[[clustering]]
==== Clustering

Clustering in OpenShift EAP is achieved through Kubernetes discovery mechanism.
This is done by configuring the JGroups protocol stack in
standalone-openshift.xml with the `<kubernetes.KUBE_PING/>` element.
The templates are configured to use `kubernetes.KUBE_PING`.

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


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

. The `KUBERNETES_NAMESPACE` environment variable must be set using the kubernetes metadata.namespace assigned to the pod.
  If not set, the server will act as if it is a single-node cluster (a "cluster of one").
. The `KUBERNETES_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.
. The value used as a `KUBERNETES_LABELS` must be added as a label in the respective deployment config.
  By convention the value is `cluster=kubernetes.ping.<name>-cluster` ,name used are console-cluster, consolemon-cluster, kieserver-cluster.
. 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}