Deploy Mobile Foundation to an existing Red Hat OpenShift Container Platform

improve this page | report issue

Learn how to install the Mobile Foundation instance on an OpenShift cluster using the IBM Mobile Foundation Operator.

There are two ways of getting the entitlement to OpenShift Container Platform (OCP).

  • You have the entitlement to IBM Cloud Pak for Applications, which includes the OpenShift Container Platform entitlement.
  • You have an existing OpenShift Container Platform (bought from Red Hat).

The steps to deploy Mobile Foundation on OCP are the same irrespective of how you have obtained the OCP entitlement.


Following are the prerequisites before you begin the process of installing Mobile Foundation instance using the Mobile Foundation Operator.

  • OpenShift cluster v3.11 or above.
  • OpenShift client tools (oc).
  • Install and setup Docker.
  • Mobile Foundation requires a database. Create a supported database and keep the database access details handy for further use. See here.
  • Mobile Foundation Analytics requires storage class or mounted storage volume for persisting Analytics data (NFS recommended).


Image below shows the internal architecture of Mobile services on Red Hat OpenShift.


Installing an IBM Mobile Foundation instance

Download the IBM Mobile Foundation package

Download the IBM Mobile Foundation package for Openshift from IBM Passport Advantage (PPA). Unpack the archive to a directory called workdir.

NOTE: Refer here if you want to validate the PPA package and verify the signature.

List of actions to perform at glance:

  • Create image pullsecret from Entitled registry credentials
  • Create database secret
  • Update pullsecret name in service_account.yaml
  • Update namespace name in role_binding.yaml
  • Deploy CRD and resources under ‘deploy’ directory
  • Run couple of oc adm policy commands
  • Update image pullsecret, ingress hostname, database details and DB secret and any other customization in Custom Resource yaml and deploy

Using Mobile Foundation images from the Entitled Registry

Apart from loading the PPA images into the OpenShift internal image registry or any other external registry, one can use the images from the Entitled Registry (ER).

  1. Get a key to the entitled registry. After you order IBM Cloud Pak for Applications, an entitlement key for the Cloud Pak software is associated with your MyIBM account. Get the entitlement key that is assigned to your ID.
    • Log in to MyIBM Container Software Library with your IBMid and password, which is associated with the entitled software.
    • In the Entitlement keys section, select Copy key to copy the entitlement key to the clipboard.
      oc login <cluster url>
      oc new-project <namespace>
      docker login -u cp -p <entitlement key>
      oc create secret docker-registry -n <namespace> mfp-image-pullsecret --docker-username=cp --docker-password=<entitlement key >
  2. Extract the installation configuration from the installer image on the Entitled Registry.
    Using a command line, run the following commands.
    • Set the Entitled Registry information. Run export commands that set the following: ENTITLED_REGISTRY to, ENTITLED_REGISTRY_USER to cp, and ENTITLED_REGISTRY_KEY to the entitlement key that you got from the previous step.
       export ENTITLED_REGISTRY_KEY=<apikey>
    • Make sure you are able to log in to the Entitled Registry with the following docker login command.
  3. Generate an image pull secret using the Entitled Registry details.
    • Use the following command:
      oc create secret docker-registry -n <my_project_name> er-image-pullsecret --docker-username=<my_username> --docker-password=<my_api_key>
    • Add the pull secrets to deploy/crds/charts_v1_mfoperator_cr.yaml file.

Set up the OpenShift project for Mobile Foundation

