eap72-mysql-s2i.adoc

eap72-mysql-s2i

An example Red Hat JBoss EAP 7 application with a MySQL database. For more information about using this template, see https://github.com/jboss-container-images/jboss-eap-7-openshift-image/blob/eap72/README.adoc.

Table of Contents

• Parameters
• Objects
  • Services
  • Routes
  • Build Configurations
  • Deployment Configurations
    • Triggers
    • Replicas
    • Pod Template
      • Image
      • Readiness Probe
      • Exposed Ports
      • Image Environment Variables
      • Volumes
  • External Dependencies
    • Clustering

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 Openshift documentation for more information.

Variable name	Image Environment Variable	Description	Example value	Required
APPLICATION_NAME	—	The name for the application.	eap-app	True
HOSTNAME_HTTPS	—	Custom hostname for https service route. Leave blank for default hostname, e.g.: secure-<application-name>-<project>.<default-domain-suffix>	—	False
SOURCE_REPOSITORY_URL	—	Git source URI for application	https://github.com/jboss-openshift/openshift-quickstarts	True
SOURCE_REPOSITORY_REF	—	Git branch/tag reference	1.3	False
CONTEXT_DIR	—	Path within Git project to build; empty for root project directory.	todolist/todolist-jdbc	False
DB_JNDI	DB_JNDI	Database JNDI name used by application to resolve the datasource, e.g. java:/jboss/datasources/mysql	java:jboss/datasources/TodoListDS	False
DB_DATABASE	DB_DATABASE	Database name	root	True
MQ_QUEUES	MQ_QUEUES	Queue names, separated by commas. These queues will be automatically created when the broker starts. Also, they will be made accessible as JNDI resources in EAP. Note that all queues used by the application must be specified here in order to be created automatically on the remote AMQ broker.	${MQ_QUEUES}	False
MQ_TOPICS	MQ_TOPICS	Topic names, separated by commas. These topics will be automatically created when the broker starts. Also, they will be made accessible as JNDI resources in EAP. Note that all topics used by the application must be specified here in order to be created automatically on the remote AMQ broker.	${MQ_TOPICS}	False
HTTPS_SECRET	—	The name of the secret containing the keystore file	eap7-app-secret	True
HTTPS_KEYSTORE	HTTPS_KEYSTORE_DIR	The name of the keystore file within the secret	keystore.jks	False
HTTPS_KEYSTORE_TYPE	HTTPS_KEYSTORE	The type of the keystore file (JKS or JCEKS)	${HTTPS_KEYSTORE}	False
HTTPS_NAME	HTTPS_NAME	The name associated with the server certificate	${HTTPS_NAME}	False
HTTPS_PASSWORD	HTTPS_PASSWORD	The password for the keystore and certificate	${HTTPS_PASSWORD}	False
DB_MIN_POOL_SIZE	DB_MIN_POOL_SIZE	Sets xa-pool/min-pool-size for the configured datasource.	${DB_MIN_POOL_SIZE}	False
DB_MAX_POOL_SIZE	DB_MAX_POOL_SIZE	Sets xa-pool/max-pool-size for the configured datasource.	${DB_MAX_POOL_SIZE}	False
DB_TX_ISOLATION	DB_TX_ISOLATION	Sets transaction-isolation for the configured datasource.	${DB_TX_ISOLATION}	False
MYSQL_LOWER_CASE_TABLE_NAMES	MYSQL_LOWER_CASE_TABLE_NAMES	Sets how the table names are stored and compared.	${MYSQL_LOWER_CASE_TABLE_NAMES}	False
MYSQL_MAX_CONNECTIONS	MYSQL_MAX_CONNECTIONS	The maximum permitted number of simultaneous client connections.	${MYSQL_MAX_CONNECTIONS}	False
MYSQL_FT_MIN_WORD_LEN	MYSQL_FT_MIN_WORD_LEN	The minimum length of the word to be included in a FULLTEXT index.	${MYSQL_FT_MIN_WORD_LEN}	False
MYSQL_FT_MAX_WORD_LEN	MYSQL_FT_MAX_WORD_LEN	The maximum length of the word to be included in a FULLTEXT index.	${MYSQL_FT_MAX_WORD_LEN}	False
MYSQL_AIO	MYSQL_AIO	Controls the innodb_use_native_aio setting value if the native AIO is broken.	${MYSQL_AIO}	False
MQ_CLUSTER_PASSWORD	MQ_CLUSTER_PASSWORD	AMQ cluster admin password	${MQ_CLUSTER_PASSWORD}	True
DB_USERNAME	DB_USERNAME	Database user name	${DB_USERNAME}	True
DB_PASSWORD	DB_PASSWORD	Database user password	${DB_PASSWORD}	True
GITHUB_WEBHOOK_SECRET	—	GitHub trigger secret	secret101	True
GENERIC_WEBHOOK_SECRET	—	Generic build trigger secret	secret101	True
IMAGE_STREAM_NAMESPACE	—	Namespace in which the ImageStreams for Red Hat Middleware images are installed. These ImageStreams are normally installed in the openshift namespace. You should only need to modify this if you’ve installed the ImageStreams in a different namespace/project.	openshift	True
JGROUPS_ENCRYPT_SECRET	JGROUPS_ENCRYPT_SECRET	The name of the secret containing the keystore file	eap7-app-secret	False
JGROUPS_ENCRYPT_KEYSTORE	JGROUPS_ENCRYPT_KEYSTORE_DIR	The name of the keystore file within the secret	jgroups.jceks	False
JGROUPS_ENCRYPT_NAME	JGROUPS_ENCRYPT_NAME	The name associated with the server certificate	${JGROUPS_ENCRYPT_NAME}	False
JGROUPS_ENCRYPT_PASSWORD	JGROUPS_ENCRYPT_PASSWORD	The password for the keystore and certificate	${JGROUPS_ENCRYPT_PASSWORD}	False
JGROUPS_CLUSTER_PASSWORD	JGROUPS_CLUSTER_PASSWORD	JGroups cluster password	${JGROUPS_CLUSTER_PASSWORD}	True
AUTO_DEPLOY_EXPLODED	AUTO_DEPLOY_EXPLODED	Controls whether exploded deployment content should be automatically deployed	false	False
MAVEN_MIRROR_URL	—	Maven mirror to use for S2I builds	—	False
MAVEN_ARGS_APPEND	—	Maven additional arguments to use for S2I builds	—	False
ARTIFACT_DIR	—	List of directories from which archives will be copied into the deployment folder. If unspecified, all archives in /target will be copied.	—	False
MYSQL_IMAGE_STREAM_TAG	—	The tag to use for the "mysql" image stream. Typically, this aligns with the major.minor version of MySQL.	5.7	True
MEMORY_LIMIT	—	Container memory limit	1Gi	False

