$ oc create -f <filename>
×
Templates
Overview
A template describes a set of objects that 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 you have permission to create within a project, for example services, build configurations, and deployment configurations. A template may 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. For a curated set of templates, see the OpenShift Image Streams and Templates library.
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.
To upload a template to your current project’s template library, pass the JSON or YAML file with the following command:
You can 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 from Templates Using the Web Console
To create the objects from an uploaded template using the web console:
-
While in the desired project, click Add to Project:
-
Select a template from the list of templates in your project, or provided by the global template library:
-
Modify template parameters in the template creation screen:
1 Template name and description. 2 Container images included in the template. 3 Parameters defined by the template. You can edit values for parameters defined in the template here. 4 Labels to assign to all items included in the template. You can add and edit labels for objects.
Creating from Templates Using the CLI
You can use the CLI to process templates and use the configuration that is generated to create objects.
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 ability to add labels in the template from the command line.
$ oc process -f <filename> -l name=otherLabel
Parameters
The list of parameters that you can override are listed in the
parameters section of the template. You 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 process --parameters -n <project> <template_name>
For example, the following shows the output when listing the parameters for one of the Quickstart templates in the default openshift project:
$ oc process --parameters -n openshift rails-postgresql-example
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:
$ oc process -f <filename>
Alternatively, if the template has already been uploaded to the current project:
$ oc process <template_name>
You can 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 may appear 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:
example 1. 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=-
Modifying an Uploaded Template
You can edit a template that has already been uploaded to your project by using the following command:
$ oc edit template <template>
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 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 should have created these templates in the default, global openshift project so you have access to them. You can list the available default Instant App and Quickstart templates with:
$ oc get templates -n openshift
If they are not available, direct your cluster administrator to the Loading the Default Image Streams and Templates topic.
By default, the templates build using a public source repository on GitHub that contains the necessary application code. In order to be able to modify the source and build your own version of the application, you must:
-
Fork the repository referenced by the template’s default
SOURCe_RePOSITORY_URLparameter. -
Override the value of the
SOURCe_RePOSITORY_URLparameter 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 point to your fork of the application code, and you can modify the code and rebuild the application at will.
A walkthrough of this process using the 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 data will be lost if the database pod restarts for any reason. |
Writing Templates
You can define new templates to make it easy to recreate all the objects of your application. The template will define the objects it creates along with some metadata to guide the creation of those objects.
example 2. 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: masterDescription
The template description covers information that informs users what your template does and helps them find it when searching in the web console. In addition to general descriptive information, it includes a set of tags. Useful tags include the name of the language your template is related to (e.g., java, php, ruby, etc.).
example 3. Template Description Metadata
kind: "Template"
apiVersion: "v1"
metadata:
name: "cakephp-mysql-example" (1)
annotations:
openshift.io/display-name: "CakePHP MySQL example" (2)
description: "An example CakePHP application with a MySQL database.\n\nFor more information see https://github.com/sclorg/cakephp-ex" (3)
tags: "instant-app,php,cakephp,mysql" (4)
iconClass: "icon-php" (5)
message: "Your admin credentials are ${ADMIN_USeRNAMe}:${ADMIN_PASSWORD}" (6)| 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 the user will
understand what is being deployed and any caveats they need to know before
deploying. It should also provide links to additional information, such as a
ReADMe file. Newline characters \n can be included to create paragraphs. |
| 4 | Tags to be associated with the template for searching and grouping. Add tags
that will include it into one of the provided catalog categories. Refer to the
id and categoryAliases in CATALOG_CATeGORIeS in the console’s
constants
file.
The categories can also be
customized
for the whole cluster. |
| 5 | An icon to be displayed with your template in the web console. Choose from our existing logo icons when possible. You can also use icons from FontAwesome. Alternatively, provide icons through CSS customizations that can be added to an OpenShift Container Platform cluster that uses your template. You must specify an icon class that exists, or it will prevent falling back to the generic icon. |
| 6 | 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. |
Labels
Templates can include a set of labels. These labels will be 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.
example 4. Template Object Labels
kind: "Template"
apiVersion: "v1"
...
labels:
template: "cakephp-mysql-example" (1)| 1 | A label that will be applied to all objects created from this template. |
Parameters
Parameters allow a value to be supplied by the user 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 the user to supply a host name 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/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 will be substituted and the resulting value will be a quoted string.
When using the ${{PARAMeTeR_NAMe}} syntax only a single parameter reference is allowed and leading/trailing characters are not permitted. The resulting value will be 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 will be 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 the user does not supply a different value:
example 5. Setting an explicit Value as the Default Value
parameters:
- name: USeRNAMe
description: "The user name for Joe"
value: joeParameter values can also be generated based on rules specified in the parameter definition:
example 6. Generating a Parameter Value
parameters:
- name: PASSWORD
description: "The random user password"
generate: expression
from: "[a-zA-Z0-9]{12}"In the example above, processing will generate 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, 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}.
Here is an example of a full template with parameter definitions and references:
example 7. A full template with parameter definitions and references
kind: Template
apiVersion: v1
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)| 1 | This value will be replaced with the value of the SOURCe_RePOSITORY_URL
parameter when the template is instantiated. |
| 2 | This value will be 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 will be 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. Don’t make this a duplicate of the display name. |
| 6 | A default value for the parameter which will be used if the user does 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 the user cannot override it with an empty value. If the parameter does not provide a default or generated value, the user must supply a value. |
| 8 | A parameter which has its value generated. |
| 9 | The input to the generator. In this case, the generator will produce a 40 character alphanumeric value including upper and lowercase characters. |
| 10 | Parameters can be included in the template message. This informs the user about generated values. |
Object List
The main portion of the template is the list of objects which will be created
when the template is instantiated. This can be any
valid API object, such as a
BuildConfig, DeploymentConfig, Service, etc. The object will be
created exactly as defined 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" (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 will be created by this template. |
|
If an object definition’s metadata includes a fixed |
Other Recommendations
-
Group related services together in the management console by adding the
service.alpha.openshift.io/dependenciesannotation to the Service object in your template.example 8. Group the Frontend and Database Services Together on the Management Console Overviewkind: "Template" apiVersion: "v1" objects: - kind: "Service" apiVersion: "v1" metadata: name: "frontend" annotations: "service.alpha.openshift.io/dependencies": "[{\"name\": \"database\", \"kind\": \"Service\"}]" ... - kind: "Service" apiVersion: "v1" metadata: name: "database" -
Set memory, CPU, and storage default sizes to make sure your application is given enough resources to run smoothly.
-
Avoid referencing the
latesttag from images if that tag is used across major versions. This may 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 template form, and then modify the template from there by adding parameters and other customizations. To export objects in a project in template form, run:
$ oc export all --as-template=<template_name> > <template_filename>
You can also substitute a particular resource type 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