Follow the steps outlined in this section to deploy the Mobile Foundation OpenShift Container Platform (OCP) package to Red Hat OpenShift cluster on IBM Cloud.

  1. Log in to Red Hat OpenShift cluster with administrator privileges and set project names for Mobile Foundation and Elasticsearch.
     oc login -u <username> -p <password> <cluster-url>
     export ES_PROJECT_NAME=<namespace_to_deploy_elasticsearch>
     export MF_PROJECT_NAME=<namespace_to_deploy_mobilefoundation>

    NOTE: Directly pull images from Entitled Registry by creating image pull secret as mentioned earlier in this topic. This process is easier compared to pushing the images present in tar.gz file to OpenShift internal registry. Upgrades are also easier when Entitled Registry pull secret is used. You can skip below steps 2 and 4 if you are pulling images from Entitled Registry.

  2. Log in into OpenShift’s internal docker registry by running the following commands.
     # Create a route from the terminal to the image registry
     oc create route reencrypt --service=image-registry -n openshift-image-registry
     oc get route image-registry -n openshift-image-registry
     # login into the OpenShift internal image registry
     docker login -u kubeadmin -p $(oc whoami -t)

    For example,

     $ oc create route reencrypt --service=image-registry -n openshift-image-registry created
     $ oc get route image-registry -n openshift-image-registry
     NAME             HOST/PORT                                                         PATH      SERVICES         PORT       TERMINATION   WILDCARD
     image-registry             image-registry   5000-tcp   reencrypt     None
     $ docker login -u kubeadmin -p $(oc whoami -t)
     WARNING! Using --password via the CLI is insecure. Use --password-stdin.
     Login Succeeded
  3. Unpack the PPA archive into a work directory (say mfoskpg).

     mkdir mfospkg
     tar xzvf IBM-MobileFoundation-Openshift-Pak-<version>.tar.gz -C mfospkg/
  4. Load and push the images to OpenShift registry from local machine. Ensure the following commands are run with values as per your environment.
     export ES_PROJECT_NAME=<namespace_to_deploy_elasticsearch>
     export MF_PROJECT_NAME=<namespace_to_deploy_mobilefoundation>
     cd mfospkg/images
     cd images
     ls * | xargs -I{} docker load --input {}
     for file in * ; do
       if [ "$file" == "es-operator"* ] || [ "$file" == *"mfpf-elasticsearch"* ]
       docker tag ${file/.tar.gz/} ${CONTAINER_REGISTRY_URL}/${OS_PROJECT}/${file/.tar.gz/}
       docker push ${CONTAINER_REGISTRY_URL}/${OS_PROJECT}/${file/.tar.gz/}
     for image in "mfpf-server" "mfpf-analytics" "mfpf-push" "mfpf-analytics-recvr" "mfpf-liveupdate" "mfpf-appcenter" "mfpf-elasticsearch" "mf-operator" "es-operator"  
       if [ "$MF_IMAGE" = "es-operator" ] || [ "$MF_IMAGE" = "mfpf-elasticsearch" ]
       docker manifest annotate ${CONTAINER_REGISTRY_URL}/${OS_PROJECT}/${MF_IMAGE}:${IMAGE_TAG} ${CONTAINER_REGISTRY_URL}/${OS_PROJECT}/${MF_IMAGE}:${IMAGE_TAG}-amd64 --os linux --arch amd64
       docker manifest annotate ${CONTAINER_REGISTRY_URL}/${OS_PROJECT}/${MF_IMAGE}:${IMAGE_TAG} ${CONTAINER_REGISTRY_URL}/${OS_PROJECT}/${MF_IMAGE}:${IMAGE_TAG}-ppc64le --os linux --arch ppc64le
       docker manifest annotate ${CONTAINER_REGISTRY_URL}/${OS_PROJECT}/${MF_IMAGE}:${IMAGE_TAG} ${CONTAINER_REGISTRY_URL}/${OS_PROJECT}/${MF_IMAGE}:${IMAGE_TAG}-s390x --os linux --arch s390x
       docker manifest push ${CONTAINER_REGISTRY_URL}/${OS_PROJECT}/${MF_IMAGE}:${IMAGE_TAG} --insecure
  5. Create a secret with database credentials.

     cat <<EOF | oc apply -f -
     apiVersion: v1
       MFPF_ADMIN_DB_USERNAME: <base64-encoded-string>
       MFPF_ADMIN_DB_PASSWORD: <base64-encoded-string>
       MFPF_RUNTIME_DB_USERNAME: <base64-encoded-string>
       MFPF_RUNTIME_DB_PASSWORD: <base64-encoded-string>
       MFPF_PUSH_DB_USERNAME: <base64-encoded-string>
       MFPF_PUSH_DB_PASSWORD: <base64-encoded-string>
       MFPF_LIVEUPDATE_DB_USERNAME: <base64-encoded-string>
       MFPF_LIVEUPDATE_DB_PASSWORD: <base64-encoded-string>
       MFPF_APPCNTR_DB_USERNAME: <base64-encoded-string>
       MFPF_APPCNTR_DB_PASSWORD: <base64-encoded-string>
     kind: Secret
       name: mobilefoundation-db-secret
     type: Opaque

    NOTE: An encoded string can be obtained using echo -n <string-to-encode> | base64.

  6. (Optional) To connect to Db2 database that runs on SSL, do the following steps:

    Note: If the schema already exists in the database, ignore creation of trustStore.jks and db2sslsecret as mentioned in the following steps. To establish connection with the existing schema, set the following values:

    • Set the property enabled to false under global.dbinit
    • Set the property ssl as true under mfpserver.ssl and mfppush.ssl (depending on the components you enable)
    • Set the property sslTrustStoreSecret as “”

    a. Run the following keytool command to create a truststore file based on the Db2 SSL certificate:

    If you are referring to Db2 database on IBM Cloud, then download the SSL certificate from the settings page of the Db2 dashboard.

       keytool -importcert -keystore trustStore.jks -storepass mobilefirst -file DigiCertGlobalRootCA.crt -alias db2sslcert

    NOTE: Do not change the name of the truststore file, trustStore.jks. b. Create a secret with truststore file and truststore password. You can choose to have a different password.

       kubectl create secret generic db2sslsecret --from-file=./trustStore.jks --from-literal=TRUSTSTORE_PASSWORD=mobilefirst

    c. In deploy/crds/charts_v1_mfoperator_cr.yaml file, set the value of ssl property to true and also provide the secret created in the previous step for the sslTrustStoreSecret of the db section .

  7. To enable Mobile Foundation Analytics, Elasticsearch operator must be deployed, For steps to deploy Elasticsearch operator, see here.

