diff --git a/admin_guide/selfprovisioned_projects.adoc b/admin_guide/selfprovisioned_projects.adoc index eaade2fd5305..58f205a9280e 100644 --- a/admin_guide/selfprovisioned_projects.adoc +++ b/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 `. +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 projectname@example.com 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. +---- diff --git a/dev_guide/projects.adoc b/dev_guide/projects.adoc index 229a76052c0a..46a356e34ad3 100644 --- a/dev_guide/projects.adoc +++ b/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 __ --description="__" ---display-name="__" --node-selector="_