Chapter 11. Using templates
The following sections provide an overview of templates, as well as how to use and create them.
11.1. Understanding templates
A template describes a set of objects that can be parameterized and processed to produce a list of objects for creation by Red Hat OpenShift Service on AWS. A template can be processed to create anything you have permission to create within a project, for example services, build configurations, and deployment configurations. A template can also define a set of labels to apply to every object defined in the template.
You can create a list of objects from a template using the CLI or, if a template has been uploaded to your project or the global template library, using the web console.
11.2. Uploading a template
If you have a JSON or YAML file that defines a template, you can upload the template to projects using the CLI. This saves the template to the project for repeated use by any user with appropriate access to that project. Instructions about writing your own templates are provided later in this topic.
Procedure
Upload a template using one of the following methods:
Upload a template to your current project’s template library, pass the JSON or YAML file with the following command:
$ oc create -f <filename>
Upload a template to a different project using the
-n
option with the name of the project:$ oc create -f <filename> -n <project>
The template is now available for selection using the web console or the CLI.
11.3. Creating an application by using the web console
You can use the web console to create an application from a template.
Procedure
- Select Developer from the context selector at the top of the web console navigation menu.
- While in the desired project, click +Add
- Click All services in the Developer Catalog tile.
Click Builder Images under Type to see the available builder images.
NoteOnly image stream tags that have the
builder
tag listed in their annotations appear in this list, as demonstrated here:kind: "ImageStream" apiVersion: "image.openshift.io/v1" metadata: name: "ruby" creationTimestamp: null spec: # ... tags: - name: "2.6" annotations: description: "Build and run Ruby 2.6 applications" iconClass: "icon-ruby" tags: "builder,ruby" 1 supports: "ruby:2.6,ruby" version: "2.6" # ...
- 1
- Including
builder
here ensures this image stream tag appears in the web console as a builder.
- Modify the settings in the new application screen to configure the objects to support your application.
11.4. Creating objects from templates by using the CLI
You can use the CLI to process templates and use the configuration that is generated to create objects.
11.4.1. Adding labels
Labels are used to manage and organize generated objects, such as pods. The labels specified in the template are applied to every object that is generated from the template.
Procedure
Add labels in the template from the command line:
$ oc process -f <filename> -l name=otherLabel
11.4.2. Listing parameters
The list of parameters that you can override are listed in the parameters
section of the template.
Procedure
You can list parameters with the CLI by using the following command and specifying the file to be used:
$ oc process --parameters -f <filename>
Alternatively, if the template is already uploaded:
$ oc process --parameters -n <project> <template_name>
For example, the following shows the output when listing the parameters for one of the quick start templates in the default
openshift
project:$ oc process --parameters -n openshift rails-postgresql-example
Example output
NAME DESCRIPTION GENERATOR VALUE SOURCE_REPOSITORY_URL The URL of the repository with your application source code https://github.com/sclorg/rails-ex.git SOURCE_REPOSITORY_REF Set this to a branch name, tag or other ref of your repository if you are not using the default branch CONTEXT_DIR Set this to the relative path to your project if it is not in the root of your repository APPLICATION_DOMAIN The exposed hostname that will route to the Rails service rails-postgresql-example.openshiftapps.com GITHUB_WEBHOOK_SECRET A secret string used to configure the GitHub webhook expression [a-zA-Z0-9]{40} SECRET_KEY_BASE Your secret key for verifying the integrity of signed cookies expression [a-z0-9]{127} APPLICATION_USER The application user that is used within the sample application to authorize access on pages openshift APPLICATION_PASSWORD The application password that is used within the sample application to authorize access on pages secret DATABASE_SERVICE_NAME Database service name postgresql POSTGRESQL_USER database username expression user[A-Z0-9]{3} POSTGRESQL_PASSWORD database password expression [a-zA-Z0-9]{8} POSTGRESQL_DATABASE database name root POSTGRESQL_MAX_CONNECTIONS database max connections 10 POSTGRESQL_SHARED_BUFFERS database shared buffers 12MB
The output identifies several parameters that are generated with a regular expression-like generator when the template is processed.
11.4.3. Generating a list of objects
Using the CLI, you can process a file defining a template to return the list of objects to standard output.
Procedure
Process a file defining a template to return the list of objects to standard output:
$ oc process -f <filename>
Alternatively, if the template has already been uploaded to the current project:
$ oc process <template_name>
Create objects from a template by processing the template and piping the output to
oc create
:$ oc process -f <filename> | oc create -f -
Alternatively, if the template has already been uploaded to the current project:
$ oc process <template> | oc create -f -
You can override any parameter values defined in the file by adding the
-p
option for each<name>=<value>
pair you want to override. A parameter reference appears in any text field inside the template items.For example, in the following the
POSTGRESQL_USER
andPOSTGRESQL_DATABASE
parameters of a template are overridden to output a configuration with customized environment variables:Creating a List of objects from a template
$ oc process -f my-rails-postgresql \ -p POSTGRESQL_USER=bob \ -p POSTGRESQL_DATABASE=mydatabase
The JSON file can either be redirected to a file or applied directly without uploading the template by piping the processed output to the
oc create
command:$ oc process -f my-rails-postgresql \ -p POSTGRESQL_USER=bob \ -p POSTGRESQL_DATABASE=mydatabase \ | oc create -f -
If you have large number of parameters, you can store them in a file and then pass this file to
oc process
:$ cat postgres.env POSTGRESQL_USER=bob POSTGRESQL_DATABASE=mydatabase
$ oc process -f my-rails-postgresql --param-file=postgres.env
You can also read the environment from standard input by using
"-"
as the argument to--param-file
:$ sed s/bob/alice/ postgres.env | oc process -f my-rails-postgresql --param-file=-
11.5. Modifying uploaded templates
You can edit a template that has already been uploaded to your project.
Procedure
Modify a template that has already been uploaded:
$ oc edit template <template>
11.6. Writing templates
You can define new templates to make it easy to recreate all the objects of your application. The template defines the objects it creates along with some metadata to guide the creation of those objects.
The following is an example of a simple template object definition (YAML):
apiVersion: template.openshift.io/v1 kind: Template metadata: name: redis-template annotations: description: "Description" iconClass: "icon-redis" tags: "database,nosql" objects: - apiVersion: v1 kind: Pod metadata: name: redis-master spec: containers: - env: - name: REDIS_PASSWORD value: ${REDIS_PASSWORD} image: dockerfile/redis name: master ports: - containerPort: 6379 protocol: TCP parameters: - description: Password used for Redis authentication from: '[A-Z0-9]{8}' generate: expression name: REDIS_PASSWORD labels: redis: master
11.6.1. Writing the template description
The template description informs you what the template does and helps you find it when searching in the web console. Additional metadata beyond the template name is optional, but useful to have. In addition to general descriptive information, the metadata also includes a set of tags. Useful tags include the name of the language the template is related to for example, Java, PHP, Ruby, and so on.
The following is an example of template description metadata:
kind: Template apiVersion: template.openshift.io/v1 metadata: name: cakephp-mysql-example 1 annotations: openshift.io/display-name: "CakePHP MySQL Example (Ephemeral)" 2 description: >- An example CakePHP application with a MySQL database. For more information about using this template, including OpenShift considerations, see https://github.com/sclorg/cakephp-ex/blob/master/README.md. WARNING: Any data stored will be lost upon pod destruction. Only use this template for testing." 3 openshift.io/long-description: >- This template defines resources needed to develop a CakePHP application, including a build configuration, application DeploymentConfig, and database DeploymentConfig. The database is stored in non-persistent storage, so this configuration should be used for experimental purposes only. 4 tags: "quickstart,php,cakephp" 5 iconClass: icon-php 6 openshift.io/provider-display-name: "Red Hat, Inc." 7 openshift.io/documentation-url: "https://github.com/sclorg/cakephp-ex" 8 openshift.io/support-url: "https://access.redhat.com" 9 message: "Your admin credentials are ${ADMIN_USERNAME}:${ADMIN_PASSWORD}" 10
- 1
- The unique name of the template.
- 2
- A brief, user-friendly name, which can be employed by user interfaces.
- 3
- A description of the template. Include enough detail that users understand what is being deployed and any caveats they must know before deploying. It should also provide links to additional information, such as a README file. Newlines can be included to create paragraphs.
- 4
- Additional template description. This may be displayed by the service catalog, for example.
- 5
- Tags to be associated with the template for searching and grouping. Add tags that include it into one of the provided catalog categories. Refer to the
id
andcategoryAliases
inCATALOG_CATEGORIES
in the console constants file. - 6
- An icon to be displayed with your template in the web console.
Example 11.1. Available icons
-
icon-3scale
-
icon-aerogear
-
icon-amq
-
icon-angularjs
-
icon-ansible
-
icon-apache
-
icon-beaker
-
icon-camel
-
icon-capedwarf
-
icon-cassandra
-
icon-catalog-icon
-
icon-clojure
-
icon-codeigniter
-
icon-cordova
-
icon-datagrid
-
icon-datavirt
-
icon-debian
-
icon-decisionserver
-
icon-django
-
icon-dotnet
-
icon-drupal
-
icon-eap
-
icon-elastic
-
icon-erlang
-
icon-fedora
-
icon-freebsd
-
icon-git
-
icon-github
-
icon-gitlab
-
icon-glassfish
-
icon-go-gopher
-
icon-golang
-
icon-grails
-
icon-hadoop
-
icon-haproxy
-
icon-helm
-
icon-infinispan
-
icon-jboss
-
icon-jenkins
-
icon-jetty
-
icon-joomla
-
icon-jruby
-
icon-js
-
icon-knative
-
icon-kubevirt
-
icon-laravel
-
icon-load-balancer
-
icon-mariadb
-
icon-mediawiki
-
icon-memcached
-
icon-mongodb
-
icon-mssql
-
icon-mysql-database
-
icon-nginx
-
icon-nodejs
-
icon-openjdk
-
icon-openliberty
-
icon-openshift
-
icon-openstack
-
icon-other-linux
-
icon-other-unknown
-
icon-perl
-
icon-phalcon
-
icon-php
-
icon-play
-
iconpostgresql
-
icon-processserver
-
icon-python
-
icon-quarkus
-
icon-rabbitmq
-
icon-rails
-
icon-redhat
-
icon-redis
-
icon-rh-integration
-
icon-rh-spring-boot
-
icon-rh-tomcat
-
icon-ruby
-
icon-scala
-
icon-serverlessfx
-
icon-shadowman
-
icon-spring-boot
-
icon-spring
-
icon-sso
-
icon-stackoverflow
-
icon-suse
-
icon-symfony
-
icon-tomcat
-
icon-ubuntu
-
icon-vertx
-
icon-wildfly
-
icon-windows
-
icon-wordpress
-
icon-xamarin
-
icon-zend
-
- 7
- The name of the person or organization providing the template.
- 8
- A URL referencing further documentation for the template.
- 9
- A URL where support can be obtained for the template.
- 10
- An instructional message that is displayed when this template is instantiated. This field should inform the user how to use the newly created resources. Parameter substitution is performed on the message before being displayed so that generated credentials and other parameters can be included in the output. Include links to any next-steps documentation that users should follow.
11.6.2. Writing template labels
Templates can include a set of labels. These labels are added to each object created when the template is instantiated. Defining a label in this way makes it easy for users to find and manage all the objects created from a particular template.
The following is an example of template object labels:
kind: "Template" apiVersion: "v1" ... labels: template: "cakephp-mysql-example" 1 app: "${NAME}" 2
11.6.3. Writing template parameters
Parameters allow a value to be supplied by you or generated when the template is instantiated. Then, that value is substituted wherever the parameter is referenced. References can be defined in any field in the objects list field. This is useful for generating random passwords or allowing you to supply a hostname or other user-specific value that is required to customize the template. Parameters can be referenced in two ways:
-
As a string value by placing values in the form
${PARAMETER_NAME}
in any string field in the template. -
As a JSON or YAML value by placing values in the form
${{PARAMETER_NAME}}
in place of any field in the template.
When using the ${PARAMETER_NAME}
syntax, multiple parameter references can be combined in a single field and the reference can be embedded within fixed data, such as "http://${PARAMETER_1}${PARAMETER_2}"
. Both parameter values are substituted and the resulting value is a quoted string.
When using the ${{PARAMETER_NAME}}
syntax only a single parameter reference is allowed and leading and trailing characters are not permitted. The resulting value is unquoted unless, after substitution is performed, the result is not a valid JSON object. If the result is not a valid JSON value, the resulting value is quoted and treated as a standard string.
A single parameter can be referenced multiple times within a template and it can be referenced using both substitution syntaxes within a single template.
A default value can be provided, which is used if you do not supply a different value:
The following is an example of setting an explicit value as the default value:
parameters: - name: USERNAME description: "The user name for Joe" value: joe
Parameter values can also be generated based on rules specified in the parameter definition, for example generating a parameter value:
parameters: - name: PASSWORD description: "The random user password" generate: expression from: "[a-zA-Z0-9]{12}"
In the previous example, processing generates a random password 12 characters long consisting of all upper and lowercase alphabet letters and numbers.
The syntax available is not a full regular expression syntax. However, you can use \w
, \d
, \a
, and \A
modifiers:
-
[\w]{10}
produces 10 alphabet characters, numbers, and underscores. This follows the PCRE standard and is equal to[a-zA-Z0-9_]{10}
. -
[\d]{10}
produces 10 numbers. This is equal to[0-9]{10}
. -
[\a]{10}
produces 10 alphabetical characters. This is equal to[a-zA-Z]{10}
. -
[\A]{10}
produces 10 punctuation or symbol characters. This is equal to[~!@#$%\^&*()\-_+={}\[\]\\|<,>.?/"';:`]{10}
.
Depending on if the template is written in YAML or JSON, and the type of string that the modifier is embedded within, you might need to escape the backslash with a second backslash. The following examples are equivalent:
Example YAML template with a modifier
parameters: - name: singlequoted_example generate: expression from: '[\A]{10}' - name: doublequoted_example generate: expression from: "[\\A]{10}"
Example JSON template with a modifier
{ "parameters": [ { "name": "json_example", "generate": "expression", "from": "[\\A]{10}" } ] }
Here is an example of a full template with parameter definitions and references:
kind: Template apiVersion: template.openshift.io/v1 metadata: name: my-template objects: - kind: BuildConfig apiVersion: build.openshift.io/v1 metadata: name: cakephp-mysql-example annotations: description: Defines how to build the application spec: source: type: Git git: uri: "${SOURCE_REPOSITORY_URL}" 1 ref: "${SOURCE_REPOSITORY_REF}" contextDir: "${CONTEXT_DIR}" - kind: DeploymentConfig apiVersion: apps.openshift.io/v1 metadata: name: frontend spec: replicas: "${{REPLICA_COUNT}}" 2 parameters: - name: SOURCE_REPOSITORY_URL 3 displayName: Source Repository URL 4 description: The URL of the repository with your application source code 5 value: https://github.com/sclorg/cakephp-ex.git 6 required: true 7 - name: GITHUB_WEBHOOK_SECRET description: A secret string used to configure the GitHub webhook generate: expression 8 from: "[a-zA-Z0-9]{40}" 9 - name: REPLICA_COUNT description: Number of replicas to run value: "2" required: true message: "... The GitHub webhook secret is ${GITHUB_WEBHOOK_SECRET} ..." 10
- 1
- This value is replaced with the value of the
SOURCE_REPOSITORY_URL
parameter when the template is instantiated. - 2
- This value is replaced with the unquoted value of the
REPLICA_COUNT
parameter when the template is instantiated. - 3
- The name of the parameter. This value is used to reference the parameter within the template.
- 4
- The user-friendly name for the parameter. This is displayed to users.
- 5
- A description of the parameter. Provide more detailed information for the purpose of the parameter, including any constraints on the expected value. Descriptions should use complete sentences to follow the console’s text standards. Do not make this a duplicate of the display name.
- 6
- A default value for the parameter which is used if you do not override the value when instantiating the template. Avoid using default values for things like passwords, instead use generated parameters in combination with secrets.
- 7
- Indicates this parameter is required, meaning you cannot override it with an empty value. If the parameter does not provide a default or generated value, you must supply a value.
- 8
- A parameter which has its value generated.
- 9
- The input to the generator. In this case, the generator produces a 40 character alphanumeric value including upper and lowercase characters.
- 10
- Parameters can be included in the template message. This informs you about generated values.
11.6.4. Writing the template object list
The main portion of the template is the list of objects which is created when the template is instantiated. This can be any valid API object, such as a build configuration, deployment configuration, or service. The object is created exactly as defined here, with any parameter values substituted in prior to creation. The definition of these objects can reference parameters defined earlier.
The following is an example of an object list:
kind: "Template"
apiVersion: "v1"
metadata:
name: my-template
objects:
- kind: "Service" 1
apiVersion: "v1"
metadata:
name: "cakephp-mysql-example"
annotations:
description: "Exposes and load balances the application pods"
spec:
ports:
- name: "web"
port: 8080
targetPort: 8080
selector:
name: "cakephp-mysql-example"
- 1
- The definition of a service, which is created by this template.
If an object definition metadata includes a fixed namespace
field value, the field is stripped out of the definition during template instantiation. If the namespace
field contains a parameter reference, normal parameter substitution is performed and the object is created in whatever namespace the parameter substitution resolved the value to, assuming the user has permission to create objects in that namespace.
11.6.5. Marking a template as bindable
The Template Service Broker advertises one service in its catalog for each template object of which it is aware. By default, each of these services is advertised as being bindable, meaning an end user is permitted to bind against the provisioned service.
Procedure
Template authors can prevent end users from binding against services provisioned from a given template.
-
Prevent end user from binding against services provisioned from a given template by adding the annotation
template.openshift.io/bindable: "false"
to the template.
11.6.6. Exposing template object fields
Template authors can indicate that fields of particular objects in a template should be exposed. The Template Service Broker recognizes exposed fields on ConfigMap
, Secret
, Service
, and Route
objects, and returns the values of the exposed fields when a user binds a service backed by the broker.
To expose one or more fields of an object, add annotations prefixed by template.openshift.io/expose-
or template.openshift.io/base64-expose-
to the object in the template.
Each annotation key, with its prefix removed, is passed through to become a key in a bind
response.
Each annotation value is a Kubernetes JSONPath expression, which is resolved at bind time to indicate the object field whose value should be returned in the bind
response.
Bind
response key-value pairs can be used in other parts of the system as environment variables. Therefore, it is recommended that every annotation key with its prefix removed should be a valid environment variable name — beginning with a character A-Z
, a-z
, or _
, and being followed by zero or more characters A-Z
, a-z
, 0-9
, or _
.
Unless escaped with a backslash, Kubernetes' JSONPath implementation interprets characters such as .
, @
, and others as metacharacters, regardless of their position in the expression. Therefore, for example, to refer to a ConfigMap
datum named my.key
, the required JSONPath expression would be {.data['my\.key']}
. Depending on how the JSONPath expression is then written in YAML, an additional backslash might be required, for example "{.data['my\\.key']}"
.
The following is an example of different objects' fields being exposed:
kind: Template apiVersion: template.openshift.io/v1 metadata: name: my-template objects: - kind: ConfigMap apiVersion: v1 metadata: name: my-template-config annotations: template.openshift.io/expose-username: "{.data['my\\.username']}" data: my.username: foo - kind: Secret apiVersion: v1 metadata: name: my-template-config-secret annotations: template.openshift.io/base64-expose-password: "{.data['password']}" stringData: password: <password> - kind: Service apiVersion: v1 metadata: name: my-template-service annotations: template.openshift.io/expose-service_ip_port: "{.spec.clusterIP}:{.spec.ports[?(.name==\"web\")].port}" spec: ports: - name: "web" port: 8080 - kind: Route apiVersion: route.openshift.io/v1 metadata: name: my-template-route annotations: template.openshift.io/expose-uri: "http://{.spec.host}{.spec.path}" spec: path: mypath
An example response to a bind
operation given the above partial template follows:
{ "credentials": { "username": "foo", "password": "YmFy", "service_ip_port": "172.30.12.34:8080", "uri": "http://route-test.router.default.svc.cluster.local/mypath" } }
Procedure
-
Use the
template.openshift.io/expose-
annotation to return the field value as a string. This is convenient, although it does not handle arbitrary binary data. -
If you want to return binary data, use the
template.openshift.io/base64-expose-
annotation instead to base64 encode the data before it is returned.
11.6.7. Waiting for template readiness
Template authors can indicate that certain objects within a template should be waited for before a template instantiation by the service catalog, Template Service Broker, or TemplateInstance
API is considered complete.
To use this feature, mark one or more objects of kind Build
, BuildConfig
, Deployment
, DeploymentConfig
, Job
, or StatefulSet
in a template with the following annotation:
"template.alpha.openshift.io/wait-for-ready": "true"
Template instantiation is not complete until all objects marked with the annotation report ready. Similarly, if any of the annotated objects report failed, or if the template fails to become ready within a fixed timeout of one hour, the template instantiation fails.
For the purposes of instantiation, readiness and failure of each object kind are defined as follows:
Kind | Readiness | Failure |
---|---|---|
| Object reports phase complete. | Object reports phase canceled, error, or failed. |
| Latest associated build object reports phase complete. | Latest associated build object reports phase canceled, error, or failed. |
| Object reports new replica set and deployment available. This honors readiness probes defined on the object. | Object reports progressing condition as false. |
| Object reports new replication controller and deployment available. This honors readiness probes defined on the object. | Object reports progressing condition as false. |
| Object reports completion. | Object reports that one or more failures have occurred. |
| Object reports all replicas ready. This honors readiness probes defined on the object. | Not applicable. |
The following is an example template extract, which uses the wait-for-ready
annotation. Further examples can be found in the Red Hat OpenShift Service on AWS quick start templates.
kind: Template apiVersion: template.openshift.io/v1 metadata: name: my-template objects: - kind: BuildConfig apiVersion: build.openshift.io/v1 metadata: name: ... annotations: # wait-for-ready used on BuildConfig ensures that template instantiation # will fail immediately if build fails template.alpha.openshift.io/wait-for-ready: "true" spec: ... - kind: DeploymentConfig apiVersion: apps.openshift.io/v1 metadata: name: ... annotations: template.alpha.openshift.io/wait-for-ready: "true" spec: ... - kind: Service apiVersion: v1 metadata: name: ... spec: ...
Additional recommendations
- Set memory, CPU, and storage default sizes to make sure your application is given enough resources to run smoothly.
-
Avoid referencing the
latest
tag from images if that tag is used across major versions. This can cause running applications to break when new images are pushed to that tag. - A good template builds and deploys cleanly without requiring modifications after the template is deployed.
11.6.8. Creating a template from existing objects
Rather than writing an entire template from scratch, you can export existing objects from your project in YAML form, and then modify the YAML from there by adding parameters and other customizations as template form.
Procedure
Export objects in a project in YAML form:
$ oc get -o yaml all > <yaml_filename>
You can also substitute a particular resource type or multiple resources instead of
all
. Runoc get -h
for more examples.The object types included in
oc get -o yaml all
are:-
BuildConfig
-
Build
-
DeploymentConfig
-
ImageStream
-
Pod
-
ReplicationController
-
Route
-
Service
-
Using the all
alias is not recommended because the contents might vary across different clusters and versions. Instead, specify all required resources.