Skip to content

Commit

Permalink
Merge pull request #314 from bfallonf/app_templates
Browse files Browse the repository at this point in the history 
Added section on creating from templates
  • Loading branch information
@adellape
adellape committed Apr 29, 2015
2 parents 452ee9e + 93e21ea commit a43142f
Show file tree
Hide file tree
Showing 4 changed files with 138 additions and 66 deletions.
16 changes: 12 additions & 4 deletions architecture/core_objects/overview.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,15 @@
:icons:
:experimental:

If you'd like to contribute to OpenShift documentation, see our
https://github.com/openshift/openshift-docs[source repository] and
https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/doc_guidelines.adoc[guidelines]
to get started.
The link:../../architecture/core_objects/kubernetes_model.html[Kubernetes model]
topic provides information about important resources of your OpenShift instance,
which is extended by the
link:../../architecture/core_objects/openshift_model.html[OpenShift model] topic.

The link:../../architecture/core_objects/builds.html[Builds] section outlines how
to create a working image from a build object, and the
link:../../architecture/core_objects/routing.html[Routing] section outlines the
routing process.

You can create many of these resources by utilizing
link:../../dev_guide/templates.html[templates].
33 changes: 3 additions & 30 deletions dev_guide/console.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,33 +70,6 @@ image:console_filter_step3.png["Console Filter Step 3"]
image:console_filter_active.png["Console Filter Active"]
====


== Creating from Template

A link:templates.html[template] describes a set of resources that can be created together. To create an instance from a template using the Management Console:

1. Click on the *Create* button:
+
====
image:console_create.png["Console Create"]
====

2. Select a template from the list of templates in your project, or provided by OpenShift:
+
====
image:console_select_template.png["Select Template"]
====

3. Modify template parameters. Labels and parameters can be modified in the template creation screen:
+
====
image:create_from_template.png["Create from Template"]
====
+
<1> Template name and description.
<2> Container images included in the template.
<3> Labels to assign to all items included in the template. You can add and edit labels for resources.
<4> Parameters defined by the template. You can edit values for parameters defined in the template here.
== Creating a Configuration From a Template
You can create many important Kubernetes and OpenShift resources from the
Management Console by utilizing link:../dev_guide/templates.html[templates].
155 changes: 123 additions & 32 deletions dev_guide/templates.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,12 @@
toc::[]

== Overview
A template describes a set of resources intended to be used together that can be customized and processed to produce a configuration. Each template defines a list of parameters that can be modified for consumption by containers. It also defines a set of labels to apply to every resource created by the template.
A template describes a set of
link:../architecture/core_objects/overview.html[resources] that can be
customized and processed to produce a configuration. Each template is a
parameterized list that is used by OpenShift to create a list of resources,
including services, pods, routes, buildconfigs, etc. A template also defines a
set of labels to apply to every resource created by the template.

.Sample Template JSON File:
====
Expand Down Expand Up @@ -51,67 +56,153 @@ A template describes a set of resources intended to be used together that can be
====

== Labels
link:../architecture/kubernetes_model.html#label[Labels] are used to manage and organize generated resources, such as pods. The labels specified in the template are applied to every resource that is generated from the template.
== Creating a Configuration From a Template
You can create a configuration from a template using the CLI or, if a template
has been uploaded to your project or global template library, using the
Management Console.

There is also the ability to add labels in the template from the command line.
Create a template JSON file, like the above example, then upload it with the
CLI using the following process:

=== Uploading a Template
You can upload a template to your current project's template library by passing
a JSON file with the following command:

****
`$ osc process -f _<filename>_ -l name=otherLabel`
$ `osc create -f _<filename>_`
****

== Parameters
The list of parameters that you can override are listed in the `*parameters*` section of the template. Alternatively, you can override them with the following command, specifying the file to be used:
You can upload a template to a different project using the `-n` option with the
name of the project:

****
`$ osc process --parameters -f _<filename>_`
$ `osc create -f _<filename>_ -n _<project>_`
****

The template is now available to be selected for a configuration using the
Management Console or the CLI.

=== Generating a Configuration
Generate a configuration with the following command:

****
$ `osc process -f _<filename>_`
****

The following shows the output when listing the parameters for one of the *_openshift/origin/examples_* templates.
Alternatively, you can create from a template without uploading it to the
template library by processing the template and creating from the same template
by piping both commands:

