Chapter 2. Projects
Chapter 2. Projects 2.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. Important Do not run workloads in or share access to default projects. Default projects are reserved for running core cluster components. The following default projects are considered highly privileged: default , kube-public , kube-system , openshift , openshift-infra , openshift-node , and other system-created projects that have the openshift.io/run-level label set to 0 or 1 . Functionality that relies on admission plugins, such as pod security admission, security context constraints, cluster resource quotas, and image reference resolution, does not work in highly privileged projects. 2.1.1. Creating a project You can use the OpenShift Container Platform web console or the OpenShift CLI ( oc ) to create a project in your cluster. 2.1.1.1. Creating a project by using the web console You can use the OpenShift Container Platform web console to create a project in your cluster. 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. Prerequisites Ensure that you have the appropriate roles and permissions to create projects, applications, and other workloads in OpenShift Container Platform. Procedure If you are using the Administrator perspective: Navigate to Home Projects . Click Create Project : In the Create Project dialog box, enter a unique name, such as myproject , in the Name field. Optional: Add the Display name and Description details for the project. Click Create . The dashboard for your project is displayed. Optional: Select the Details tab to view the project details. Optional: If you have adequate permissions for a project, you can use the Project Access tab to provide or revoke admin, edit, and view privileges for the project. If you are using the Developer perspective: Click the Project menu and select Create Project : Figure 2.1. Create project In the Create Project dialog box, enter a unique name, such as myproject , in the Name field. Optional: Add the Display name and Description details for the project. Click Create . Optional: Use the left navigation panel to navigate to the Project view and see the dashboard for your project. Optional: In the project dashboard, select the Details tab to view the project details. Optional: If you have adequate permissions for a project, you can use the Project Access tab of the project dashboard to provide or revoke admin, edit, and view privileges for the project. Additional resources Customizing the available cluster roles using the web console 2.1.1.2. Creating a project by 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 Run: USD oc new-project <project_name> \ --description="<description>" --display-name="<display_name>" For example: USD 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 might 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. 2.1.2. Viewing a project You can use the OpenShift Container Platform web console or the OpenShift CLI ( oc ) to view a project in your cluster. 2.1.2.1. Viewing a project by using the web console You can view the projects that you have access to by using the OpenShift Container Platform web console. Procedure If you are using the Administrator perspective: Navigate to Home Projects in the navigation menu. Select a project to view. The Overview tab includes a dashboard for your project. Select the Details tab to view the project details. Select the YAML tab to view and update the YAML configuration for the project resource. Select the Workloads tab to see workloads in the project. Select the RoleBindings tab to view and create role bindings for your project. If you are using the Developer perspective: Navigate to the Project page in the navigation menu. Select All Projects from the Project drop-down menu at the top of the screen to list all of the projects in your cluster. Select a project to view. The Overview tab includes a dashboard for your project. Select the Details tab to view the project details. If you have adequate permissions for a project, select the Project access tab view and update the privileges for the project. 2.1.2.2. 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 To view a list of projects, run: USD oc 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: USD oc project <project_name> 2.1.3. Providing access permissions to your project using the Developer perspective You can use the Project view in the Developer perspective to grant or revoke access permissions to your project. Prerequisites You have created a project. Procedure To add users to your project and provide Admin , Edit , or View access to them: In the Developer perspective, navigate to the Project page. Select your project from the Project menu. Select the Project Access tab. Click Add access to add a new row of permissions to the default ones. Figure 2.2. Project permissions Enter the user name, click the Select a role drop-down list, and select an appropriate role. Click Save to add the new permissions. You can also use: The Select a role drop-down list, to modify the access permissions of an existing user. The Remove Access icon, to completely remove the access permissions of an existing user to the project. Note Advanced role-based access control is managed in the Roles and Roles Binding views in the Administrator perspective. 2.1.4. Customizing the available cluster roles using the web console In the Developer perspective of the web console, the Project Project access page enables a project administrator to grant roles to users in a project. By default, the available cluster roles that can be granted to users in a project are admin, edit, and view. As a cluster administrator, you can define which cluster roles are available in the Project access page for all projects cluster-wide. You can specify the available roles by customizing the spec.customization.projectAccess.availableClusterRoles object in the Console configuration resource. Prerequisites You have access to the cluster as a user with the cluster-admin role. Procedure In the Administrator perspective, navigate to Administration Cluster settings . Click the Configuration tab. From the Configuration resource list, select Console operator.openshift.io . Navigate to the YAML tab to view and edit the YAML code. In the YAML code under spec , customize the list of available cluster roles for project access. The following example specifies the default admin , edit , and view roles: apiVersion: operator.openshift.io/v1 kind: Console metadata: name: cluster # ... spec: customization: projectAccess: availableClusterRoles: - admin - edit - view Click Save to save the changes to the Console configuration resource. Verification In the Developer perspective, navigate to the Project page. Select a project from the Project menu. Select the Project access tab. Click the menu in the Role column and verify that the available roles match the configuration that you applied to the Console resource configuration. 2.1.5. Adding to a project You can add items to your project by using the +Add page in the Developer perspective. Prerequisites You have created a project. Procedure In the Developer perspective, navigate to the +Add page. Select your project from the Project menu. Click on an item on the +Add page and then follow the workflow. Note You can also use the search feature in the Add* page to find additional items to add to your project. Click * under Add at the top of the page and type the name of a component in the search field. 2.1.6. Checking the project status You can use the OpenShift Container Platform web console or the OpenShift CLI ( oc ) to view the status of your project. 2.1.6.1. Checking project status by using the web console You can review the status of your project by using the web console. Prerequisites You have created a project. Procedure If you are using the Administrator perspective: Navigate to Home Projects . Select a project from the list. Review the project status in the Overview page. If you are using the Developer perspective: Navigate to the Project page. Select a project from the Project menu. Review the project status in the Overview page. 2.1.6.2. Checking project status by using the CLI You can review the status of your project by using the OpenShift CLI ( oc ). Prerequisites You have installed the OpenShift CLI ( oc ). You have created a project. Procedure Switch to your project: USD oc project <project_name> 1 1 Replace <project_name> with the name of your project. Obtain a high-level overview of the project: USD oc status 2.1.7. Deleting a project You can use the OpenShift Container Platform web console or the OpenShift CLI ( oc ) to delete a project. 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. 2.1.7.1. Deleting a project by using the web console You can delete a project by using the web console. Prerequisites You have created a project. You have the required permissions to delete the project. Procedure If you are using the Administrator perspective: Navigate to Home Projects . Select a project from the list. Click the Actions drop-down menu for the project and select Delete Project . Note The Delete Project option is not available if you do not have the required permissions to delete the project. In the Delete Project? pane, confirm the deletion by entering the name of your project. Click Delete . If you are using the Developer perspective: Navigate to the Project page. Select the project that you want to delete from the Project menu. Click the Actions drop-down menu for the project and select Delete Project . Note If you do not have the required permissions to delete the project, the Delete Project option is not available. In the Delete Project? pane, confirm the deletion by entering the name of your project. Click Delete . 2.1.7.2. Deleting a project by using the CLI You can delete a project by using the OpenShift CLI ( oc ). Prerequisites You have installed the OpenShift CLI ( oc ). You have created a project. You have the required permissions to delete the project. Procedure Delete your project: USD oc delete project <project_name> 1 1 Replace <project_name> with the name of the project that you want to delete. 2.2. Creating a project as another user Impersonation allows you to create a project as a different user. 2.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. 2.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: USD oc new-project <project> --as=<user> \ --as-group=system:authenticated --as-group=system:authenticated:oauth 2.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. 2.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 2.1. Default project template parameters 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 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. 2.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: Prerequisites You have access to an OpenShift Container Platform cluster using an account with cluster-admin permissions. Procedure Log in as a user with cluster-admin privileges. Generate the default project template: USD oc adm create-bootstrap-project-template -o yaml > template.yaml Use a text editor to modify the generated template.yaml file by adding objects or modifying existing objects. The project template must be created in the openshift-config namespace. Load your modified template: USD oc create -f template.yaml -n openshift-config Edit the project configuration resource using the web console or CLI. Using the web console: Navigate to the Administration Cluster Settings page. Click Configuration to view all configuration resources. Find the entry for Project and click Edit YAML . Using the CLI: Edit the project.config.openshift.io/cluster resource: USD oc edit project.config.openshift.io/cluster 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> # ... After you save your changes, create a new project to verify that your changes were successfully applied. 2.3.3. Disabling project self-provisioning You can prevent an authenticated user group from self-provisioning new projects. Procedure Log in as a user with cluster-admin privileges. View the self-provisioners cluster role binding usage by running the following command: USD oc describe clusterrolebinding.rbac self-provisioners Example output 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. 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: USD 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: USD oc adm policy \ remove-cluster-role-from-group self-provisioner \ system:authenticated:oauth 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: Run the following command: USD oc edit clusterrolebinding.rbac self-provisioners 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: USD oc patch clusterrolebinding.rbac self-provisioners -p '{ "metadata": { "annotations": { "rbac.authorization.kubernetes.io/autoupdate": "false" } } }' Log in as an authenticated user and verify that it can no longer self-provision a project: USD oc new-project test Example output 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. 2.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 Edit the project configuration resource using the web console or CLI. Using the web console: Navigate to the Administration Cluster Settings page. Click Configuration to view all configuration resources. Find the entry for Project and click Edit YAML . Using the CLI: Log in as a user with cluster-admin privileges. Edit the project.config.openshift.io/cluster resource: USD oc edit project.config.openshift.io/cluster 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. # ... 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.
oc new-project <project_name> --description="<description>" --display-name="<display_name>" oc new-project hello-openshift --description="This is an example project" --display-name="Hello OpenShift" oc get projects oc project <project_name> apiVersion: operator.openshift.io/v1 kind: Console metadata: name: cluster spec: customization: projectAccess: availableClusterRoles: - admin - edit - view oc project <project_name> 1 oc status oc delete project <project_name> 1 oc new-project <project> --as=<user> --as-group=system:authenticated --as-group=system:authenticated:oauth oc adm create-bootstrap-project-template -o yaml > template.yaml oc create -f template.yaml -n openshift-config oc edit project.config.openshift.io/cluster apiVersion: config.openshift.io/v1 kind: Project metadata: spec: projectRequestTemplate: name: <template_name> 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 oc patch clusterrolebinding.rbac self-provisioners -p '{"subjects": null}' oc adm policy remove-cluster-role-from-group self-provisioner system:authenticated:oauth oc edit clusterrolebinding.rbac self-provisioners apiVersion: authorization.openshift.io/v1 kind: ClusterRoleBinding metadata: annotations: rbac.authorization.kubernetes.io/autoupdate: "false" oc patch clusterrolebinding.rbac self-provisioners -p '{ "metadata": { "annotations": { "rbac.authorization.kubernetes.io/autoupdate": "false" } } }' oc new-project test Error from server (Forbidden): You may not request a new project via this API. You may not request a new project via this API. oc edit project.config.openshift.io/cluster apiVersion: config.openshift.io/v1 kind: Project metadata: spec: projectRequestMessage: <message_string> apiVersion: config.openshift.io/v1 kind: Project metadata: spec: projectRequestMessage: To request a project, contact your system administrator at projectname@example.com.