Skip to content

Added section on creating from templates #314

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
adellape merged 1 commit into from
Apr 29, 2015
Merged

Added section on creating from templates #314

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 12 additions & 4 deletions architecture/core_objects/overview.adoc
View file
Open in desktop
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.
Copy link
Contributor

@adellape adellape Apr 27, 2015

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/seciton/section/

Copy link
Author

@bfallonf bfallonf Apr 27, 2015

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oops


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
Open in desktop
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
Copy link
Contributor

@bparees bparees Apr 27, 2015

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we probably still need some sort of link from the console doc to templates... eg a high level summary of "here's all the stuff you can do in the console (link, link, link)"

Copy link
Author

@bfallonf bfallonf Apr 27, 2015

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bparees Sorry, not too sure what you mean here too. Alex mentioned above that Bilhar's suggested that we split up the console doc and put all the bits into other topics, so the Creating from a Template section will be in this section after (if) this PR is merged.

Do you mean we should be linking to other parts of the docs to show what else can be created from templates?

Copy link
Contributor

@bparees bparees Apr 27, 2015

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if we're getting rid of the console section entirely I guess that's ok (sorry I didn't catch up on all the iteration that occurred while I was out) then...but I was assuming and think it would be better if we still have a section dedicated to the console that would cover at a high level what you can do from the console. As a user I don't want to have to read through specific sections to find out what i can do in the console. How I do those things in the console belong in the specific sections.

Copy link
Contributor

@adellape adellape Apr 27, 2015

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1

Copy link
Author

@bfallonf bfallonf Apr 27, 2015

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah ok. @bparees I see what you mean now. Including this doc as a whole might be something I can talk to @CowboysFan about. As for now, I've added a small section to the console doc about creating from templates, linking to here. It's really a placeholder; once we settle on what else should be here it might work better as a list or table or something.

Management Console by utilizing link:../dev_guide/templates.html[templates].
155 changes: 123 additions & 32 deletions dev_guide/templates.adoc
View file
Open in desktop
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>_`
****
Copy link
Contributor

@adellape adellape Apr 28, 2015

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(Unless I missed it in the PR conversation somewhere) Is there a reason this whole part (from "Alternatively" through the syntax sidebar) is in the "Uploading a Template" section? Seems like strange placement. The second half of the next section, "Generating a Configuration", rehashes this concept and shows an actual example, so why not move this there so the syntax and example are together?


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>_`
Copy link
Contributor

@bparees bparees Apr 27, 2015

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this example lists the parameters, it does not override them. if you want to override the parameter values, you use the -v flag, as in "osc process -v FOO=BAR,KEY=VAL -f mytemplate.json"

****

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
Open in desktop
Empty file.