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 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 `<kubernetes.KUBE_PING/>` or `<dns.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 `dns.DNS_PING` or `kubernetes.KUBE_PING`.
`kubernetes.KUBE_PING` is the default used by the image if no value is specified
for `JGROUPS_PING_PROTOCOL`.

For `DNS_PING` to work on `IPv4 or IPv6 single-stack cluster`, 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.
.. The `spec.publishNotReadyAddresses` field of this service must be set to
   `"true"`. Omitting the setting of this boolean 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 definition of a ping service for use with DNS_PING on a single-stack (IPv4 or IPv6) cluster
[source,yaml]
----
kind: Service
apiVersion: v1
spec:
    clusterIP: None
    ipFamilyPolicy: SingleStack
    ports:
    - name: ping
      port: 8888
    publishNotReadyAddresses: true
    selector:
        deploymentConfig: sso
metadata:
    name: sso-ping
    annotations:
        description: "The JGroups ping port for clustering."
----

*Moreover, the `DNS_PING` to work also on dual-network clusters* that support both IPv4 and IPv6
address families, the `spec.ipFamilyPolicy` field of the ping service for the cluster (see table
above) must be set to `PreferDualStack` or `RequireDualStack`. This ensures the control plane
assigns both IPv4 and IPv6 cluster IP addresses for the ping service on clusters that have dual-stack
configured, enabling reverse DNS lookups for both IPv4 and IPv6 IP addresses to work properly,
and creating corresponding DNS SRV records for the ping headless service:

.Example of ping service DNS SRV records on a dual-stack configured cluster with `spec.ipFamilyPolicy` matching `PreferDualStack`
[source,bash]
----
$ host -t SRV "${OPENSHIFT_DNS_PING_SERVICE_NAME}"
sso-ping.dual-stack-demo.svc.cluster.local has SRV record 0 50 8888 10-128-0-239.sso-ping.dual-stack-demo.svc.cluster.local.
sso-ping.dual-stack-demo.svc.cluster.local has SRV record 0 50 8888 fd01-0-0-1--b8.sso-ping.dual-stack-demo.svc.cluster.local.
----

.Example definition of a ping service for use with DNS_PING on dual-stack (IPv4 and IPv6) cluster
[source,yaml]
----
kind: Service
apiVersion: v1
spec:
    clusterIP: None
    ipFamilyPolicy: PreferDualStack
    ports:
    - name: ping
      port: 8888
    publishNotReadyAddresses: true
    selector:
        deploymentConfig: sso
metadata:
    name: sso-ping
    annotations:
        description: "The JGroups ping port for clustering."
----

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

. The `KUBERNETES_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 `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.
. 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 sso-service-account in the myproject namespace:
....
oc policy add-role-to-user view system:serviceaccount:myproject:sso-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.