Red Hat Training

A Red Hat training course is available for OpenShift Container Platform

Chapter 1. Projects

1.1. Working with projects

A project allows a community of users to organize and manage their content in isolation from other communities.

Note

Projects starting with openshift- and kube- are default projects. These projects host cluster components that run as Pods and other infrastructure components. As such, OpenShift Container Platform does not allow you to create Projects starting with openshift- or kube- using the oc new-project command. Cluster administrators can create these Projects using the oc adm new-project command.

1.1.1. Creating a project using the web console

If allowed by your cluster administrator, you can create a new project.

Note

Projects starting with openshift- and kube- are considered critical by OpenShift Container Platform. As such, OpenShift Container Platform does not allow you to create Projects starting with openshift- using the web console.

Procedure

  1. Navigate to Home → Projects.
  2. Click Create Project.
  3. Enter your project details.
  4. Click Create.

1.1.2. Creating a project using the CLI

If allowed by your cluster administrator, you can create a new project.

Note

Projects starting with openshift- and kube- are considered critical by OpenShift Container Platform. As such, OpenShift Container Platform does not allow you to create Projects starting with openshift- or kube- using the oc new-project command. Cluster administrators can create these Projects using the oc adm new-project command.

Procedure

  1. Run: 
$ oc new-project <project_name> \
    --description="<description>" --display-name="<display_name>"

For example: 

$ oc new-project hello-openshift \
    --description="This is an example project" \
    --display-name="Hello OpenShift"
Note

The number of projects you are allowed to create may be limited by the system administrator. After your limit is reached, you might have to delete an existing project in order to create a new one.

1.1.3. Viewing a project using the web console

Procedure

  1. Navigate to Home → Projects.

  2. Select a project to view.

    On this page, click the Resources button to see workloads in the project and click the Dashboard button to see metrics and details about the project.

1.1.4. Viewing a project using the CLI

When viewing projects, you are restricted to seeing only the projects you have access to view based on the authorization policy.

Procedure

  1. To view a list of projects, run: 

    $ oc get projects

  2. 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: 

    $ oc project <project_name>

1.1.5. Adding to a project

Procedure

  1. Navigate to Home → Projects.
  2. Select a project.
  3. In the upper right-hand corner of the Project Status menu, click Add, then choose from the provided options.

1.1.6. Checking project status using the web console

Procedure

  1. Navigate to Home → Projects.
  2. Select a project to see its status.

1.1.7. Checking project status using the CLI

Procedure

  1. Run: 

    $ oc status

    This command provides a high-level overview of the current project, with its components and their relationships.

1.1.8. Deleting a project using the web console

Procedure

  1. Navigate to Home → Projects.
  2. Locate the project that you want to delete from the list of projects.
  3. On the far right side of the project listing, select Delete Project from the menu. If you do not have permissions to delete the project, the Delete Project option is grayed out and the option is not clickable.

1.1.9. Deleting a project using the CLI

When you delete a project, the server updates the project status to Terminating from Active. Then, the server clears all content from a project that is in the Terminating state before finally removing the project. While a project is in Terminating status, you cannot add new content to the project. Projects can be deleted from the CLI or the web console.

Procedure

  1. Run: 

    $ oc delete project <project_name>

1.2. Creating a project as another user

Impersonation allows you to create a project as a different user.

1.2.1. API impersonation

You can configure a request to the OpenShift Container Platform API to act as though it originated from another user. For more information, see User impersonation in the Kubernetes documentation.

1.2.2. Impersonating a user when you create a project

You can impersonate a different user when you create a project request. Because system:authenticated:oauth is the only bootstrap group that can create project requests, you must impersonate that group.

Procedure

  • To create a project request on behalf of a different user: 

    $ oc new-project <project> --as=<user> \
    --as-group=system:authenticated --as-group=system:authenticated:oauth

1.3. Configuring project creation

In OpenShift Container Platform, projects are used to group and isolate related objects. When a request is made to create a new project using the web console or oc new-project command, an endpoint in OpenShift Container Platform is used to provision the project according to a template, which can be customized.

As a cluster administrator, you can allow and configure how developers and service accounts can create, or self-provision, their own projects.

1.3.1. About project creation

The OpenShift Container Platform API server automatically provisions new projects based on the project template that is identified by the projectRequestTemplate parameter in the cluster’s project configuration resource. 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.

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

Table 1.1. Default project template parameters

ParameterDescription

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 user name of the administrating user.

PROJECT_REQUESTING_USER

The user name 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.

1.3.2. Modifying the template for new projects

As a cluster administrator, you can modify the default project template so that new projects are created using your custom requirements.

