Authorizing foundational services to perform operations on workloads in a namespace

This version of documentation is no longer updated. For the latest information, see the following links:
- Continuous Delivery (CD) documentation
- Support Cycle-2 (SC-2) documentation

Manage operator and service workload authority across namespaces.

The IBM NamespaceScope Operator is used to project operator permissions so that IBM Cloud Paks® can request and share IBM Cloud Pak foundational services capabilities that are running in different namespaces in the cluster.

The IBM NamespaceScope Operator runs in the foundational-services namespace. It watches the target namespace and extends the roles and role bindings of the operator and associated workloads to the namespace that is specified in a NamespaceScope CR.

The runtime permissions of the operator from the original namespace are aggregated into a role for the operator in the target namespace. The name of role in the target namespace is nss-runtime-managed-role-from-<original-namespace>.

Scope definitions
Topologies that need the IBM NamespaceScope operator
Deploying and authorizing the IBM NamespaceScope Operator
Revoking the authorization

Scope definitions

Your cluster might have one or multiple foundational services instances. An instance might serve a single IBM Cloud Pak or multiple IBM Cloud Paks.

The following terms provide information about the ways in which you can set the scope of the foundational services instances:

single namespace-scoped instance: The foundational services instance manages the resources only in a single namespace. Typically, this is a scenario where you installed your IBM Cloud Pak and foundational services in the same namespace. You don't need the common-service-maps ConfigMap.
tenant-scoped instance: When a foundational services instance serves one or more IBM Cloud Paks that are in another namespace, then the foundational services namespace is considered as a tenant.
- The scope of this tenant includes the IBM Cloud Paks namespaces that it serves, and its own namespace. In a common-service-maps ConfigMap, these namespaces would be the ones in the requested-from-namespace section and the corresponding map-to-common-service-namespace section.
- The Operand Deployment Lifecycle Manager (ODLM) that is deployed in the map-to-common-service-namespace namespace looks for and reconciles operand requests that come only from the namespaces in the same tenant.
- Access rights are grouped for the namespaces that work together. For example, you can create users with detailed access rights for tenant-1 without giving them any access to tenant-2.
- All scenarios in Topologies that need the IBM NamespaceScope operator need a tenant-scoped instance.
cluster-scoped instance: A cluster-scoped instance is used across the entire cluster. In foundational services, the Certificate Manager and License Service are cluster-scoped because only one instance of these services can be deployed per cluster. Cluster-scoped resources are used cluster-wide and are less concerned with specific namespaces.

Topologies that need the IBM NamespaceScope operator

You do not need the IBM NamespaceScope operator if each IBM Cloud Pak that is installed in your cluster has its own foundational services instance.

Deployment of the IBM NamespaceScope operator is required only when you are sharing a foundational services instance across multiple IBM Cloud Paks. See the following topologies:

Topology 1: You have a namespace-scoped foundational services instance, and IBM Cloud Paks that are installed in other namespaces need to share the instance.
Topology 2: You want to install all operators in one namespace and deploy all operands in another namespace.
Topology 3: Topology 2 with a tenant-scoped foundational services instance that is shared by multiple namespaces.

Deploying and authorizing the IBM NamespaceScope Operator

Before you proceed, understand the following key components:

Subscription: To deploy the IBM NamespaceScope Operator, you need to manually create the operator subscription.
NamespaceScope CR: You must also create the NamespaceScope CR. Following parameters that are found in the NamespaceScope CR need to be carefully specified:
- The namespaceMembers contains a list of namespaces in the cluster that have the following requirement:
  - These namespaces need to be watched by specific operators or operands that run in the foundational-services namespace.
  - The service accounts of the specific operator or operand pods in the foundational-services namespace are authorized to these namespaces.
    
    The namespace where you create the NamespaceScope CR, which is foundational-services namespace, is always considered as a namespace member, even if you do not add it to the list in the CR.
