$ oc create -f <filename>
The following sections provide an overview of templates, as well as how to use and create them.
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 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.
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.
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.
You can use the web console to create an application from a template.
While in the desired project, click Add to Project.
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 |
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. |
Modify the settings in the new application screen to configure the objects to support your application.
You can use the CLI to process templates and use the configuration that is generated to create objects.
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.
Add labels in the template from the command line:
$ oc process -f <filename> -l name=otherLabel
The list of parameters that you can override are listed in the parameters
section of the template.
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
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.
Using the CLI, you can process a file defining a template to return the list of objects to standard output.
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
and POSTGRESQL_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=-
You can edit a template that has already been uploaded to your project.
Modify a template that has already been uploaded:
$ oc edit template <template>
OpenShift Container Platform 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.
You can list the available default instant app and quick start templates with:
$ oc get templates -n openshift
To modify the source and build your own version of the application:
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 now points to your fork of the application code, and you can modify the code and rebuild the application at will.
Some of the instant app and quick start 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 is lost if the database pod restarts for any reason. |
A quick start template is a basic example of an application running on OpenShift Container Platform. 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 OpenShift Container Platform 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.
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
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
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: >-