Deploy the IBM Mobile Foundation Operator

  1. Update image pull secret name in deploy/service_account.yaml (REPLACE_SECRET).
  2. Update namespace name in deploy/role_binding.yaml (REPLACE_NAMESPACE).
  3. Run the following commands to deploy CRD, operator and install Security Context Constraints (SCC).

     oc create -f deploy/crds/charts_v1_mfoperator_crd.yaml
     oc create -f deploy/service_account.yaml
     oc create -f deploy/role.yaml
     oc create -f deploy/role_binding.yaml
     oc create –f deploy/scc.yaml
     oc adm policy add-scc-to-group mf-operator system:serviceaccounts:$MFOS_PROJECT
     oc create -f deploy/operator.yaml

    IMPORTANT: From onwards, mf-operator is enabled to run without cluster-admin access, so you can skip running the following command:

     oc adm policy add-cluster-role-to-user cluster-admin system:serviceaccount:$MFOS_PROJECT:mf-operator

Deploy IBM Mobile Foundation components

  1. To deploy any of the Mobile Foundation components, modify the custom resource configuration deploy/crds/charts_v1_mfoperator_cr.yaml according to your requirements. Complete reference to the custom configuration is found here.

    IMPORTANT NOTE : To access the Mobile Foundation instances after deployment we need to configure ingress hostname. Please make sure ingress is configured in the custom resource configuration. Refer this link on configuring the same.

     oc apply -f deploy/crds/charts_v1_mfoperator_cr.yaml
  2. Run the following command and ensure the pods are created and running successfully. In a deployment scenario where Mobile Foundation Server and push are enabled with 3 replicas each (default), the output looks as shown below.

       $ oc get pods
       NAME                           READY     STATUS    RESTARTS   AGE
       mf-operator-5db7bb7w5d-b29j7   1/1       Running   0          1m
       mfpf-server-2327bbewss-3bw31   1/1       Running   0          1m 20s
       mfpf-server-29kw92mdlw-923ks   1/1       Running   0          1m 21s
       mfpf-server-5woxq30spw-3bw31   1/1       Running   0          1m 19s
       mfpf-push-2womwrjzmw-239ks     1/1       Running   0          59s
       mfpf-push-29kw92mdlw-882pa     1/1       Running   0          52s
       mfpf-push-1b2w2s973c-983lw     1/1       Running   0          52s

    NOTE: Pods in Running (1/1) status shows the service is available for access.

  3. Check if the routes are created for accessing the Mobile Foundation endpoints by running the following command.

     $ oc get routes
     NAME                                      HOST/PORT               PATH        SERVICES             PORT      TERMINATION   WILDCARD
     ibm-mf-cr-1fdub-mfp-ingress-57khp   /imfpush          ibm-mf-cr--mfppush     9080                    None
     ibm-mf-cr-1fdub-mfp-ingress-8skfk   /mfpconsole       ibm-mf-cr--mfpserver   9080                    None
     ibm-mf-cr-1fdub-mfp-ingress-dqjr7   /doc              ibm-mf-cr--mfpserver   9080                    None
     ibm-mf-cr-1fdub-mfp-ingress-ncqdg   /mfpadminconfig   ibm-mf-cr--mfpserver   9080                    None
     ibm-mf-cr-1fdub-mfp-ingress-x8t2p   /mfpadmin         ibm-mf-cr--mfpserver   9080                    None
     ibm-mf-cr-1fdub-mfp-ingress-xt66r   /mfp              ibm-mf-cr--mfpserver   9080                    None