- The configmapName is the name of a configmap that is created to contain a namespaces key. The key has a common-separated list of the namespaces that need to be watched. All operators and operands that want to participate in namespace extension must be configured to watch this key. The configmapName parameter is optional. The default value is namespace-scope. See the following example:
```
  env:
    - name: WATCH_NAMESPACE
      valueFrom:
        configMapKeyRef:
          name: namespace-scope
          key: namespaces
```
- The restartLabels list specifies the labels for the operator and operand pods that need to be restarted when the namespaceMembers list changes. The pods restart so that they can reset their watch parameters. Moreover, the IBM NamespaceScope Operator copies the roles that are used by these pods to the target namespaces that are in the namespaceMembers list. The restartLabels parameter is optional. The default label is intent=projected.
authorize-namespace.sh script: The IBM NamespaceScope Operator has permission only within the foundational-services namespace. You must run the authorize-namespace.sh script to authorize the IBM NamespaceScope Operator with permissions to your target namespaces in your topology.

Proceed with deploying and authorizing the IBM NamespaceScope Operator for your topology.

Note: If you do not want to manually do your topology configurations, you can use the installation script. The script installs the ibm-namespace-scope-operator and deploys the NamespaceScope resource in the foundational-services namespace during foundational services installation. For more information, see Installing foundational services by using a script.

Topology 1

Complete these steps before you install foundational services.

Create all required namespaces. For the steps to create a namespace, see create a namespace. You need the following namespaces:
- a namespace for your foundational services instance
- a separate namespace for each IBM Cloud Pak instance

Create or update the OperatorGroup in your ibm-common-service-operator namespace. For more information, see the operatorNamespace parameter.

 apiVersion: operators.coreos.com/v1
 kind: OperatorGroup
 metadata:
   name: og-tenant1-services       # --> This is name of the operator group.
   namespace: tenant1-services     # --> This is namespace of the operator group.
 spec:
   targetNamespaces:
     - tenant1-services           # --> This is your foundational services namespace.

Create the ibm-namespace-scope-operator subscription.

 apiVersion: operators.coreos.com/v1alpha1
 kind: Subscription
 metadata:
   name: ibm-namespace-scope-operator
   namespace: tenant1-services    # --> This is your foundational services namespace.
 spec:
   channel: v4.2
   installPlanApproval: Automatic
   name: ibm-namespace-scope-operator
   source: opencloud-operators         # --> This is name of the `ibm-namespace-scope-operator` catalog source.
   sourceNamespace: openshift-marketplace      # --> This is namespace of the `ibm-namespace-scope-operator` catalog source.

Create the NamespaceScope CR for your topology. Following is a sample YAML specification of the NamespaceScope CR for topology 1.

Note: Ensure that you add the foundational-services namespace in the metadata.namespace parameter. Later, the foundational services are installed in this namespace.

 apiVersion: operator.ibm.com/v1
 kind: NamespaceScope
 metadata:
   name: common-service
   namespace: tenant1-services          # --> This is your foundational services namespace.
 spec:
   csvInjector:
     enable: true
   configmapName: namespace-scope
   namespaceMembers:
     - tenant1-services
     - tenant1-cp4ba                    # --> This is your IBM Cloud Pak 1 namespace that uses the foundational services from the tenant1-services namespace.
     - tenant1-cp4i                     # --> This is your IBM Cloud Pak 2 namespace that uses the foundational services from the tenant1-services namespace.
   restartLabels:
     intent: projected

Authorize the IBM NamespaceScope Operator to access workloads in the other namespaces.
1. Log in to your cluster as a cluster administrator by using the oc login command.
2. Download the script that you need for manually authorizing namespaces.
```
 wget https://raw.githubusercontent.com/IBM/ibm-namespace-scope-operator/master/scripts/authorize-namespace.sh
```
3. Run the script for each namespace that you are authorizing.
```
 ./authorize-namespace.sh <target-namespace> -to <foundational-services-namespace>
```
  See the following examples for topology 1:
  - For the tenant1-cp4ba namespace:
```
  ./authorize-namespace.sh tenant1-cp4ba -to tenant1-services
```
  - For the tenant1-cp4i namespace:
```
  ./authorize-namespace.sh tenant2-cp4i -to tenant1-services
```
Continue with the installation of foundational services. Proceed with Configuring the services. If needed, update the common-service CR to specify the servicesNamespace for the shared services.

Topology 2

Complete these steps before you install foundational services.