Objects

The CLI supports various object types. A list of these object types as well as their abbreviations can be found in the Openshift documentation.

Services

A service is an abstraction which defines a logical set of pods and a policy by which to access them. Refer to the container-engine documentation for more information.

Service	Port	Name	Description
${APPLICATION_NAME}	8080	—	The web server’s http port.
secure-${APPLICATION_NAME}	8443	—	The web server’s https port.
${APPLICATION_NAME}-mysql	3306	—	The database server’s port.
${APPLICATION_NAME}-ping	8888	ping	The JGroups ping port for clustering.

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 Openshift documentation for more information.

Service	Security	Hostname
	${APPLICATION_NAME}-https	TLS passthrough

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 Openshift documentation for more information.

S2I image	link	Build output	BuildTriggers and Settings
jboss-eap72-openshift:1.0	``	${APPLICATION_NAME}:latest	GitHub, Generic, ImageChange, ConfigChange

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 Openshift documentation for more information.

Triggers

A trigger drives the creation of new deployments in response to events, both inside and outside OpenShift. Refer to the Openshift documentation for more information.

Deployment	Triggers
${APPLICATION_NAME}	ImageChange
${APPLICATION_NAME}-mysql	ImageChange

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 container-engine documentation for more information.

Deployment	Replicas
${APPLICATION_NAME}	1
${APPLICATION_NAME}-mysql	1

Pod Template

Image

Deployment	Image
${APPLICATION_NAME}	${APPLICATION_NAME}
${APPLICATION_NAME}-mysql	mysql

Readiness Probe

${APPLICATION_NAME}

/bin/bash -c /opt/eap/bin/readinessProbe.sh

${APPLICATION_NAME}-mysql

/bin/sh -i -c MYSQL_PWD="$MYSQL_PASSWORD" mysql -h 127.0.0.1 -u $MYSQL_USER -D $MYSQL_DATABASE -e 'SELECT 1'

Exposed Ports

Deployments	Name	Port	Protocol
${APPLICATION_NAME}	jolokia	8778	TCP
	http	8080	TCP
	https	8443	TCP
	ping	8888	TCP
${APPLICATION_NAME}-mysql	—	3306	TCP

Image Environment Variables

