Managing projects

Learn how to create and work with projects.

What is a project?

A project is a grouping of Code Engine entities such as applications, jobs, and builds. A project is based on a Kubernetes namespace. The name of your project must be unique within your IBM Cloud® resource group, user account, and region. Projects are used to manage resources and provide access to its entities.

A project provides the following items.

Provides a unique namespace for entity names.
Manages access to project resources (inbound access).
Manages access to backing services, registries, and repositories (outbound access).
Has an automatically generated certificate for Transport Layer Service (TLS).

For more information about managing access control to projects with IAM, see Managing user access.

Projects incur no costs, but instead serve as folders for your apps, jobs, and functions.

How can I see what projects I can access?

You can see a list of your projects in the Code Engine console.

You can also run the project list command.

ibmcloud ce project list

Example output

Getting projects...
OK

Name             ID                                    Status  Selected  Tags  Region    Resource Group  Age
myproj-eude      01234567-abcd-abcd-abcd-abcdabcd2222  active  false           eu-de     default         27d
myproject        01234567-abcd-abcd-abcd-abcdabcd1111  active  true            us-south  default         52d

How can I see details about a project?

From the Code Engine console, you can see details of a project by clicking the name of a project from the Code Engine Projects page.

When you are working with a component in Code Engine from the console such as apps, jobs, or functions, or their related entities such as access, bindings, or subscriptions, you can view details about the associated project. From the page of the particular Code Engine entity, click Details to learn more about the associated project. Use this page to view details of the associated project, which includes information such as the region, CRN (Cloud Resource Name), GUID (globally unique identifier), network addresses (public and private), and more!

You can also run the project get command to display details of a project. Replace PROJECT_NAME with the name of your project. If your project is selected as the current context, the output of this command includes details about limits and quota usage of Code Engine project resources. For more information about limits for projects, see Project quotas.

ibmcloud ce project get --name PROJECT_NAME

Example output

Getting project 'myproject'...
OK

Name:                       myproject
ID:                         01234567-abcd-abcd-abcd-abcdabcd1111
Status:                     active
Selected:                   true
Region:                     us-south
Resource Group:             default
Service Binding Service ID: ServiceId-1234abcd-abcd-abcd-1111-1a2b3c4d5e6f
Age:                        52d
Created:                    Fri, 15 Jan 2021 13:32:30 -0500
Updated:                    Fri, 15 Jan 2021 13:32:45 -0500

Quotas:
    Category                                  Used       Limit
    App revisions                             33         100
    Apps                                      10         100
    Build runs                                4          100
    Builds                                    4          100
    Configmaps                                7          100
    CPU                                       6.15       64
    Ephemeral storage                         5415750Ki  256G
    Instances (active)                        6          250
    Instances (total)                         9          2500
    Job runs                                  4          100
    Jobs                                      3          100
    Memory                                    26400M     256G
    Secrets                                   21         100
    Subscriptions (cron)                      1          100
    Subscriptions (IBM Cloud Object Storage)  0          100

How can I set policies so others can work with my project?

See information about managing user access to learn about setting IAM policies so others can work with your Code Engine project.

Are there project limits to consider?

The maximum number of projects that you can create per region is 20. For more information about limits for projects, see Project quotas.

Create a project

You can create a project through the console or with the CLI.

Creating a project from the console

From the Projects page on the Code Engine console, click Create. Alternatively, you can create your project when you create your Code Engine app, job, or function with the Code Engine console fast path. From the Code Engine console, select Let's go, and click Create project from the Start creating page.
Choose a location to deploy the project.
Enter a name for the project. The name must be unique for all your projects within the specified location.
Choose the resource group where you want to create the project.
Click Create.

To view the service instance for the project resource, go to your IBM Cloud dashboard and find your project name in Code Engine.

Creating a project with the CLI

When you create a project, it is automatically selected as the current context. To create a project that is not automatically selected, use the --no-select option.

Install the Code Engine CLI. Target the resource group that you want to use for the project.
Create a project with the project create command. Use a project name that is unique to your region.
```
ibmcloud ce project create --name PROJECT_NAME 
```
Example output
```
Creating project 'myproject'...
OK
```

Verify that your new project is created with the project get command.

ibmcloud ce project get --name PROJECT_NAME

Example output

Getting project 'myproject'...
OK
Name:                       myproject
ID:                         01234567-abcd-abcd-abcd-abcdabcd1111
Status:                     active
Selected:                   true
Region:                     us-south
Resource Group:             default
Service Binding Service ID: ServiceId-1234abcd-abcd-abcd-1111-1a2b3c4d5e6f
Age:                        52d
Created:                    Fri, 15 Jan 2021 13:32:30 -0500
Updated:                    Fri, 15 Jan 2021 13:32:45 -0500

Quotas:
Category                                  Used      Limit
App revisions                             1         100
Apps                                      1         100
Build runs                                0         100
Builds                                    0         100
Configmaps                                2         100
CPU                                       1.025     64
Ephemeral storage                         902625Ki  256G
Instances (active)                        1         250
Instances (total)                         2         2500
Job runs                                  1         100
Jobs                                      1         100
Memory                                    4400M     256G
Secrets                                   5         100
Subscriptions (cron)                      0         100
Subscriptions (IBM Cloud Object Storage)  0         100

You can also list all projects and this output displays which project is your selected project. In the following example, myproject is the project that is selected as the current context.

ibmcloud ce project list

Example output

Getting projects...
OK

Name             ID                                    Status  Selected  Tags  Region    Resource Group  Age
myproj-eude      01234567-abcd-abcd-abcd-abcdabcd2222  active  false           eu-de     default         27d
myproject        01234567-abcd-abcd-abcd-abcdabcd1111  active  true            us-south  default         52d

Work with a project