Create all required namespaces. For the steps to create a namespace, see create a namespace. You need the following namespaces:
- a namespace for all your operators
- a namespace for all operands

Create or update the OperatorGroup in your ibm-common-service-operator namespace. For more information, see the operatorNamespace parameter.

 apiVersion: operators.coreos.com/v1
 kind: OperatorGroup
 metadata:
   name: og-tenant1-services       # --> This is name of the operator group.
   namespace: tenant1-control     # --> This is the namespace where all operators are installed.
 spec:
   targetNamespaces:
     - tenant1-control           # --> This is the namespace where all operators are installed.

Create the ibm-namespace-scope-operator subscription.

 apiVersion: operators.coreos.com/v1alpha1
 kind: Subscription
 metadata:
   name: ibm-namespace-scope-operator
   namespace: tenant1-control    # --> This is the namespace where all operators are installed.
 spec:
   channel: v4.2
   installPlanApproval: Automatic
   name: ibm-namespace-scope-operator
   source: opencloud-operators         # --> This is name of the `ibm-namespace-scope-operator` catalog source.
   sourceNamespace: openshift-marketplace      # --> This is namespace of the `ibm-namespace-scope-operator` catalog source.

Create the NamespaceScope CR for your topology. Following is a sample YAML specification of the NamespaceScope CR for topology 2.

Note: Ensure that you add the foundational-services namespace in the metadata.namespace parameter. Later, the foundational services are installed in this namespace.

 apiVersion: operator.ibm.com/v1
 kind: NamespaceScope
 metadata:
   name: common-service
   namespace: tenant1-control            # --> This is your foundational services namespace.
 spec:
   csvInjector:
     enable: true
   configmapName: namespace-scope
   namespaceMembers:
     - tenant1-control                  # --> This is the namespace where all operators are installed.
     - tenant1-data                     # --> This is the namespace where all operands are installed.
   restartLabels:
     intent: projected

Authorize the IBM NamespaceScope Operator to access workloads in the other namespaces.
1. Log in to your cluster as a cluster administrator by using the oc login command.
2. Download the script that you need for manually authorizing namespaces.
```
 wget https://raw.githubusercontent.com/IBM/ibm-namespace-scope-operator/master/scripts/authorize-namespace.sh
```
3. Run the script for each namespace that you are authorizing.
```
 ./authorize-namespace.sh <target-namespace> -to <foundational services-namespace>
```
  See the following example for topology 2:
```
./authorize-namespace.sh tenant1-data -to tenant1-control
```
Update the CommonService CR in the tenant1-control namespace to indicate that the services are to be placed in the tenant1-data namespace. The OperandRequest and OperandConfig CRs are also then installed in tenant1-data namespace. For more information, see Parameters in the CommonService CR.
```
 apiVersion: v1
 kind: CommonService
 metadata:
   name: common-service
   namespace: tenant1-control
 spec:
   servicesNamespace: tenant1-data
   operatorNamespace: tenant1-control
   ...
```
Ensure that you install your IBM Cloud Pak in the tenant1-control namespace. You must annotate the ClusterServiceVersion (CSV) of your IBM Cloud Pak operators to allow the IBM NamespaceScope Operator to inject the proper WATCH and label statements to project their scope to the tenant1-data namespace. See the following example:
```
 kind: ClusterServiceVersion
 metadata:
 annotations:
   alm-examples: ‘[…]’
   nss.operator.ibm.com/managed-operators: <package-name>
```
You must create all your IBM Cloud Pak CRs in the tenant1-data namespace so that their operands are deployed in the tenant1-data namespace. Any subsequent OperandRequest CRs are deployed such that they connect to the required foundational services.
Continue with the installation of foundational services. Proceed with Configuring the services.

Topology 3

Complete these steps before you install foundational services.

Create all required namespaces. For the steps to create a namespace, see create a namespace. You need the following namespaces:
- a namespace for all your operators
- a namespace for all operands where all the shared services are hosted
- a namespace for hosting your IBM Cloud Pak

