Supported project (namespace) configurations

Important: IBM Cloud Pak® for Data Version 4.6 will reach end of support (EOS) on 31 July, 2025. For more information, see the Discontinuance of service announcement for IBM Cloud Pak for Data Version 4.X.

Upgrade to IBM Software Hub Version 5.1 before IBM Cloud Pak for Data Version 4.6 reaches end of support. For more information, see Upgrading IBM Software Hub in the IBM Software Hub Version 5.1 documentation.

The projects (namespaces) that you must create on your cluster depend on several factors. Review the following information to determine which projects you must create.

Security considerations

The IBM Cloud Pak for Data operators are part of operator groups that specify InstallModeType: ownNamespace.

By default, this means that the operators can manage only software that is deployed in the same namespace as the operators. However, IBM Cloud Pak foundational services deploys a special operator called the IBM NamespaceScope Operator.

The IBM NamespaceScope Operator enables the IBM Cloud Pak foundational services operators and the IBM Cloud Pak for Data operators to manage software that is installed and running in another project by extending the privileges of the operators to those other projects.

Note: By default, the IBM NamespaceScope Operator has cluster permissions so that role binding projections can be completed automatically. However, you can optionally remove the cluster permissions from the IBM NamespaceScope Operator and manually authorize the projections. For details, see Authorizing foundational services to perform operations on workloads in a namespace in the IBM Cloud Pak foundational services documentation.

You have two options for installing the IBM Cloud Pak for Data operators:

Option Security considerations for this installation option
Install the IBM Cloud Pak for Data operators in the same project as the IBM Cloud Pak foundational services operators.

This installation is called an express installation.

In an express installation, the operators are installed in the ibm-common-services project.

 An express installation does not enforce strict distinction between Red Hat® OpenShift® projects (namespaces) that are managed by operators.

Both the IBM Cloud Pak foundational services operators and the IBM Cloud Pak for Data operators watch any projects where IBM® Cloud Paks are installed.

This means that all of the operators are granted RBAC to all of the projects where IBM Cloud Paks are installed even though it is unnecessary for the IBM Cloud Pak for Data operators to be granted permissions on projects where IBM Cloud Pak for Data is not installed.

This might not be important if you don't plan to install other IBM Cloud Paks.
Install the IBM Cloud Pak for Data operators in their own project.

This installation is called a specialized installation.

In a specialized installation, the IBM Cloud Pak foundational services are typically installed in the ibm-common-services project, and the Cloud Pak for Data operators are installed in the project of your choosing.

 A specialized installation also facilitates strict division between Red Hat OpenShift projects (namespaces):
  • The IBM Cloud Pak foundational services operators watch any projects where IBM Cloud Paks are installed.

    This means that the IBM Cloud Pak foundational services operators are granted RBAC to all of the projects where IBM Cloud Paks are installed.

  • The Cloud Pak for Data operators watch only the projects where Cloud Pak for Data is installed

    This means that the Cloud Pak for Data operators are granted RBAC to only the projects where Cloud Pak for Data is installed, which limits the permissions scope of the Cloud Pak for Data operators.

After you choose an installation method, review the Multitenancy considerations.

Multitenancy considerations

At a minimum, you must create a project where you will deploy an instance of IBM Cloud Pak for Data.

However, you can create multiple projects if you want to install multiple instances of Cloud Pak for Data on the cluster. Create one project for each instance of Cloud Pak for Data that you want to install.

When you run the cpd-cli manage commands, the cpd-cli updates the appropriate instances of the IBM NamespaceScope Operator to ensure that the operators can watch the projects where you want to install the Cloud Pak for Data platform and services.

Tethered projects

Some services can be installed in a project that is tethered to the project where the Cloud Pak for Data platform (control plane) is installed.

The software or workload in the tethered project is managed by Cloud Pak for Data control plane but is otherwise isolated from the control plane and the other services and workloads that are running in the main Cloud Pak for Data project.

You might want to deploy a workload or service instance into a tethered project in the following situations:
  • You are running a custom application that needs to access a specific service instance, but for security reasons, you don't want the application to access other services that are running in Cloud Pak for Data.
  • You are running a workload that requires specific compute resources or a particular quality of service.

Because the tethered project is logically isolated from the main Cloud Pak for Data project, the tethered project can have its own NetworkPolicies, SecurityContext, and ResourceQuota.

Restriction: Not all services support running workloads or service instances in tethered projects. For details, see Multitenancy support.

For details on setting up a tethered project, see Setting up projects (namespaces) on Red Hat OpenShift Container Platform.

