Deploying a devfile using odo

Deploying a portable devfile that describes your development environment

Understanding odo Devfile file reference

Introduction to devfile

What is a devfile?

A devfile is a portable file that describes your development environment. It allows reproducing a portable developmental environment without the need of reconfiguration.

With a devfile you can describe:

  • Development components such as container definition for build and application runtimes

  • A list of pre-defined commands that can be run

  • Projects to initially clone

Odo takes this devfile and transforms it into a workspace of multiple containers running on OpenShift, Kubernetes or Docker.

Devfiles are YAML files with a defined schema.

Odo and devfile

Odo can now create components from devfiles as recorded in registries. Odo automatically consults the default registry but users can also add their own registries. Devfiles contribute new component types that users can pull to begin development immediately.

An example deployment scenario:

  1. odo create will consult the recorded devfile registries to offer the user a selection of available component types and pull down the associated devfile.yaml file

  2. odo push parses and then deploys the component in the following order:

    1. Parses and validates the YAML file

    2. Deploys the development environment to your OpenShift cluster

    3. Synchronizes your source code to the containers

    4. Executes any prerequisite commands

Deploying your first devfile

Prerequisites for an OpenShift Cluster

  • Enable experimental mode for odo. This can be done by: odo preference set experimental true

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

    1. Log in to an OpenShift cluster:

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

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

Prerequisites for a Kubernetes Cluster

  • Enable experimental mode for odo. This can be done by: odo preference set experimental true

  • Before proceeding, you must know your ingress domain name or ingress IP to specify --host for odo url create.

    Ingress IP is usually the external IP of ingress controller service, for Minikube or CRC clusters running in a virtual machine you can get it by minikube ip or crc ip. Checkout this document to know more about ingress.

Listing all available devfile components

  • Before deploying your first component, have a look at what is available:

      $ odo catalog list components
      Odo OpenShift Components:
      NAME              PROJECT       TAGS                        SUPPORTED
      java              openshift     11,8,latest                 YES
      nodejs            openshift     10-SCL,8,8-RHOAR,latest     YES
      dotnet            openshift     2.1,2.2,3.0,latest          NO
      golang            openshift     1.11.5,latest               NO
      httpd             openshift     2.4,latest                  NO
      modern-webapp     openshift     10.x,latest                 NO
      nginx             openshift     1.10,1.12,latest            NO
      perl              openshift     5.24,5.26,latest            NO
      php               openshift     7.0,7.1,7.2,latest          NO
      python            openshift     2.7,3.6,latest              NO
      ruby              openshift     2.4,2.5,latest              NO
        
      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
    

In our example, we will be using java-spring-boot to deploy a sample Springboot component.

Deploying a Java Spring Boot® component to an OpenShift / Kubernetes cluster

In this example we will be deploying an example Spring Boot® component that uses Maven and Java 8 JDK.

  1. Download the example Spring Boot® component.

     $ git clone https://github.com/odo-devfiles/springboot-ex
    

    Alternatively, you can pass in --starter to odo create to have odo download a project specified in the devfile.

  2. Change the current directory to the component directory:

     $ cd <directory-name>
    
  3. Create a component configuration using the java-spring-boot component-type named myspring:

       $ odo create java-spring-boot myspring
       Experimental mode is enabled, use at your own risk
        
       Validation
        ✓  Checking devfile compatibility [195728ns]
        ✓  Creating a devfile component from registry: DefaultDevfileRegistry [170275ns]
        ✓  Validating devfile component [281940ns]
        
        Please use odo push command to create the component with source deployed
    
  4. List the contents of the directory to see the devfile and sample Java application source code:

      $ ls
      README.md devfile.yaml    pom.xml     src
    
  5. Create a URL in order to access the deployed component:

     $ odo url create
      ✓  URL myspring-8080.apps-crc.testing created for component: myspring
        
     To apply the URL configuration changes, please use odo push
    

    Note

    If deploying on Kubernetes, you need to pass ingress domain name via --host flag.

  6. Push the component to the cluster:

      $ odo push
        
      Validation
       ✓  Validating the devfile [81808ns]
        
      Creating Kubernetes resources for component myspring
       ✓  Waiting for component to start [5s]
        
      Applying URL changes
       ✓  URL myspring-8080: http://myspring-8080.apps-crc.testing created
        
      Syncing to component myspring
       ✓  Checking files for pushing [2ms]
       ✓  Syncing files to the component [1s]
        
      Executing devfile commands for component myspring
       ✓  Executing devbuild command "/artifacts/bin/build-container-full.sh" [1m]
       ✓  Executing devrun command "/artifacts/bin/start-server.sh" [2s]
        
      Pushing devfile component myspring
       ✓  Changes successfully pushed to component
    
  7. List the URLs of the component:

     $ odo url list
     Found the following URLs for component myspring
     NAME              URL                                       PORT     SECURE
     myspring-8080     http://myspring-8080.apps-crc.testing     8080     false
    
  8. View your deployed application using the generated URL:

      $ curl http://myspring-8080.apps-crc.testing
    
  9. To delete your deployed application:

      $ odo delete
      ? Are you sure you want to delete the devfile component: myspring? Yes
       ✓  Deleting devfile component myspring [152ms]
       ✓  Successfully deleted component
    