Deploying Elasticsearch for Mobile Foundation Analytics

Elasticsearch operator is a prerequisite to deploy Mobile Foundation Analytics on OpenShift cluster from iFix IF202006151151 onwards.


  • (Mandatory) A pre-created PersistentVolume (PV) and PersistentVolumeClaim (PVC) or Storageclass should be available.

Deploy Elasticsearch operator

  1. Log in to the Openshift cluster and create a new project.
    export MFES_PROJECT=<project-name>
    oc login -u <username> -p <password> <cluster-url>
    oc new-project $MFES_PROJECT
  2. Create Entitled Registry (ER) Secret by replacing the apikey and password in the following command.
    oc create secret docker-registry -n $MFES_PROJECT cp-docker-secret --docker-username=<apikey> --docker-password=<password>
  3. Add ImagePullSecret (cp-docker-secret) by replacing REPLACE_SECRET placeholder in the file es/deploy/service_account.yaml.

  4. Update Namespace name by replacing REPLACE_NAMESPACE placeholder in the file es/deploy/role_binding.yaml.

  5. For Elasticsearch deployment, either claimName (PVC) or storageClassName must be specified in es/deploy/crds/charts_v1_esoperator_cr.yaml.
      storageClassName: ""
      claimName: ""
  6. To use claimName, PV and PVC should be configured. Use the following command configure a PersistentVolume (PV).
     cat <<EOF | kubectl apply -f -
     apiVersion: v1
     kind: PersistentVolume
         name: mfanalyticspv  
       name: mfanalyticspv
         storage: 20Gi
         - ReadWriteMany
       persistentVolumeReclaimPolicy: Retain
         path: <nfs-mount-volume-path>
         server: <nfs-server-hostname-or-ip>

    To configure a PersistentVolumeClaim (PVC) use the following command.

      cat <<EOF | kubectl apply -f -
       apiVersion: v1
       kind: PersistentVolumeClaim
         name: mfanalyticsvolclaim
         namespace: <projectname-or-namespace>
           - ReadWriteMany
             storage: 20Gi
             name: mfanalyticspv
         volumeName: mfanalyticspv

    Note: Ensure that you add the nfs-server-hostname-or-ip and nfs-mount-volume-path entries in the yaml and ensure that the PVC is in bound state.

  7. Execute the following commands to deploy the Elasticsearch operator.
     oc create -f es/deploy/crds/charts_v1_esoperator_crd.yaml
     oc create -f es/deploy/service_account.yaml
     oc create -f es/deploy/role.yaml
     oc create -f es/deploy/role_binding.yaml
     oc adm policy add-scc-to-group anyuid system:serviceaccounts:$MFES_PROJECT  
     oc create -f es/deploy/operator.yaml  

    IMPORTANT: From onwards, es-operator is enabled to run without cluster-admin access, so you can skip running the following command:

    oc adm policy add-cluster-role-to-user cluster-admin system:serviceaccount:$MFES_PROJECT:es-operator

    Ensure to update image pull secret and storageclass/pvc name in Custom resource yaml:

    oc apply -f es/deploy/crds/charts_v1_esoperator_cr.yaml
  8. After the deployment is completed, Elasticsearch runs as an internal service and can be used by Mobile Foundation Analytics.

