Setting Up MobileFirst Server on IBM Cloud Kubernetes Cluster

improve this page | report issue

Overview

This tutorial demonstrates how to take a locally developed IBM MobileFirst Platform Foundation project and run it on IBM Cloud on a Kubernetes Cluster. To achieve this, complete the following steps:

  • Create a Kubernetes Cluster of type: Standard (paid cluster).
  • Setup your host computer with the required tools (Docker, Cloud Foundry CLI ( cf ), IBM Cloud CLI ( bx ), Container Service Plugin for IBM Cloud CLI ( bx cs ), Container Registry Plugin for IBM Cloud CLI ( bx cr ), Kubernetes CLI (kubectl)).
  • Build a MobileFirst Server Docker image and push it to the IBM Cloud repository.
  • Finally, you will run the Docker image on a Kubernetes Cluster.

Note:

  • Windows OS is currently not supported for running these scripts.
  • The MobileFirst Server Configuration tools cannot be used for deployments to IBM Containers.

Jump to:

Register an account on IBM Cloud

If you do not have an account yet, visit the IBM Cloud website and click Get Started Free or Sign Up. You need to fill up a registration form before you can move on to the next step.

IBM Cloud Dashboard

After signing in to IBM Cloud, you are presented with the IBM Cloud Dashboard, which provides an overview of the active IBM Cloud space. By default, this work area receives the name dev. You can create multiple work areas/spaces if needed.

Set up your host machine

To manage containers and images, you need to install the following tools:

  • Docker
  • IBM Cloud CLI (bx)
  • Container Service Plugin for IBM Cloud CLI ( bx cs )
  • Container Registry Plugin for IBM Cloud CLI ( bx cr )
  • Kubernetes CLI (kubectl)

Refer to the IBM Cloud documentation for steps to setup the prerequisite CLIs.

Create and setup a Kubernetes Cluster with IBM Cloud Container Service

Follow the steps in the IBM Cloud documentation to setup a Kubernetes Cluster on IBM Cloud.

Note: Paid Kubernetes Cluster Type is required for deploying Mobile Foundation.

Download the ibm-mfpf-container-7.1.0.0 archive

To set up Mobile Foundation as a Kubernetes Cluster using IBM Cloud containers, you must first create an image that will later be pushed to IBM Cloud.
Interim fixes for the MobileFirst Server on IBM Containers can be obtained from the IBM Fix Central.
The latest iFix from Fix Central has support for deploying Mobile Foundation to Kubernetes Cluster. Download the latest interim fix from Fix central by searching for IBM MobileFirst Platform Foundation and version 7.1.0.0.

The archive file contains the files for building an image (dependencies and mfpf-libs) and the files for building and deploying a MobileFirst Server and MobileFirst Analytics on Kubernetes (bmx-kubenetes).

The extracted ZIP file contains the files for building an image (dependencies and mfpf-libs), the files for building and deploying an IBM MobileFirst Foundation Operational Analytics Container (bmx-kubernetes/usr-mfpf-analytics),and the files for configuring an IBM MobileFirst Foundation Server Container (bmx-kubernetes/usr-mfpf-server).

bmx-kubernetes folder

Contains the customization files and scripts required to deploy to a Kubernetes Cluster with IBM Cloud Container Service.

  • Dockerfile-mfpf-server: Text document that contains all the commands that are necessary to build the MobileFirst Server image.
  • Dockerfile-mfpf-analytics: Text document that contains all the commands that are necessary to build the MobileFirst Analytics image.
  • usr-mfpf-server folder:
    • bin folder: Contains the script file that gets executed when the container starts. You can add your own custom code to be executed.
    • config folder: Contains server key store configuration, user registry configuration, and MobileFirst Platform Foundation server properties (which includes runtime configuration, analytics, attribute store etc).
    • env folder: Contains server environment configuration (ports, application root names etc).
    • jre-security folder: You can update the JRE security related files (truststore, policy jars etc) by placing them in this folder
    • projects folder: The location of your MobileFirst Platform Foundation project runtime (.war file). You will place the project runtime files here.
    • security folder: The key store, trust store and the LTPA keys files (ltpa.keys) should be placed here.
    • wxs folder: Contains the data cache/extreme scale client library when Data Cache is used as attribute store for the server.
  • usr-mfpf-analytics folder:
    • bin folder: Contains the script file that gets executed when the container starts. You can add your own custom code to be executed.
    • config folder: Contains server key store configuration, user registry configuration, and MobileFirst Platform Foundation server properties (which includes runtime configuration, analytics, attribute store etc).
    • env folder: Contains server environment configuration (ports, application root names etc).
    • jre-security folder: You can update the JRE security related files (truststore, policy jars etc) by placing them in this folder
    • security folder: The key store, trust store and the LTPA keys files (ltpa.keys) should be placed here.
  • scripts folder: This folder contains the scripts required to log into IBM Cloud, build a MobileFirst Server image, deploy the project runtime and to push and run the image on IBM Cloud. This folder also contains the args folder, which contains a set of configuration and yaml files for deploying the uploaded images to Kubernetes Cluster.


