Chapter 2. Developer CLI (odo)

1. Creating resources

   If not already created, odo push creates the following OpenShift Container Platform resources:

   • DeploymentConfig object:

     • Two init containers are executed: copy-supervisord and copy-files-to-volume. The init containers copy files onto the emptyDir and the PersistentVolume type of volumes respectively.
     • The application container starts. The first process in the application container is the go-init process with PID=1.

     • go-init process starts the SupervisorD daemon.

       Note

       The user application code has not been copied into the application container yet, so the SupervisorD daemon does not execute the run script.

   • Service object
   • Secret objects
   • PersistentVolumeClaim object

2. Indexing files

   • A file indexer indexes the files in the source code directory. The indexer traverses through the source code directories recursively and finds files which have been created, deleted, or renamed.
   • A file indexer maintains the indexed information in an odo index file inside the .odo directory.
   • If the odo index file is not present, it means that the file indexer is being executed for the first time, and creates a new odo index JSON file. The odo index JSON file contains a file map - the relative file paths of the traversed files and the absolute paths of the changed and deleted files.

3. Pushing code

   Local code is copied into the application container, usually under /tmp/src.

4. Executing assemble-and-restart

   On a successful copy of the source code, the assemble-and-restart script is executed inside the running application container.

Procedure

1. Log in to an OpenShift Container Platform cluster:

   $ odo login -u developer -p developer

2. Create a project:

   $ odo project create myproject

   Example output

    ✓  Project 'myproject' is ready for use
    ✓  New project created and now using project : myproject

Procedure

1. Create a directory for your components:

   $ mkdir my_components && cd my_components

2. Download the example Node.js application:

   $ git clone https://github.com/openshift/nodejs-ex

3. Change the current directory to the directory with your application:

   $ cd <directory_name>

4. Add a component of the type Node.js to your application:

   $ odo create nodejs

   Note

   By default, the latest image is used. You can also explicitly specify an image version by using odo create openshift/nodejs:8.

5. Push the initial source code to the component:

   $ odo push

   Your component is now deployed to OpenShift Container Platform.

6. Create a URL and add an entry in the local configuration file as follows:

   $ odo url create --port 8080

7. Push the changes. This creates a URL on the cluster.

   $ odo push

8. List the URLs to check the desired URL for the component.

   $ odo url list

9. View your deployed application using the generated URL.

   $ curl <url>

1. Edit one of the layout files within the Node.js directory with your preferred text editor.

2. Update your component:

   $ odo push

3. Refresh your application in the browser to see the changes.

Procedure

1. Add the storage to your component:

   $ odo storage create <storage_name> --path=<path_to_the_directory> --size=<size>

2. Push the storage to the cluster:

   $ odo push

3. Verify that the storage is now attached to your component by listing all storage in the component:

   $ odo storage list

   Example output

   The component 'nodejs' has the following storage attached:
   NAME           SIZE     PATH      STATE
   mystorage      1Gi      /data     Pushed

4. Delete the storage from your component:

   $ odo storage delete <storage_name>

5. List all storage to verify that the storage state is Locally Deleted:

   $ odo storage list

   Example output

   The component 'nodejs' has the following storage attached:
   NAME           SIZE     PATH      STATE
   mystorage      1Gi      /data     Locally Deleted

6. Push the changes to the cluster:

   $ odo push

Procedure

1. Import the image into OpenShift Container Platform:

   $ oc import-image openjdk18 \
   --from=registry.access.redhat.com/redhat-openjdk-18/openjdk18-openshift \
   --confirm

2. Tag the image to make it accessible to odo:

   $ oc annotate istag/openjdk18:latest tags=builder

3. Deploy the image with odo:

   $ odo create openjdk18 --git \
   https://github.com/openshift-evangelists/Wild-West-Backend

Procedure

1. List the applications in the current project:

   $ odo app list

   Example output

       The project '<project_name>' has the following applications:
       NAME
       app

2. List the components associated with the applications. These components will be deleted with the application:

   $ odo component list

   Example output

       APP     NAME                      TYPE       SOURCE        STATE
       app     nodejs-nodejs-ex-elyf     nodejs     file://./     Pushed

3. Delete the application:

   $ odo app delete <application_name>

   Example output

       ? 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.

Procedure

1. Log in to an OpenShift Container Platform cluster:

   $ odo login -u developer -p developer

2. Create a project:

   $ odo project create myproject

   Example output

    ✓  Project 'myproject' is ready for use
    ✓  New project created and now using project : myproject

Procedure

1. Import openjdk18 into the cluster:

   $ oc import-image openjdk18 \
   --from=registry.access.redhat.com/redhat-openjdk-18/openjdk18-openshift --confirm