While deploying Mobile Foundation Analytics, update esnamespace in the CR yaml with the project name where Elasticsearch is deployed.

Accessing the console of IBM Mobile Foundation components

Following are the endpoints for accessing the consoles of Mobile Foundation components

  • Mobile Foundation Server Administration Console - http://<ingress_hostname>/mfpconsole
  • Operational Analytics Console - http://<ingress_hostname>/analytics/console
  • Application Center Console - http://<ingress_hostname>/appcenterconsole

For Operator image tag 8.1.4 onwards, a default random console password will be generated, which can be obtained by running the commands below depending on the components you chose during the deployment. You can override the default behaviour. For more details, refer here.

oc get secret ibm-mf-mfpserver-consolesecret -o jsonpath='{.data.MFPF_ADMIN_PASSWORD}' | base64 -D
oc get secret ibm-mf-mfpanalytics-consolesecret -o jsonpath='{.data.MFPF_ANALYTICS_ADMIN_PASSWORD}' | base64 -D
oc get secret ibm-mf-mfpappcenter-consolesecret -o jsonpath='{.data.MFPF_APPCNTR_ADMIN_PASSWORD}' | base64 -D

Backup and recovery of Mobile Foundation Analytics data

The Mobile Foundation Analytics data is available as part of Kubernetes PersistentVolume or PersistentVolumeClaim. You may be using one of the volume plugins that Kubernetes offers. Backup and restore depends on the volume plugins that you use. There are various tools using which the volume can be backed-up or restored.

Kuberenetes provides VolumeSnapshot, VolumeSnapshotContent, and Restore options. You may take a copy of the volume in the cluster that has been provisioned by an administrator.

Use the sample yaml files to test the snapshot feature.

You may also leverage other tools to take a backup of the volume and restore the same.


Use the following commands to perform uninstallation:

oc delete -f deploy/crds/charts_v1_mfoperator_cr.yaml

If the above command gets stuck, then run the patch command:

oc patch crd/ -p '{"metadata":{"finalizers":[]}}' --type=merge"
oc delete -f deploy/
oc delete -f deploy/crds/charts_v1_mfoperator_crd.yaml

Uninstall Elasticsearch

oc delete -f es/deploy/crds/charts_v1_esoperator_cr.yaml

If the above command gets stuck, then run the patch command:

