Bug 1281926

(WIP) PR: https://github.com/openshift/openshift-docs/pull/2219

Doc plan: 
- Convert example in section "Output Without Creation" from JSON to YAML.
- Expand section "Output Without Creation" to include node-selection setting as an example of what to do in the "vi myapp.yaml" step.

This docs makes me confused.
Which part need I edit to add node-selector, in myapp project or the myapp.yaml get from 'oc new-app https://github.com/openshift/ruby-hello-world -o yaml > myapp.yaml'

(In reply to XiuJuan Wang from comment #4)
> This docs makes me confused.
> Which part need I edit to add node-selector, in myapp project or the
> myapp.yaml get from 'oc new-app
> https://github.com/openshift/ruby-hello-world -o yaml > myapp.yaml'

Thanks for the review.

Does this change help?
https://github.com/openshift/openshift-docs/pull/2219/commits/9b20c23416a060e1cc45e27e9a5692327f2b2f0b

@Thien
Did I get your point? My understand as below, but when replaced this yaml, got error

$oc new-project myapp

$oc get namespace myapp -o yaml > myapp.yaml

$vi myapp.yaml
apiVersion: v1
kind: Namespace
metadata:
  annotations:
    openshift.io/description: ""
    openshift.io/display-name: ""
    openshift.io/requester: xiuwang
    openshift.io/sa.scc.mcs: s0:c9,c4
    openshift.io/sa.scc.supplemental-groups: 1000080000/10000
    openshift.io/sa.scc.uid-range: 1000080000/10000
    openshift.io/node-selector: region=west
  creationTimestamp: 2016-06-23T03:02:19Z
  name: myapp
  resourceVersion: "71878"
  selfLink: /api/v1/namespaces/myapp

$oc replace -f myapp.yaml
Error from server: error when replacing "myapp.yaml": User "xiuwang" cannot update namespaces in project "myapp"

(In reply to XiuJuan Wang from comment #6)
> Did I get your point?

I think there is a misunderstanding.

> My understand as below, but when replaced this yaml, got error
>
> $oc new-project myapp
>
> $oc get namespace myapp -o yaml > myapp.yaml

In the beginning of the "Useful Edits" section, there is a link (with text "edits to make") that points to a sequence of commands:

$ oc new-app https://github.com/openshift/ruby-hello-world -o yaml > myapp.yaml
$ vi myapp.yaml
$ oc create -f myapp.yaml

In this sequence, the command that creates the myapp.yaml file is "oc new-app ... -o yaml", which differs from the command you gave above (using "oc get namespace").  In myapp.yaml created from "oc new-app", there are many objects, one of which is the "kind: Project" that the example in the "Useful Edits" section talks about.

To make this clearer, i've installed the change:
https://github.com/openshift/openshift-docs/pull/2219/commits/8764fe6f78116919453132d733dd27ce223326ae

Does that help?

My bad, so I need add the following code to myapp.yaml which comes from 'oc new-app https://github.com/openshift/ruby-hello-world -o yaml > myapp.yaml'

- apiVersion: v1
  kind: Project
  metadata:
    name: myapp
    annotations:
      openshift.io/node-selector: region=west

Unfortunately, I met error again.

$ oc create  -f  myapp.yaml 
imagestream "ruby-22-centos7" created
imagestream "ruby-hello-world" created
buildconfig "ruby-hello-world" created
deploymentconfig "ruby-hello-world" created
service "ruby-hello-world" created
Error from server: User "xiuwang" cannot create projects at the cluster scope

(In reply to XiuJuan Wang from comment #8)
1. create the myapp project.
2.Get the myapp.yaml
oc new-app https://github.com/openshift/ruby-hello-world -o yaml > myapp.yaml
3.Add below code to myapp.yaml
- apiVersion: v1
  kind: Project
  metadata:
    name: myapp
    annotations:
      openshift.io/node-selector: region=infra
4.Create resources via myapp.yaml
$oc  create -f myapp.yaml 
imagestream "ruby-22-centos7" created
imagestream "ruby-hello-world" created
buildconfig "ruby-hello-world" created
deploymentconfig "ruby-hello-world" created
service "ruby-hello-world" created
Error from server: User "xiuwang" cannot create projects at the cluster scope
5.Check if the pod is created in region=infra node
 oc get pods  -o wide 
NAME                       READY     STATUS    RESTARTS   AGE       NODE
ruby-hello-world-1-build   1/1       Running   0          5m        openshift-108.lab.sjc.redhat.com


@Thien-Thi
You can see the pod is be assigeed to related node, but has a error in the step 4.

(In reply to XiuJuan Wang from comment #9)
 My apology, I add the below code to wrong code level.
 Should add in the first code level, before I add it to the second level.No error in the comment #9 when create myapp.yaml now

apiVersion: v1
kind: Project
metadata:
  name: myapp
  annotations:
    openshift.io/node-selector: region=infra

(In reply to XiuJuan Wang from comment #10)
> (In reply to XiuJuan Wang from comment #9)
>  My apology, I add the below code to wrong code level.
>  Should add in the first code level, before I add it to the second level.No
> error in the comment #9 when create myapp.yaml now
>
> apiVersion: v1
> kind: Project
> metadata:
>   name: myapp
>   annotations:
>     openshift.io/node-selector: region=infra

Thank-you for the update.  Based on this feedback
(and on playing w/ the docs team ose v3 test instance)
i have installed:
https://github.com/openshift/openshift-docs/pull/2219/commits/486405a9ccbc6b14e307f2506d43c2c5ff728532

Do you think this would have helped initially?

PR has been rebased.  Pretty rendering here:
http://file.brq.redhat.com/~tnguyen/bz1281926/new_app.html

Commit pushed to master at https://github.com/openshift/openshift-docs

https://github.com/openshift/openshift-docs/commit/6eac8f9f85c0b8fcead0a0810f311125b9c75948
Merge pull request #2219 from tnguyen-rh/bz1281926

Fixes bug 1281926 -- add node placement info to 'oc new-app' description.

> Do you think this would have helped initially?

PR merged; if there are any problems, we can open a new BZ.
Moving status to RELEASE_PENDING.

@Thien Acctually we need the project code to the first level(not the second level) in the myapp.yaml, otherwise will met error in comment #9.

(In reply to XiuJuan Wang from comment #15)
> Acctually we need the project code to the first level(not the second
> level) in the myapp.yaml, otherwise will met error in comment #9.

I think "first" and "second" are confusing terms, because it depends where you start to count (from one or from zero).  Most non-programmers count from one (thus "first" means 1).  Some programmers count from zero (thus "first" means 0).

In this case, putting on my programmer hat, level 0 defines a single field ‘items’ (of ‘kind: List’), level 1 defines several objects of ‘kind: ImageStream’.  The new ‘kind: Project’ object should be added at level 1 (and not level 2), as you correctly noted in your feedback.

The reason i say "second" in the documentation is because the audience is more likely to be non-programmers than programmers.  In any case, i added the qualifier "peer to ImageStream"  to clarify further, and expanded the fragment to show the relationship between the new Project and the existing ImageStream definitions.

I'll leave the text as-is for now.  Thanks very much for your reviews.

(BTW, my given name is "Thien-Thi", not "Thien".  Do you prefer "Xiu" or "XiuJuan" or something else?)

@Thien-Thi you can call me Xiujuan ：）
More clear now, thanks your detailed feedback. :)

Docs live:
https://docs.openshift.com/enterprise/3.2/dev_guide/new_app.html#useful-edits

Moving status to CLOSED CURRENTRELEASE.