Prerequisites

You need to have a working knowledge of Kubernetes. Refer to Kubernetes docs, to learn more.

We will use the IBM Container registry to upload the Docker images. If you have not already done so, you need to create your own private namespace in the container registry. The namespace is a unique name to identify your private repository on the IBM Cloud registry. Choose a namespace according to following rules:

  • It can contain only lowercase letters, numbers, or underscores (_).
  • It can be 4 - 30 characters. If you plan to manage containers from the command line, you might prefer to have a short namespace that can be typed quickly.
  • It must be unique in the IBM Cloud registry.

To set a namespace, run the command:

bx cr namespace-add new_name

To get namespaces that you have reserved in your account, run the command:

bx cr namespace-list

As we will see further in this tutorial, the eventual Docker images that you will upload will be of the format registry-prefix/namespace/image-name:tag. (For example: registry.ng.bluemix.net/mymfpnamespace/mymfp71server:v1)

Create an IBM MobileFirst Platform Foundation project

Create a new MobileFirst project or use an existing one. You can find tutorials on how to create a new project, and their associated sample projects, in the Getting Started with Foundation page.

Setting Up the MobileFirst and Analytics Servers on Kubernetes Cluster with IBM Containers

As explained above, you can choose to run the scripts interactively or by using the configuration files:

  • Using the configuration files - run the scripts and pass the respective configuration file as an argument.
  • Interactively - run the scripts without any arguments.

Note: If you choose to run the scripts interactively, you can skip the configuration, but it is strongly suggested to read and understand the arguments that you will need to provide.

When you run interactively, a copy of the arguments provided is saved in a directory: ./recorded-args/. So you can use the interactive mode for the first time and reuse the property files as a reference for future deployments.

The args folder contains a set of configuration files which contain the arguments that are required to run the scripts. Fill in the argument values in the following files:

initenv.properties

  • IBM_CLOUD_API_URL - The geo or region where you want your deployment.
    For example: api.ng.bluemix.net for US region or api.eu-de.bluemix.net for Germany or api.au-syd.bluemix.net for Sydney
  • IBM_CLOUD_ACCOUNT_ID - Your account id, which is an alpha-numeric value such as a1b1b111d11e1a11d1fa1cc999999999
    Use the command bx target to get the Account id.
  • IBM_CLOUD_USER - Your IBM Cloud username (email).
  • IBM_CLOUD_PASSWORD - Your IBM Cloud password.
  • IBM_CLOUD_ORG - Your IBM Cloud organization name.
  • IBM_CLOUD_SPACE - Your IBM Cloud space (as explained previously).

prepareserverdbs.properties

The Mobile Foundation service requires an external DB2 on cloud instance.
After you have set up your DB2 on Cloud instance, provide the required arguments:
  • DB_TYPE - dashDB ( if you are using DB2 on Cloud ) or DB2 if you are using your own DB2 database.
  • Provide the following if you are using your own DB2 database (i.e. DB_TYPE=DB2).
    • DB_SRV_NAME - the dashDB service instance name for storing admin data.
    • ADMIN_SCHEMA_NAME - the schema name for admin data. The default is MFPDATA.
    • RUNTIME_ NAME - name of the MobileFirst Project Runtime. If you keep it empty, the script prepareserverdbs.sh will configure the MFP Admin database.
    • SCHEMA_NAME - the schema name for runtime data. The default is name of the MobileFirst Project runtime
  • Note: If your DB2 database service instance is being shared by many users or by multiple Mobile Foundation deployments, make sure that you provide unique schema names.

prepareserver.properties

  • SERVER_IMAGE_TAG - A tag for the image. Should be of the form: registry-url/namespace/image:tag.
  • PROJECT_LOC (Optional) - This argument allows you to directly supply your Eclipse project location. This is an alternative to dropping the MobileFirst Project runtime .war in the usr-mfpf-server/projects/ folder. Mutiple projects can be delimited by comma.
  • ANALYTICS_IMAGE_TAG - A tag for the image. Should be of the form: registry-url/namespace/image:tag.
  • For example: registry.ng.bluemix.net/myuniquenamespace/mymfpserver:v1
    If you have not yet created a docker registry namespace, create the registry namespace using one of these commands:
    • bx cr namespace-add myuniquenamespace
    • bx cr namespace-list

