diff --git a/architecture/core_objects/overview.adoc b/architecture/core_objects/overview.adoc index 8d97ce35d5eb..7f64563a9e78 100644 --- a/architecture/core_objects/overview.adoc +++ b/architecture/core_objects/overview.adoc @@ -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]. diff --git a/dev_guide/console.adoc b/dev_guide/console.adoc index b24014ee60ee..e38580b9065f 100644 --- a/dev_guide/console.adoc +++ b/dev_guide/console.adoc @@ -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]. diff --git a/dev_guide/templates.adoc b/dev_guide/templates.adoc index eceafd538211..bdd1d4154047 100644 --- a/dev_guide/templates.adoc +++ b/dev_guide/templates.adoc @@ -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: ==== @@ -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 __ -l name=otherLabel` +$ `osc create -f __` **** -== 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 __` +$ `osc create -f __ -n __` +**** + +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 __` **** -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 __ | 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 __` -**** +==== -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 _