How To Make Chapter 8 Templates

8.i. Overview

A template describes a set of objects that tin can be parameterized and processed to produce a list of objects for creation by OpenShift Container Platform. A template can be processed to create anything yous have permission to create inside a project, for case services, build configurations, and deployment configurations. A template may as well ascertain a gear up of labels to apply to every object defined in the template.

You tin can create a listing 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.

8.two. Uploading a Template

If you have a JSON or YAML file that defines a template, for case as seen in this example, you tin can upload the template to projects using the CLI. This saves the template to the project for repeated apply by any user with advisable admission to that project. Instructions on writing your ain templates are provided later in this topic.

To upload a template to your current project'due south template library, pass the JSON or YAML file with the following command:

$ oc create -f <filename>

Yous can upload a template to a dissimilar project using the -n option with the name of the project:

$ oc create -f <filename> -due north <project>

The template is now available for selection using the web console or the CLI.

eight.3. Creating from Templates Using the Web Console

To create the objects from an uploaded template using the spider web panel:

While in the desired project, click Add to Projection :
Select a template from the list of templates in your projection, or provided by the global template library:
Change template parameters in the template creation screen:

Template proper noun and clarification.

Container images included in the template.

Parameters defined by the template. Y'all can edit values for parameters divers in the template here.

Labels to assign to all items included in the template. You can add and edit labels for objects.

8.4. Creating from Templates Using the CLI

Y'all can utilize the CLI to procedure templates and use the configuration that is generated to create objects.

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

There is also the power to add labels in the template from the command line.

$ oc procedure -f <filename> -l name=otherLabel

8.4.2. Parameters

The list of parameters that yous tin override are listed in the parameters section of the template. Yous can list them 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 procedure --parameters -n <project> <template_name>

For example, the following shows the output when listing the parameters for 1 of the Quickstart templates in the default openshift project:

$ oc procedure --parameters -n openshift runway-postgresql-example Name                         DESCRIPTION                                                                                              GENERATOR           VALUE SOURCE_REPOSITORY_URL        The URL of the repository with your application source code                                                                  https://github.com/openshift/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 information technology is not in the root of your repository APPLICATION_DOMAIN           The exposed hostname that volition route to the Rail service                                                                    rails-postgresql-case.openshiftapps.com GITHUB_WEBHOOK_SECRET        A secret string used to configure the GitHub webhook                                                     expression          [a-zA-Z0-9]{forty} 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 proper noun                                                                                                        postgresql POSTGRESQL_USER              database username                                                                                        expression          user[A-Z0-9]{3} POSTGRESQL_PASSWORD          database password                                                                                        expression          [a-zA-Z0-9]{eight} POSTGRESQL_DATABASE          database name                                                                                                                root POSTGRESQL_MAX_CONNECTIONS   database max connections                                                                                                     x 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.

8.4.3. Generating a List of Objects

Using the CLI, yous can 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 electric current projection:

$ oc procedure <template_name>

You lot can create objects from a template by processing the template and pipe the output to oc create:

$ oc procedure -f <filename> | oc create -f -

Alternatively, if the template has already been uploaded to the current projection:

$ oc process <template> | oc create -f -

Y'all can override any parameter values defined in the file by calculation the -v pick followed by a comma-separated list of <name>=<value> pairs. A parameter reference may appear in whatsoever text field inside the template items.

For instance, in the post-obit the POSTGRESQL_USER and POSTGRESQL_DATABASE parameters of a template are overridden to output a configuration with customized environment variables:

Example eight.1. Creating a Listing of Objects from a Template

$ oc procedure -f my-rails-postgresql \     -5 POSTGRESQL_USER=bob,POSTGRESQL_DATABASE=mydatabase

The JSON file tin 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 \     -v POSTGRESQL_USER=bob,POSTGRESQL_DATABASE=mydatabase \     | oc create -f -

8.5. Modifying an Uploaded Template

You can edit a template that has already been uploaded to your projection past using the following command:

$ oc edit template <template>

viii.half dozen. Using the Instant App and Quickstart Templates

OpenShift Container Platform provides a number of default Instant App and Quickstart templates to make it easy to speedily become started creating a new awarding for different languages. Templates are provided for Track (Ruby), Django (Python), Node.js, CakePHP (PHP), and Dancer (Perl). Your cluster administrator should take created these templates in the default, global openshift project so you have access to them. You can list the bachelor default Instant App and Quickstart templates with:

$ oc get templates -n openshift

If they are not available, directly your cluster ambassador to the Loading the Default Epitome Streams and Templates topic.

Past default, the templates build using a public source repository on GitHub that contains the necessary awarding code. In order to be able to alter the source and build your ain version of the application, y'all must:

Fork the repository referenced by the template's default SOURCE_REPOSITORY_URL parameter.
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 will now betoken to your fork of the application code, and y'all can modify the lawmaking and rebuild the application at will.

A walkthrough of this process using the spider web console is provided in Getting Started for Developers: Web Console.

Some of the Instant App and Quickstart templates define a database deployment configuration. The configuration they define uses ephemeral storage for the database content. These templates should be used for demonstration purposes only as all database information will be lost if the database pod restarts for any reason.

eight.vii. Writing Templates