The following instructions demonstrate how to run the scripts by using the configuration files. A list of command-line arguments is also available should you choose to in a non-interactive mode:

  1. initenv.sh – Logging in to IBM Cloud
    Run the initenv.sh script to create an environment for building and running Mobile Foundation on IBM Containers: Interactive Mode
    ./initenv.sh
    Non-interactive Mode
    ./initenv.sh args/initenv.properties
  2. prepareserverdbs.sh - Prepare the MobileFirst Server database
    The prepareserverdbs.sh script is used to configure your MobileFirst project database with the DB2 on Cloud service. You will need to run it separately, once for the admin database and once for every MobileFirst project runtime database. The service instance of the dashDB service should be available in the Organization and Space that you logged in to in step 1. Run the following: Interactive Mode For the admin database run the following once for the admin database (provide an empty value for the Runtime name) and then once for each MobileFirst runtime.
    ./prepareserverdbs.sh
    Non-interactive Mode For the admin database make sure to comment out the RUNTIME_NAME argument and run:
    ./prepareserverdbs.sh args/prepareserverdbs.properties
    For each MobileFirst project runtime database - first uncomment the project RUNTIME_NAME argument, change its value to match the specific project war file and run:
    ./prepareserverdbs.sh args/prepareserverdbs.properties
  3. initenv.sh(Optional) – Logging in to IBM Cloud
    This step is required only if you need to create your containers in a different Organization and Space than where the DB2 service instance is available. If yes, then update the initenv.properties with the new Organization and Space where the containers have to be created (and started), and rerun the initenv.sh script:
    ./initenv.sh args/initenv.properties
  4. prepareserver.sh - Prepare the MobileFirst Server and MobileFirst Analytics images
    Run the prepareserver.sh script in order to build the MobileFirst Server and MobileFirst Analytics images and push it to your IBM Cloud repository. To view all available images in your IBM Cloud repository, run: bx cr image-list
    The list contains the image name, date of creation, and ID.
    Interactive Mode
    ./prepareserver.sh
    Non-interactive Mode
    ./prepareserver.sh args/prepareserver.properties
  5. Deploy MobileFirst Server and MobileFirst Analytics on Docker containers on a Kubernetes cluster using IBM Cloud Container Service.
    1. Set your terminal context to your cluster
      bx cs cluster-config my-cluster
      To know your Cluster name, run the following command:
      bx cs clusters
      In the output, the path to your configuration file is displayed as a command to set an environment variable, for example:
      export KUBECONFIG=/Users/ibm/.bluemix/plugins/container-service/clusters/my-cluster/kube-config-prod-dal12-my-cluster.yml
      Copy and paste the command above, after replacing my-cluster with your Cluster name, to set the environment variable in your terminal and press Enter.
    2. [Mandatory for MobileFirst Analytics]: Create a Persistent Volume Claim. This will be used to persist analytics data. This is a one time step. You can reuse the PVC if you have already created it prior. Edit the yaml file args/mfpf-persistent-volume-claim.yaml and then run the command. All the variables have to be substituted with their values before executing the following kubectl command.
      kubectl create -f ./args/mfpf-persistent-volume-claim.yaml
      Note down the name of the Persistent Volume Claim, as you have to provide it in the subsequent step.
    3. To get your Ingress domain run the following command:
      bx cs cluster-get my-cluster
      Note down your Ingress domain. If you need to configure TLS, note down the Ingress secret.
    4. Create the Kubernetes deployments
      Edit the yaml file args/mfpf-deployment-all.yaml, and fill out the details. All the variables have to be substituted with their values before executing the kubectl command.
      ./args/mfpf-deployment-all.yaml contains the deployment for the following:
      • a kubernetes deployment for MobileFirst Server consisting of 3 instances (replicas), of 2048MB memory and 1Core CPU.
      • a kubernetes deployment for MobileFirst Analytics consisting of 2 instances (replicas), of 2048MB memory and 1Core CPU.
      • a kubernetes service for MobileFirst Server.
      • a kubernetes service for MobileFirst Analytics.
      • an ingress for the whole setup including all the REST endpints for MobileFirst Server and MobileFirst Analytics.
      • a configMap to make the environment variables available in the MobileFirst Server and MobileFirst Analytics instances.
      Following values have to be edited in the YAML file:
      1. Cluster End point: All occurences of my-cluster.us-south.containers.mybluemix.net with the output of Ingress Domain from the output of bx cs cluster-get command as stated above.
      2. Project path in the Ingress: This is the path that will be exposed via the Ingres. You have to create an entry for each MobileFirst runtime here
      3. Image name: registry.ng.bluemix.net/repository/mfpfanalytics:latest and registry.ng.bluemix.net/repository/mfpfserver:latest - Use the same names that you used in prepareserver.sh to upload the images.
      4. claimName: mfppvc - Use the name Persistent Volume Claim name as you have used above to create the PVC.
      Execute the following command:
      kubectl create -f ./args/mfpf-deployment-all.yaml
      Note:
      The following template yaml files are supplied:
      • mfpf-deployment-all.yaml: Deploys the MobileFirst Server and the MobileFirst Analytics with http.
      • mfpf-deployment-all-tls.yaml: Deploys the MobileFirst Server and the MobileFirst Analytics with https.
      • mfpf-deployment-server.yaml: Deploys the MobileFirst Server with http.
      • mfpf-deployment-analytics.yaml: Deploys the MobileFirst Analytics with http.
      • mfpf-ingress.yaml: Creates just the ingress definition for MFP.

      Non-production deployment using Lite Cluster

      If you have a Lite cluster, then you can use the following yaml files.

      • mfpf-deployment-lite-server.yaml: Deploys the MobileFirst Server meant for a Lite Cluster.
      • mfpf-deployment-lite-analytics.yaml: Deploys the MobileFirst Analytics meant for a Lite Cluster.

      Lite clusters do not come with Persistent volume and Ingress. Lite Cluster will use the NodePort based deployment (Worker node, Public IP and Kubernetes Service Port ) instead of Ingress. Since Persistent volumes are not available for Lite cluster, Analytics data cannot be persisted across deployments.

  6. After creation, to use the Kubernetes dashboard, execute the following command:
    kubectl proxy
    Open localhost:8001/ui, in your browser.

