Adding documentation for create from URL (aka, run on OpenShift)

and fixing heading semantics (several headings were improperly declared
as h3s or h4s when they should have been h2s or h3s).

_topic_map.yml

@@ -687,6 +687,8 @@ Topics:
     File: jobs
   - Name: Cron Jobs
     File: cron_jobs
+  - Name: Create from URL
+    File: create_from_url
   - Name: Revision History
     File: revhistory_dev_guide
     Distros: openshift-enterprise,openshift-dedicated

dev_guide/create_from_url.adoc

@@ -0,0 +1,86 @@
+[[dev-guide-create-from-url]]
+= Create from URL
+{product-author}
+{product-version}
+:data-uri:
+:icons:
+:experimental:
+:toc: macro
+:toc-title:
+:prewrap!:
+
+toc::[]
+
+[[overview]]
+== Overview
+
+Create From URL is a function that allows you to construct a URL from an image
+stream, image tag, or template.
+
+Create from URL only works with image streams or templates from
+namespaces that have been explicitly whitelisted.  The whitelist contains
+the 'openshift' namespace by default.  To add namespaces to the whitelist, see
+xref:../install_config/web_console_customization.adoc#configuring-the-create-
+from-url-namespace-whitelist[Configuring the Create From URL Namespace Whitelist].
+
+[[create-for-url-using-an-image-stream-and-image-tag]]
+== Using an Image Stream and Image Tag
+
+[[image-stream-and-image-tag-query-string-parameters]]
+=== Query String Parameters
+
+[options="header"]
+|===
+|Name|Description|Required|Schema|Default
+|imageStream|The value metadata.name as defined in the image stream to be used.|
+true|string|
+|imageTag|The value spec.tags.name as defined in the image stream to be used.|
+true|string|
+|namespace|The name of the namespace containing the image stream and image tag
+to use.|false|string|openshift
+|name|Identifies the resources created for this application.|false|string|
+|sourceURI|The git repository URL containing the application source code.|false|
+string|
+|sourceRef|The branch, tag, or commit for the application source code specified
+in sourceURI.|false|string|
+|contextDir|The subdirectory for the application source code specified in
+sourceURI, used as the context directory for the build.|false|string|
+|===
+
+[NOTE]
+====
+link:https://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters[Reserved characters] in parameter values should be URL encoded.
+====
+
+[[example-usage-of-an-image-stream-and-image-tag]]
+==== Example
+----
+ create?imageStream=nodejs&imageTag=4&name=nodejs&sourceURI=https%3A%2F%2Fgithub.com%2Fopenshift%2Fnodejs-ex.git&sourceRef=master&contextDir=%2F
+----
+
+[[create-from-url-using-a-template]]
+== Using a Template
+
+[[template-query-string-parameters]]
+=== Query String Parameters
+
+[options="header"]
+|===
+|Name|Description|Required|Schema|Default
+|template|The value of metadata.name as defined in the template to be used.|
+true|string|
+|templateParamsMap|A JSON parameters map containing the template parameter name
+and corresponding value you wish to override.|false|JSON|
+|namespace|The name of the namespace containing the template to use.|false|string|openshift
+|===
+
+[NOTE]
+====
+link:https://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters[Reserved characters] in parameter values should be URL encoded.
+====
+
+[[example-usage-of-a-template]]
+==== Example
+----
+ create?template=nodejs-mongodb-example&templateParamsMap={"SOURCE_REPOSITORY_URL"%3A"https%3A%2F%2Fgithub.com%2Fopenshift%2Fnodejs-ex.git"}
+----

install_config/web_console_customization.adoc

@@ -115,7 +115,7 @@ window.OPENSHIFT_EXTENSION_PROPERTIES = {
 ====
 
 [[customizing-the-logo]]
-=== Customizing the Logo
+== Customizing the Logo
 
 The following style changes the logo in the web console header:
 
@@ -142,7 +142,7 @@ assetConfig:
 ----
 
 [[changing-links-to-documentation]]
-=== Changing Links to Documentation
+== Changing Links to Documentation
 
 Links to external documentation are shown in various sections of the web
 console. The following example changes the URL for two given links to the
@@ -164,7 +164,7 @@ assetConfig:
 ----
 
 [[adding-or-changing-links-to-download-the-cli]]
-=== Adding or Changing Links to Download the CLI
+== Adding or Changing Links to Download the CLI
 
 The *About* page in the web console provides download links for the
 xref:../cli_reference/index.adoc#cli-reference-index[command line interface (CLI)] tools. These
@@ -250,9 +250,9 @@ assetConfig:
 ----
 
 [[configuring-navigation-menus]]
-=== Configuring Navigation Menus
+== Configuring Navigation Menus
 
-==== Top Navigation Dropdown Menus
+=== Top Navigation Dropdown Menus
 
 The top navigation bar of the web console contains the help icon and the user
 dropdown menus. You can add additional menu items to these using the
@@ -300,7 +300,7 @@ angular
 hawtioPluginLoader.addModule('<myExtensionModule>');
 ----
 
-==== Project Left Navigation
+=== Project Left Navigation
 
 When navigating within a project, a menu appears on the left with primary and
 secondary navigation. This menu structure is defined as a constant and can be
@@ -407,7 +407,7 @@ endif::[]
 endif::[]
 
 [[configuring-catalog-categories]]
-=== Configuring Catalog Categories
+== Configuring Catalog Categories
 
 Catalog categories organize the display of builder images and templates on the
 *Add to Project* page on the {product-title} web console. A builder image or
@@ -506,8 +506,58 @@ endif::[]
 
 endif::[]
 
+[[configuring-the-create-from-url-namespace-whitelist]]
+== Configuring the Create From URL Namespace Whitelist
+
+xref:../dev_guide/create_from_url.adoc#dev-guide-create-from-url[Create from URL]
+only works with image streams or templates from namespaces that have been
+explicitly specified in OPENSHIFT_CONSTANTS.CREATE_FROM_URL_WHITELIST.  To add
+namespaces to the whitelist, follow these steps:
+
+[NOTE]
+====
+'openshift' is included in the whitelist by default.  It should not be removed.
+====
+
+. Create the following configuration scripts within a file (for example,
+*_create-from-url-whitelist.js_*):
++
+====
+----
+// Add a namespace containing the image streams and/or templates
+window.OPENSHIFT_CONSTANTS.CREATE_FROM_URL_WHITELIST.push(
+  'shared-stuff'
+);
+----
+====
+
+. Save the file and add it to the master configuration at
+*_/etc/origin/master/master-config.yml_*:
++
+====
+----
+assetConfig:
+  ...
+  extensionScripts:
+    - /path/to/create-from-url-whitelist.js
+----
+====
+
+. Restart the master host:
++
+====
+ifdef::openshift-origin[]
+# systemctl restart origin-master
+endif::[]
+ifdef::openshift-enterprise[]
+# systemctl restart atomic-openshift-master
+endif::[]
+====
+
+endif::[]
+
 [[web-console-enable-wildcard-routes]]
-=== Enabling Wildcard Routes
+== Enabling Wildcard Routes
 
 If you enabled wildcard routes for a router, you can also enable wildcard
 routes in the web console. This lets users enter hostnames starting with an
@@ -532,7 +582,7 @@ xref:../install_config/router/default_haproxy_router.adoc#using-wildcard-routes[
 how to configure HAProxy routers to allow wildcard routes].
 
 [[web-console-enable-tech-preview-feature]]
-=== Enabling Features in Technology Preview
+== Enabling Features in Technology Preview
 
 Sometimes features are available in Technology Preview. By default, these
 features are disabled in the web console and hidden from end users.