1. Documentation
    2. history bug_report picture_as_pdf
×

odo CLI reference

odo build-images

odo can build container images based on Dockerfiles, and push these images to their registries.

When running the odo build-images command, odo searches for all components in the devfile.yaml with the image type, for example:

components:
- image:
    imageName: quay.io/myusername/myimage
    dockerfile:
      uri: ./Dockerfile (1)
      buildContext: ${PROJECTS_ROOT} (2)
  name: component-built-from-dockerfile
1 The uri field indicates the relative path of the Dockerfile to use, relative to the directory containing the devfile.yaml. The devfile specification indicates that uri could also be an HTTP URL, but this case is not supported by odo yet.
2 The buildContext indicates the directory used as build context. The default value is ${PROJECTS_ROOT}.

For each image component, odo executes either podman or docker (the first one found, in this order), to build the image with the specified Dockerfile, build context, and arguments.

If the --push flag is passed to the command, the images are pushed to their registries after they are built.

odo catalog

odo uses different catalogs to deploy components and services.

Components

odo uses the portable devfile format to describe the components. It can connect to various devfile registries to download devfiles for different languages and frameworks. See odo registry for more information.

Listing components

To list all the devfiles available on the different registries, run the command:

$ odo catalog list components
Example output
 NAME             DESCRIPTION                          REGISTRY
 go               Stack with the latest Go version     DefaultDevfileRegistry
 java-maven       Upstream Maven and OpenJDK 11        DefaultDevfileRegistry
 nodejs           Stack with Node.js 14                DefaultDevfileRegistry
 php-laravel      Stack with Laravel 8                 DefaultDevfileRegistry
 python           Python Stack with Python 3.7         DefaultDevfileRegistry
 [...]

Getting information about a component

To get more information about a specific component, run the command:

$ odo catalog describe component

For example, run the command:

$ odo catalog describe component nodejs
Example output
* Registry: DefaultDevfileRegistry (1)

Starter Projects: (2)
---
name: nodejs-starter
attributes: {}
description: ""
subdir: ""
projectsource:
  sourcetype: ""
  git:
    gitlikeprojectsource:
      commonprojectsource: {}
      checkoutfrom: null
      remotes:
        origin: https://github.com/odo-devfiles/nodejs-ex.git
  zip: null
  custom: null
1 Registry is the registry from which the devfile is retrieved.
2 Starter projects are sample projects in the same language and framework of the devfile, that can help you start a new project.

See odo create for more information on creating a project from a starter project.

Services

odo can deploy services with the help of Operators.

Only Operators deployed with the help of the Operator Lifecycle Manager are supported by odo.

Listing services

To list the available Operators and their associated services, run the command:

$ odo catalog list services
Example output
 Services available through Operators
 NAME                                 CRDs
 postgresql-operator.v0.1.1           Backup, Database
 redis-operator.v0.8.0                RedisCluster, Redis

In this example, two Operators are installed in the cluster. The postgresql-operator.v0.1.1 Operator deploys services related to PostgreSQL: Backup and Database. The redis-operator.v0.8.0 Operator deploys services related to Redis: RedisCluster and Redis.

To get a list of all the available Operators, odo fetches the ClusterServiceVersion (CSV) resources of the current namespace that are in a Succeeded phase. For Operators that support cluster-wide access, when a new namespace is created, these resources are automatically added to it. However, it may take some time before they are in the Succeeded phase, and odo may return an empty list until the resources are ready.

Searching services

To search for a specific service by a keyword, run the command:

$ odo catalog search service

For example, to retrieve the PostgreSQL services, run the command:

$ odo catalog search service postgres
Example output
 Services available through Operators
 NAME                           CRDs
 postgresql-operator.v0.1.1     Backup, Database

You will see a list of Operators that contain the searched keyword in their name.

Getting information about a service

To get more information about a specific service, run the command:

$ odo catalog describe service

For example:

$ odo catalog describe service postgresql-operator.v0.1.1/Database
Example output
KIND:    Database
VERSION: v1alpha1

DESCRIPTION:
     Database is the Schema for the the Database Database API

FIELDS:
   awsAccessKeyId (string)
     AWS S3 accessKey/token ID

     Key ID of AWS S3 storage. Default Value: nil Required to create the Secret
     with the data to allow send the backup files to AWS S3 storage.
[...]

A service is represented in the cluster by a CustomResourceDefinition (CRD) resource. The previous command displays the details about the CRD such as kind, version, and the list of fields available to define an instance of this custom resource.

