Deploy Metric Insights on OpenShift 3/4

OpenShift is Red Hat's version of Kubernetes. It is a viable option for container orchestration, especially if your organization already has a Red Hat subscription.

PREREQUISITES:

The following topics are covered in this article:

  1. Understanding the Metric Insights Application Architecture in OpenShift
  2. Create a Project for the Metric Insights Application in the OpenShift Container Platform
  3. Configure the Storage Class for Persistent Volumes
  4. Obtain Docker Registry Credentials
  5. Generate the Deployment Files for the Metric Insights
  6. Create Secrets Files for Each MI Service
  7. Create & Upload Secrets for Each MI Service
  8. Deploy the Metric Insights Application
  9. Check if the Application Has Been Deployed
  10. Create Routes for the Web Service and the Monitoring Service
  11. Basic Console Commands

For non-orchestrated environments, see the help article on using Simple Installer.

Starting v6.4.1. services inside containers are run by one unprivileged user. The ownership for the network shared volume must be manually set to www-data, uid: 33 before updating to v6.4.1.

1. Understanding the Metric Insights Application Architecture in OpenShift

Below is an architectural diagram of Metric Insights deployed in OpenShift. A namespace is a virtual cluster that consists of several Nodes (servers). The nodes host Pods which is essentially a Container. Metric Insights consists of services that run inside their own container, rooted to a shared file system for persistence. 

The deployment scheme consists of the following services deployed in individual pods (1 service per pod):

Required services:

  1. Web Master  
  2. Web Slave replicas
  3. Data Analyzer    
  4. Data Processor  
  5. Seed   
  6. Monitoring

 Additional items of note:

  • A minimum of 3 Nodes are required for automatic failover
  • MySQL is required to host the Metric Insights application database, and it should run on a remote server
  • Persistent storage is required for the shared file system
  • Web Master and Slave listen to HTTP/HTTPS traffic on different ports (forwarded from standard ports 80/443)
    • Web Master = 6080/6443
    • Web Slave = 7080/7443

2. Create a Project for the Metric Insights Application in the OpenShift Container Platform

  1. [+ Create Project]
  2. Fill in the fields
  3. [Create]

3. Configure the Storage Class for Persistent Volumes

The Openshift 3 deployment supports only NFS type for the application file system, which is shared across pods as persistent volumes.

In /etc/exports, set the mounted share to /opt/mi with the following options:

/opt/mi <worker_ip>(rw,fsid=1,crossmnt,no_subtree_check,no_root_squash,async)

4. Obtain Docker Registry Credentials

Contact Metric Insights Support for access to the official Metric Insights Docker Registry. Credentials are required for pulling Docker images for each Metric Insights service.

The Metric Insights Docker Registry address (docker.metricinsights.com) is specified in the deployment configuration file.

5. Generate the Deployment Files for the Metric Insights

It is possible to:

Generate the Deployment File by the Installer

Depending on the deployment type, replace <deployment_type>  in the commands described below with the following values:

  • OpenShift 3:  <deployment_type>  -> openshift3
  • OpenShift 4:  <deployment_type> -> k8s
  • If the remote database server has the same timezone as the Metric Insights application, run ./installer.py kubernetes --type <deployment_type> --storage-class nfs --nfs-server-address <nfs.example.com> --ingress-controller-type nginx --hostname <MI_hostname> --dp-hostname <dataprocessor_hostname> --registry <registry_url> --timezone <MI_app_timezone> -o <deployment_file>.yml
  • If the remote database server has a different timezone than the Metric Insights application,  use ./installer.py kubernetes --type <deployment_type> --storage-class nfs --nfs-server-address <nfs.example.com> --ingress-controller-type nginx --hostname <MI_hostname> --dp-hostname <dataprocessor_hostname> --registry <registry_url> --timezone <MI_app_timezone> --mysql-timezone <remote_database_server_timezone> -o <deployment_file>.yml

Use ./installer.py kubernetes -h for more options. See Basic Console Commands section for details.

Generate the Deployment Files by the Installation Wizard

To generate the set of files required for the Metric Insights deployment, refer to Generate the Deployment Files by the Installation Wizard article.

6. Create Secrets Files for Each MI Service

This step is required only in case you have generated the deployment file by the Installer.

There are template files for creating secrets files for each service in MetricInsights-Installer-v6.x.x-Full/utils/orchestration/kubernetes/secrets/:

File Template  Description 
data-analyzer.env.j2
 Template file for creating the secret file for Data Analyzer Service container.
dataprocessor.env.j2
 Template file for creating the secret file for Data Processor Service container.
monitoring.env.j2
 Template file for creating the secret file for Monitoring Service container.
mysql.secret.j2
 Template file for creating the secret file for MySQL Service container.
seed.env.j2
 Template file for creating the secret file for Seed Service container.
web.env.j2
 Template file for creating the secret file for Web Service container.

It is required to create the secrets files from the templates:

  1. Copy each template file without .j2 extension from the installer directory to desired directory.
  2. Open each file in an editor and customize all variables. Ensure passwords are consistent between files. You can encode passwords of our choice or create random passwords:
    • to encode, run echo -n '<password>' | base64
    • to generate a random password, use openssl rand -base64 8 | tr -d /=+ | cut -c -11

7. Create & Upload Secrets for Each MI Service

It is possible to:

Create Secrets Using the Command Line

After running all the commands below, all the secrets will be automatically created in the OpenShift Container Platform.

1. Create the secret for MySQL Service container:

oc create secret generic --namespace <namespace> metricinsights-mysql-root-password --from-file mysql.secret

