Setup and Configure K4M

This section helps you in setting-up, configuring and launching VMware K4M.

Procedure

Modify files (Optional):
If VMware K4M has been installed under default location /opt, you may skip this step. Otherwise replace occurrence of /opt with the full path to the parent folder of your VMware K4M installation in the following files:
1. All scripts under VMWARE_K4M_HOME/scripts.
2. VMWARE_K4M_HOME/config/k4m-rest-application.properties
Configure system settings, download system and open-source packages:
Change to VMWARE_K4M_HOME/scripts. Run the script "step-1-as-root.sh" and follow prompts.

$ ./step-1-as-root.sh
This will:
1. Create the user k4m and give it ownership of the installation under VMWARE_K4M_HOME. The default password is "k4m”.
2. Download and install system packages including OpenJDK.
3. Configure SSHD.
4. Add the following entry into /etc/hosts file such that k4m01 refers to the localhost. k4m01 is referred in other scripts.
```
127.0.0.1 k4m01
```
  Note:
  1. On RHEL and CentOS 6.9 and 6.10, when the script finishes you will see the following. This can be ignored as necessary configuration is made by the OS by default../step-1-as-root.sh: line 64: sshd-keygen: command not found
  2. The script uses the yum command to install dependencies. Rarely, installation of some dependent system package may fail, because of the specific configuration of your OS. When something fails to install you can try these steps:
    
    Based on the error on your terminal, identify the dependency package. Open the script and note down the exact name and version.
    
    If using RHEL, ensure your host is subscribed to the Red Hat Subscription Service (refer to Red Hat documentation) so you can download the dependency. Then re-run the command to install the package as follows:$ yum install -y REQUIRED_PACKAGE_NAME
    
    Sometimes a package may fail to install due to another existing dependency's version. In that case update that existing package or even all your system software and then re-run the command to install the required dependency.
    $ yum update EXISTING_PACKAGE OR $ yum update
    
    then
    $ yum install -y REQUIRED_PACKAGE_NAME
  3. jq package manual installation:The jq package is installed in script "step-1-as-root.sh" as well using yum and can fail to install due to the reasons mentioned above in 2. If the steps to rectify mentioned above do not work, one should manually install the package as follows. Login as root and navigate to the /opt. There run the following:
    $ wget -O jq https://github.com/stedolan/jq/releases/download/jq-1.6/jq-linux64 $ chmod +x ./jq $ cp jq /usr/bin
    The jq package is used later in the automated health check script to verify that K4M is installed correctly.
Configure MongoDB [1]
Note: It is assumed that the reader is familiar with MongoDB administration.
1. Create a database “k4m-rest” and user “k4m” in your MongoDB instance. A script has been provided with the configuration viz. VMWARE_K4M_HOME/config/mongo-config.js as shown below:
```
db.createUser(
    {
        user: "k4m",
 
        pwd: "k4m",
 
        roles: [ { role: "readWrite", db: "k4m-rest" } ]
    }
)
```
  One may change the database name (db) and user name (user), and if you do so, you must follow the steps below to make corresponding changes in other places. Recommend to use the default settings. Change to VMWARE_K4M_HOME/config folder and run the MongoDB Admin command line tool to execute the script as shown below:
```
$ mongo --host MONGODB_HOST --port MONGODB_PORT --username ADMIN_USERNAME --password ADMIN_PASSWORD admin mongo-config.js
```
  where
  - MONGODB_HOST and MONGODB_PORT need to be specified only if your MongoDB instance is running on a remote host. If MongoDB is running locally then you don't need --host and --port options. Default host is localhost and port is 27017.
  - ADMIN_USERNAME and ADMIN_PASSWORD are your MongoDB instance administrative account credentials
  - The "admin" database is specified to store the user "k4m" being created.
  On running the above command machine displays:
```
MongoDB shell version v4.0.9
connecting to: mongodb://127.0.0.1:27017/admin?gssapiServiceName=mongodb
Implicit session: session { "id" : UUID("d1e1b971-12f0-4aa7-a12f-64236138785d") }
MongoDB server version: 4.0.9
Successfully added user: {
"user" : "k4m",
"roles" : [
{
"role" : "readWrite",
"db" : "k4m-rest"
}
]
}
```
  You can also verify by logging into the Mongo Shell, then switching to the admin database and listing the users as shown below. Notice that the k4m user is created in the admin db but has privileges for the k4m-rest db as it should be.
```
$ mongo HOST:PORT --username ADMIN_USERNAME --password ADMIN_PASSWORD
> use admin
switched to db admin
> show users
{
"_id" : "admin.admin",
"userId" : UUID("437b6bea-e8db-4d1d-b244-3464e75b682f"),
"user" : "admin",
"db" : "admin",
"roles" : [
{
"role" : "root",
"db" : "admin"
}
],
"mechanisms" : [
"SCRAM-SHA-1",
"SCRAM-SHA-256"
]
}
{
"_id" : "admin.k4m",
"userId" : UUID("c4ff7994-ba17-4709-927e-96c103cc814d"),
"user" : "k4m",
"db" : "admin",
"roles" : [
{
"role" : "readWrite",
"db" : "k4m-rest"
}
],
"mechanisms" : [
"SCRAM-SHA-1",
"SCRAM-SHA-256"
]
}
```
2. Modify the VMWARE_K4M_HOME/config/k4m-rest-application.properties file as follows:
  1. The database connection details should be updated according to your MongoDB instance's details. The K4M REST Service uses these details to connect to the KPI Configuration Store. The defaults are as follows:
```
spring.data.mongodb.uri=mongodb://k4m:k4m@k4m01:27017
spring.data.mongodb.database=k4m-rest
```
    where
    - k4m:k4m is the database user and password created in the step above. Recommend default.
    - k4m01 is the localhost. Replace only if your MongoDB is running remotely, with the remote host's IP address or hostname.
    - 27017 is the default port. Replace only if your MongoDB instance has a different port configured.
    - k4m-rest is the database created in the step above. Recommend default.
Install Flink and the K4M REST Service:
Become k4m user:
```
$ su k4m
```
Run the script "step-2-as-k4m.sh". This will:
1. Configure SSH keys
2. Download and install Flink. Flink is extracted into folder "flink-VERSION", created under the same directory that vmware-k4m is installed. By default, it is under /opt or the path specified by you when modifying the scripts in step 1 above. We will refer to this complete path as FLINK_HOME (also set as environment variable).
3. Install the K4M REST Service:
```
$ ./step-2-as-k4m.sh
```
Start the Flink cluster and K4M REST Service:
Run the script "step-3-as-k4m.sh”
```
$ ./step-3-as-k4m.sh
```