The list of fields is extracted from the OpenAPI schema included in the CRD. This information is optional in a CRD, and if it is not present, it is extracted from the ClusterServiceVersion (CSV) resource representing the service instead.

It is also possible to request the description of an Operator-backed service, without providing CRD type information. To describe the Redis Operator on a cluster, without CRD, run the following command:

$ odo catalog describe service redis-operator.v0.8.0
Example output
NAME:	redis-operator.v0.8.0
DESCRIPTION:

	A Golang based redis operator that will make/oversee Redis
	standalone/cluster mode setup on top of the Kubernetes. It can create a
	redis cluster setup with best practices on Cloud as well as the Bare metal
	environment. Also, it provides an in-built monitoring capability using

... (cut short for beverity)

	Logging Operator is licensed under [Apache License, Version
	2.0](https://github.com/OT-CONTAINER-KIT/redis-operator/blob/master/LICENSE)


CRDs:
	NAME           DESCRIPTION
	RedisCluster   Redis Cluster
	Redis          Redis

odo create

odo uses a devfile to store the configuration of a component and to describe the component’s resources such as storage and services. The odo create command generates this file.

Creating a component

To create a devfile for an existing project, run the odo create command with the name and type of your component (for example, nodejs or go):

odo create nodejs mynodejs

In the example, nodejs is the type of the component and mynodejs is the name of the component that odo creates for you.

For a list of all the supported component types, run the command odo catalog list components.

If your source code exists outside the current directory, the --context flag can be used to specify the path. For example, if the source for the nodejs component is in a folder called node-backend relative to the current working directory, run the command:

odo create nodejs mynodejs --context ./node-backend

The --context flag supports relative and absolute paths.

To specify the project or app where your component will be deployed, use the --project and --app flags. For example, to create a component that is part of the myapp app inside the backend project, run the command:

odo create nodejs --app myapp --project backend

If these flags are not specified, they will default to the active app and project.

Starter projects

Use the starter projects if you do not have existing source code but want to get up and running quickly to experiment with devfiles and components. To use a starter project, add the --starter flag to the odo create command.

To get a list of available starter projects for a component type, run the odo catalog describe component command. For example, to get all available starter projects for the nodejs component type, run the command:

odo catalog describe component nodejs

Then specify the desired project using the --starter flag on the odo create command:

odo create nodejs --starter nodejs-starter

This will download the example template corresponding to the chosen component type, in this instance, nodejs. The template is downloaded to your current directory, or to the location specified by the --context flag. If a starter project has its own devfile, then this devfile will be preserved.

Using an existing devfile

If you want to create a new component from an existing devfile, you can do so by specifying the path to the devfile using the --devfile flag. For example, to create a component called mynodejs, based on a devfile from GitHub, use the following command:

odo create mynodejs --devfile https://raw.githubusercontent.com/odo-devfiles/registry/master/devfiles/nodejs/devfile.yaml

Interactive creation

You can also run the odo create command interactively, to guide you through the steps needed to create a component:

$ odo create

? Which devfile component type do you wish to create go
? What do you wish to name the new devfile component go-api
? What project do you want the devfile component to be created in default
Devfile Object Validation
 ✓  Checking devfile existence [164258ns]
 ✓  Creating a devfile component from registry: DefaultDevfileRegistry [246051ns]
Validation
 ✓  Validating if devfile name is correct [92255ns]
? Do you want to download a starter project Yes

Starter Project
 ✓  Downloading starter project go-starter from https://github.com/devfile-samples/devfile-stack-go.git [429ms]

Please use odo push command to create the component with source deployed

You are prompted to choose the component type, name, and the project for the component. You can also choose whether or not to download a starter project. Once finished, a new devfile.yaml file is created in the working directory.

To deploy these resources to your cluster, run the command odo push.

odo delete

The odo delete command is useful for deleting resources that are managed by odo.

Deleting a component

To delete a devfile component, run the odo delete command:

$ odo delete

If the component has been pushed to the cluster, the component is deleted from the cluster, along with its dependent storage, URL, secrets, and other resources. If the component has not been pushed, the command exits with an error stating that it could not find the resources on the cluster.

Use the -f or --force flag to avoid the confirmation questions.

Undeploying devfile Kubernetes components

To undeploy the devfile Kubernetes components, that have been deployed with odo deploy, execute the odo delete command with the --deploy flag:

$ odo delete --deploy

Use the -f or --force flag to avoid the confirmation questions.

Delete all

To delete all artifacts including the following items, run the odo delete command with the --all flag :

  • devfile component

  • Devfile Kubernetes component that was deployed using the odo deploy command

  • Devfile

  • Local configuration

$ odo delete --all

Available flags

-f, --force

Use this flag to avoid the confirmation questions.

-w, --wait

Use this flag to wait for component deletion and any dependencies. This flag does not work when undeploying.

The documentation on Common Flags provides more information on the flags available for commands.

odo deploy

odo can be used to deploy components in a manner similar to how they would be deployed using a CI/CD system. First, odo builds the container images, and then it deploys the Kubernetes resources required to deploy the components.

When running the command odo deploy, odo searches for the default command of kind deploy in the devfile, and executes this command. The kind deploy is supported by the devfile format starting from version 2.2.0.

The deploy command is typically a composite command, composed of several apply commands:

  • A command referencing an image component that, when applied, will build the image of the container to deploy, and then push it to its registry.

  • A command referencing a Kubernetes component that, when applied, will create a Kubernetes resource in the cluster.

With the following example devfile.yaml file, a container image is built using the Dockerfile present in the directory. The image is pushed to its registry and then a Kubernetes Deployment resource is created in the cluster, using this freshly built image.

schemaVersion: 2.2.0
[...]
variables:
  CONTAINER_IMAGE: quay.io/phmartin/myimage
commands:
  - id: build-image
    apply:
      component: outerloop-build
  - id: deployk8s
    apply:
      component: outerloop-deploy
  - id: deploy
    composite:
      commands:
        - build-image
        - deployk8s
      group:
        kind: deploy
        isDefault: true
components:
  - name: outerloop-build
    image:
      imageName: "{{CONTAINER_IMAGE}}"
      dockerfile:
        uri: ./Dockerfile
        buildContext: ${PROJECTS_ROOT}
  - name: outerloop-deploy
    kubernetes:
      inlined: |
        kind: Deployment
        apiVersion: apps/v1
        metadata:
          name: my-component
        spec:
          replicas: 1
          selector:
            matchLabels:
              app: node-app
          template:
            metadata:
              labels:
                app: node-app
            spec:
              containers:
                - name: main
                  image: {{CONTAINER_IMAGE}}

The odo link command helps link an odo component to an Operator-backed service or another odo component. It does this by using the Service Binding Operator. Currently, odo makes use of the Service Binding library and not the Operator itself to achieve the desired functionality.

Various linking options

odo provides various options for linking a component with an Operator-backed service or another odo component. All these options (or flags) can be used whether you are linking a component to a service or to another component.

Default behavior

By default, the odo link command creates a directory named kubernetes/ in your component directory and stores the information (YAML manifests) about services and links there. When you use odo push, odo compares these manifests with the state of the resources on the Kubernetes cluster and decides whether it needs to create, modify or destroy resources to match what is specified by the user.

The --inlined flag

If you specify the --inlined flag to the odo link command, odo stores the link information inline in the devfile.yaml in the component directory, instead of creating a file under the kubernetes/ directory. The behavior of the --inlined flag is similar in both the odo link and odo service create commands. This flag is helpful if you want everything stored in a single devfile.yaml. You have to remember to use --inlined flag with each odo link and odo service create command that you execute for the component.

The --map flag

Sometimes, you might want to add more binding information to the component, in addition to what is available by default. For example, if you are linking the component with a service and would like to bind some information from the service’s spec (short for specification), you could use the --map flag. Note that odo does not do any validation against the spec of the service or component being linked. Using this flag is only recommended if you are comfortable using the Kubernetes YAML manifests.

The --bind-as-files flag

For all the linking options discussed so far, odo injects the binding information into the component as environment variables. If you would like to mount this information as files instead, you can use the --bind-as-files flag. This will make odo inject the binding information as files into the /bindings location within your component’s Pod. Compared to the environment variables scenario, when you use --bind-as-files, the files are named after the keys and the value of these keys is stored as the contents of these files.

Examples

In the following example, the backend component is linked with the PostgreSQL service using the default odo link command. For the backend component, make sure that your component and service are pushed to the cluster:

$ odo list
Sample output
APP     NAME        PROJECT       TYPE       STATE      MANAGED BY ODO
app     backend     myproject     spring     Pushed     Yes
$ odo service list
Sample output
NAME                      MANAGED BY ODO     STATE      AGE
PostgresCluster/hippo     Yes (backend)      Pushed     59m41s

Now, run odo link to link the backend component with the PostgreSQL service:

$ odo link PostgresCluster/hippo
Example output
 ✓  Successfully created link between component "backend" and service "PostgresCluster/hippo"

To apply the link, please use `odo push`

And then run odo push to actually create the link on the Kubernetes cluster.

After a successful odo push, you will see a few outcomes:

  1. When you open the URL for the application deployed by backend component, it shows a list of todo items in the database. For example, in the output for the odo url list command, the path where todos are listed is included:

    $ odo url list
    Sample output
    Found the following URLs for component backend
NAME         STATE      URL                                       PORT     SECURE     KIND
8080-tcp     Pushed     http://8080-tcp.192.168.39.112.nip.io     8080     false      ingress

    The correct path for the URL would be http://8080-tcp.192.168.39.112.nip.io/api/v1/todos. The exact URL depends on your setup. Also note that there are no todos in the database unless you add some, so the URL might just show an empty JSON object.

  2. You can see binding information related to the Postgres service injected into the backend component. This binding information is injected, by default, as environment variables. You can check it using the odo describe command from the backend component’s directory:

    $  odo describe
    Example output:
    Component Name: backend
Type: spring
Environment Variables:
  · PROJECTS_ROOT=/projects
  · PROJECT_SOURCE=/projects
  · DEBUG_PORT=5858
Storage:
  · m2 of size 3Gi mounted to /home/user/.m2
URLs:
  · http://8080-tcp.192.168.39.112.nip.io exposed via 8080
Linked Services:
  · PostgresCluster/hippo
    Environment Variables:
    · POSTGRESCLUSTER_PGBOUNCER-EMPTY
    · POSTGRESCLUSTER_PGBOUNCER.INI
    · POSTGRESCLUSTER_ROOT.CRT
    · POSTGRESCLUSTER_VERIFIER
    · POSTGRESCLUSTER_ID_ECDSA
    · POSTGRESCLUSTER_PGBOUNCER-VERIFIER
    · POSTGRESCLUSTER_TLS.CRT
    · POSTGRESCLUSTER_PGBOUNCER-URI
    · POSTGRESCLUSTER_PATRONI.CRT-COMBINED
    · POSTGRESCLUSTER_USER
    · pgImage
    · pgVersion
    · POSTGRESCLUSTER_CLUSTERIP
    · POSTGRESCLUSTER_HOST
    · POSTGRESCLUSTER_PGBACKREST_REPO.CONF
    · POSTGRESCLUSTER_PGBOUNCER-USERS.TXT
    · POSTGRESCLUSTER_SSH_CONFIG
    · POSTGRESCLUSTER_TLS.KEY
    · POSTGRESCLUSTER_CONFIG-HASH
    · POSTGRESCLUSTER_PASSWORD
    · POSTGRESCLUSTER_PATRONI.CA-ROOTS
    · POSTGRESCLUSTER_DBNAME
    · POSTGRESCLUSTER_PGBOUNCER-PASSWORD
    · POSTGRESCLUSTER_SSHD_CONFIG
    · POSTGRESCLUSTER_PGBOUNCER-FRONTEND.KEY
    · POSTGRESCLUSTER_PGBACKREST_INSTANCE.CONF
    · POSTGRESCLUSTER_PGBOUNCER-FRONTEND.CA-ROOTS
    · POSTGRESCLUSTER_PGBOUNCER-HOST
    · POSTGRESCLUSTER_PORT
    · POSTGRESCLUSTER_ROOT.KEY
    · POSTGRESCLUSTER_SSH_KNOWN_HOSTS
    · POSTGRESCLUSTER_URI
    · POSTGRESCLUSTER_PATRONI.YAML
    · POSTGRESCLUSTER_DNS.CRT
    · POSTGRESCLUSTER_DNS.KEY
    · POSTGRESCLUSTER_ID_ECDSA.PUB
    · POSTGRESCLUSTER_PGBOUNCER-FRONTEND.CRT
    · POSTGRESCLUSTER_PGBOUNCER-PORT
    · POSTGRESCLUSTER_CA.CRT

    Some of these variables are used in the backend component’s src/main/resources/application.properties file so that the Java Spring Boot application can connect to the PostgreSQL database service.

  3. Lastly, odo has created a directory called kubernetes/ in your backend component’s directory that contains the following files:

    $ ls kubernetes
odo-service-backend-postgrescluster-hippo.yaml  odo-service-hippo.yaml

    These files contain the information (YAML manifests) for two resources:

    1. odo-service-hippo.yaml - the Postgres service created using odo service create --from-file ../postgrescluster.yaml command.

    2. odo-service-backend-postgrescluster-hippo.yaml - the link created using odo link command.

Using the --inlined flag with the odo link command has the same effect as an odo link command without th