Deploying a Node.js® component to an OpenShift / Kubernetes cluster

In this example we will be deploying an example Node.js® component that uses NPM.

  1. Download the example Node.js® component

     $ git clone https://github.com/odo-devfiles/nodejs-ex
    
  2. Change the current directory to the component directory:

     $ cd <directory-name>
    
  3. List the contents of the directory to confirm that the application is indeed a Node.js® application:

     $ ls
     app  LICENSE  package.json  package-lock.json  README.md
    
  4. Create a component configuration using the nodejs component-type named mynodejs:

     $ odo create nodejs mynodejs
     Experimental mode is enabled, use at your own risk
        
     Validation
      ✓  Checking devfile compatibility [111738ns]
      ✓  Creating a devfile component from registry: DefaultDevfileRegistry [89567ns]
      ✓  Validating devfile component [186982ns]
        
     Please use odo push command to create the component with source deployed
    
  5. Create a URL in order to access the deployed component:

     $ odo url create
      ✓  URL mynodejs-8080.apps-crc.testing created for component: mynodejs
        
     To apply the URL configuration changes, please use odo push
    

    Note

    If deploying on Kubernetes, you need to pass ingress domain name via --host flag.

  6. Push the component to the cluster:

      $ odo push
        
      Validation
       ✓  Validating the devfile [89380ns]
        
      Creating Kubernetes resources for component mynodejs
       ✓  Waiting for component to start [3s]
        
      Applying URL changes
       ✓  URL mynodejs-3000: http://mynodejs-3000.apps-crc.testing created
        
      Syncing to component mynodejs
       ✓  Checking files for pushing [2ms]
       ✓  Syncing files to the component [1s]
        
      Executing devfile commands for component mynodejs
       ✓  Executing devbuild command "npm install" [3s]
       ✓  Executing devrun command "nodemon app.js" [2s]
        
      Pushing devfile component mynodejs
       ✓  Changes successfully pushed to component
    
  7. List the URLs of the component:

     $ odo url list
         Found the following URLs for component mynodejs
         NAME              URL                                       PORT     SECURE
         mynodejs-8080     http://mynodejs-8080.apps-crc.testing     8080     false
    
  8. View your deployed application using the generated URL:

       $ curl http://mynodejs-8080.apps-crc.testing
    
  9. To delete your deployed application:

       $ odo delete
       ? Are you sure you want to delete the devfile component: mynodejs? Yes
        ✓  Deleting devfile component mynodejs [139ms]
        ✓  Successfully deleted component
    

Deploying a Quarkus Application to an OpenShift / Kubernetes cluster

In this example we will be deploying a Quarkus component that uses GraalVM and JDK1.8+.

  1. Download the example Quarkus component

     $ git clone https://github.com/odo-devfiles/quarkus-ex && cd quarkus-ex
    
  2. Create a Quarkus odo component

       $ odo create java-quarkus myquarkus
       Experimental mode is enabled, use at your own risk
        
       Validation
        ✓  Checking devfile compatibility [195728ns]
        ✓  Creating a devfile component from registry: DefaultDevfileRegistry [170275ns]
        ✓  Validating devfile component [281940ns]
        
        Please use odo push command to create the component with source deployed
    
  3. Create a URL in order to access the deployed component:

     $ odo url create
      ✓  URL myquarkus-8080.apps-crc.testing created for component: myquarkus
        
     To apply the URL configuration changes, please use odo push
    

    Note

    If deploying on Kubernetes, you need to pass ingress domain name via --host flag.

  4. Push the component to the cluster:

      $ odo push
        
    Validation
     ✓  Validating the devfile [44008ns]
        
    Creating Kubernetes resources for component myquarkus
     ✓  Waiting for component to start [10s]
        
    Applying URL changes
     ✓  URLs are synced with the cluster, no changes are required.
        
    Syncing to component myquarkus
     ✓  Checking files for pushing [951138ns]
     ✓  Syncing files to the component [204ms]
        
    Executing devfile commands for component myquarkus
     ✓  Executing init-compile command "mvn compile" [3m]
     ✓  Executing dev-run command "mvn quarkus:dev" [1s]
        
    Pushing devfile component myquarkus
     ✓  Changes successfully pushed to component
    
  5. View your deployed application in a browser using the generated url

     $ odo url list
     Found the following URLs for component myspring
     NAME              URL                                       PORT     SECURE
     myquarkus-8080     http://myquarkus-8080.apps-crc.testing     8080     false
    

You can now continue developing your application. Just run odo push and refresh your browser to view the latest changes.

You can also run odo watch to watch changes in the source code. Just refreshing the browser will render the source code changes.

Run odo delete to delete the application from cluster.

  1. To delete your deployed application:

       $ odo delete
       ? Are you sure you want to delete the devfile component: java-spring-boot? Yes
        ✓  Deleting devfile component java-spring-boot [139ms]
        ✓  Successfully deleted component