After you create a project, you can work with the project by using the Code Engine console or CLI.

Working with a project from the console

To work with a project, go to the Code Engine Projects page and click the name of the project from the list.

To work with Code Engine components, you must work with the components in the context of a project. From the context of your project, you can create and work with Code Engine components, such as applications, jobs, or functions. To determine the project from which you are currently working, see the breadcrumb of your Code Engine component.

Working with a project with the CLI

To work with a project with the CLI, the project must be selected as the current context. A project is automatically selected as the current context when it is created, unless you specify the --no-select option. To select a project that is not currently targeted, use the project select command.

ibmcloud ce project select --name PROJECT_NAME

Example output

Selecting project 'myproject'...

From within the context of the selected project, you can work with Code Engine components, such as applications, jobs, or functions.

Determining which project is selected as the current context

You can find details about the project that is selected as the current context by using the project current command.

Delete a project

When you no longer need a project, you can delete it. Deleting a project deletes all the components that it contains. You can use the console or the CLI.

When you delete a project from the console or with the CLI, it is soft deleted and can be restored. You must restore your project within 7 days or it is permanently deleted. For more information about restoring projects, see Restoring deleted projects. To permanently delete a project, see Permanently deleting projects.

When you delete a project, any projects that are not permanently deleted count toward the maximum of 20 total projects per region that are allowed.

Project names within a region must be unique. When you soft delete a project (or delete the project with reclamation), you cannot reuse the project name until the project is permanently deleted.

Deleting a project from the console

To delete a project from the console, go to the Code Engine Projects page, select the project that you want to delete, and click the delete icon. If you open a specific project, you can also delete the project from the Actions menu.

When you delete a project from the console, the project is soft deleted and can be restored within 7 days before it is permanently deleted. Project reclamations represent deleted projects that can still be restored. From the Code Engine Projects page, the number of project reclamations is displayed. Click restorable projects to open the Project reclamations page and display a list of projects that can be restored or permanently deleted.

Deleting a project with the CLI

To delete a project with the CLI, use the project delete command. You can optionally use the -f option to force the delete of a project without confirmation. After a project is soft deleted, you can manage this project with the reclamation commands. The following example soft deletes the myproject project,

ibmcloud ce project delete --name myproject -f

Example output

Deleting project 'myproject'...
OK

To permanently delete a project so that it cannot be restored, specify the --hard option with the project delete command. You can optionally use the -f option to force the delete of a project without confirmation. The following example permanently deletes the myproject1 project,

ibmcloud ce project delete --name myproject1 --hard -f

Example output

Deleting project 'myproject1'...
OK

If you specify the --hard option with the project delete command, the project is immediately deleted and cannot be restored by using IBM Cloud resource reclamation. If you do not specify the --hard option, the project can be restored within 7 days by using the reclamation restore command.

If you previously soft deleted a project (without specifying the --hard option), you can specify a subsequent delete only by using the project delete command with the --hard option. This action completely deletes the project so that it cannot be restored.

Restoring deleted projects

Restoring deleted projects from the console

After you soft delete a project, you can restore it or permanently delete it from the console. You must restore your project within 7 days or it is permanently deleted.

From the Projects page on the Code Engine console, view the list of projects in your region. The number of project reclamations is displayed.
Click the link for project reclamations.
From the Project reclamations page, you can view the number of remaining days that you can restore your project.
- To restore your project, click the restore icon.
- To permanently delete your project, click the delete icon.

If you take no action on a project that is listed on the Project reclamations page, the project is automatically deleted permanently after 7 days.

Restoring deleted projects with the CLI

Projects that are soft deleted can be managed with the reclamation commands. reclamation commands.

Discover projects that are soft deleted by using the reclamation list command.

ibmcloud ce reclamation list

Example output

Getting project reclamations...
OK
Name          ID                                    Reclamation ID                        Status        Region    Resource Group  Age   Time to Hard Deletion
myproject     def218c5-abcd-abcd-abcd-97854c288d76  48e3d7a2-abcd-abcd-abcd-99db7152b8fe  soft deleted  us-south  default         40h   6d23h
myproject2    01f0bc66-abcd-abcd-abcd-3ef7e99f6f69  af2cd017-abcd-abcd-abcd-d32e2bb79136  soft deleted  jp-osa    default         8m58s 2d11h

Use the reclamation restore command to restore a soft deleted project to an active state. The following example restores the myproject2 project and its components. Make sure that you are targeting the correct region of the project that you want to restore.
```
ibmcloud ce reclamation restore --name myproject 
```
Example output
```
Restoring project 'myproject'...
OK
```

Alternatively, you can use the project restore command to restore a soft deleted project to an active state.

Permanently deleting projects

Permanently deleting projects from the console

After you soft delete a project (or delete the project with reclamation), you can restore it or permanently delete it from the console. When a project is permanently deleted, it cannot be restored.

From the Projects page on the Code Engine console, view the list of projects in your region. The number of project reclamations is displayed.
Click the link for project reclamations.
From the Project reclamations page, you can view the number of remaining days that you can restore your project. To permanently delete your project, click Delete.

If you take no action on deleted projects that are listed on the Project reclamations page, the project is automatically deleted permanently after 7 days.

Permanently deleting projects with the CLI

If your project is soft deleted, you can use the reclamation delete command to permanently delete the project. By using the --force option with this command, the delete is forced without confirmation.

ibmcloud ce reclamation delete -n myproject --f

Example output

Hard deleting project 'myproject'...
OK

If your project is not soft deleted, then to permanently delete a project so that it cannot be restored, use the --hard option with the project delete command to specify to immediately and permanently delete the project. For example, to permanently delete the myproject3 project,

ibmcloud ce project delete --name myproject3 --hard

Example output

Deleting project 'myproject3'...
OK