Deployment	Variable name	Description	Example value
${APPLICATION_NAME}	DB_SERVICE_PREFIX_MAPPING	—	${APPLICATION_NAME}-mysql=DB
	DB_JNDI	Database JNDI name used by application to resolve the datasource, e.g. java:/jboss/datasources/mysql	${DB_JNDI}
	DB_USERNAME	Database user name	${DB_USERNAME}
	DB_PASSWORD	Database user password	${DB_PASSWORD}
	DB_DATABASE	Database name	${DB_DATABASE}
	TX_DATABASE_PREFIX_MAPPING	—	${APPLICATION_NAME}-mysql=DB
	DB_MIN_POOL_SIZE	Sets xa-pool/min-pool-size for the configured datasource.	${DB_MIN_POOL_SIZE}
	DB_MAX_POOL_SIZE	Sets xa-pool/max-pool-size for the configured datasource.	${DB_MAX_POOL_SIZE}
	DB_TX_ISOLATION	Sets transaction-isolation for the configured datasource.	${DB_TX_ISOLATION}
	JGROUPS_PING_PROTOCOL	—	dns.DNS_PING
	OPENSHIFT_DNS_PING_SERVICE_NAME	—	${APPLICATION_NAME}-ping
	OPENSHIFT_DNS_PING_SERVICE_PORT	—	8888
	HTTPS_KEYSTORE_DIR	The name of the keystore file within the secret	/etc/eap-secret-volume
	HTTPS_KEYSTORE	The name of the keystore file within the secret	${HTTPS_KEYSTORE}
	HTTPS_KEYSTORE_TYPE	The name of the keystore file within the secret	${HTTPS_KEYSTORE_TYPE}
	HTTPS_NAME	The name associated with the server certificate	${HTTPS_NAME}
	HTTPS_PASSWORD	The password for the keystore and certificate	${HTTPS_PASSWORD}
	MQ_CLUSTER_PASSWORD	AMQ cluster admin password	${MQ_CLUSTER_PASSWORD}
	MQ_QUEUES	Queue names, separated by commas. These queues will be automatically created when the broker starts. Also, they will be made accessible as JNDI resources in EAP. Note that all queues used by the application must be specified here in order to be created automatically on the remote AMQ broker.	${MQ_QUEUES}
	MQ_TOPICS	Topic names, separated by commas. These topics will be automatically created when the broker starts. Also, they will be made accessible as JNDI resources in EAP. Note that all topics used by the application must be specified here in order to be created automatically on the remote AMQ broker.	${MQ_TOPICS}
	JGROUPS_ENCRYPT_SECRET	The name of the secret containing the keystore file	${JGROUPS_ENCRYPT_SECRET}
	JGROUPS_ENCRYPT_KEYSTORE_DIR	The name of the keystore file within the secret	/etc/jgroups-encrypt-secret-volume
	JGROUPS_ENCRYPT_KEYSTORE	The name of the keystore file within the secret	${JGROUPS_ENCRYPT_KEYSTORE}
	JGROUPS_ENCRYPT_NAME	The name associated with the server certificate	${JGROUPS_ENCRYPT_NAME}
	JGROUPS_ENCRYPT_PASSWORD	The password for the keystore and certificate	${JGROUPS_ENCRYPT_PASSWORD}
	JGROUPS_CLUSTER_PASSWORD	JGroups cluster password	${JGROUPS_CLUSTER_PASSWORD}
	AUTO_DEPLOY_EXPLODED	Controls whether exploded deployment content should be automatically deployed	${AUTO_DEPLOY_EXPLODED}
	DEFAULT_JOB_REPOSITORY	—	${APPLICATION_NAME}-mysql
	TIMER_SERVICE_DATA_STORE	—	${APPLICATION_NAME}-mysql
${APPLICATION_NAME}-mysql	MYSQL_USER	—	${DB_USERNAME}
	MYSQL_PASSWORD	—	${DB_PASSWORD}
	MYSQL_DATABASE	—	${DB_DATABASE}
	MYSQL_LOWER_CASE_TABLE_NAMES	Sets how the table names are stored and compared.	${MYSQL_LOWER_CASE_TABLE_NAMES}
	MYSQL_MAX_CONNECTIONS	The maximum permitted number of simultaneous client connections.	${MYSQL_MAX_CONNECTIONS}
	MYSQL_FT_MIN_WORD_LEN	The minimum length of the word to be included in a FULLTEXT index.	${MYSQL_FT_MIN_WORD_LEN}
	MYSQL_FT_MAX_WORD_LEN	The maximum length of the word to be included in a FULLTEXT index.	${MYSQL_FT_MAX_WORD_LEN}
	MYSQL_AIO	Controls the innodb_use_native_aio setting value if the native AIO is broken.	${MYSQL_AIO}

Volumes

Deployment	Name	mountPath	Purpose	readOnly
${APPLICATION_NAME}	eap-keystore-volume	/etc/eap-secret-volume	ssl certs	True
${APPLICATION_NAME}-mysql	${APPLICATION_NAME}-data	/var/lib/mysql/data	—	false

External Dependencies

Clustering

Clustering in OpenShift EAP is achieved through one of two discovery mechanisms: KUBE_PING or DNS_PING. This is done by configuring the JGroups protocol stack in standalone-openshift.xml with any of the following mechanisms: <kubernetes.KUBE_PING>, <dns.DNS_PING>, <openshift.KUBE_PING/> or <openshift.DNS_PING/>. 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 openshift.DNS_PING, kubernetes.KUBE_PING, dns.DNS_PING or openshift.KUBE_PING. KUBE_PING is the default used by the image if no value is specified for JGROUPS_PING_PROTOCOL for compatibility with previous releases.

WARN: openshift.DNS_PING and openshift.KUBE_PING are deprecated and may be removed in a future release.

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

1. 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").

2. 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.

3. A ping service which exposes the ping port must be defined. This service should be "headless" (ClusterIP=None) and must have the following:

   1. The port must be named for port discovery to work.

   2. 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

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:

For kubernetes.KUBE_PING: . 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.

For legacy openshift.KUBE_PING . 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.

For both implementations: . 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.

Example 1. 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