2. Tag the image as builder to make it accessible for odo:

   $ oc annotate istag/openjdk18:latest tags=builder

3. Run odo catalog list components to see the created image:

   $ odo catalog list components

   Example output

   Odo Devfile Components:
   NAME                 DESCRIPTION                            REGISTRY
   java-maven           Upstream Maven and OpenJDK 11          DefaultDevfileRegistry
   java-openliberty     Open Liberty microservice in Java      DefaultDevfileRegistry
   java-quarkus         Upstream Quarkus with Java+GraalVM     DefaultDevfileRegistry
   java-springboot      Spring Boot® using Java                DefaultDevfileRegistry
   nodejs               Stack with NodeJS 12                   DefaultDevfileRegistry
   
   Odo OpenShift Components:
   NAME        PROJECT       TAGS                                                                           SUPPORTED
   java        openshift     11,8,latest                                                                    YES
   dotnet      openshift     2.1,3.1,latest                                                                 NO
   golang      openshift     1.13.4-ubi7,1.13.4-ubi8,latest                                                 NO
   httpd       openshift     2.4-el7,2.4-el8,latest                                                         NO
   nginx       openshift     1.14-el7,1.14-el8,1.16-el7,1.16-el8,latest                                     NO
   nodejs      openshift     10-ubi7,10-ubi8,12-ubi7,12-ubi8,latest                                         NO
   perl        openshift     5.26-el7,5.26-ubi8,5.30-el7,latest                                             NO
   php         openshift     7.2-ubi7,7.2-ubi8,7.3-ubi7,7.3-ubi8,latest                                     NO
   python      openshift     2.7-ubi7,2.7-ubi8,3.6-ubi7,3.6-ubi8,3.8-ubi7,3.8-ubi8,latest                   NO
   ruby        openshift     2.5-ubi7,2.5-ubi8,2.6-ubi7,2.6-ubi8,2.7-ubi7,latest                            NO
   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:

   $ mkdir my_components && cd my_components

5. Download the example back-end application:

   $ git clone https://github.com/openshift-evangelists/Wild-West-Backend backend

6. Change to the back-end source directory:

   $ cd backend

7. Check that you have the correct files in the directory:

   $ ls

   Example output

   debug.sh  pom.xml  src

8. Build the back-end source files with Maven to create a JAR file:

   $ mvn package

   Example output

   ...
   [INFO] --------------------------------------
   [INFO] BUILD SUCCESS
   [INFO] --------------------------------------
   [INFO] Total time: 2.635 s
   [INFO] Finished at: 2019-09-30T16:11:11-04:00
   [INFO] Final Memory: 30M/91M
   [INFO] --------------------------------------

9. Create a component configuration of Java component-type named backend:

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

   Example output

    ✓  Validating component [1ms]
    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:

    $ odo config view

    Example output

    COMPONENT SETTINGS
    ------------------------------------------------
    PARAMETER         CURRENT_VALUE
    Type              openjdk18
    Application       app
    Project           myproject
    SourceType        binary
    Ref
    SourceLocation    target/wildwest-1.0.jar
    Ports             8080/TCP,8443/TCP,8778/TCP
    Name              backend
    MinMemory
    MaxMemory
    DebugPort
    Ignore
    MinCPU
    MaxCPU

11. Push the component to the OpenShift Container Platform cluster.

    $ odo push

    Example output

    Validation
     ✓  Checking component [6ms]
    
    Configuration changes
     ✓  Initializing component
     ✓  Creating component [124ms]
    
    Pushing to component backend of type binary
     ✓  Checking files for pushing [1ms]
     ✓  Waiting for component to start [48s]
     ✓  Syncing files to the component [811ms]
     ✓  Building component [3s]

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

12. Validate:

    • The status of the action in odo:

      $ odo log -f

      Example output

      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:

      $ odo list

      Example output

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

Procedure

1. Download the example front-end application:

   $ git clone https://github.com/openshift/nodejs-ex frontend

2. Change the current directory to the front-end directory:

   $ cd frontend

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

   $ ls

   Example output

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

   Note

   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:

   $ odo create nodejs frontend

   Example output

    ✓  Validating component [5ms]
   Please use `odo push` command to create the component with source deployed

5. Push the component to a running container.

   $ odo push

   Example output

   Validation
    ✓  Checking component [8ms]
   
   Configuration changes
    ✓  Initializing component
    ✓  Creating component [83ms]
   
   Pushing to component frontend of type local
    ✓  Checking files for pushing [2ms]
    ✓  Waiting for component to start [45s]
    ✓  Syncing files to the component [3s]
    ✓  Building component [18s]
    ✓  Changes successfully pushed to component

