Skip to content

Latest commit

 

History

History
252 lines (154 loc) · 8.15 KB

04_03_rhoar_vertx_configmap_openshift_Lab.adoc

File metadata and controls

252 lines (154 loc) · 8.15 KB
Raw

Red Hat OpenShift Application Runtimes - Vert.x ConfigMap lab

Table of Contents

In this lab you will learn how to develop a Vert.x project that uses ConfigMaps. This lab provides a basic example of using ConfigMap to take advantage of external configuration sources. This lab shows you how to:

  • Setup and configuration of ConfigMap.

  • Use the configuration provided by ConfigMap within an application.

  • Deploy changes to ConfigMap to applications that are already running.

You will also deploy this project to the OpenShift Container Platform.

Requirements

  • Knowledge of OpenShift concepts

About ConfigMap

ConfigMap is an object used by OpenShift to inject configuration data as simple key and value pairs into one or more Linux containers while keeping the those containers agnostic of Openshift. You can create a ConfigMap object in a variety of different ways, including using a YAML file, and inject it into the Linux container. You can find more information about ConfigMap in the OpenShift documentation.

Why is ConfigMap Important?

It is important for an application’s configuration to be externalized and separate from it’s code. This allows for the application’s configuration to change as it moves through different environments while leaving the code unchanged. This also keeps sensitive or internal information out of your codebase and version control. Many languages and application servers provide environment variables to support externalizing an application’s configuration. Microservices and Linux containers increase the complexity of this by adding pods, or groups of containers representing a deployment, and polyglot environments. ConfigMap enables application configuration to be externalized and used in individual Linux containers and pods in a language agnostic way. ConfigMap also allows sets of configuration data to be easily grouped and scaled, which enables you to configure an arbitrarily large number of environments beyond the basic Dev, Stage, and Production.

1. Find lab3 project files

Each lab in this course is housed in separate directories. Using the command line, find and observe the files for this lab:

cd $HOME/vert.x/lab3
Important
 Be sure to replace $HOME with the directory you chose to put the content in previous labs.

2. Open lab3 using the IDE

  • Use your favorite IDE and open the project files for lab3 (maven project).

Once loaded, you should see the lab files and be able to navigate amongst the files. The components of this first project are laid out in different subdirectories according to Maven best practices:

  • pom.xml - The Maven project file

  • app-config.yml - ConfigMap property file

  • src/main/java - The source code to the project

  • src/main/resources - The static resource files referenced in the code

3. View the ConfigMap property file

  • In your IDE, open the file: app-config.yml

message : "Hello, %s from a ConfigMap !"
level : INFO

This is a properties file that defines properties for a message and level. Our Vert.x app will use these values for configuration.

4. Review code for our HTTP verticle

This verticle returns a hello world message, based on information from the ConfigMap. It also configures the logger level based on ConfigMap info.

  • In your IDE, open the file: src/main/java/io.openshift.booster/HttpApplication.java

  • Review the contents of this file

  • The start method does the following:

    • Sets up the configuration - gets a handle to the config map

    • Creates router endpoints for the service

    • Retrieves the message template from the config map

    • Creates a timer to fire every two seconds to refresh the config map

  • The setLoggerLevel method sets the level based on info from the config map

  • The greeting method returns a JSON greeting based on info from config map

  • The remaining methods retrieveMessageTemplateFromConfiguration and setUpConfiguration are self-explanatory.

4.1. Review Maven POM file

  1. Review the pom.xml file, more specifically the configuration of the Fabric8 Vert.x plugin

    • The vert.x:package goal is attached to the package maven goal

    • The main verticle is set as a property vertx.verticle in the pom file.

  2. Build the application with maven. From the command line:

    $ mvn clean package

5. Login to OpenShift via the CLI

  • If you are not logged into OpenShift, do so now:

$ oc login ${YOUR-OPENSHIFT-SERVER} -u USER -p PASS

Replace ${YOUR-OPENSHIFT-SERVER} with the server name for your training environment. Be sure to replace USER and PASS with your supplied credentials and accept any security exceptions (which is never a good idea in a production scenario, but is fine for this lab).

You should get a Login successful message indicating you’ve successfully logged in.

6. Create a new project

OpenShift separates different projects using the concept of a project (also known as a Kubernetes Namespace).

To house your project and keep it separate from other users, create a new project using your username as part of the project:

  • Create a new project

$ oc new-project configmap-demo-userXX

Be sure to replace userXX with your username.

  • Add a policy for the project

$ oc policy add-role-to-user view -n $(oc project -q) -z default

7. Deploy your ConfigMap configuration to OpenShift

  • Deploy your configuration to OpenShift

$ oc create configmap app-config --from-file=app-config.yml

  • Verify your ConfigMap configuration has been deployed.

$ oc get configmap app-config -o yaml

You should see the following output

apiVersion: v1
data:
  app-config.yml: |-
      message : "Hello, %s from a ConfigMap !"
      level : INFO
...

8. Build and Deploy service to OpenShift

It’s time to build and deploy our service! To build and deploy:

$ mvn clean fabric8:deploy -Popenshift

  • Check the status of the deployment in the OpenShift Web console, or using the CLI.

$ oc get pods
NAME                             READY     STATUS      RESTARTS   AGE
configmap-demo-1-m73d5       1/1       Running     0          30s

  • Check the log of application pod to make sure that the application did start up correctly:

$ oc logs -f configmap-demo-1-m73d5
Starting the Java application using /opt/run-java/run-java.sh ...
...
Aug 03, 2017 8:20:51 PM io.vertx.core.impl.launcher.commands.VertxIsolatedDeployer
INFO: Succeeded in deploying verticle

8.1. Testing the application

You can test the application using curl.

  • To exercise the application from outside of OpenShift, first discover the external hostname:

$ oc get routes

The hostname of the service will be different depending on your cluster, but in this example the hostname is configmap-demo-user30.apps.83de.openshift.opentlc.com.

  • To test the endpoint, use the following curl command

$ curl $YOUR-APP-URL/api/greeting
{"content":"Hello, World from a ConfigMap !"}

Be sure to replace $YOUR-APP-URL with your actual hostname from the oc get routes command.

9. Update the deployed ConfigMap

  • Update your ConfigMap configuration.

$ oc edit configmap app-config

  • Change the value for the message key to Bonjour, %s from a ConfigMap ! and save the file.

  • Update of the config map should be read by the application within an acceptable time (a few seconds) without requiring a restart of the application.

  • Use curl to execute a GET request against the booster with the updated ConfigMap configuration.

$ curl $YOUR-APP-URL/api/greeting

  • You should see your updated greeting.

{"content":"Bonjour, World from a ConfigMap !"}

10. ConfigMap - Additional Documentation

More background and related information on ConfigMap can be found here: