Supported project (namespace) configurations

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.

Tip: The cpd-cli can automatically create projects for you. However, if you prefer to create these projects manually, the installation and upgrade documentation includes guidance on creating the projects from the OpenShift® CLI.

Projects for shared cluster components

The shared cluster components are installed exactly once on the cluster and are shared by all instances of IBM Cloud Pak® for Data on the cluster. Each component is installed in its own project, and no other software should be installed in the project.

The following table provides the default project name and the environment variable that is used to identify the project in commands throughout the documentation. You are not required to use the default project names. The default names are used only if you don't specify a project name when you install the components.

Component	Default project name	Environment variable
IBM® Certificate manager	`ibm-cert-manager`	`${PROJECT_CERT_MANAGER}`
License Service	`ibm-licensing`	`${PROJECT_CS_CONTROL}`
Scheduling service	No default.	`${PROJECT_SCHEDULING_SERVICE}`

For more information about these components see Shared components.

If you are upgrading to IBM Cloud Pak for Data Version 4.7, you must create an additional project. During an upgrade to Version 4.7, the IBM Certificate manager and License Service are temporarily installed in this project. The project is referred to as the cs-control project, but you can use any name for this project. The ${PROJECT_CS_CONTROL} environment variable refers to this project.

Projects required to install an instance of IBM Cloud Pak for Data

At a minimum, an instance of Cloud Pak for Data has two projects (namespaces): the operators project and the operands project.

Only the specified software should be installed in the operators project and the operands project. The projects do not have default names.

Operators project

The project where the operators are installed.

In installation and administration commands, the ${PROJECT_CPD_INST_OPERATORS} environment variable refers to the operators project.

What are operators?

An operator is a custom Kubernetes controller. A controller implements a control loop that continually watches the state of specific objects on your cluster and makes adjustments as needed to ensure that the objects are running as expected.

Each component of Cloud Pak for Data includes an operator that is responsible for managing that component. For example, the control plane has a dedicated operator, and each service has a dedicated operator.

Each instance of Cloud Pak for Data has its own set of operators. All the operators in this project must be installed at the same release. For example, all the operators must be installed at Version 4.7.4.

Install the operators for the services that you plan to install in the operands project. Each operator monitors the appropriate operands in the operands project.

Operands project

The project where the Cloud Pak for Data control plane and services are installed.

In installation and administration commands, the ${PROJECT_CPD_INST_OPERANDS} environment variable refers to the operands project.

The operators monitor the operands to ensure that they are running as expected.

Each instance of Cloud Pak for Data has its own set of operands. The operands in this project must be installed at the same release as the operators in the operators project.

Optional projects for an instance of IBM Cloud Pak for Data

You can optionally tether one or more projects to the operands project.

Only the specified software should be installed in tethered projects. The projects do not have default names.

Tethered projects

Projects where you can deploy workloads or service instances.

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

Tethered projects are identified by the following environment variables:

In installation and administration commands, the ${PROJECT_CPD_INSTANCE_TETHERED} refers to a single tethered project that is associated with an instance of Cloud Pak for Data.
In installation and administration commands, the ${PROJECT_CPD_INSTANCE_TETHERED_LIST} environment variable refers to a list of tethered projects that are associated with an instance of Cloud Pak for Data.

The Cloud Pak for Data control plane manages the software in the tethered project. However, the software is otherwise isolated from the control plane and the other services and workloads that are running in the operands project.

When you tether a project to the operands project, the

cpd-cli
manage
setup-tethered-ns

command:

Updates the IBM NamespaceScope Operator in the operators project to enable the operators to watch the tethered project.
Updates the ZenService custom resource in the operands project to add the 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.

You might want to deploy a workload or service instance to 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.

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.

Because a tethered project is logically isolated from the operands project, the tethered project can have its own NetworkPolicies, SecurityContext, and ResourceQuota.

For more information on tethering projects to the operands project, see Tethering projects to the IBM Cloud Pak for Data control plane.

Multitenancy considerations

If you want to install multiple instances of Cloud Pak for Data on a cluster, you must create an operators project and operands project for each instance that you want to install. Tethered projects cannot be shared by multiple instances of Cloud Pak for Data. If you want to use tethered projects, you must create tethered projects for each instance where you want to use them.

Sample project configurations

The following diagrams show sample project configurations. The diagrams illustrate environments with multiple instances of Cloud Pak for Data on the same cluster.

Sample configuration with an unspecified number of instances of Cloud Pak for Data. — Figure 1. High-level overview of the interaction between shared cluster components and the instances of Cloud Pak for Data on the cluster

The preceding diagram illustrates how the shared cluster components interact with each instance of Cloud Pak for Data on the cluster:

The IBM Certificate manager enables the Cloud Pak for Data control plane and services to in each instance to generate and automatically rotate TLS certificates for secure micro-service to micro-service communications.
The License Service watches over each instance of Cloud Pak for Data to track VPC use. The data enables you to generate an audit snapshot of your use.
The scheduling service watches over each instance of Cloud Pak for Data to:
- Schedule the pods that are started by the Cloud Pak for Data control plane and services.
- Apply specific scheduling policies.
- Enforce quotas.

Sample configuration with two instances of Cloud Pak for Data. — Figure 2. Detailed view of the projects that are associated with different instances of Cloud Pak for Data

The preceding diagram shows a cluster with two instances of Cloud Pak for Data.

Each instance of Cloud Pak for Data has its own operators project and its own operands project. In this example, each instance has at least one tethered project. However, tethered projects are optional.

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-
```