When you tether a project to the ${PROJECT_CPD_INSTANCE} project, the cpd-cli manage setup-tethered-ns command:
  • Updates the appropriate instances of the IBM NamespaceScope Operator to enable the operators to watch the tethered project.
  • Updates the ZenService custom resource in the ${PROJECT_CPD_INSTANCE} project to add the ${PROJECT_TETHERED} project to the tetheredNamespaces entry.

    This enables the Cloud Pak for Data control plane to monitor and manage the workloads in the tethered project.

Many services support only one service instance in a given project. So if you want to create multiple instances of a service, you must deploy each instance of the service in a different project. You can achieve this by creating multiple tethered projects and creating one instance of the service in each tethered project.

You can co-locate service instances and workloads for different services in the same tethered project, or you can create different tethered projects if one service or workload requires more privileges. You can use different tethered projects to give each service instance or workload the privileges it needs to align with the Principle of Least Privileges.

Projects for an express installation

An express installation requires the following projects:
  • The project where the IBM Cloud Pak foundational services and the Cloud Pak for Data operators are installed (ibm-common-services).

    If you install the scheduling service, it is also installed in this project.

  • The project where the Cloud Pak for Data software is installed.
You might have additional projects if:
  • You want to install multiple instances of Cloud Pak for Data.

    You must create a project for each instance of Cloud Pak for Data that you want to install.

  • You want to deploy service instances or workloads in tethered projects.
This image depicts the required projects for an express installation. This diagram also shows optional projects for multitenancy and tethering. The image is described in the surrounding text.

The preceding diagram shows how the operators in the ibm-common-services project manage the software in the deployment projects and any projects that are tethered to the deployment projects.

Because all of the operators are in a single project, they belong to the same operator group. The Cloud Pak for Data operators can manage software in the same projects that the IBM Cloud Pak foundational services operators can manage.

In this example, there are 3 deployment projects (cpd-instance-1, cpd-instance-2, and cpd-instance-3) to support a multitenant deployment. Each instance of Cloud Pak for Data has different services based on the needs of the users who access the instance. The Cloud Pak for Data control plane that is running in the cpd-instance-1 project manages the workload that is running in the tethered project (cpd-tethered-1).

With the exception of ibm-common-services, all of the project names are user-defined. If you want to install IBM Cloud Pak foundational services in a different project, choose a specialized installation.

Projects for a specialized installation

A specialized installation requires the following projects:
  • The project where the IBM Cloud Pak foundational services operators are installed.

    If you install the scheduling service, it is also installed in this project.

  • The project where the Cloud Pak for Data operators are installed.
  • The project where the Cloud Pak for Data software is installed.
You might have additional projects if:
  • You want to install multiple instances of Cloud Pak for Data.

    You must create a project for each instance of Cloud Pak for Data that you want to install.

  • You want to deploy service instances or workloads in tethered projects.
This image depicts the required projects for a specialized installation. This diagram also shows optional projects for multitenancy and tethering. The image is described in the surrounding text.

The preceding diagram shows how the operators in the ibm-common-services project and in the cpd-operators project manage the software in the deployment projects and any projects that are tethered to the deployment projects.

Each operator project belongs to a different operator group. The operators in the ibm-common-services can manage software that is deployed in other projects. The operators in the cpd-operators project can manage only the software in the specified deployment projects.

In this example, there are 3 deployment projects (cpd-instance-1, cpd-instance-2, and cpd-instance-3) to support a multitenant deployment. Each instance of Cloud Pak for Data has different services based on the needs of the users who access the instance. The Cloud Pak for Data control plane that is running in the cpd-instance-1 project manages the workload that is running in the tethered project (cpd-tethered-1).

All of the project names are user-defined, although ibm-common-services is used by default.

Best practice: Creating groups to manage projects in a multitenant environment

If you deploy multiple instances of Cloud Pak for Data and you use tethered projects, you should use groups to identify projects that are associated with a specific instance of Cloud Pak for Data.

In the following example, there are two deployments of Cloud Pak for Data:
  • One instance of Cloud Pak for Data is deployed in a project called dev.

    The following projects are tethered to the dev project:

    • apps-dev
    • db-dev
  • One instance of Cloud Pak for Data is deployed in a project called prod.

    The following projects are tethered to the prod project:

    • apps-prod
    • db-prod

You can use labels to group the projects:

  • To label the projects that are associated with the dev deployment with cpdgroup=dev, run the following command:
    oc label namespace dev apps-dev db-dev cpdgroup=dev
  • To group the projects that are associated with the prod deployment with cpdgroup=prod, run the following command:
    oc label namespace prod apps-prod db-prod cpdgroup=prod
Related commands:
  • To validate that the label was applied to a project, use the oc describe command. For example, to validate the label that was applied to the db-dev project, run:
    oc describe namespace db-dev
  • You can remove a project from a group, if needed. For example, to remove the dv-dev project from the dev group
    oc label namespace db-dev cpdgroup-