Added section on creating from templates

[bfallonf]

Very much a WIP. Not sure if all the correct information is here.

@bparees @smarterclayton I asked @adellape a few questions about this today and he gave me a little more context. I'm not sure if "Project" is the thing that's actually being created from templates here. I can't find anything particularly indicative in my notes.

I'm particularly interested why this is explaining the same process as outlined later in the same file under the "Generating a Configuration" section... At least, the process Ben explained to me via email is essentially the same here.

[bparees]

i don't think we offer to upload a template today, do we?

[jcantrill]

@bparees we do not offer an 'upload' function unless this refers to a 'osc create -f '. I have considered adding some functionality to eclipse which would allow you to 'create app' from a template that you select from disk

[adellape]

@jcantrill Agreed, that section currently exists here: http://docs.openshift.org/latest/dev_guide/console.html#creating-from-template. Bilhar has suggested that that dev_guide/console.adoc topic will likely be broken up and absorbed into other relevant topics, so maybe this is an opportunity to just move it here now.

@bfallonf Item 1 in @bparees' list above would be a new section, like "Loading Templates to a Library" or something. E.g., when you try to browse the template library in the Mgmt Console before loading any, it says: "There are no templates to select from. To add a template to your project run osc create -f <template_file> -n testproject" ("testproject" is the name of the project I was viewing). This is related to your https://trello.com/c/yws1qwmQ that we talked about last night.

The Mgmt Console part of item 2 in the list is what you were describing with your WIP content. That flow assumes a template has already been loaded. This is what you could probably just pull/move Cesar's content mentioned above for.

The CLI part of item 2 and all of 3 in the list is what is currently in the "Generating a Configuration" section in this topic, though it needs to get updated (it still talks about osc apply instead of create).

[bfallonf]

@bparees Ok. I think it looks a lot better now. I've done as @jcantrill and @adellape suggested and moved across the console stuff (cos yes, I remember Bilhar talking about that too), and moved the Generating a Configuration stuff to the relevant part of the doc. I've also added in a small section about uploading the template to the library and reworded a few of the sentences. I have a few more questions though:

1. What exactly is being generated? At first I thought it was a template for a project, but above you've been using the word "stuff" and the docs now use "configuration". I take it a number of things can be created using a template? Is there a way I can find out exactly what can be created here so that I can make a list or something?
2. Is there a difference between osc create -f and osc process -f. The current CLI docs seem to state the same thing: https://github.com/openshift/openshift-docs/blob/master/cli_reference/basic_cli_operations.adoc#common-operations

and

https://github.com/openshift/openshift-docs/blob/master/cli_reference/basic_cli_operations.adoc#project-operations

1. @jcantrill Your work on Eclipse is mentioned here. Is there a trello card or something that I can attach myself to so I can see any changes this will need in the future?

Guys, thanks for your help on this!

[jcantrill]

@bfallonf In response to your questions:

1. A configuration is being generated from the template. Early releases it was actually a config kind but that has since been made more generic to just a list. A template is a parameterized list of openshift resources that once 'processed' will provide you with a list of resources that can be 'applied'/created in openshift. The resources can be any(at least almost any) valid OpenShift kind (e.g. service, pod, route, buildconfig, etc).

2. 'create' is simply create the resource. 'process' is template specific (I think) and means take the parameters defined in the template and substitute them throughout the list resources in the template and give me back a list of resources that can be created on the server.

In regards to the eclipse work, there are several cards listed here: https://trello.com/b/wqe9UaaZ/openshift-origin-developer-experience. Specifically, the ones either completed or in play are: https://trello.com/c/vv8XBZky and https://trello.com/c/f2fMXYjc

[adellape]

It would be nice to be linked here (probably on the word "resources" in the first sentence) to something that helps inform or remind what those resources could be. Maybe the best target right now would be http://docs.openshift.org/latest/architecture/core_objects/overview.html. It's a stub at the moment, but it would at least get them in the right subdir (to then check out kubernetes_model.adoc and openshift_model.adoc), and we can add some info there to give context.

Also a reminder to try and hard-wrap this line at 80 while you're in the file.

[adellape]

Thanks for filling this stub out. It's a bit of a misnomer to say the kubernetes_model topic outlines the "Kubernetes infrastructure", when in a neighboring directory we have infrastructure_components/kubernetes_infrastructure. Maybe something like:

"The following topics provide information on important resources in the link:kubernetes_model.html[Kubernetes model], which is extended by the link:openshift_model[OpenShift model]."

[bfallonf]

Changed to "The Kubernetes model topic provides information about important resources of your OpenShift instance, which is extended by the OpenShift model topic."

I think putting in "the following" might be specific to books or sections of the same topic.

[bfallonf]

@bparees @adellape I think this is it for comments. If there's anything else, please let me know. Otherwise, this might be ready to merge. Thanks all!

[Bilhar-rh]

@bparees @adellape @bfallonf The Dev Guide will be task based, with those tasks categorized. If any task can be accomplished with the CLI and the console, then we will document those there. The only way I see a separate console dir/topic is if customers can accomplish every CLI task in the console as well. Otherwise, we're going to keep our docs task focused, and that will result in this topic being broken up into those relevant tasks. Hope that makes sense.

[bparees]

@CowboysFan yeah i think so.

[bparees]

that command isn't uploading the template, it's just processing it from the filesystem, so the template doesn't end up in the template library.

[bfallonf]

Oh, now I get you. I've changed this to:

"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:"

[bparees]

i still don't like that we're calling this a "JSON string" everywhere. the user isn't trying to create a "JSON string", they're trying to create a definition of the objects they ultimately want to create in openshift.

[bfallonf]

Ok. I think I know what you mean. I've taken out the few references where it says JSON string, and worded around it so it sounds ok.

[bfallonf]

Made a few more changes after @bparees 's suggestions.

[adellape]

Most of the links in this topic are bad.

[bfallonf]

This took me a while, but fixed.

[bfallonf]

@adellape You're right, your other comment disappeared. I placed the "Alternatively..." section to your suggested place. I believe my reasoning was mistakenly about it serving both purposes; uploading and creating. But it isn't about uploading.

Let me know if there's anything for this PR.

[adellape]

Thanks for the updates. Merging.