Deploy Mobile Foundation to an existing Red Hat OpenShift Container Platform
improve this page | report issueLearn 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.
Prerequisites
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 mounted storage volume for persisting Analytics data (NFS recommended).
Architecture
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.
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).
- 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.
- 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 cp.icr.io, ENTITLED_REGISTRY_USER to cp, and ENTITLED_REGISTRY_KEY to the entitlement key that you got from the previous step.
export ENTITLED_REGISTRY=cp.icr.io export ENTITLED_REGISTRY_USER=cp export ENTITLED_REGISTRY_KEY=<apikey>
- Make sure you are able to log in to the Entitled Registry with the following
docker login
command.docker login "$ENTITLED_REGISTRY" -u "$ENTITLED_REGISTRY_USER" -p "$ENTITLED_REGISTRY_KEY"
- Set the Entitled Registry information. Run export commands that set the following:
ENTITLED_REGISTRY to cp.icr.io, ENTITLED_REGISTRY_USER to cp, and ENTITLED_REGISTRY_KEY to the entitlement key that you got from the previous step.
- 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-server=cp.icr.io --docker-username=<my_username> --docker-password=<my_api_key>
- Add the pull secrets to the
deploy/operator.yaml
anddeploy/crds/charts_v1_mfoperator_cr.yaml
files.
- Use the following command:
Setup the OpenShift project for Mobile Foundation
- Log in to OpenShift cluster and create a new project.
export MFOS_PROJECT=<project-name> oc login -u <username> -p <password> <cluster-url> oc new-project $MFOS_PROJECT
- Unpack the IBM Mobile Foundation package for Openshift using the following command.
tar xzvf IBM-MobileFoundation-Openshift-Pak-<version>.tar.gz -C <workdir>/
- Load and push the images to OpenShift registry from local.
docker login -u <username> -p $(oc whoami -t) $(oc registry info) cd <workdir>/images ls * | xargs -I{} docker load --input {} for file in * ; do docker tag ${file/.tar.gz/} $(oc registry info)/$MFOS_PROJECT/${file/.tar.gz/} docker push $(oc registry info)/$MFOS_PROJECT/${file/.tar.gz/} done
-
Create a secret with database credentials.
cat <<EOF | oc apply -f - apiVersion: v1 data: 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 metadata: name: mobilefoundation-db-secret type: Opaque EOF
NOTE: An encoded string can be obtained using
echo -n <string-to-encode> | base64
. - To enable Mobile Foundation Analytics, Elasticsearch operator must be deployed, For steps to deploy Elasticsearch operator, see here.
Deploy the IBM Mobile Foundation Operator
-
Ensure the Operator image name (mf-operator) with tag is set for the operator in
deploy/operator.yaml
(REPO_URL).sed -i 's|REPO_URL|<image-repo-url>:<image-tag>|g' deploy/operator.yaml
-
Ensure the namespace is set for the cluster role binding definition in
deploy/cluster_role_binding.yaml
(REPLACE_NAMESPACE).sed -i 's|REPLACE_NAMESPACE|$MFOS_PROJECT|g' deploy/cluster_role_binding.yaml
For Operator image tag 1.0.11 onwards, use the command below.
sed -i 's|REPLACE_NAMESPACE|$MFOS_PROJECT|g' deploy/role_binding.yaml
-
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/ oc adm policy add-scc-to-group mf-operator system:serviceaccounts:$MFOS_PROJECT
For Operator image tag 1.0.11 onwards, use the commands below.
oc create -f deploy/crds/charts_v1_mfoperator_crd.yaml oc create -f deploy/ oc adm policy add-scc-to-group mf-operator system:serviceaccounts:$MFOS_PROJECT oc adm policy add-cluster-role-to-user cluster-admin system:serviceaccount:$MFOS_PROJECT:mf-operator
Deploy IBM Mobile Foundation components
-
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
-
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.
-
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 myhost.mydomain.com /imfpush ibm-mf-cr--mfppush 9080 None ibm-mf-cr-1fdub-mfp-ingress-8skfk myhost.mydomain.com /mfpconsole ibm-mf-cr--mfpserver 9080 None ibm-mf-cr-1fdub-mfp-ingress-dqjr7 myhost.mydomain.com /doc ibm-mf-cr--mfpserver 9080 None ibm-mf-cr-1fdub-mfp-ingress-ncqdg myhost.mydomain.com /mfpadminconfig ibm-mf-cr--mfpserver 9080 None ibm-mf-cr-1fdub-mfp-ingress-x8t2p myhost.mydomain.com /mfpadmin ibm-mf-cr--mfpserver 9080 None ibm-mf-cr-1fdub-mfp-ingress-xt66r myhost.mydomain.com /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.
Prerequisites
- (Mandatory) A pre-created PersistentVolume (PV) and PersistentVolumeClaim (PVC) or Storageclass should be available.
Deploy Elasticsearch operator
- 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
- Create Entitled Registry (ER) Secret by replacing the apikey and password in the following command.
kubectl create secret docker-registry -n $MFES_PROJECT cp-docker-secret --docker-server=cp.stg.icr.io --docker-username=<apikey> --docker-password=<password>
-
Add ImagePullSecret by replacing
REPLACE_SECRET
placeholder in the filees/deploy/service_account.yaml
. - For Elasticsearch deployment, either claimName (PVC) or storageClassName must be specified in
es/deploy/crds/charts_v1_esoperator_cr.yaml
.persistence: storageClassName: "" claimName: ""
- 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 metadata: labels: name: mfanalyticspv name: mfanalyticspv spec: capacity: storage: 20Gi accessModes: - ReadWriteMany persistentVolumeReclaimPolicy: Retain nfs: path: <nfs-mount-volume-path> server: <nfs-server-hostname-or-ip> EOF
To configure a PersistentVolumeClaim (PVC) use the following command.
cat <<EOF | kubectl apply -f - apiVersion: v1 kind: PersistentVolumeClaim metadata: name: mfanalyticsvolclaim namespace: <projectname-or-namespace> spec: accessModes: - ReadWriteMany resources: requests: storage: 20Gi selector: matchLabels: name: mfanalyticspv volumeName: mfanalyticspv EOF
Note: Ensure that you add the
nfs-server-hostname-or-ip
andnfs-mount-volume-path
entries in the yaml and ensure that the PVC is in bound state. - 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/ oc adm policy add-scc-to-group es-operator system:serviceaccounts:$MFES_PROJECT oc adm policy add-cluster-role-to-user cluster-admin system:serviceaccount:$MFES_PROJECT:es-operator oc apply -f es/deploy/crds/charts_v1_esoperator_cr.yaml
- 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
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.
- IBM Cloud Automation Manager (CAM), leverage the capabilities of CAM and strategies for Backup/Restore, High Availability (HA) and Disaster Recovery (DR) for CAM instances.
- Portworx is a storage solution designed for applications deployed as containers or via container orchestrators such as Kubernetes.
- Stash by AppsCode, using Stash you can backup the volumes in Kubernetes.
Uninstall
Use the following commands to perform a post installation clean up.
oc delete -f deploy/crds/charts_v1_mfoperator_cr.yaml
oc delete -f deploy/
oc delete -f deploy/crds/charts_v1_mfoperator_crd.yaml
oc patch crd/ibmmf.charts.helm.k8s.io -p '{"metadata":{"finalizers":[]}}' --type=merge
Additional References
- Setting up of Mobile Foundation databases
- Using Oracle (or) MySQL as IBM Mobile Foundation database
- Custom Resource configuration parameters for Mobile Foundation
- Scenarios in enabling Ingress
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.