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® Software Hub 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.

Projects required to install an instance of IBM Software Hub

At a minimum, an instance of IBM Software Hub 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 IBM Software Hub 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 IBM Software Hub 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 5.3.0.

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 IBM Software Hub 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 IBM Software Hub 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 Software Hub

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 IBM Software Hub.
  • 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 IBM Software Hub.

The IBM Software Hub 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 IBM Software Hub 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 on IBM Software Hub.
  • 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 Software Hub control plane.

Multitenancy considerations

If you want to install multiple instances of IBM Software Hub 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 IBM Software Hub. 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 IBM Software Hub on the same cluster.

Figure 1. High-level overview of the interaction between shared cluster components and the instances of IBM Software Hub on the cluster
Sample configuration with an unspecified number of instances of IBM Software Hub.
The preceding diagram illustrates how the shared cluster components interact with each instance of IBM Software Hub on the cluster:
  • The IBM Certificate manager enables the IBM Software Hub control plane and services 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 IBM Software Hub to track VPC use. The data enables you to generate an audit snapshot of your use.
  • The scheduling service watches over each instance of IBM Software Hub to:
    • Schedule the pods that are started by the IBM Software Hub control plane and services.
    • Apply specific scheduling policies.
    • Enforce quotas.
Figure 2. Detailed view of the projects that are associated with different instances of IBM Software Hub
Sample configuration with two instances of IBM Software Hub.

The preceding diagram shows a cluster with two instances of IBM Software Hub.

Each instance of IBM Software Hub 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 IBM Software Hub and you use tethered projects, you should use groups to identify projects that are associated with a specific instance of IBM Software Hub.

In the following example, there are two deployments of IBM Software Hub:
  • One instance of IBM Software Hub is deployed in a project called dev.

    The following projects are tethered to the dev project:

    • apps-dev
    • db-dev
  • One instance of IBM Software Hub 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-