.Example Template Output
****
$ `osc process -f _<filename.json>_ | osc create -f -`
****

You can override any link:../dev_guide/templates.html#parameters[parameters]
defined in the JSON file by adding the `-v` option and any desired parameters.
For example, you can override the *`ADMIN_USERNAME`* and *`MYSQL_DATABASE`*
parameters to create a configuration with customized environment variables:

.Generating a Configuration
====
----
$ osc process --parameters -f examples/sample-app/application-template-dockerbuild.json
NAME DESCRIPTION GENERATOR VALUE
ADMIN_USERNAME administrator username expression admin[A-Z0-9]{3}
ADMIN_PASSWORD administrator password expression [a-zA-Z0-9]{8}
MYSQL_ROOT_PASSWORD database password expression [a-zA-Z0-9]{8}
MYSQL_DATABASE database name root
$ osc process -f examples/sample-app/application-template-dockerbuild.json -v
ADMIN_USERNAME=root,MYSQL_DATABASE=admin
----
====

The output identifies several parameters that are generated with a regex expression generator when the template is processed.
The JSON file can either be redirected to a file or applied directly without
uploading the template by piping the process output to the `create` command:

== Generating a Configuration
When OpenShift processes a template, it creates a configuration. You can override the parameters with the values defined in the configuration file by adding the appropriate flags.
====
Generate a configuration with the following command:
----
$ osc process -f examples/sample-app/application-template-dockerbuild.json -v
ADMIN_USERNAME=root,MYSQL_DATABASE=admin | osc create -f -
----
****
`osc process -f _<filename>_`
****
====

Continuing with the previous example, you can override the *`ADMIN_USERNAME`* and *`MYSQL_DATABASE`* environment variables to create a JSON string to apply to the server. The JSON string represents a configuration with customized environment variables, as shown in the following example.
=== Creating from Template

.Generating a Configuration
To create a configuration from an link:#uploading-a-template[uploaded template]
using the Management Console:

1. While in the desired project, click on the *Create+* button:
+
====
----
$ osc process -f examples/sample-app/application-template-dockerbuild.json -v ADMIN_USERNAME=root,MYSQL_DATABASE=admin
----
image:console_create.png["Console Create"]
====

2. Select a template from the list of templates in your project, or provided by
the global template library:
+
====
The JSON string can either be redirected to a file or applied directly by piping the process output to the `apply` command, as shown in the following example.
image:console_select_template.png["Select Template"]
====

3. Modify template parameters in the template creation screen:
+
====
image:create_from_template.png["Create from Template"]
====
+
<1> Template name and description.
<2> Container images included in the template.
<3> Labels to assign to all items included in the template. You can add and edit
labels for resources.
<4> Parameters defined by the template. You can edit values for parameters
defined in the template here.

=== Modifying an Uploaded Template
You can edit a template that has already been uploaded to your project by using
the following command:

****
$ `osc edit template _<template>_`
****

== Labels
link:../architecture/core_objects/kubernetes_model.html#label[Labels]
are used to manage and organize generated resources, such as pods. The labels
specified in the template are applied to every resource that is generated from
the template.

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

****
`$ osc 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:

****
`$ osc process --parameters -f _<filename>_`
****

The following shows the output when listing the parameters for one of the
link:..https://github.com/openshift/origin/tree/master/examples[*_openshift/origin/examples_*]
templates:

.Redirecting JSON String
====
----
$ osc process -f examples/sample-app/application-template-dockerbuild.json -v ADMIN_USERNAME=root,MYSQL_DATABASE=admin | osc apply -f -
----
$ osc process --parameters -f
examples/sample-app/application-template-dockerbuild.json NAME
DESCRIPTION GENERATOR VALUE ADMIN_USERNAME
administrator username expression admin[A-Z0-9]{3} ADMIN_PASSWORD
administrator password expression [a-zA-Z0-9]{8} MYSQL_ROOT_PASSWORD
database password expression [a-zA-Z0-9]{8} MYSQL_DATABASE
database name root ----
====

The output identifies several parameters that are generated with a regex
expression generator when the template is processed.
Empty file added export
View file
Empty file.

0 comments on commit a43142f

Please sign in to comment.