Managing Projects | Cluster Administration

Overview
Self-provisioning Projects
- Modifying the Template for New Projects
- Disabling Self-provisioning
Using Node Selectors

Overview

In OpenShift, projects are used to isolate content from groups of developers. As an OpenShift administrator, you can give developers access to certain projects, allow them to create their own, and give them administrator rights.

Self-provisioning Projects

You can allow developers to create their own projects. There is an endpoint that will provision a project according to a template. The web console and oc new-project command use this endpoint when a developer creates a new project.

Modifying the 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.

To create your own custom project template:

Start with the current default project template:

$ oadm create-bootstrap-project-template -o yaml > template.yaml

Modify the template by adding objects or modifying existing objects:
```
$ oc edit template template.yaml
```
Load the template:
```
$ oc create -f template.yaml -n default
```

Modify the master-config.yaml file to reference the loaded template:

...
projectConfig:
  projectRequestTemplate: "default/project-request"
  ...

When a project request is submitted, the API substitutes the following parameters into the template:

Parameter	Description
PROJECT_NAME	The name of the project. Required.
PROJECT_DISPLAYNAME	The display name of the project. May be empty.
PROJECT_DESCRIPTION	The description of the project. May be empty.
PROJECT_ADMIN_user	The username of the administrating user.
PROJECT_REQUESTING_user	The username of the requesting user.

Parameter

Description

PROJECT_NAME

The name of the project. Required.

PROJECT_DISPLAYNAME

The display name of the project. May be empty.

PROJECT_DESCRIPTION

The description of the project. May be empty.

PROJECT_ADMIN_user

The username of the administrating user.

PROJECT_REQUESTING_user

The username of the requesting user.

Access to the API is granted to developers with the self-provisioner role and the self-provisioners cluster role binding. This role is available to all authenticated developers by default.

Disabling Self-provisioning

You can prevent an authenticated user group from self-provisioning new projects.

Remove the self-provisioners cluster role from the group.

$ oadm policy remove-cluster-role-from-group self-provisioner system:authenticated system:authenticated:oauth

Set the projectRequestMessage parameter value in the master-config.yaml file to instruct developers how to request a new project. This parameter value is a string that will be presented to a user in the web console and command line when the user attempts to self-provision a project. You might use one of the following messages:
- To request a project, contact your system administrator at projectname@example.com.
- To request a new project, fill out the project request form located at https://internal.example.com/openshift-project-request.
Example YAML file
```
...
projectConfig:
  ProjectRequestMessage: "message"
  ...
```

Edit the self-provisioners cluster role to prevent automatic updates to the role. Automatic updates reset the cluster roles to the default state.

To update the role from the command line:

Run the following command:
```
$ oc edit clusterrole self-provisioner
```

In the displayed role, set the openshift.io/reconcile-protect parameter value to true, as shown in the following example:

apiVersion: authorization.openshift.io/v1
kind: ClusterRole
metadata:
  annotations:
    authorization.openshift.io/system-only: "true"
    openshift.io/description: A user that can request project.
    openshift.io/reconcile-protect: "true"
...

To update the role by using automation, use the following command:

$ oc patch clusterrole self-provisioner -p '{ "metadata": { "annotations": { "openshift.io/reconcile-protect": "true" } } }'

Using Node Selectors

Node selectors are used in conjunction with labeled nodes to control pod placement.

Labels can be assigned during an advanced installation, or added to a node after installation.

Setting the Cluster-wide Default Node Selector

As a cluster administrator, you can set the cluster-wide default node selector to restrict pod placement to specific nodes.

Edit the master configuration file at /etc/origin/master/master-config.yaml and add a value for a default node selector. This is applied to the pods created in all projects without a specified nodeSelector value:

...
projectConfig:
  defaultNodeSelector: "type=user-node,region=east"
...

Restart the OpenShift service for the changes to take effect:

# systemctl restart atomic-openshift-master

Setting the Project-wide Node Selector

To create an individual project with a node selector, use the --node-selector option when creating a project. For example, if you have an OpenShift topology with multiple regions, you can use a node selector to restrict specific OpenShift projects to only deploy pods onto nodes in a specific region.

The following creates a new project named myproject and dictates that pods be deployed onto nodes labeled user-node and east:

$ oadm new-project myproject \
    --node-selector='type=user-node,region=east'

Once this command is run, this becomes the adminstrator-set node selector for all pods contained in the specified project.

While the new-project subcommand is available for both oadm and oc, the cluster administrator and developer commands respectively, creating a new project with a node selector is only available with the oadm command. The new-project subcommand is not available to project developers when self-provisioning projects.

Using the oadm new-project command adds an annotation section to the project. You can edit a project, and change the openshift.io/node-selector value to override the default:

...
metadata:
  annotations:
    openshift.io/node-selector: type=user-node,region=east
...

If openshift.io/node-selector is set to an empty string (oadm new-project --node-selector=""), the project will not have an adminstrator-set node selector, even if the cluster-wide default has been set. This means that, as a cluster administrator, you can set a default to restrict developer projects to a subset of nodes and still enable infrastructure or other projects to schedule the entire cluster.

Developer-specified Node Selectors

OpenShift developers can set a node selector on their pod configuration if they wish to restrict nodes even further. This will be in addition to the project node selector, meaning that you can still dictate node selector values for all projects that have a node selector value.

For example, if a project has been created with the above annotation (openshift.io/node-selector: type=user-node,region=east) and a developer sets another node selector on a pod in that project, for example clearance=classified, the pod will only ever be scheduled on nodes that have all three labels (type=user-node, region=east, and clearance=classified). If they set region=west on a pod, their pods would be demanding nodes with labels region=east and region=west, which cannot work. The pods will never be scheduled, because labels can only be set to one value.