Soon, all Red Hat OpenShift documentation will only be available on docs.redhat.com, the official location of all Red Hat product documentation. Get familiar with the updated experience today!
  1. Documentation
×

Working with projects

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

Projects starting with openshift- and kube- are default projects. These projects host cluster components that run as pods and other infrastructure components. As such, OKD 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.

You cannot assign an SCC to pods created in one of the default namespaces: default, kube-system, kube-public, openshift-node, openshift-infra, and openshift. You cannot use these namespaces for running pods or services.

Creating a project using the web console

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

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

You cannot assign an SCC to pods created in one of the default namespaces: default, kube-system, kube-public, openshift-node, openshift-infra, and openshift. You cannot use these namespaces for running pods or services.
Procedure

  1. Navigate to Home → Projects.

  2. Click Create Project.

  3. Enter your project details.

  4. Click Create.

Creating a project using the Developer perspective in the web console

You can use the Developer perspective in the OKD web console to create a project in your cluster.

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

You cannot assign an SCC to pods created in one of the default namespaces: default, kube-system, kube-public, openshift-node, openshift-infra, and openshift. You cannot use these namespaces for running pods or services.
Prerequisites

  • Ensure that you have the appropriate roles and permissions to create projects, applications, and other workloads in OKD.

Procedure

You can create a project using the Developer perspective, as follows:

  1. Click the Project drop-down menu to see a list of all available projects. Select Create Project.

    odc create project
    Figure 1. Create project

  2. In the Create Project dialog box, enter a unique name, such as myproject, in the Name field.

  3. Optional: Add the Display Name and Description details for the project.

  4. Click Create.

  5. Use the left navigation panel to navigate to the Project view and see the dashboard for your project.

  6. Optional:

    • Use the Project drop-down menu at the top of the screen and select all projects to list all of the projects in your cluster.

    • Use the Details tab to see the project details.

    • If you have adequate permissions for a project, you can use the Project Access tab to provide or revoke administrator, edit, and view privileges for the project.

Creating a project using the CLI

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

Projects starting with openshift- and kube- are considered critical by OKD. As such, OKD 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.

You cannot assign an SCC to pods created in one of the default namespaces: default, kube-system, kube-public, openshift-node, openshift-infra, and openshift. You cannot use these namespaces for running pods or services.
Procedure

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

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.

Viewing a project using the web console

Procedure

  1. Navigate to Home → Projects.

  2. Select a project to view.

    On this page, click Workloads to see workloads in the project.

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>

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.

Procedure

To add users to your project and provide Admin, Edit, or View access to them:

  1. In the Developer perspective, navigate to the Project view.

  2. In the Project page, select the Project Access tab.

  3. Click Add Access to add a new row of permissions to the default ones.

    odc project permissions
    Figure 2. Project permissions

  4. Enter the user name, click the Select a role drop-down list, and select an appropriate role.

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

Advanced role-based access control is managed in the Roles and Roles Binding views in the Administrator perspective.

Customizing the available cluster roles using the Developer perspective

The users of a project are assigned to a cluster role based on their access control. You can access these cluster roles by navigating to the Project → Project access → Role. By default, these roles are Admin, Edit, and View.

To add or edit the cluster roles for a project, you can customize the YAML code of the cluster.

Procedure

To customize the different cluster roles of a project:

  1. In the Search view, use the Resources drop-down list to search for Console.

  2. From the available options, select the Console operator.openshift.io/v1.

    odc cluster console
    Figure 3. Searching Console resource

  3. Select cluster under the Name list.

  4. Navigate to the YAML tab to view and edit the YAML code.

  5. In the YAML code under spec, add or edit the list of availableClusterRoles and save your changes:

    spec:
  customization:
    projectAccess:
      availableClusterRoles:
      - admin
      - edit
      - view

Adding to a project

Procedure

  1. Select Developer from the context selector at the top of the web console navigation menu.

  2. Click +Add

  3. At the top of the page, select the name of the project that you want to add to.

  4. Click a method for adding to your project, and then follow the workflow.

You can also add components to the topology using quick search.

Checking project status using the web console

Procedure

  1. Navigate to Home → Projects.

  2. Select a project to see its status.

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.

Deleting a project using the web console

You can delete a project by using the OKD web console.

If you do not have permissions to delete the project, the Delete Project option is not available.
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 Options menu kebab.

  4. When the Delete Project pane opens, enter the name of the project that you want to delete in the field.

  5. Click Delete.

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>