Creating a multicomponent application with odo

odo allows you to create a multicomponent application, modify it, and link its components in an easy and automated way.

This example describes how to deploy a multicomponent application - a shooter game. The application consists of a front-end Node.js component and a back-end Java component.

Prerequisites

  • odo is installed.

  • You have a running cluster. Developers can use CodeReady Containers (CRC) to deploy a local cluster quickly.

  • Maven is installed.

Creating a project

Create a project to keep your source code, tests, and libraries organized in a separate single unit.

Procedure

  1. Log in to an OKD cluster:

    1. $ odo login -u developer -p developer
  2. Create a project:

    1. $ odo project create myproject

    Example output

    1. Project 'myproject' is ready for use
    2. New project created and now using project : myproject

Deploying the back-end component

To create a Java component, import the Java builder image, download the Java application and push the source code to your cluster with odo.

Procedure

  1. Import openjdk18 into the cluster:

    1. $ oc import-image openjdk18 \
    2. --from=registry.access.redhat.com/redhat-openjdk-18/openjdk18-openshift --confirm
  2. Tag the image as builder to make it accessible for odo:

    1. $ oc annotate istag/openjdk18:latest tags=builder
  3. Run odo catalog list components to see the created image:

    1. $ odo catalog list components

    Example output

    1. Odo Devfile Components:
    2. NAME DESCRIPTION REGISTRY
    3. java-maven Upstream Maven and OpenJDK 11 DefaultDevfileRegistry
    4. java-openliberty Open Liberty microservice in Java DefaultDevfileRegistry
    5. java-quarkus Upstream Quarkus with Java+GraalVM DefaultDevfileRegistry
    6. java-springboot Spring Boot® using Java DefaultDevfileRegistry
    7. nodejs Stack with NodeJS 12 DefaultDevfileRegistry
    8. Odo OpenShift Components:
    9. NAME PROJECT TAGS SUPPORTED
    10. java openshift 11,8,latest YES
    11. dotnet openshift 2.1,3.1,latest NO
    12. golang openshift 1.13.4-ubi7,1.13.4-ubi8,latest NO
    13. httpd openshift 2.4-el7,2.4-el8,latest NO
    14. nginx openshift 1.14-el7,1.14-el8,1.16-el7,1.16-el8,latest NO
    15. nodejs openshift 10-ubi7,10-ubi8,12-ubi7,12-ubi8,latest NO
    16. perl openshift 5.26-el7,5.26-ubi8,5.30-el7,latest NO
    17. php openshift 7.2-ubi7,7.2-ubi8,7.3-ubi7,7.3-ubi8,latest NO
    18. python openshift 2.7-ubi7,2.7-ubi8,3.6-ubi7,3.6-ubi8,3.8-ubi7,3.8-ubi8,latest NO
    19. ruby openshift 2.5-ubi7,2.5-ubi8,2.6-ubi7,2.6-ubi8,2.7-ubi7,latest NO
    20. wildfly openshift 10.0,10.1,11.0,12.0,13.0,14.0,15.0,16.0,17.0,18.0,19.0,20.0,8.1,9.0,latest NO
  4. Create a directory for your components:

    1. $ mkdir my_components && cd my_components
  5. Download the example back-end application:

    1. $ git clone https://github.com/openshift-evangelists/Wild-West-Backend backend
  6. Change to the back-end source directory:

    1. $ cd backend
  7. Check that you have the correct files in the directory:

    1. $ ls

    Example output

    1. debug.sh pom.xml src
  8. Build the back-end source files with Maven to create a JAR file:

    1. $ mvn package

    Example output

    1. ...
    2. [INFO] --------------------------------------
    3. [INFO] BUILD SUCCESS
    4. [INFO] --------------------------------------
    5. [INFO] Total time: 2.635 s
    6. [INFO] Finished at: 2019-09-30T16:11:11-04:00
    7. [INFO] Final Memory: 30M/91M
    8. [INFO] --------------------------------------
  9. Create a component configuration of Java component-type named backend:

    1. $ odo create --s2i openjdk18 backend --binary target/wildwest-1.0.jar

    Example output

    1. Validating component [1ms]
    2. Please use `odo push` command to create the component with source deployed

    Now the configuration file config.yaml is in the local directory of the back-end component that contains information about the component for deployment.

  10. Check the configuration settings of the back-end component in the config.yaml file using:

    1. $ odo config view

    Example output

    1. COMPONENT SETTINGS
    2. ------------------------------------------------
    3. PARAMETER CURRENT_VALUE
    4. Type openjdk18
    5. Application app
    6. Project myproject
    7. SourceType binary
    8. Ref
    9. SourceLocation target/wildwest-1.0.jar
    10. Ports 8080/TCP,8443/TCP,8778/TCP
    11. Name backend
    12. MinMemory
    13. MaxMemory
    14. DebugPort
    15. Ignore
    16. MinCPU
    17. MaxCPU
  11. Push the component to the OKD cluster.

    1. $ odo push

    Example output

    1. Validation
    2. Checking component [6ms]
    3. Configuration changes
    4. Initializing component
    5. Creating component [124ms]
    6. Pushing to component backend of type binary
    7. Checking files for pushing [1ms]
    8. Waiting for component to start [48s]
    9. Syncing files to the component [811ms]
    10. Building component [3s]

    Using odo push, OKD creates a container to host the back-end component, deploys the container into a pod running on the OKD cluster, and starts the backend component.

  12. Validate:

    • The status of the action in odo:

      1. $ odo log -f

      Example output

      1. 2019-09-30 20:14:19.738 INFO 444 --- [ main] c.o.wildwest.WildWestApplication : Starting WildWestApplication v1.0 onbackend-app-1-9tnhc with PID 444 (/deployments/wildwest-1.0.jar started by jboss in /deployments)
    • The status of the back-end component:

      1. $ odo list

      Example output

      1. APP NAME TYPE SOURCE STATE
      2. app backend openjdk18 file://target/wildwest-1.0.jar Pushed