Procedure

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

   $ odo list

   Example output

   OpenShift Components:
   APP     NAME         PROJECT     TYPE          SOURCETYPE     STATE
   app     backend      testpro     openjdk18     binary         Pushed
   app     frontend     testpro     nodejs        local          Pushed

2. Link the current front-end component to the back end:

   $ odo link backend --port 8080

   Example output

    ✓  Component backend has been successfully linked from the component frontend
   
   Following environment variables were added to frontend component:
   - COMPONENT_BACKEND_HOST
   - COMPONENT_BACKEND_PORT

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

Procedure

1. Navigate to the frontend directory:

   $ cd frontend

2. Create an external URL for the application:

   $ odo url create frontend --port 8080

   Example output

    ✓  URL frontend created for component: frontend
   
   To create URL on the OpenShift  cluster, use `odo push`

3. Apply the changes:

   $ odo push

   Example output

   Validation
    ✓  Checking component [21ms]
   
   Configuration changes
    ✓  Retrieving component data [35ms]
    ✓  Applying configuration [29ms]
   
   Applying URL changes
    ✓  URL frontend: http://frontend-app-myproject.192.168.42.79.nip.io created
   
   Pushing to component frontend of type local
    ✓  Checking file changes for pushing [1ms]
    ✓  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.

Procedure

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

   $ cd frontend

2. Monitor the changes on the file system using:

   $ odo watch

3. Edit the index.html file to change the displayed name for the game.

   Note

   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:

   File /root/frontend/index.html changed
   File  changed
   Pushing files...
    ✓  Waiting for component to start
    ✓  Copying files to component
    ✓  Building component

4. Refresh the application page in the web browser. The new name is now displayed.

Procedure

1. List the applications in the current project:

   $ odo app list

   Example output

       The project '<project_name>' has the following applications:
       NAME
       app

2. List the components associated with the applications. These components will be deleted with the application:

   $ odo component list

   Example output

       APP     NAME                      TYPE       SOURCE        STATE
       app     nodejs-nodejs-ex-elyf     nodejs     file://./     Pushed

3. Delete the application:

   $ odo app delete <application_name>

   Example output

       ? 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.

Procedure

1. Log in to an OpenShift Container Platform cluster:

   $ odo login -u developer -p developer

2. Create a project:

   $ odo project create myproject

   Example output

    ✓  Project 'myproject' is ready for use
    ✓  New project created and now using project : myproject

Procedure

1. Download the example front-end application:

   $ git clone https://github.com/openshift/nodejs-ex frontend

2. Change the current directory to the front-end directory:

   $ cd frontend

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

   $ ls

   Example output

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

   Note

   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:

   $ odo create nodejs frontend

   Example output

    ✓  Validating component [5ms]
   Please use `odo push` command to create the component with source deployed

5. Create a URL to access the frontend interface.

   $ odo url create myurl

   Example output

    ✓  URL myurl created for component: nodejs-nodejs-ex-pmdp

6. Push the component to the OpenShift Container Platform cluster.

   $ odo push

   Example output

   Validation
    ✓  Checking component [7ms]
   
    Configuration changes
    ✓  Initializing component
    ✓  Creating component [134ms]
   
    Applying URL changes
    ✓  URL myurl: http://myurl-app-myproject.192.168.42.79.nip.io created
   
    Pushing to component nodejs-nodejs-ex-mhbb of type local
    ✓  Checking files for pushing [657850ns]
    ✓  Waiting for component to start [6s]
    ✓  Syncing files to the component [408ms]
    ✓  Building component [7s]
    ✓  Changes successfully pushed to component

1. List the available services:

   $ odo catalog list services

   Example output

   NAME                         PLANS
   django-psql-persistent       default
   jenkins-ephemeral            default
   jenkins-pipeline-example     default
   mariadb-persistent           default
   mongodb-persistent           default
   mysql-persistent             default
   nodejs-mongo-persistent      default
   postgresql-persistent        default
   rails-pgsql-persistent       default

2. Choose the mongodb-persistent type of service and see the required parameters:

   $ odo catalog describe service mongodb-persistent

   Example output

     ***********************        | *****************************************************
     Name                           | default
     -----------------              | -----------------
     Display Name                   |
     -----------------              | -----------------
     Short Description              | Default plan
     -----------------              | -----------------
     Required Params without a      |
     default value                  |
     -----------------              | -----------------
     Required Params with a default | DATABASE_SERVICE_NAME
     value                          | (default: 'mongodb'),
                                    | MEMORY_LIMIT (default:
                                    | '512Mi'), MONGODB_VERSION
                                    | (default: '3.2'),
                                    | MONGODB_DATABASE (default:
                                    | 'sampledb'), VOLUME_CAPACITY
                                    | (default: '1Gi')
     -----------------              | -----------------
     Optional Params                | MONGODB_ADMIN_PASSWORD,
                                    | NAMESPACE, MONGODB_PASSWORD,
                                    | MONGODB_USER