With MobileFirst Server running on IBM Cloud, you can now start your application development. Review the Mobile Foundation tutorials.

Applying MobileFirst Server Fixes

Interim fixes for the MobileFirst Server on IBM Containers can be obtained from IBM Fix Central.
Before you apply an interim fix, back up your existing configuration files. The configuration files are located in the the following folders:

  • MobileFirst Analytics: package_root/bmx-kubernetes/usr-mfpf-analytics
  • MobileFirst Server Liberty Cloud Foundry Application: package_root/bmx-kubernetes/usr-mfpf-server

Steps to apply the iFix:

  1. Download the interim fix archive and extract the contents to your existing installation folder, overwriting the existing files.
  2. Restore your backed-up configuration files into the package_root/bmx-kubernetes/usr-mfpf-server and package_root/bmx-kubernetes/usr-mfpf-analytics folders, overwriting the newly installed configuration files.
  3. You can now build and deploy the updated server.

    a. Run the prepareserver.sh script to rebuild the server image and push it to the IBM Containers service.

    b. Run the kubectl create –f my-deployment-yaml to deploy MobileFirst Server and MobileFirst Analytics to the Kubernetes Cluster.

    You can also do a rolling update by running the command: kubectl rolling-update NAME -f FILE

Removing the Container from IBM Cloud

When you remove a container from IBM Cloud, you must also remove the image name from the registry.

Run the following commands to remove a container from IBM Cloud:

  1. kubectl get pods –o wide (Lists the kubernetes pods currently running)
  2. kubectl describe pod <pod-name> (Get details of each running pod)
  3. kubectl delete –f <FILE> (Deletes all the kubernetes resources defined in the FILE)

Run the following commands to remove a container from IBM Cloud:

  1. cf ic ps (Lists the containers currently running)
  2. cf ic stop <container_id> (Stops the container)
  3. cf ic rm <container_id> (Removes the container)

Run the following cf ic commands to remove an image name from the IBM Cloud registry:

  1. cf ic images (Lists the images in the registry)
  2. cf ic rmi <image_id> (Removes the image from the registry)

Removing the Kubernetes deployments from IBM Cloud

Run the following commands to remove your deployed instances from IBM Cloud Kubernetes cluster:

kubectl delete -f mfpf-deployment-all.yaml ( Removes all the kubernetes types defined in the yaml )

Run the following commands to remove image name from the IBM Cloud registry:

bx cr image-list (Lists the images in the registry)
bx cr image-rm <image-name> (Removes the image from the registry)

Removing the database service configuration from IBM Cloud

If you ran the prepareserverdbs.sh script during the configuration of the MobileFirst Server image, the configurations and database tables required for MobileFirst Server are created. This script also creates the database schema for the container.

To remove the database service configuration from IBM Cloud, perform the following procedure using IBM Cloud dashboard.

  1. From the IBM Cloud dashboard, select the DB2 on cloud service you have used. Choose the DB2 service name that you had provided as parameter while running the prepareserverdbs.sh script.
  2. Launch the DB2 console to work with the schemas and database objects of the selected DB2 service instance.
  3. Select the schemas related to IBM MobileFirst Server configuration. The schema names are ones that you have provided as parameters while running the prepareserverdbs.sh script.
  4. Delete each of the schema after carefully inspecting the schema names and the objects under them. The database configurations are removed from IBM Cloud.
Last modified on December 12, 2017