2. Create the secret for Data Analyzer Service container:

oc create secret generic --namespace <namespace> metricinsights-data-analyzer --from-file data-analyzer.env

3. Create the secret for the Web Service container:

oc create secret generic --namespace <namespace> metricinsights-web --from-file web.env

4. Create the secret for Seed Service container:

oc create secret generic --namespace <namespace> metricinsights-seed --from-file seed.env

5. Create the secret for Data Processor Service container:

oc create secret generic --namespace <namespace> metricinsights-dataprocessor --from-file dataprocessor.env

6. Create the secret for the Monitoring Service container:

oc create secret generic --namespace <namespace> metricinsights-monitoring --from-file monitoring.env

7. Create the secret to pull the Docker image:

oc create secret docker-registry --namespace <namespace> metricinsights-secret --docker-server <docker_server_address> --docker-username <docker_username> --docker-password <docker_password> --docker-email <email_address>

Create Secrets Using the OpenShift Container Platform

Secret is an object for storing and managing sensitive information like passwords and OAuth tokens. Before deploying to OpenShift 3/4, Docker Registry credentials must be registered as the Secret for K8s to reference. Metric Insights uses a secret labeled docker-registry to authenticate in Docker Registry to pull the images.

7.1. Access the Created Project for Metric Insights Application

  1. Click the project

7.2. Access Resources > Secrets

7.3. Create the Secret to Pull the Docker Image

  1. [Create Secret]
  2. Fill in the fields
  3. [Create]

7.4. Create the Secrets for the Metric Insights Services

The screenshot displays an example on how the fields must be filled to create the secret for Data Analyzer Service (data-analyzer.env). Proceed the steps below to create the secrets for remaining services: Web, Data Processor, Seed, Monitoring, MySQL.

  1. Select Generic Secret from Secret Type drop-down menu
  2. Enter a unique secret name
  3. Enter a unique key for the secret
  4. To upload a file template, click [Browse]
  5. If you have uploaded the file template, you do not need to copy and paste its content to the field

8. Deploy the Metric Insights Application

It is possible to:

Deploy the Application Using the OpenShift Container Platform

8.1. Access Add to Project > Import YAML / JSON

8.2. Upload the Deployment File  

  1. To upload the deployment file, click [Browse].
  2. Optionally, copy and paste the YAML file content in the field. This step is appropriate if you have not uploaded it using [Browse]
  3. [Create]

8.3. Deploy the Metric Insights Application

  1. [Continue]
  2. [Create]

8.4. Confirm the Deployment of the Metric Insights Application

  1. [Create Anyway]

8.5. Finish the Deployment of the Metric Insights Application

  1. The confirmation message must be visible
  2. [Close]
Deploy the Application Using the Command Line

To deploy the application, apply the deployment file: 

oc --namespace <namespace> apply -f <deployment_file>.yml

If <deployment_file>.yml is updated, run the following command to apply the changes: 

$ oc process -f <deployment_file>.yml | oc apply -f - 
service/metricinsights-web unchanged 
deployment.apps/metricinsights-web-master unchanged 
deployment.apps/metricinsights-web-slave unchanged 
service/metricinsights-seed unchanged 
deployment.apps/metricinsights-seed unchanged 
service/metricinsights-dataprocessor unchanged 
deployment.apps/metricinsights-dataprocessor unchanged 
service/metricinsights-data-analyzer unchanged 
deployment.apps/metricinsights-data-analyzer unchanged 
service/metricinsights-monitoring unchanged 
deployment.apps/metricinsights-monitoring unchanged 
persistentvolume/metricinsights-default-data configured 
persistentvolumeclaim/metricinsights-default-data unchanged

9. Check if the Application Has Been Deployed

To check if the application has been deployed, run oc get pods -n <namespace>.

10. Create Routes for the Web Service and the Monitoring Service

10.1. Access the Routes Creation Form  

  1. Click Networking
  2. Click Routes
  3. [Create Route]

10.2. Fill in the Routes Creation Form

  1. Enter a name for the Web Service/the Monitoring Service within the project
  2. Enter a hostname for the Web Service/the Monitoring Service within the project
  3. Select the pod of the Web Service/the Monitoring Service from the drop-down menu
  4. After you select the pod, the drop-down menu becomes active. For the Web Service, select "443 -> 443 (TCP)". For the Monitoring Service, select "8081 -> 8081 (TCP)"
  5. Tick the checkbox

10.3. Apply the Valid Certificate and Private Key for the Web Service and the Monitoring Service

  1. Select "Re-encrypt" from TLS Termination drop-down menu
  2. Select "Redirect" from Insecure Traffic drop-down menu
  3. Click [Browse] to select the certificate in PEM format
  4. Click [Browse] to select the Private Key
  5. Click [Browse] to select the CA certificate
  6. [Browse] to select ca.crt certificate. You can retrieve the certificate from the web pod: /opt/mi/ssl/ca.crt.

10.4. Create and Check the Routes

Click [Create] at the bottom. To check the routes, open the Web Service and the Monitoring Service hostnames in a browser. You will see the login pages.

11. Basic Console Commands

Basic console commands can be checked by running ./installer.py kubernetes --help .

The following list of utilities are available to use on the host.

Note, all of these tools become available only if the Web Component is installed.

Optional Parameters
--registry REGISTRY Docker registry URL, that will be used for deploying MI components. Example: <hostname> or <hostname>:<port>. (default: None)
--hostname HOSTNAME Web service additional hostname (default: None). The option is used to assign 127.0.0.1 to the Web container. It helps the Metric Insights application to interact with its internal components faster inside the container.