Create or update the OperatorGroup in your ibm-common-service-operator namespace. For more information, see the operatorNamespace parameter.

 apiVersion: operators.coreos.com/v1
 kind: OperatorGroup
 metadata:
   name: og-tenant1-services       # --> This is name of the operator group.
   namespace: tenant1-operators     # --> This is the namespace where all operators are installed.
 spec:
   targetNamespaces:
     - tenant1-operators           # --> This is the namespace where all operators are installed.

Create the ibm-namespace-scope-operator subscription.

 apiVersion: operators.coreos.com/v1alpha1
 kind: Subscription
 metadata:
   name: ibm-namespace-scope-operator
   namespace: tenant1-operators    # --> This is the namespace where all operators are installed.
 spec:
   channel: v4.2
   installPlanApproval: Automatic
   name: ibm-namespace-scope-operator
   source: opencloud-operators         # --> This is name of the `ibm-namespace-scope-operator` catalog source.
   sourceNamespace: openshift-marketplace      # --> This is namespace of the `ibm-namespace-scope-operator` catalog source.

Create the NamespaceScope CR for your topology. Following is a sample YAML specification of the NamespaceScope CR for topology 3.

Note: Ensure that you add the foundational-services namespace in the metadata.namespace parameter. Later, the foundational services are installed in this namespace.

 apiVersion: operator.ibm.com/v1
 kind: NamespaceScope
 metadata:
   name: common-service
   namespace: tenant1-operators
 spec:
   csvInjector:
     enable: true
   configmapName: namespace-scope
   namespaceMembers:
     - tenant1-operators                    # --> This is the namespace where all operators are installed.
     - tenant1-instance                     # --> This is your foundational services namespace, where all operands are installed.
     - tenant1-instance-tethered1           # --> This is a namespace that has your IBM Cloud Pak capability and uses the foundational services from the tenant1-instance.
     - tenant1-instance-tethered2           # --> This is a namespace that has your IBM Cloud Pak capability and uses the foundational services from the tenant1-instance.
   restartLabels:
     intent: projected

Authorize the IBM NamespaceScope Operator to access workloads in the other namespaces.
1. Log in to your cluster as a cluster administrator by using the oc login command.
2. Download the script that you need for manually authorizing namespaces.
```
 wget https://raw.githubusercontent.com/IBM/ibm-namespace-scope-operator/master/scripts/authorize-namespace.sh
```
3. Run the script for each namespace that you are authorizing.
```
 ./authorize-namespace.sh <target-namespace> -to <foundational-services-namespace>
```
  See the following examples for topology 3:
  - For the tenant1-instance namespace:
```
  ./authorize-namespace.sh tenant1-instance -to tenant1-operators
```
  - For the tenant1-instance-tethered1 namespace:
```
  ./authorize-namespace.sh tenant1-instance-tethered1 -to tenant1-operators
```
  - For the tenant1-instance-tethered2 namespace:
```
  ./authorize-namespace.sh tenant1-instance-tethered2 -to tenant1-operators
```
Update the CommonService CR in the tenant1-operators namespace to indicate that the services are to be placed in the tenant1-operators namespace. The OperandRequest and OperandConfig CRs are also then installed in tenant1-operators namespace. For more information, see Parameters in the CommonService CR.
```
 apiVersion: v1
 kind: CommonService
 metadata:
   name: common-service
   namespace: tenant1-operators
 spec:
   servicesNamespace: tenant1-instance
   operatorNamespace: tenant1-operators
   ...
```
You can install your IBM Cloud Pak operators in any namespace that is listed in the NamespaceScope CR. If you install the IBM Cloud Pak in the tenant1-operators namespace, you must annotate the CSV of your IBM Cloud Pak operators to allow the IBM NamespaceScope Operator to inject the proper WATCH and label statements to project their scope to the tenant1-data namespace. See the following example:
```
 kind: ClusterServiceVersion
 metadata:
 annotations:
   alm-examples: ‘[…]’
   nss.operator.ibm.com/managed-operators: <package-name>
```
You must install your IBM Cloud Pak CRs in the namespace in which their operands are to be deployed. Any subsequent OperandRequest CRs are deployed such that they connect to the required foundational services.
Continue with the installation of foundational services. Proceed with Configuring the services.

Revoking the authorization

If you need to revoke the permission at any point in time, run this command:

./authorize-namespace.sh <target-namespace> -delete