Y'all tin define new templates to make it easy to recreate all the objects of your application. The template will ascertain the objects it creates along with some metadata to guide the creation of those objects.

8.7.i. Description

The template clarification covers information that informs users what your template does and helps them notice it when searching in the spider web console. In addition to general descriptive data, it includes a set of tags. Useful tags include the proper name of the linguistic communication your template is related to (eastward.g., java , php , cherry , etc.). In addition, adding the special tag instant-app causes your template to be displayed in the list of Instant Apps on the template selection page of the web console.

kind: "Template" apiVersion: "v1" metadata:   name: "cakephp-mysql-instance"                                                                  1                annotations:     openshift.io/display-name: "CakePHP MySQL Example"                                                                  2                clarification: "An instance CakePHP application with a MySQL database"                                                                  3                tags: "instant-app,php,cakephp,mysql"                                                                  four                iconClass: "icon-php"                                                                  5                message: "Your admin credentials are ${ADMIN_USERNAME}:${ADMIN_PASSWORD}"                                                                  vi

ane: The proper name of the template every bit information technology volition appear to users.
ii: A user-friendly proper name, which can be employed past user interfaces.
three: A description of the template.
4: Tags to be associated with the template for searching and grouping.
5: An icon to be displayed with your template in the spider web console.
half dozen: An instructional message that is displayed when this template is instantiated. This field should inform the user how to use the newly created resource. Parameter substitution is performed on the message before beingness displayed then that generated credentials and other parameters tin can be included in the output.

viii.7.2. Labels

Templates can include a set of labels. These labels will exist added to each object created when the template is instantiated. Defining a characterization in this manner makes it like shooting fish in a barrel for users to find and manage all the objects created from a particular template.

kind: "Template" apiVersion: "v1" ... labels:   template: "cakephp-mysql-example"                                                                  ane

1: A label that will be applied to all objects created from this template.

viii.7.iii. Parameters

Parameters allow a value to exist supplied by the user or generated when the template is instantiated. This is useful for generating random passwords or assuasive the user to supply a host name or other user-specific value that is required to customize the template. Parameters can be referenced by placing values in the form "${PARAMETER_NAME}" in place of whatsoever string field in the template.

kind: Template apiVersion: v1 objects:   - kind: BuildConfig     apiVersion: v1     metadata:       proper noun: cakephp-mysql-instance       annotations:         clarification: Defines how to build the awarding     spec:       source:         type: Git         git:           uri: "${SOURCE_REPOSITORY_URL}"                                                                  1                ref: "${SOURCE_REPOSITORY_REF}"         contextDir: "${CONTEXT_DIR}" parameters:   - name: SOURCE_REPOSITORY_URL                                                                  2                description: The URL of the repository with your application source code                                                                  3                value: https://github.com/openshift/cakephp-ex.git                                                                  4                required: true                                                                  5                - name: GITHUB_WEBHOOK_SECRET     description: A secret cord used to configure the GitHub webhook     generate: expression                                                                  6                from: "[a-zA-Z0-9]{40}"                                                                  7                bulletin: "... The GitHub webhook secret is ${GITHUB_WEBHOOK_SECRET} ..."                                                                  eight

ane: This value volition exist replaced with the value of the SOURCE_REPOSITORY_URL parameter when the template is instantiated.
two: The name of the parameter. This value is displayed to users and used to reference the parameter within the template.
3: A clarification of the parameter.
four: A default value for the parameter which will be used if the user does not override the value when instantiating the template.
v: Indicates this parameter is required, meaning the user cannot override information technology with an empty value. If the parameter does not provide a default or generated value, the user must supply a value.
6: A parameter which has its value generated via a regular expression-like syntax.
7: The input to the generator. In this case, the generator will produce a forty grapheme alphanumeric value including upper and lowercase characters.
eight: Parameters can exist included in the template message. This informs the user almost generated values.

8.7.4. Object List

The main portion of the template is the list of objects which will be created when the template is instantiated. This tin can be any valid API object, such as a BuildConfig , DeploymentConfig , Service , etc. The object will be created exactly as divers here, with any parameter values substituted in prior to creation. The definition of these objects can reference parameters defined earlier.

kind: "Template" apiVersion: "v1" objects:   - kind: "Service"                                                                  ane                apiVersion: "v1"     metadata:       name: "cakephp-mysql-instance"       annotations:         description: "Exposes and load balances the application pods"     spec:       ports:         - proper noun: "web"           port: 8080           targetPort: 8080       selector:         proper name: "cakephp-mysql-example"

1: The definition of a Service which volition be created by this template.

If an object definition'due south metadata includes a namespace field, the field will be stripped out of the definition during template instantiation. This is necessary because all objects created during instantiation are placed into the target namespace, so it would exist invalid for the object to declare a unlike namespace.

viii.7.5. Creating a Template from Existing Objects

Rather than writing an unabridged template from scratch, you can export existing objects from your project in template form, and then modify the template from there by calculation parameters and other customizations. To export objects in a project in template course, run:

$ oc consign all --as-template=<template_name> > <template_filename>

Y'all tin can also substitute a particular resource blazon or multiple resources instead of all . Run oc export -h for more examples.

The object types included in oc export all are:

BuildConfig
Build
DeploymentConfig
ImageStream
Pod
ReplicationController
Route
Service