oc patch crd/ -p '{"metadata":{"finalizers":[]}}' --type=merge"
oc delete -f es/deploy/
oc delete -f es/deploy/crds/charts_v1_esoperator_crd.yaml


  1. For Mobile Foundation deployment related issues, share the following information with IBM Support:
    • Version of the mf-operator installed. You can get it from deploy/operator.yaml file
    • Mobile Foundation custom resource (charts_v1_mfoperator_cr.yaml)
    • Output of oc get pods
    • Operator pod logs (oc logs <mf-operator-pod-name>)
    • Output of command oc describe pod <pod-name> for each pod
    • Mobile Foundation pod logs (oc logs <pod-name>)of all pods
  2. For Mobile Foundation functionality related issues: Enable Mobile Foundation traces using Custom configuration described here Get the logs by running the following command:

    oc cp <server-pod-name>:/logs/messages.log ./server-messages.log
    oc cp <server-pod-name>:/logs/trace.log ./server-trace.log
  3. For es-operator related issues, share the following information with IBM Support:
    • Version of the es-operator installed. You can get it from es/deploy/operator.yaml file
    • Elasticsearch custom resource (charts_v1_esoperator_cr.yaml)
    • Output of oc get pods
    • Operator pod logs (oc logs <es-operator-pod-name>)
    • Output of command oc describe pod <pod-name> for each pod
    • Elasticsearch pod logs (oc logs <pod-name>)of all pods
  4. For installation related issues, perform the following actions: You might encounter issues when you install Mobile Foundation on Red Hat OpenShift cluster. Following are some of the common issues you may encounter during the installation process:

    1. mf-operator pod does not show up Possible cause: The scc.yaml is not deployed or mf-operator scc assignment is not done. Error:

      $ oc get rs
      NAME                    DESIRED   CURRENT   READY   AGE
      mf-operator-87b88494f   1         0         0       33s
      $ oc describe rs mf-operator-87b88494f
      Type     Reason        Age                   From                   Message
      ----     ------        ----                  ----                   -------
      Warning  FailedCreate  96s (x14 over 2m17s)  replicaset-controller  Error creating: pods "mf-operator-87b88494f-" is forbidden: unable to validate against any security context constraint: [spec.containers[0].securityContext.securityContext.runAsUser: Invalid value: 1001: must be in the ranges: [1000570000, 1000579999]] 

      Resolution: Assign mf-operator scc by using the following command:

      oc adm policy add-scc-to-group mf-operator system:serviceaccounts:<project-name>
    2. Operator pod STATUS shows ErrImagePull

      Possible cause: Image pull secret is not updated in service_account.yaml. The updated pull secret does not exist or the secret exists with wrong registry credentials.


      $ oc get pods
      NAME                          READY   STATUS         RESTARTS   AGE
      mf-operator-87b88494f-gtpq2   0/1     ErrImagePull   0          4s

      Resolution: Ensure that the image pull secret is created with right registry credentials and the same secret name is updated in service_account.yaml.

    3. After deploying custom resource, no pods show up.

      Possible cause: The namespace name is not updated in role_binding.yaml or wrong namespace name is updated. Error in operator pod logs:

      Failed to list, Kind=MFOperator: is forbidden: User "system:serviceaccount:mfnew:mf-operator" cannot list resource "mfoperators" in API group "" in the namespace "mfnew"

      Resolution: Ensure proper namespace name is updated in role_binding.yaml.

    4. The dbinit-job shows error

      Possible cause: Db details (host, port and name) provided in custom resource(charts_v1_mfoperator_cr.yaml) are not correct, Db is not reachable or dbsecret is created with wrong credentials.


      $ oc get pods
      NAME                          READY   STATUS    RESTARTS   AGE
      ibm-mf-dbinit-job-9c2gb       0/3     Error     3          32s

      If db-init pod log reports error particularly for TABLE PUSH_DEVICES, then Mobile Foundation database could have been created without PAGESIZE. Refer here to create a database with PAGESIZE.

      Resolution: Correct the DB details and redeploy.

    5. Mobile Foundation pods show 0/1 READY

       $ oc get pods
       NAME                              READY   STATUS      RESTARTS   AGE
       ibm-mf-defaultsecrets-job-7z42m   0/1     Completed   0          5m21s
       ibm-mf-push-77fb65c758-wtg28      0/1     Running     0          5m16s
       ibm-mf-server-d87ddf67f-x9n4x     0/1     Running     0          5m16s

      Check if the Database that Mobile Foundation is connected to is reachable or not. For more details on the issue, check the pod logs.

      Resolution: If no errors are shown on the pod logs and Db is reachable, delete the existing pods so that new pods are recreated. For any other issues, check the operator pod logs to get more details on the issue.

    6. Elasticsearch data pod is not coming up properly

      Possible cause: Storage class is not provided in custom resource (charts_v1_esoperator_cr.yaml) or the provided PVC does not have proper access for the Elasticsearch to write data.

      Resolution: If the claimName is provided in custom resource(charts_v1_esoperator_cr.yaml), then make sure Elasticsearch data has access to the mount location. Run the following commands on the mount path:

       chown -R 1001:1001 <mount_path>
       chmod -R ug+rwx <mount_path>
    7. Mobile Foundation routes are not created/accessible

      Possible cause: spec.ingress.hostname is not updated in custom resource yaml or pods are not properly running.

      Resolution: Update spec.ingress.hostname and redeploy the custom resource.

Additional References

  1. Setting up of Mobile Foundation databases
  2. Using Oracle (or) MySQL as IBM Mobile Foundation database
  3. Custom Resource configuration parameters for Mobile Foundation
  4. Scenarios in enabling Ingress
  5. Upgrading Mobile Foundation

What next

Inclusive terminology note: The Mobile First Platform team is making changes to support the IBM® initiative to replace racially biased and other discriminatory language in our code and content with more inclusive language. While IBM values the use of inclusive language, terms that are outside of IBM's direct influence are sometimes required for the sake of maintaining user understanding. As other industry leaders join IBM in embracing the use of inclusive language, IBM will continue to update the documentation to reflect those changes.
Last modified on May 06, 2021