Using templates

The following sections provide an overview of templates, as well as how to use and create them.

Understanding templates

A template describes a set of objects that can be parameterized and processed to produce a list of objects for creation by OKD. 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.

Uploading a template

If you have a JSON or YAML file that defines a template, for example as seen in this example, 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 on writing your own templates are provided later in this topic.

Procedure

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

Creating an application by using the web console

You can use the web console to create an application from a template.

Procedure

1. While in the desired project, click Add to Project.

2. Select either a builder image from the list of images in your project, or from the service catalog.

   Only image stream tags that have the builder tag listed in their annotations appear in this list, as demonstrated here:

   kind: "ImageStream"
   apiVersion: "v1"
   metadata:
     name: "ruby"
     creationTimestamp: null
   spec:
     dockerImageRepository: "registry.redhat.io/rhscl/ruby-26-rhel7"
     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.

3. Modify the settings in the new application screen to configure the objects to support your application.

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.

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

Listing parameters

The list of parameters that you can override are listed in the parameters section of the template.

Procedure

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

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

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

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

3. 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 and POSTGRESQL_DATABASE parameters of a template are overridden to output a configuration with customized environment variables:

   1. Creating a List of objects from a template

      $ oc process -f my-rails-postgresql \
          -p POSTGRESQL_USER=bob \
          -p POSTGRESQL_DATABASE=mydatabase

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

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

   4. 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=-

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>

Using instant app and quick start templates

OKD provides a number of default instant app and quick start templates to make it easy to quickly get started creating a new application for different languages. Templates are provided for Rails (Ruby), Django (Python), Node.js, CakePHP (PHP), and Dancer (Perl). Your cluster administrator must create these templates in the default, global openshift project so you have access to them.

By default, the templates build using a public source repository on GitHub that contains the necessary application code.

Procedure

1. You can list the available default instant app and quick start templates with:

   $ oc get templates -n openshift

2. To modify the source and build your own version of the application:

   1. Fork the repository referenced by the template’s default SOURCE_REPOSITORY_URL parameter.

   2. Override the value of the SOURCE_REPOSITORY_URL parameter when creating from the template, specifying your fork instead of the default value.

      By doing this, the build configuration created by the template now points to your fork of the application code, and you can modify the code and rebuild the application at will.

Quick start templates

A quick start template is a basic example of an application running on OKD. Quick starts come in a variety of languages and frameworks, and are defined in a template, which is constructed from a set of services, build configurations, and deployment configurations. This template references the necessary images and source repositories to build and deploy the application.

To explore a quick start, create an application from a template. Your administrator must have already installed these templates in your OKD cluster, in which case you can simply select it from the web console.

Quick starts refer to a source repository that contains the application source code. To customize the quick start, fork the repository and, when creating an application from the template, substitute the default source repository name with your forked repository. This results in builds that are performed using your source code instead of the provided example source. You can then update the code in your source repository and launch a new build to see the changes reflected in the deployed application.

Web framework quick start templates

These quick start templates provide a basic application of the indicated framework and language:

• CakePHP: a PHP web framework that includes a MySQL database

• Dancer: a Perl web framework that includes a MySQL database

• Django: a Python web framework that includes a PostgreSQL database

• NodeJS: a NodeJS web application that includes a MongoDB database

• Rails: a Ruby web framework that includes a PostgreSQL database

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: 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

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: 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)

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)

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

  parameters:
  - name: singlequoted_example
    generate: expression
    from: ‘[\A]{10}’
  - name: doublequoted_example
    generate: expression
    from: “[\A]{10}”

{
    “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: v1
metadata:
  name: my-template
objects:
  - kind: BuildConfig
    apiVersion: 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: 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)

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"

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.

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.

The following is an example of different objects’ fields being exposed:

kind: Template
apiVersion: 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: bar
- 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: 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.

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:

The following is an example template extract, which uses the wait-for-ready annotation. Further examples can be found in the OKD quick start templates.

kind: Template
apiVersion: v1
metadata:
  name: my-template
objects:
- kind: BuildConfig
  apiVersion: 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: 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.

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. Run oc get -h for more examples.

  The object types included in oc get -o yaml all are:

  • BuildConfig

  • Build

  • DeploymentConfig

  • ImageStream

  • Pod

  • ReplicationController

  • Route

  • Service