Edits to self_provisioning file

admin_guide/selfprovisioned_projects.adoc

@@ -10,31 +10,105 @@
 toc::[]
 
 == Overview
-In some cases, it is desirable to allow users to create projects for themselves without administrator intervention.  To make this simpler, a user accessible endpoint is present that will provision a project according to a template.  This endpoint is made accessible via: `osc new-project <project-name>`.
+You can allow developers to create their own projects. An accessible endpoint
+exists that will provision a project according to a
+link:../dev_guide/templates.html[template]. This endpoint is made accessible
+when a developer link:../dev_guide/projects.html[creates a new project].
 
-== Configuration
-=== New project template
-The API server creates new auto-provisioned projects based on a template that it finds based on the `projectRequestTemplate` property of the master-config.yaml.  The property is in the form "namespace/templatename", by default "openshift/project-request".  If the template does not exist, the API server will create a default template that creates a project with the requested name and assigns the requesting user to the "admin" role for that project.  If the property is empty, then no action is taken and self-provisioning will fail.
+== Template for New Projects
+The API server automatically provisions projects based on the template that is
+defined in the `projectRequestTemplate` parameter of the *_master-config.yaml_*
+file. If the parameter is not defined, the API server creates a default template
+that creates a project with the requested name, and assigns the requesting user
+to the "admin" role for that project.
 
-If you want to change the way the shape of self-provisioned projects, you can change the template.  The API will substitute the following parameters into the template:
+You can create your own custom template by using the below as an example, and
+defining the desired template's location in the *_master-config.yaml_* file:
 
- .  PROJECT_NAME - name of the project
+.Example New Project Template
+====
+----
+apiVersion: v1beta3
+kind: Template
+metadata:
+  name: project-request
+  namespace: openshift
+objects:
+- apiVersion: v1beta1
+  displayName: ${PROJECT_DISPLAYNAME}
+  kind: Project
+  metadata:
+    annotations:
+      description: ${PROJECT_DESCRIPTION}
+      displayName: ${PROJECT_DISPLAYNAME}
+    creationTimestamp: null
+    name: ${PROJECT_NAME}
+  spec: {}
+  status: {}
+- apiVersion: v1beta1
+  groupNames: []
+  kind: RoleBinding
+  metadata:
+    creationTimestamp: null
+    name: admins
+    namespace: ${PROJECT_NAME}
+  roleRef:
+    name: admin
+  userNames:
+  - ${PROJECT_ADMIN_USER}
+parameters:
+- name: PROJECT_NAME <1>
+- name: PROJECT_DISPLAYNAME <2>
+- name: PROJECT_DESCRIPTION <3>
+- name: PROJECT_ADMIN_USER <4>
+----
 
- .  PROJECT_DISPLAYNAME = display name of the project (defaults to PROJECT_NAME)
+<1> The name of the project
+<2> The display name of the project. Defaults to *PROJECT_NAME*.
+<3> The description of the project. Defaults to *PROJECT_DISPLAYNAME*.
+<4> The name of the requesting user.
 
- .  PROJECT_DESCRIPTION = description of the project (defaults to PROJECT_DISPLAYNAME)
+====
+////
+The API substitutes the following parameters into the template:
 
- .  PROJECT_ADMIN_USER = name of the requesting user
+[cols="4,8",options="header"]
+|===
+|Parameter |Description
 
+|*PROJECT_NAME*
+|The name of the project
 
+|*PROJECT_DISPLAYNAME*
+|The display name of the project. Defaults to *PROJECT_NAME*.
 
-=== Permissions
-Access to this API is granted via the `self-provisioner` role and the `self-provisioners` cluster role binding.  By default, it is available to all authenticated users.  
+|*PROJECT_DESCRIPTION*
+|The description of the project. Defaults to *PROJECT_DISPLAYNAME*.
 
-=== Disabling auto-provisioning
-Deleting the `self-provisioners` cluster role binding will deny permissions for auto-provisioning new projects.  If you remove this permission, you should consider setting the `projectRequestMessage` option inside of the master-config.yaml file with instructions for how users can request a project.  That field is a string that will be presented to user in the webui and the cli when they attempt to self-provision a project.  Some common examples are:
+|*PROJECT_ADMIN_USER*
+|The name of the requesting user.
+|===
+////
 
- .  Call Bob at (555) 867-5309 to request a project
+Access to the API is granted to developers with the
+link:../dev_guide/authorization.html#roles[`self-provisioner` role] and the
+`self-provisioners` cluster role binding. This role is available to all
+authenticated developers by default.
 
- .  Fill out the project request form located at https://internal.example.com/openshift-project-request
-
+== Disabling Self-provisioning
+Deleting the `self-provisioners` link:../architecture/additional_concepts/authorization.html#roles[cluster role binding] will deny permissions for
+self-provisioning any new projects. When disabling self-provisioning, set the
+`projectRequestMessage` parameter in the *_master-config.yaml_* file instructing developers on how to request a new project. This parameter is a
+string that will be presented to the developer in the Management Console and
+command line when they attempt to self-provision a project. For example:
+
+----
+Contact your system administrator at [email protected] to request a project.
+----
+
+or:
+
+----
+To request a new project, fill out the project request form located at
+https://internal.example.com/openshift-project-request.
+----

dev_guide/projects.adoc

@@ -25,10 +25,10 @@ Constraints:: quota for the project, limit pods in a project to a pool of nodes
 
 To create a new project:
 
-****
-`$ osc new-project _<project_name>_ --description="_<description>_"
---display-name="_<display_name>_" --node-selector="_<label>_"`
-****
+----
+$ osc new-project <project_name> --description="<description>"
+--display-name="<display_name>" --node-selector="<label>"
+----
 
 For example:
 
@@ -43,24 +43,24 @@ demonstrate OpenShift v3" --display-name="Hello OpenShift"
 
 == Viewing Projects [[view-projects]]
 
-When you view projects, you are restricted to only seeing the projects you have
+When viewing projects, you are restricted to seeing only the projects you have
 access to view based on the
 link:../architecture/additional_concepts/authorization.html[authorization
 policy].
 
-To view the list of projects:
+To view a list of projects:
 
-****
-`$ osc get projects`
-****
+----
+$ osc get projects
+----
 
 You can change from the current project to a different project for CLI
 operations. The specified project is then used in all subsequent operations that
 manipulate project-scoped content:
 
-****
-`$ osc project _<project_name>_`
-****
+----
+$ osc project <project_name>
+----
 
 You can also use the
 link:../architecture/infrastructure_components/management_console.html[Management
@@ -86,9 +86,9 @@ overview] for that project.
 The `osc status` command provides a high-level overview of the current project,
 with its components and their relationships. This command takes no argument:
 
-****
-`$ osc status`
-****
+----
+$ osc status
+----
 
 == Filtering by Labels
 You can filter the contents of a project page in the
@@ -147,6 +147,6 @@ Terminating status, a user cannot add new content to the project.
 
 To delete a project:
 
-****
-`$ osc delete project _<project_name>_`
-****
+----
+$ osc delete project _<project_name>_
+----