Deploying the front-end component

To create and deploy a front-end component, download the Node.js application and push the source code to your cluster with odo.

Procedure

  1. Download the example front-end application:

    1. $ git clone https://github.com/openshift/nodejs-ex frontend
  2. Change the current directory to the front-end directory:

    1. $ cd frontend
  3. List the contents of the directory to see that the front end is a Node.js application.

    1. $ ls

    Example output

    1. README.md openshift server.js views
    2. helm package.json tests

    The front-end component is written in an interpreted language (Node.js); it does not need to be built.

  4. Create a component configuration of Node.js component-type named frontend:

    1. $ odo create --s2i nodejs frontend

    Example output

    1. Validating component [5ms]
    2. Please use `odo push` command to create the component with source deployed
  5. Push the component to a running container.

    1. $ odo push

    Example output

    1. Validation
    2. Checking component [8ms]
    3. Configuration changes
    4. Initializing component
    5. Creating component [83ms]
    6. Pushing to component frontend of type local
    7. Checking files for pushing [2ms]
    8. Waiting for component to start [45s]
    9. Syncing files to the component [3s]
    10. Building component [18s]
    11. Changes successfully pushed to component

Linking both components

Components running on the cluster need to be connected in order to interact. OKD provides linking mechanisms to publish communication bindings from a program to its clients.

Procedure

  1. List all the components that are running on the cluster:

    1. $ odo list

    Example output

    1. OpenShift Components:
    2. APP NAME PROJECT TYPE SOURCETYPE STATE
    3. app backend testpro openjdk18 binary Pushed
    4. app frontend testpro nodejs local Pushed
  2. Link the current front-end component to the back end:

    1. $ odo link backend --port 8080

    Example output

    1. Component backend has been successfully linked from the component frontend
    2. Following environment variables were added to frontend component:
    3. - COMPONENT_BACKEND_HOST
    4. - COMPONENT_BACKEND_PORT

    The configuration information of the back-end component is added to the front-end component and the front-end component restarts.

Exposing components to the public

Procedure

  1. Navigate to the frontend directory:

    1. $ cd frontend
  2. Create an external URL for the application:

    1. $ odo url create frontend --port 8080

    Example output

    1. URL frontend created for component: frontend
    2. To create URL on the OpenShift cluster, use `odo push`
  3. Apply the changes:

    1. $ odo push

    Example output

    1. Validation
    2. Checking component [21ms]
    3. Configuration changes
    4. Retrieving component data [35ms]
    5. Applying configuration [29ms]
    6. Applying URL changes
    7. URL frontend: http://frontend-app-myproject.192.168.42.79.nip.io created
    8. Pushing to component frontend of type local
    9. Checking file changes for pushing [1ms]
    10. No file changes detected, skipping build. Use the '-f' flag to force the build.
  4. Open the URL in a browser to view the application.

If an application requires permissions to the active service account to access the OKD namespace and delete active pods, the following error may occur when looking at odo log from the back-end component:

Message: Forbidden!Configured service account doesn’t have access. Service account may have been revoked

To resolve this error, add permissions for the service account role:

  1. $ oc policy add-role-to-group view system:serviceaccounts -n <project>
  1. $ oc policy add-role-to-group edit system:serviceaccounts -n <project>

Do not do this on a production cluster.

Modifying the running application

Procedure

  1. Change the local directory to the front-end directory:

    1. $ cd frontend
  2. Monitor the changes on the file system using:

    1. $ odo watch
  3. Edit the index.html file to change the displayed name for the game.

    A slight delay is possible before odo recognizes the change.

    odo pushes the changes to the front-end component and prints its status to the terminal:

    1. File /root/frontend/index.html changed
    2. File changed
    3. Pushing files...
    4. Waiting for component to start
    5. Copying files to component
    6. Building component
  4. Refresh the application page in the web browser. The new name is now displayed.

Deleting an application

Use the odo app delete command to delete your application.

Procedure

  1. List the applications in the current project:

    1. $ odo app list

    Example output

    1. The project '<project_name>' has the following applications:
    2. NAME
    3. app
  2. List the components associated with the applications. These components will be deleted with the application:

    1. $ odo component list

    Example output

    1. APP NAME TYPE SOURCE STATE
    2. app nodejs-nodejs-ex-elyf nodejs file://./ Pushed
  3. Delete the application:

    1. $ odo app delete <application_name>

    Example output

    1. ? Are you sure you want to delete the application: <application_name> from project: <project_name>
  4. Confirm the deletion with Y. You can suppress the confirmation prompt using the -f flag.