In-place migration

In-place migration will migrate a dedicated foundational services without creating any new instances of foundational services. This method should only be used if the foundational services you are migrating is already dedicated to a IBM Cloud Pak, that is, running in multiple-instance mode.

Note: You can choose to migrate by either using a script or using manual steps.

Prerequisites

See supported starting versions in Migrating foundational services v3.x to 4.x.
Foundational services is dedicated to an IBM Cloud Pak.
Create new CatalogSource or update existing CatalogSource to the new 4.x version.
- For online migration, reference the required CatalogSource for the corresponding version.
- For offline migration, reference the upgrade steps to mirror images, and apply the new CatalogSource.
Download the migration scripts, and go to the installer_scripts directory. For more information, see Downloading scripts for additional configuration from specific version CASE bundle.

Migrating using a script

Run the script, migrate_tenant.sh, with the following options:

 ./migrate_tenant.sh --license-accept \
 --enable-licensing \
 --operator-namespace ibm-common-services \
 --cert-manager-source ibm-cert-manager-catalog \
 --licensing-source ibm-licensing-catalog \
 -c v4.5 \
 -i Automatic \
 -s opencloud-operators-v4-1 \
 -v 1

If you have deployed License Service Reporter, use the following command to migrate the IBM License Service Reporter:

 ./migrate_tenant.sh --license-accept \
 --enable-licensing \
 --enable-license-service-reporter\
 --operator-namespace ibm-common-services \
 --cert-manager-source ibm-cert-manager-catalog \
 --licensing-source ibm-licensing-catalog \
 -c v4.5 \
 -i Automatic \
 -s opencloud-operators-v4-1 \
 -v 1

After running the automation script, this ends up with the existing IM works as is, until CloudPaks are upgraded and stop creating OperandRequests for ibm-iam-operator and ibm-zen-operator.

Cloud Paks should update OperandRequest to only request ibm-im-operator and ibm-platformui-operator

apiVersion: operator.ibm.com/v1alpha1
kind: OperandRequest
metadata:
  name: common-service
  namespace: tenant1-cp4ba-namespace
spec:
  requests:
    - operands:
        - name: ibm-im-operator
        - name: ibm-platformui-operator
      registry: common-service
      registryNamespace: ibm-common-services

Migrate using manual steps

Take down utility operators
- Scale down ibm-common-service-operator deployment in the Common Service Namespace
- Delete ODLM operator in the Common Service Namespace
- Delete default OperandRegistry and OperandConfig named common-service in Common Service Namespace
Migrate cluster singleton services
- Migrate to cluster level cert-manager
  - Deactivate foundational services version 3.x cert-manager in Control Namespace
    - Edit ibm-cpp-config ConfigMap by adding deployCSCertManagerOperands: false to disable cert-manager operands:
```
  kind: ConfigMap
  apiVersion: v1
  metadata:
    name: ibm-cpp-config
    namespace: cs-control
  data:
    deployCSCertManagerOperands: 'false'
    storageclass.default: rook-ceph-block
    storageclass.list: 'rook-ceph-block,rook-cephfs'
```
    - Delete certManager CR named default
    - Restart ibm-cert-manager operator Pod
    - Verify that the foundational services cert-manager pods are no longer running(except for ibm-cert-manager-operator)
  - Deploy foundational services version 4.1 cert-manager at cluster scope
    - foundational services version 4.1 cert-manager will be deployed in ibm-cert-manager namespace at AllNamespaces Mode
    - Both foundational services version 4.1 and OpenShift Container Platform cert-manager can co-exist with CP2 ibm-cert-manager. Only foundational services version 4.1 and OpenShift Container Platform cert-manager will perform certificate management.
- Migrate into cluster-level License Service
  - Migrate the existing License Service data (ConfigMaps, Secrets)
  - Disable License Service in Common Service or Control Namespace
  - Deploy LicenseService at the cluster level

Propagate default CommonService CR to every namespace in the tenant

Create/Update CommonService CR named common-service in every namespace in the tenant with proper values of servicesNamespace and operatorNamespace. The following is an example CommonService CRs:

apiVersion: operator.ibm.com/v3
kind: CommonService
metadata:
  name: common-service
  namespace: tenant1-cp4ba-cs-namespace
spec:
  operatorNamespace: tenant1-cp4ba-cs-namespace
  servicesNamespace: tenant1-cp4ba-cs-namespace
  size: starterset
-----------------------------
apiVersion: operator.ibm.com/v3
kind: CommonService
metadata:
  name: common-service
  namespace: tenant1-cp4ba-namespace
spec:
  operatorNamespace: tenant1-cp4ba-cs-namespace
  servicesNamespace: tenant1-cp4ba-cs-namespace
  size: starterset

Upgrade Common Service and ODLM operator
- Upgrade ibm-common-services-operator
  - Channel switch:
    - in ibm-common-services namespace into v4.5
    - in cloudpak namespaces (for example, cp4ba)
    - The sequence of upgrading common service operator in different namespace does not matter, the preceding step takes care of this.
    - The following shows a common service operator pod log in the cp4ba namespace:
```
I0308 05:52:06.172662 1 main.go:132] Identifying Common Service Operator Role in the namespace cp4i
I0308 05:52:06.179092 1 main.go:261] Common Service Operator goes dormant in the namespace cp4i
I0308 05:52:06.179109 1 main.go:262] Common Service Operator in the namespace ibm-common-services takes charge of resource management
```
- Upgrade operand-deployment-lifecycle-manager
  - ibm-common-services-operator v4 will upgrade ODLM to v4 as well
Clean up foundational services version 3.x resources
- Delete SecretShare Deployment and its CRs
- Delete Crossplane Components
- Delete ibm-common-service webhook and its configurations
- Clean up old NamespaceScope CR - nss-odlm-scope:
```
> oc get namespacescope -n ibm-common-services | grep -v common-service
NAME                        AGE
nss-odlm-scope              7h18m
```
Upgrade Namespace Scope Operator
- Upgrade ibm-namespace-scope-operator
  - If you are using NSS Operator restricted in foundational services version 3.x, uninstall the NSS operator restricted and reinstall the foundational services version 4.1 NSS operator by creating a new subscription
  - Use the authorize-namespace.sh script to project Namespace Scope roles and role bindings to the other namespace in the topology. For more information, see Authorization and Permissions.
- Update NamespaceScope CR named common-service in Common Service Namespace to include all namespaces in this tenant:
```
apiVersion: operator.ibm.com/v1
kind: NamespaceScope
metadata:
  name: common-service
  namespace: tenant1-cp4ba-cs-namespace
spec:
  csvInjector:
    enable: true
  namespaceMembers:
    - tenant1-cp4ba-cs-namespace
    - tenant1-cp4ba-namespace
  restartLabels:
    intent: projected
```

After completing the preceding manual steps, the existing IM works as is, until CloudPaks are upgraded and stop creating OperandRequests for ibm-iam-operator and ibm-zen-operator.

If you are an IBM Cloud Paks user, update OperandRequest to only request ibm-im-operator and ibm-platformui-operator

apiVersion: operator.ibm.com/v1alpha1
kind: OperandRequest
metadata:
  name: common-service
  namespace: tenant1-cp4ba-namespace
spec:
  requests:
    - operands:
        - name: ibm-im-operator
        - name: ibm-platformui-operator
      registry: common-service
      registryNamespace: tenant1-cp4ba-cs-namespace