3. Pass the required parameters as flags and wait for the deployment of the database:

   $ odo service create mongodb-persistent --plan default --wait -p DATABASE_SERVICE_NAME=mongodb -p MEMORY_LIMIT=512Mi -p MONGODB_DATABASE=sampledb -p VOLUME_CAPACITY=1Gi

1. Link the database to the front-end service:

   $ odo link mongodb-persistent

   Example output

    ✓  Service mongodb-persistent has been successfully linked from the component nodejs-nodejs-ex-mhbb
   
   Following environment variables were added to nodejs-nodejs-ex-mhbb component:
   - database_name
   - password
   - uri
   - username
   - admin_password

2. See the environment variables of the application and the database in the pod:

   1. Get the pod name:

      $ oc get pods

      Example output

      NAME                                READY     STATUS    RESTARTS   AGE
      mongodb-1-gsznc                     1/1       Running   0          28m
      nodejs-nodejs-ex-mhbb-app-4-vkn9l   1/1       Running   0          1m

   2. Connect to the pod:

      $ oc rsh nodejs-nodejs-ex-mhbb-app-4-vkn9l

   3. Check the environment variables:

      sh-4.2$ env

      Example output

      uri=mongodb://172.30.126.3:27017
      password=dHIOpYneSkX3rTLn
      database_name=sampledb
      username=user43U
      admin_password=NCn41tqmx7RIqmfv

3. Open the URL in the browser and notice the database configuration in the bottom right:

   $ odo url list

   Example output

   Request information
   Page view count: 24
   
   DB Connection Info:
   Type:	MongoDB
   URL:	mongodb://172.30.126.3:27017/sampledb

Procedure

1. List the applications in the current project:

   $ odo app list

   Example output

       The project '<project_name>' has the following applications:
       NAME
       app

2. List the components associated with the applications. These components will be deleted with the application:

   $ odo component list

   Example output

       APP     NAME                      TYPE       SOURCE        STATE
       app     nodejs-nodejs-ex-elyf     nodejs     file://./     Pushed

3. Delete the application:

   $ odo app delete <application_name>

   Example output

       ? 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.

1. Run the odo utils convert-to-devfile command, which creates devfile.yaml and env.yaml based on your component:

   $ odo utils convert-to-devfile

2. Push the component to your cluster:

   $ odo push

   Note

   If the devfile component deployment failed, delete it by running: odo delete -a

3. Verify that the devfile component deployed successfully:

   $ odo list

4. Delete the S2I component:

   $ odo delete --s2i

Procedure

1. Log in to an OpenShift Container Platform cluster:

   $ odo login -u developer -p developer

2. Create a project:

   $ odo project create myproject

   Example output

    ✓  Project 'myproject' is ready for use
    ✓  New project created and now using project : myproject

1. Print the YAML of the service as a file on your local drive:

   $ oc get csv/etcdoperator.v0.9.4 -o yaml

2. Verify that the values of the service are valid:

   apiVersion: etcd.database.coreos.com/v1beta2
   kind: EtcdCluster
   metadata:
     name: example
   spec:
     size: 3
     version: 3.2.13

3. Start an EtcdCluster service from the etcdoperator.v0.9.4 Operator:

   $ odo service create etcdoperator.v0.9.4 EtcdCluster

4. Verify that a service has started:

   $ oc get EtcdCluster

1. To display the YAML of the service, run:

   $ odo service create <operator-name> --dry-run

   For example, to print YAML definition of EtcdCluster provided by the etcdoperator.v0.9.4 Operator, run:

   $ odo service create etcdoperator.v0.9.4 --dry-run

   The YAML is saved as the etcd.yaml file.

2. Modify the etcd.yaml file:

   apiVersion: etcd.database.coreos.com/v1beta2
   kind: EtcdCluster
   metadata:
     name: my-etcd-cluster 1
   spec:
     size: 1 2
     version: 3.2.13

   1

   Change the name from example to my-etcd-cluster

   2

   Reduce the size from 3 to 1

3. Start a service from the YAML file:

   $ odo service create --from-file etcd.yaml

4. Verify that the EtcdCluster service has started with one pod instead of the pre-configured three pods:

   $ oc get pods | grep my-etcd-cluster

Procedure

1. After an application is deployed, start the port forwarding for your component to debug the application:

   $ odo debug port-forward

2. Attach the debugger bundled in your IDE to the component. Instructions vary depending on your IDE.