Setting Up MobileFirst Appcenter on IBM Cloud Kubernetes Cluster

improve this page | report issue

Overview

Follow the instructions below to configure a MobileFirst Application Center instance on IBM Cloud. To achieve this you will go through 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 Application Center 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

Refer to the IBM Cloud documentation to setup a Kubernetes Cluster on IBM Cloud.

Note: Kubernetes Cluster Type: Standard (paid cluster) is required for deploying Mobile Foundation.

Download the ibm-mfpf-container-8.0.0.0 archive

To set up MobileFirst Application Center 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.
Download the latest interim fix from Fix central. Kubernetes support is available from iFix 8.0.0.0-IF201708220656.

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

Image showing the file system structure of the archive file

bmx-kubernetes folder

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

Dockerfile-mfp-appcenter

  • Dockerfile-mfp-appcenter: Text document that contains all the commands that are necessary to build the MobileFirst Application Center image.
  • scripts folder: This folder contains the args folder, which contains a set of configuration files. It also contains scripts required to log into IBM Cloud, building a MobileFirst Application Center image and for pushing and running the image on IBM Cloud. You can choose to run the scripts interactively or by pre-configuring the configuration files, explained later. Other than the customizable args /*.properties files, do not modify any elements in this folder. For script usage help, use the -h or --help command-line arguments (for example, scriptname.sh --help).
  • usr-mfp-appcenter folder:
    • bin folder: Contains the script file (mfp-appcenter-init) that gets executed when the container starts. You can add your own custom code to be executed.
    • config folder: Contains the server configuration fragments (keystore, server properties, user registry) used by MobileFirst Application Center.
    • keystore.xml - the configuration of the repository of security certificates used for SSL encryption. The files listed must be referenced in the ./usr/security folder.
    • ltpa.xml - the configuration file defining the LTPA key and its password.
    • appcentersqldb.xml - JDBC Data source definition to connect to the DB2 or dashDB database.
    • registry.xml - user registry configuration. The basicRegistry (a basic XML-based user-registry configuration is provided as the default. User names and passwords can be configured for basicRegistry or you can configure ldapRegistry.
    • tracespec.xml - Trace specification to enable debugging as well as logging levels.
  • jre-security folder: You can update the JRE security-related files (truststore, policy JAR files, and so on) by placing them in this folder. The files in this folder get copied to the JAVA_HOME/jre/lib/security/ folder in the container.
  • security folder: used to store the key store, trust store, and the LTPA keys files (ltpa.keys).
  • env folder: Contains the environment properties used for server initialization (server.env) and custom JVM options (jvm.options).

  • Property Default Value Description
    APPCENTER_SERVER_HTTPPORT 9080* The port used for client HTTP requests. Use -1 to disable this port.
    APPCENTER_SERVER_HTTPSPORT 9443* The port used for client HTTP requests secured with SSL (HTTPS). Use -1 to disable this port.
    APPCENTER_ROOT applicationcenter The context root at which the MobileFirst Application Center Administration Services are made available.
    APPCENTER_CONSOLE_ROOT appcenterconsole The context root at which the MobileFirst Application Center console is made available.
    APPCENTER_ADMIN_GROUP appcenteradmingroup The name of the user group assigned the predefined role appcenteradmin.
    APPCENTER_USER_GROUP appcenterusergroup The name of the user group assigned the predefined role appcenteruser.

  • dependencies folder: Contains the Mobile Foundation runtime and IBM Java JRE 8.
  • mfpf-libs folder folder: Contains MobileFirst product component libraries and CLI.

Prerequisites

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

Setting Up the MobileFirst Application Center 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).

prepareappcenterdbs.properties

The MobileFirst Application Center requires an external DB2 on cloud instance.
Note: You can also use your own DB2 database. The IBM Cloud Kubernetes Cluster should be configured to connect to the database.
After you have set up your DB2 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).
    • DB2_HOST - hostname of your DB2 setup.
    • DB2_DATABASE - name of the database.
    • DB2_PORT - port on which you will connect to the database.
    • DB2_USERNAME - the DB2 database user ( the user should have the permissions to create Tables within the schema provided or if the schema does not already exist, the user should be able to create a schema )
    • DB2_PASSWORD - DB2 user's password.
  • Provide the following if you are using DB2 on Cloud (i.e DB_TYPE=dashDB).
    • APPCENTER_DB_SRV_NAME - Your dashDB service instance name for storing appcenter data.
  • APPCENTER_SCHEMA_NAME - Your schema name for appcenter data. The default is APPCNTR.
  • Note: If your DB2 database service instance is being shared by many users or by multiple MobileFirst Application Center deployments, make sure that you provide unique schema names.

prepareappcenter.properties

  • SERVER_IMAGE_TAG - A tag for the image. Should be of the form: registry-url/namespace/image:tag.
  • For example: registry.ng.bluemix.net/myuniquenamespace/myappcenter: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 MobileFirst Application Center on IBM Containers: Interactive Mode
    ./initenv.sh
    Non-interactive Mode
    ./initenv.sh args/initenv.properties
  2. prepareappcenterdbs.sh - Prepare the MobileFirst Application Center database
    The prepareappcenterdbs.sh script is used to configure your MobileFirst Application Center with the DB2 database service. The service instance of the DB2 service should be available in the Organization and Space that you logged in to in step 1. Run the following: Interactive Mode
    ./prepareappcenterdbs.sh
    Non-interactive Mode
    ./prepareappcenterdbs.sh args/prepareappcenterdbs.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. prepareappcenter.sh - Prepare a MobileFirst Application Center image
    Run the prepareappcenter.sh script in order to build the MobileFirst Application Center image 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
    ./prepareappcenter.sh
    Non-interactive Mode
    ./prepareappcenter.sh args/prepareappcenter.properties
  5. Deploy MobileFirst Application Center 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. 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.
    3. Create the Kubernetes deployments
      Edit the yaml file args/mfp-deployment-appcenter.yaml, and fill out the details. All the variables have to be substituted with their values before executing the kubectl command.
      ./args/mfp-deployment-appcenter.yaml contains the deployment for the following:
      • a kubernetes deployment for MobileFirst Application Center consisting of 1 instance (replica), of 1024MB memory and 1Core CPU.
      • a kubernetes service for MobileFirst Application Center.
      • an ingress for the whole setup including all the REST endpints for MobileFirst Application Center.
      • a configMap to make the environment variables available in the MobileFirst Application Center instance.
      Following values have to be edited in the YAML file:
      1. Different 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. registry.ng.bluemix.net/repository/mfpappcenter:latest - Use the same names that you used in prepareappcenter.sh to upload the image.
      Execute the following command:
      kubectl create -f ./args/mfp-deployment-appcenter.yaml
      Note:
      The following template yaml files are supplied:
      • mfp-deployment-appcenter.yaml: Deploys the MobileFirst Application Center with http.
      • mfp-deployment-appcenter-with-tls.yaml: Deploys the MobileFirst Application Center with https.
      After creation, to use the Kubernetes dashboard, execute the following command:
      kubectl proxy
      Open localhost:8001/ui, in your browser.

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. 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 mfp-deployment-appcenter.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 prepareappcenterdbs.sh script during the configuration of the MobileFirst Application Center image, the configurations and database tables required for MobileFirst Application Center 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 prepareappcenterdbs.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 prepareappcenterdbs.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