Configuring an external EDB PostgreSQL database for IM

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

From foundational services version 4.6, Identity Management (IM) service uses EDB PostgreSQL as a database to store IM data. If you upgrade foundational services from version 3.19, 3.23, 4.0 or later to 4.6 or later, IM operator migrates IAM/IM data from MongoDB to EDB PostgreSQL database. For more information, see Migrating foundational services version 3.x to 4.x.

Ensure that you configure the IM with the embedded or external EDB PostgreSQL database before you install or upgrade the foundational services. You cannot migrate data from embedded PostgreSQL to external EDB PostgreSQL after you install or upgrade the foundational services.

For the Isolated migration of the cluster with two or more Cloud Paks in the same namespace, the MongoDB data is migrated successfully when you upgrade the first Cloud Pak. To migrate the MongoDB data from other Cloud Paks, run the following command:

   #!/bin/bash

   DB_POD="icp-mongodb-0"

   # Execute MongoDB rollback commands
   echo 'use samlDB
   db.saml.updateMany({}, {$unset:{migrated: null}})

   use platform-db
   db.cloudpak_ibmid_v3.updateMany({}, {$unset:{migrated: null}})
   db.cloudpak_ibmid_v2.updateMany({}, {$unset:{migrated: null}})
   db.Directory.updateMany({}, {$unset:{migrated: null}})
   db.Users.updateMany({}, {$unset:{migrated: null}})
   db.UserPreferences.updateMany({}, {$unset:{migrated: null}})
   db.ZenInstance.updateMany({}, {$unset:{migrated: null}})
   db.ZenInstanceUsers.updateMany({}, {$unset:{migrated: null}})
   db.ScimAttributes.updateMany({}, {$unset:{migrated: null}})
   db.ScimAttributeMapping.updateMany({}, {$unset:{migrated: null}})
   db.Groups.updateMany({}, {$unset:{migrated: null}})
   db.ScimServerUsers.updateMany({}, {$unset:{migrated: null}})
   db.ScimServerGroups.updateMany({}, {$unset:{migrated: null}})

   use OAuthDBSchema
   db.OauthClient.updateMany({}, {$unset:{migrated: null}})' | oc exec -ti $DB_POD -- bash -ec 'mongo --host rs0/mongodb:27017 --username $ADMIN_USER --password $ADMIN_PASSWORD --authenticationDatabase admin --ssl --sslCAFile /data/configdb/tls.crt --sslPEMKeyFile /work-dir/mongo.pem'

Prerequisites

Complete the following prerequisites to configure IM with the EDB PostgreSQL database:

  1. Set up the database server if you use new external database server. For more information, see Setting up an external PostgreSQL database server.

    You can skip this step if you already completed the setup for the external database server with all the certificates.

  2. Configure Secure Sockets Layer (SSL) modes for IM. For more information, see Configuring SSL modes for IM.

  3. You need to generate the following key files in the database server to configure IM to use EDB PostgreSQL as a database:

    • client.crt
    • client.key
    • client_key.pem
    • client.pem
    • root.pem

    To generate the key files, see Generating key files for IM.

Supported database

IM supports embedded and external PostgreSQL database. IM is configured with the embedded EDB PostgreSQL database as default.

You can configure IM with PostgreSQL version 16 as the external database and use the SSL client-certificate authentication method.

Configuring SSL modes for IM

You can configure IM with the require, verify-ca, and verify-full SSL modes. By default, IM is configured with the require SSL mode.

You can change the default SSL mode for IM with one of the following methods:

Generating key files for IM

To configure IM with an external PostgreSQL database, generate the key files in the database server with the following steps:

  1. Login to an external database server and copy the key files to your target cluster.

    scp client.crt client.key client_key.pem client.pem root.pem root@<your_ocp_IPaddress>:/root

    Replace <your_ocp_IPaddress> with the Red Hat OpenShift Container Platform IP address.

  2. Export the following environment variables.

    export PGREQUIRESSL=require 
export PGSSLCERT=client.crt 
export PGSSLKEY=client.key

  3. Download and enable PostgreSQL 16 on your target cluster.

    sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm 
sudo dnf -qy module disable postgresql 
sudo dnf install -y postgresql16-server

  4. Test the PostgreSQL server connection.

    psql --host=<yourFyreClusterName>1.fyre.ibm.com --port=5432 --dbname=im --username=im_user -c "SELECT VERSION()" -c "SHOW ssl" -c "SHOW max_connections" -c "\list" -c "\dn" -c "\du"

    Replace <yourFyreClusterName> with your Fyre cluster name to specify the host name of the PostgreSQL server.

  5. Create the im-metastore-edb-secret secret.

    oc create secret generic im-datastore-edb-secret \
    --type=kubernetes.io/tls \
    --from-file=ca.crt=root.pem \
    --from-file=tls.crt=client.pem \
    --from-file=tls.key=client_key.pem \
    -n <your foundational service operand namespace>

    Replace <your foundational service operand namespace> with the namespace where you deployed the foundational services.

    You can update ca.crt, tls.crt, and tls.key parameters with the appropriate values.

  6. Verify that the certificates are stored in the secret.

    oc extract secret/im-datastore-edb-secret -n <your foundational service operand namespace> --to=- --keys=ca.crt | openssl x509 -noout -subject -issuer -startdate -enddate

oc extract secret/im-datastore-edb-secret -n <your foundational service operand namespace> --to=- --keys=tls.crt | openssl x509 -noout -subject -issuer -startdate -enddate

    Replace <your foundational service operand namespace> with the namespace where you deployed the foundational services.

  7. Create the im-metastore-edb-cm configmap.

    apiVersion: v1
kind: ConfigMap
metadata:
  name: im-datastore-edb-cm
  namespace: <your foundational service operand namespac>
data:
  DATABASE_CA_CERT: ca.crt
  DATABASE_CLIENT_CERT: tls.crt
  DATABASE_CLIENT_KEY: tls.key
  DATABASE_NAME: im
  DATABASE_PORT: "5432"
  DATABASE_R_ENDPOINT: sertexternaledb16x1.fyre.ibm.com
  DATABASE_RW_ENDPOINT: sertexternaledb16x1.fyre.ibm.com
  DATABASE_SCHEMA: public
  DATABASE_USER: im_user
  IS_EMBEDDED: 'false'

    Replace <your foundational service operand namespace> with the namespace where you deployed the foundational services.

    You can update the DATABASE_R_ENDPOINT, DATABASE_RW_ENDPOINT, DATABASE_USER, and DATABASE_NAME parameters with the appropriate values.

  8. Apply the im-metastore-edb-cm configmap.

    oc apply -f im-metastore-edb-cm.yaml

  9. Create a operand-request.yaml file with the following definitions:

    apiVersion: operator.ibm.com/v1alpha1
kind: OperandRequest
metadata:
 name: common-service
 namespace: $<your foundational service namespace>
spec:
 requests:
   - operands:
       - name: ibm-im-operator
       - name: ibm-events-operator
       - name: ibm-platformui-operator
       - name: cloud-native-postgresql
     registry: common-service
     registryNamespace: $<your foundational service namespace>

    Replace <your foundational service namespace> with the namespace where you deployed the foundational services.

  10. Verify that the platform-auth-service, platform-identity-management, and platform-identity-provider pods are running. Ensure that the common-service-db cluster is not created and its pods are not running.