Deploying PMF on existing container platform
Prerequisites
Ensure you have the following prerequisites before you start the process of installing PMF instance using the PMF operator.
- Installed and configured Red Hat® OpenShift® Container Platform Version cluster v4.15.
- Installed and configured OpenShift CLI (oc).
- Installed and configured Docker.
- Created a supported database and have the database access details handy for further use. See Setting Up Databases.
- Ensured that PMF Analytics has
storage class
or mountedstorage volume
for persisting Analytics data (NFS recommended). - Downloaded the PMF package for Red Hat® OpenShift® from the authorized link and unpacked the archive to a directory.
Installing the PMF instance
Install the PMF instance by following steps.
-
Deploy PMF OpenShift Container Platform (OCP) package
-
Deploy the PMF Operator
-
Deploy PMF components (if required)
-
Deploy PMF Analytics component
-
Accessing PMF component consoles
Deploying PMF OpenShift Container Platform (OCP) package
To deploy the PMF OpenShift Container Platform (OCP) package to Red Hat OpenShift cluster proceed as follows.
-
Log in to the Red Hat OpenShift cluster with administrator privileges and create new namespace by using the following command.
oc new-project mfp
-
Create docker registry secret by replacing the
apikey
and password by using the following command.oc create secret docker-registry -n mfp mfp-image-pullsecret --docker-server=index.docker.io --docker-username=<username> --docker-password=<your_password>
-
Create console secrets for the respective components by using the following command.
oc create secret generic serverlogin --from-literal=MFPF_ADMIN_USER=admin --from-literal=MFPF_ADMIN_PASSWORD=admin
oc create secret generic appcenterlogin --from-literal=MFPF_APPCNTR_ADMIN_USER=admin --from-literal=MFPF_APPCNTR_ADMIN_PASSWORD=admin
-
Create a secret with database credentials by using the following command.
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: mfpf-server-db-secret type: Opaque EOF
Note: An encoded string can be obtained by using the following command.
echo -n <string-to-encode> | base64
-
Optional: Connect to the Db2 database that runs on the Secure Sockets Layer (SSL), proceed as follows.
-
If the schema already exists, set the property enabled to
false
underglobal.dbinit
. -
If the schema does not exist, set the property enabled to
true
underglobal.dbinit
so that the script creates tables according to the enable components.
To establish connection with the existing schema, set the following values.
-
Run the following keytool command to create a
truststore
file based on the Db2 SSL certificate.keytool -importcert -keystore trustStore.jks -storepass pmfcloud -file DigiCertGlobalRootCA.crt -alias db2sslcert
For the IBM Cloud Db2 database, download the SSL certificate from the Settings page of the Db2 dashboard.
NOTE: Do not change the name of the
truststore
file ortrustStore.jks
file. -
Create a secret with the
truststore
file andtruststore
password by using the following command.oc create secret generic db2sslsecret --from-file=./trustStore.jks --from-literal=TRUSTSTORE_PASSWORD=pmfcloud
You can choose to have a different password.
-
In the
deploy/crds/charts_v1_mfoperator_cr.yaml
file, set the value of thessl
property to “true” and also provide the secret created in the previous step for thesslTrustStoreSecret
of the db section.
-
NOTE:
-
To enable (or disable) specific PMF components, see Custom Resource definitions.
-
To enable PMF Analytics, Elasticsearch operator must be deployed. For more information, see Deploying PMF Analytics.
Deploying the PMF Operator
To deploy PMF Operator, proceed as follows.
- Update “image pull secret name” by replacing the REPLACE_SECRET placeholder in the
deploy/service_account.yaml
file. - Update “namespace name” by replacing the REPLACE_NAMESPACE placeholder in the
deploy/role_binding.yaml
file. -
Navigate to the
deploy
folder inside PMF Red Hat OpenShift package and run the following commands to deploy CRD, operator, and install Security Context Constraints (SCC).export MFOS_PROJECT=<namespace_to_deploy_mobilefoundation> 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 oc adm policy add-cluster-role-to-user cluster-admin system:serviceaccount:$MFOS_PROJECT:mf-operator
Deploying PMF components
To deploy any of the PMF components, proceed as follows.
-
Modify the custom resource configuration
deploy/crds/charts_v1_mfoperator_cr.yaml
file as per your requirements. For more information, see Custom Resource definitions.oc apply -f deploy/crds/charts_v1_mfoperator_cr.yaml
-
Run the following command and ensure the pods are created and running successfully.
oc get pods
In a deployment scenario where PMF Server and push are enabled with 3 replicas each (default), following output is expected.
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 that the service is available for access.
-
Check if the routes are created for accessing the PMF 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
Important : To access the PMF instances after deployment you need to configure the ingress hostname
. Ensure that ingress is configured in the Custom Resource. For more information, see Configuring Ingress parameters.
Deploying PMF Analytics
To deploy PMF Analytics component, proceed as follows.
Prerequisites
- You must ensure that you have created PersistentVolume (PV) and PersistentVolumeClaim (PVC) or StorageClass.
- Ensure that you deploy the Elasticsearch operator. For more information, see Deploy Elasticsearch operator.
-
Release 9.1 Create the
config.properties
file at preferred location and add following variables in it:allowed.hostname= maximum.request=20 time.window=1
-
Create a
configmap
and provide a full file path of theconfig.properties
file. For example :oc create configmap analytics-custom-config --from-file= /<path>/config.properties
Ensure that you update the
configmap
in the deployment file for analytics. Edit the deployment yaml file and specify thisconfigmap
name else Analytics will not be able to identify user configuration and continue to run on the default settings.Release 9.2 The
config.properties
file is automatically created for the PMF Server console, PMF Appcenter console, and PMF Analytics console. -
Enable mfpanalytics component in the MFOperator CR yaml file, if not already done and reapply the cr yaml.
kubectl apply -f crds/charts_v1_mfoperator_cr.yaml
Note: Any changes to the
configmap
, need a restart of analytics pod to reflect the updates for that you can simply delete the pod.
Deploying Elasticsearch operator
To deploy Elasticsearch operator, proceed as follows.
-
Log in to the Red Hat OpenShift cluster and create a new project.
oc login -u <username> -p <password> <cluster-url> oc new-project mfp
-
Create docker registry secret by using the following command and replace the apikey and password.
oc create secret docker-registry -n mfp mfp-image-pullsecret --docker-server=index.docker.io --docker-username=<username> --docker-password=<your_password>
- Add “image pull secret” (mfp-image-pullsecret) by replacing the
REPLACE_SECRET
placeholder in thees/deploy/service_account.yaml
file. -
Update “namespace name” by replacing the REPLACE_NAMESPACE placeholder in the
es/deploy/role_binding.yaml
file. -
Specify either claimName (PVC) or storageClassName in the
es/deploy/crds/charts_v1_esoperator_cr.yaml
file.persistence: storageClassName: "" claimName: ""
-
To use claimName, PersistentVolume and PersistentVolumeClaim should be configured by using the following command.
PersistentVolume
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
PersistentVolumeClaim
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 file 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/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:mfp oc create -f es/deploy/operator.yaml
oc adm policy add-cluster-role-to-user cluster-admin system:serviceaccount:mfp: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
After the deployment is completed, Elasticsearch runs as an internal service and can be used by Persistent Mobile Foundation Analytics.
Note: If if Elasticsearch is deployed in a different namespace then Persistent Mobile Foundation Analytics. then while deploying Persistent Mobile Foundation Analytics, update esnamespace
in the charts_v1_esoperator_cr.yaml
with the project name where Elasticsearch is deployed.
Accessing PMF component consoles
Following are the endpoints for accessing the consoles of PMF components
PMF console | URL |
---|---|
PMF 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, a default random console password is generated, that can be obtained by using the following commands depending on the components you have chosen during the deployment.
oc get secret mf-mfpserver-consolesecret -o jsonpath='{.data.MFPF_ADMIN_PASSWORD}' | base64 -D
oc get secret mf-mfpanalytics-consolesecret -o jsonpath='{.data.MFPF_ANALYTICS_ADMIN_PASSWORD}' | base64 -D
oc get secret mf-mfpappcenter-consolesecret -o jsonpath='{.data.MFPF_APPCNTR_ADMIN_PASSWORD}' | base64 -D
You can override the default behaviour. For more details, refer Creating custom-defined console login secrets.
Uninstalling PMF on Cloud
Uninstall by using the following commands.
oc delete -f deploy/crds/charts_v1_mfoperator_cr.yaml
If the above command gets stuck, then run the following patch command.
oc patch crd/mfoperators.mf.ibm.com -p '{"metadata":{"finalizers":[]}}' --type=merge"
oc delete -f deploy/
oc delete -f deploy/crds/charts_v1_mfoperator_crd.yaml
Uninstall Elasticsearch by using the following command.
oc delete -f es/deploy/crds/charts_v1_esoperator_cr.yaml
If the above command gets stuck, then run the following patch command.
oc patch crd/esoperators.es.ibm.com -p '{"metadata":{"finalizers":[]}}' --type=merge"
oc delete -f es/deploy/
oc delete -f es/deploy/crds/charts_v1_esoperator_crd.yaml
Pushing PMF images to a private docker container registry (Optional)
To push PMF images to a private docker container registry, proceed as follows.
-
Unpack the PMF package into a work directory (for example,
mfoskpg
).mkdir mfospkg tar xzvf PMF-OpenShift-Pak-<version>.tar.gz -C mfospkg/
-
Load and push the images to the container registry from local machine by using the following commands with values as per your environment.
#!/bin/bash export CONTAINER_REGISTRY_URL="index.docker.io/persistentmobilefoundation" export OPERATOR_IMAGE_TAG="9.1.0" export IMAGE_TAG="9.1.0" cd images ls * | xargs -I{} docker load --input {} for file in * ; do docker tag ${file/.tar.gz/} ${CONTAINER_REGISTRY_URL}/${file/.tar.gz/} docker push ${CONTAINER_REGISTRY_URL}/${file/.tar.gz/} done for MF_IMAGE in "mfpf-server" "mfpf-analytics" "mfpf-push" "mfpf-analytics-recvr" "mfpf-liveupdate" "mfpf-appcenter" "mfpf-elasticsearch" "mf-operator" "es-operator" do docker manifest create ${CONTAINER_REGISTRY_URL}/${MF_IMAGE}:${OPERATOR_IMAGE_TAG} ${CONTAINER_REGISTRY_URL}/${MF_IMAGE}:${OPERATOR_IMAGE_TAG}-amd64 --amend --insecure docker manifest annotate ${CONTAINER_REGISTRY_URL}/${MF_IMAGE}:${IMAGE_TAG} ${CONTAINER_REGISTRY_URL}/${MF_IMAGE}:${IMAGE_TAG}-amd64 --os linux --arch amd64 docker manifest push ${CONTAINER_REGISTRY_URL}/${MF_IMAGE}:${IMAGE_TAG} --insecure done
Where,
CONTAINER_REGISTRY_URL
= Your private container registryOPERATOR_IMAGE_TAG
andIMAGE_TAG
= Downloaded PMF image version