To create your own custom project template:

Procedure

  1. Log in as a user with cluster-admin privileges.

  2. Generate the default project template: 

    $ oc adm create-bootstrap-project-template -o yaml > template.yaml
  3. Use a text editor to modify the generated template.yaml file by adding objects or modifying existing objects.

  4. The project template must be created in the openshift-config namespace. Load your modified template: 

    $ oc create -f template.yaml -n openshift-config

  5. Edit the project configuration resource using the web console or CLI.

    • Using the web console:

      1. Navigate to the Administration → Cluster Settings page.
      2. Click Global Configuration to view all configuration resources.
      3. Find the entry for Project and click Edit YAML.

    • Using the CLI:

      1. Edit the project.config.openshift.io/cluster resource: 

        $ oc edit project.config.openshift.io/cluster

  6. Update the spec section to include the projectRequestTemplate and name parameters, and set the name of your uploaded project template. The default name is project-request.

    Project configuration resource with custom project template

    apiVersion: config.openshift.io/v1
kind: Project
metadata:
  ...
spec:
  projectRequestTemplate:
    name: <template_name>

  7. After you save your changes, create a new project to verify that your changes were successfully applied.

1.3.3. Disabling project self-provisioning

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

Procedure

  1. Log in as a user with cluster-admin privileges.

  2. View the self-provisioners cluster role binding usage by running the following command: 

    $ oc describe clusterrolebinding.rbac self-provisioners

Name:		self-provisioners
Labels:		<none>
Annotations:	rbac.authorization.kubernetes.io/autoupdate=true
Role:
  Kind:	ClusterRole
  Name:	self-provisioner
Subjects:
  Kind	Name				Namespace
  ----	----				---------
  Group	system:authenticated:oauth

    Review the subjects in the self-provisioners section.

  3. Remove the self-provisioner cluster role from the group system:authenticated:oauth.

    • If the self-provisioners cluster role binding binds only the self-provisioner role to the system:authenticated:oauth group, run the following command: 

      $ oc patch clusterrolebinding.rbac self-provisioners -p '{"subjects": null}'

    • If the self-provisioners cluster role binding binds the self-provisioner role to more users, groups, or service accounts than the system:authenticated:oauth group, run the following command: 

      $ oc adm policy \
    remove-cluster-role-from-group self-provisioner \
    system:authenticated:oauth

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

    • To update the role binding using the CLI:

      1. Run the following command: 

        $ oc edit clusterrolebinding.rbac self-provisioners

      2. In the displayed role binding, set the rbac.authorization.kubernetes.io/autoupdate parameter value to false, as shown in the following example: 

        apiVersion: authorization.openshift.io/v1
kind: ClusterRoleBinding
metadata:
  annotations:
    rbac.authorization.kubernetes.io/autoupdate: "false"
  ...

    • To update the role binding by using a single command: 

      $ oc patch clusterrolebinding.rbac self-provisioners -p '{ "metadata": { "annotations": { "rbac.authorization.kubernetes.io/autoupdate": "false" } } }'

  5. Login as an authenticated user and verify that it can no longer self-provision a project: 

    $ oc new-project test

Error from server (Forbidden): You may not request a new project via this API.

    Consider customizing this project request message to provide more helpful instructions specific to your organization.

1.3.4. Customizing the project request message

When a developer or a service account that is unable to self-provision projects makes a project creation request using the web console or CLI, the following error message is returned by default: 

You may not request a new project via this API.

Cluster administrators can customize this message. Consider updating it to provide further instructions on how to request a new project specific to your organization. For example:

  • 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.

To customize the project request message:

Procedure

  1. Edit the project configuration resource using the web console or CLI.

    • Using the web console:

      1. Navigate to the Administration → Cluster Settings page.
      2. Click Global Configuration to view all configuration resources.
      3. Find the entry for Project and click Edit YAML.

    • Using the CLI:

      1. Log in as a user with cluster-admin privileges.

      2. Edit the project.config.openshift.io/cluster resource: 

        $ oc edit project.config.openshift.io/cluster

  2. Update the spec section to include the projectRequestMessage parameter and set the value to your custom message:

    Project configuration resource with custom project request message

    apiVersion: config.openshift.io/v1
kind: Project
metadata:
  ...
spec:
  projectRequestMessage: <message_string>

    For example: 

    apiVersion: config.openshift.io/v1
kind: Project
metadata:
  ...
spec:
  projectRequestMessage: To request a project, contact your system administrator at projectname@example.com.
  3. After you save your changes, attempt to create a new project as a developer or service account that is unable to self-provision projects to verify that your changes were successfully applied.