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:

  1. components:
  2. - image:
  3.     imageName: quay.io/myusername/myimage
  4.     dockerfile:
  5.       uri: ./Dockerfile (1)
  6.       buildContext: ${PROJECTS_ROOT} (2)
  7.   name: component-built-from-dockerfile
1The 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.
2The 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:

  1. $ odo catalog list components

Example output

  1.  NAME             DESCRIPTION                          REGISTRY
  2.  go               Stack with the latest Go version     DefaultDevfileRegistry
  3.  java-maven       Upstream Maven and OpenJDK 11        DefaultDevfileRegistry
  4.  nodejs           Stack with Node.js 14                DefaultDevfileRegistry
  5.  php-laravel      Stack with Laravel 8                 DefaultDevfileRegistry
  6.  python           Python Stack with Python 3.7         DefaultDevfileRegistry
  7.  [...]

Getting information about a component

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

  1. $ odo catalog describe component

For example, run the command:

  1. $ odo catalog describe component nodejs

Example output

  1. * Registry: DefaultDevfileRegistry (1)
  3. Starter Projects: (2)
  4. ---
  5. name: nodejs-starter
  6. attributes: {}
  7. description: ""
  8. subdir: ""
  9. projectsource:
  10.   sourcetype: ""
  11.   git:
  12.     gitlikeprojectsource:
  13.       commonprojectsource: {}
  14.       checkoutfrom: null
  15.       remotes:
  16.         origin: https://github.com/odo-devfiles/nodejs-ex.git
  17.   zip: null
  18.   custom: null
1Registry is the registry from which the devfile is retrieved.
2Starter 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:

  1. $ odo catalog list services

Example output

  1.  Services available through Operators
  2.  NAME                                 CRDs
  3.  postgresql-operator.v0.1.1           Backup, Database
  4.  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:

  1. $ odo catalog search service

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

  1. $ odo catalog search service postgres

Example output

  1.  Services available through Operators
  2.  NAME                           CRDs
  3.  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:

  1. $ odo catalog describe service

For example:

  1. $ odo catalog describe service postgresql-operator.v0.1.1/Database

Example output

  1. KIND:    Database
  2. VERSION: v1alpha1
  4. DESCRIPTION:
  5.      Database is the Schema for the the Database Database API
  7. FIELDS:
  8.    awsAccessKeyId (string)
  9.      AWS S3 accessKey/token ID
  11.      Key ID of AWS S3 storage. Default Value: nil Required to create the Secret
  12.      with the data to allow send the backup files to AWS S3 storage.
  13. [...]

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:

  1. $ odo catalog describe service redis-operator.v0.8.0

Example output

  1. NAME:    redis-operator.v0.8.0
  2. DESCRIPTION:
  4.     A Golang based redis operator that will make/oversee Redis
  5.     standalone/cluster mode setup on top of the Kubernetes. It can create a
  6.     redis cluster setup with best practices on Cloud as well as the Bare metal
  7.     environment. Also, it provides an in-built monitoring capability using
  9. ... (cut short for beverity)
  11.     Logging Operator is licensed under [Apache License, Version
  12.     2.0](https://github.com/OT-CONTAINER-KIT/redis-operator/blob/master/LICENSE)
  15. CRDs:
  16.     NAME           DESCRIPTION
  17.     RedisCluster   Redis Cluster
  18.     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):

  1. 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:

  1. 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:

  1. 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:

  1. odo catalog describe component nodejs

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

  1. 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:

  1. 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:

  1. $ odo create
  3. ? Which devfile component type do you wish to create go
  4. ? What do you wish to name the new devfile component go-api
  5. ? What project do you want the devfile component to be created in default
  6. Devfile Object Validation
  7.  ✓  Checking devfile existence [164258ns]
  8.  ✓  Creating a devfile component from registry: DefaultDevfileRegistry [246051ns]
  9. Validation
  10.  ✓  Validating if devfile name is correct [92255ns]
  11. ? Do you want to download a starter project Yes
  13. Starter Project
  14.  ✓  Downloading starter project go-starter from https://github.com/devfile-samples/devfile-stack-go.git [429ms]
  16. 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:

  1. $ 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:

  1. $ 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

  1. $ 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.

  1. schemaVersion: 2.2.0
  2. [...]
  3. variables:
  4.   CONTAINER_IMAGE: quay.io/phmartin/myimage
  5. commands:
  6.   - id: build-image
  7.     apply:
  8.       component: outerloop-build
  9.   - id: deployk8s
  10.     apply:
  11.       component: outerloop-deploy
  12.   - id: deploy
  13.     composite:
  14.       commands:
  15.         - build-image
  16.         - deployk8s
  17.       group:
  18.         kind: deploy
  19.         isDefault: true
  20. components:
  21.   - name: outerloop-build
  22.     image:
  23.       imageName: "{{CONTAINER_IMAGE}}"
  24.       dockerfile:
  25.         uri: ./Dockerfile
  26.         buildContext: ${PROJECTS_ROOT}
  27.   - name: outerloop-deploy
  28.     kubernetes:
  29.       inlined: |
  30.         kind: Deployment
  31.         apiVersion: apps/v1
  32.         metadata:
  33.           name: my-component
  34.         spec:
  35.           replicas: 1
  36.           selector:
  37.             matchLabels:
  38.               app: node-app
  39.           template:
  40.             metadata:
  41.               labels:
  42.                 app: node-app
  43.             spec:
  44.               containers:
  45.                 - name: main
  46.                   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

Default odo link

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:

  1. $ odo list

Sample output

  1. APP     NAME        PROJECT       TYPE       STATE      MANAGED BY ODO
  2. app     backend     myproject     spring     Pushed     Yes
  1. $ odo service list

Sample output

  1. NAME                      MANAGED BY ODO     STATE      AGE
  2. PostgresCluster/hippo     Yes (backend)      Pushed     59m41s

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

  1. $ odo link PostgresCluster/hippo

Example output

  1.  ✓  Successfully created link between component "backend" and service "PostgresCluster/hippo"
  3. 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:

    1. $ odo url list

    Sample output

    1. Found the following URLs for component backend
    2. NAME         STATE      URL                                       PORT     SECURE     KIND
    3. 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:

    1. $  odo describe

    Example output:

    1. Component Name: backend
    2. Type: spring
    3. Environment Variables:
    4.   · PROJECTS_ROOT=/projects
    5.   · PROJECT_SOURCE=/projects
    6.   · DEBUG_PORT=5858
    7. Storage:
    8.   · m2 of size 3Gi mounted to /home/user/.m2
    9. URLs:
    10.   · http://8080-tcp.192.168.39.112.nip.io exposed via 8080
    11. Linked Services:
    12.   · PostgresCluster/hippo
    13.     Environment Variables:
    14.     · POSTGRESCLUSTER_PGBOUNCER-EMPTY
    15.     · POSTGRESCLUSTER_PGBOUNCER.INI
    16.     · POSTGRESCLUSTER_ROOT.CRT
    17.     · POSTGRESCLUSTER_VERIFIER
    18.     · POSTGRESCLUSTER_ID_ECDSA
    19.     · POSTGRESCLUSTER_PGBOUNCER-VERIFIER
    20.     · POSTGRESCLUSTER_TLS.CRT
    21.     · POSTGRESCLUSTER_PGBOUNCER-URI
    22.     · POSTGRESCLUSTER_PATRONI.CRT-COMBINED
    23.     · POSTGRESCLUSTER_USER
    24.     · pgImage
    25.     · pgVersion
    26.     · POSTGRESCLUSTER_CLUSTERIP
    27.     · POSTGRESCLUSTER_HOST
    28.     · POSTGRESCLUSTER_PGBACKREST_REPO.CONF
    29.     · POSTGRESCLUSTER_PGBOUNCER-USERS.TXT
    30.     · POSTGRESCLUSTER_SSH_CONFIG
    31.     · POSTGRESCLUSTER_TLS.KEY
    32.     · POSTGRESCLUSTER_CONFIG-HASH
    33.     · POSTGRESCLUSTER_PASSWORD
    34.     · POSTGRESCLUSTER_PATRONI.CA-ROOTS
    35.     · POSTGRESCLUSTER_DBNAME
    36.     · POSTGRESCLUSTER_PGBOUNCER-PASSWORD
    37.     · POSTGRESCLUSTER_SSHD_CONFIG
    38.     · POSTGRESCLUSTER_PGBOUNCER-FRONTEND.KEY
    39.     · POSTGRESCLUSTER_PGBACKREST_INSTANCE.CONF
    40.     · POSTGRESCLUSTER_PGBOUNCER-FRONTEND.CA-ROOTS
    41.     · POSTGRESCLUSTER_PGBOUNCER-HOST
    42.     · POSTGRESCLUSTER_PORT
    43.     · POSTGRESCLUSTER_ROOT.KEY
    44.     · POSTGRESCLUSTER_SSH_KNOWN_HOSTS
    45.     · POSTGRESCLUSTER_URI
    46.     · POSTGRESCLUSTER_PATRONI.YAML
    47.     · POSTGRESCLUSTER_DNS.CRT
    48.     · POSTGRESCLUSTER_DNS.KEY
    49.     · POSTGRESCLUSTER_ID_ECDSA.PUB
    50.     · POSTGRESCLUSTER_PGBOUNCER-FRONTEND.CRT
    51.     · POSTGRESCLUSTER_PGBOUNCER-PORT
    52.     · 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:

    1. $ ls kubernetes
    2. 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 the flag, in that it injects binding information. However, the subtle difference is that in the above case, there are two manifest files under kubernetes/ directory, one for the Postgres service and another for the link between the backend component and this service. However, when you pass the --inlined flag, odo does not create a file under the kubernetes/ directory to store the YAML manifest, but rather stores it inline in the devfile.yaml file.

To see this, unlink the component from the PostgreSQL service first:

  1. $ odo unlink PostgresCluster/hippo

Example output:

  1.  ✓  Successfully unlinked component "backend" from service "PostgresCluster/hippo"
  3. To apply the changes, please use `odo push`

To unlink them on the cluster, run odo push. Now if you inspect the kubernetes/ directory, you see only one file:

  1. $ ls kubernetes
  2. odo-service-hippo.yaml

Next, use the --inlined flag to create a link:

  1. $ odo link PostgresCluster/hippo --inlined

Example output:

  1.  ✓  Successfully created link between component "backend" and service "PostgresCluster/hippo"
  3. To apply the link, please use `odo push`

You need to run odo push for the link to get created on the cluster, like the procedure that omits the --inlined flag. odo stores the configuration in devfile.yaml. In this file, you can see an entry like the following:

  1.  kubernetes:
  2.     inlined: |
  3.       apiVersion: binding.operators.coreos.com/v1alpha1
  4.       kind: ServiceBinding
  5.       metadata:
  6.         creationTimestamp: null
  7.         name: backend-postgrescluster-hippo
  8.       spec:
  9.         application:
  10.           group: apps
  11.           name: backend-app
  12.           resource: deployments
  13.           version: v1
  14.         bindAsFiles: false
  15.         detectBindingResources: true
  16.         services:
  17.         - group: postgres-operator.crunchydata.com
  18.           id: hippo
  19.           kind: PostgresCluster
  20.           name: hippo
  21.           version: v1beta1
  22.       status:
  23.         secret: ""
  24.   name: backend-postgrescluster-hippo

Now if you were to run odo unlink PostgresCluster/hippo, odo would first remove the link information from the devfile.yaml, and then a subsequent odo push would delete the link from the cluster.

Custom bindings

odo link accepts the flag --map which can inject custom binding information into the component. Such binding information will be fetched from the manifest of the resource that you are linking to your component. For example, in the context of the backend component and PostgreSQL service, you can inject information from the PostgreSQL service’s manifest postgrescluster.yaml file into the backend component.

If the name of your PostgresCluster service is hippo (or the output of odo service list, if your PostgresCluster service is named differently), when you want to inject the value of postgresVersion from that YAML definition into your backend component, run the command:

  1. $ odo link PostgresCluster/hippo --map pgVersion='{{ .hippo.spec.postgresVersion }}'

Note that, if the name of your Postgres service is different from hippo, you will have to specify that in the above command in the place of .hippo in the value for pgVersion.

After a link operation, run odo push as usual. Upon successful completion of the push operation, you can run the following command from your backend component directory, to validate if the custom mapping got injected properly:

  1. $ odo exec -- env | grep pgVersion

Example output:

  1. pgVersion=13

Since you might want to inject more than just one piece of custom binding information, odo link accepts multiple key-value pairs of mappings. The only constraint is that these should be specified as --map <key>=<value>. For example, if you want to also inject PostgreSQL image information along with the version, you could run:

  1. $ odo link PostgresCluster/hippo --map pgVersion='{{ .hippo.spec.postgresVersion }}' --map pgImage='{{ .hippo.spec.image }}'

and then run odo push. To validate if both the mappings got injected correctly, run the following command:

  1. $ odo exec -- env | grep -e "pgVersion\|pgImage"

Example output:

  1. pgVersion=13
  2. pgImage=registry.developers.crunchydata.com/crunchydata/crunchy-postgres-ha:centos8-13.4-0
To inline or not?

You can accept the default behavior where odo link generate a manifests file for the link under kubernetes/ directory. Alternatively, you can use the --inlined flag if you prefer to store everything in a single devfile.yaml file.

Binding as files

Another helpful flag that odo link provides is --bind-as-files. When this flag is passed, the binding information is not injected into the component’s Pod as environment variables but is mounted as a filesystem.

Ensure that there are no existing links between the backend component and the PostgreSQL service. You could do this by running odo describe in the backend component’s directory and check if you see output similar to the following:

  1. Linked Services:
  2.  · PostgresCluster/hippo

Unlink the service from the component using:

  1. $ odo unlink PostgresCluster/hippo
  2. $ odo push

--bind-as-files examples

By default, odo creates the manifest file under the kubernetes/ directory, for storing the link information. Link the backend component and PostgreSQL service using:

  1. $ odo link PostgresCluster/hippo --bind-as-files
  2. $ odo push

Example odo describe output:

  1. $ odo describe
  3. Component Name: backend
  4. Type: spring
  5. Environment Variables:
  6.  · PROJECTS_ROOT=/projects
  7.  · PROJECT_SOURCE=/projects
  8.  · DEBUG_PORT=5858
  9.  · SERVICE_BINDING_ROOT=/bindings
  10.  · SERVICE_BINDING_ROOT=/bindings
  11. Storage:
  12.  · m2 of size 3Gi mounted to /home/user/.m2
  13. URLs:
  14.  · http://8080-tcp.192.168.39.112.nip.io exposed via 8080
  15. Linked Services:
  16.  · PostgresCluster/hippo
  17.    Files:
  18.     · /bindings/backend-postgrescluster-hippo/pgbackrest_instance.conf
  19.     · /bindings/backend-postgrescluster-hippo/user
  20.     · /bindings/backend-postgrescluster-hippo/ssh_known_hosts
  21.     · /bindings/backend-postgrescluster-hippo/clusterIP
  22.     · /bindings/backend-postgrescluster-hippo/password
  23.     · /bindings/backend-postgrescluster-hippo/patroni.yaml
  24.     · /bindings/backend-postgrescluster-hippo/pgbouncer-frontend.crt
  25.     · /bindings/backend-postgrescluster-hippo/pgbouncer-host
  26.     · /bindings/backend-postgrescluster-hippo/root.key
  27.     · /bindings/backend-postgrescluster-hippo/pgbouncer-frontend.key
  28.     · /bindings/backend-postgrescluster-hippo/pgbouncer.ini
  29.     · /bindings/backend-postgrescluster-hippo/uri
  30.     · /bindings/backend-postgrescluster-hippo/config-hash
  31.     · /bindings/backend-postgrescluster-hippo/pgbouncer-empty
  32.     · /bindings/backend-postgrescluster-hippo/port
  33.     · /bindings/backend-postgrescluster-hippo/dns.crt
  34.     · /bindings/backend-postgrescluster-hippo/pgbouncer-uri
  35.     · /bindings/backend-postgrescluster-hippo/root.crt
  36.     · /bindings/backend-postgrescluster-hippo/ssh_config
  37.     · /bindings/backend-postgrescluster-hippo/dns.key
  38.     · /bindings/backend-postgrescluster-hippo/host
  39.     · /bindings/backend-postgrescluster-hippo/patroni.crt-combined
  40.     · /bindings/backend-postgrescluster-hippo/pgbouncer-frontend.ca-roots
  41.     · /bindings/backend-postgrescluster-hippo/tls.key
  42.     · /bindings/backend-postgrescluster-hippo/verifier
  43.     · /bindings/backend-postgrescluster-hippo/ca.crt
  44.     · /bindings/backend-postgrescluster-hippo/dbname
  45.     · /bindings/backend-postgrescluster-hippo/patroni.ca-roots
  46.     · /bindings/backend-postgrescluster-hippo/pgbackrest_repo.conf
  47.     · /bindings/backend-postgrescluster-hippo/pgbouncer-port
  48.     · /bindings/backend-postgrescluster-hippo/pgbouncer-verifier
  49.     · /bindings/backend-postgrescluster-hippo/id_ecdsa
  50.     · /bindings/backend-postgrescluster-hippo/id_ecdsa.pub
  51.     · /bindings/backend-postgrescluster-hippo/pgbouncer-password
  52.     · /bindings/backend-postgrescluster-hippo/pgbouncer-users.txt
  53.     · /bindings/backend-postgrescluster-hippo/sshd_config
  54.     · /bindings/backend-postgrescluster-hippo/tls.crt

Everything that was an environment variable in the key=value format in the earlier odo describe output is now mounted as a file. Use the cat command to view the contents of some of these files:

Example command:

  1. $ odo exec -- cat /bindings/backend-postgrescluster-hippo/password

Example output:

  1. q({JC:jn^mm/Bw}eu+j.GX{k

Example command:

  1. $ odo exec -- cat /bindings/backend-postgrescluster-hippo/user

Example output:

  1. hippo

Example command:

  1. $ odo exec -- cat /bindings/backend-postgrescluster-hippo/clusterIP

Example output:

  1. 10.101.78.56

Using --inlined

The result of using --bind-as-files and --inlined together is similar to using odo link --inlined. The manifest of the link gets stored in the devfile.yaml, instead of being stored in a separate file under kubernetes/ directory. Other than that, the odo describe output would be the same as earlier.

Custom bindings

When you pass custom bindings while linking the backend component with the PostgreSQL service, these custom bindings are injected not as environment variables but are mounted as files. For example:

  1. $ odo link PostgresCluster/hippo --map pgVersion='{{ .hippo.spec.postgresVersion }}' --map pgImage='{{ .hippo.spec.image }}' --bind-as-files
  2. $ odo push

These custom bindings get mounted as files instead of being injected as environment variables. To validate that this worked, run the following command:

Example command:

  1. $ odo exec -- cat /bindings/backend-postgrescluster-hippo/pgVersion

Example output:

  1. 13

Example command:

  1. $ odo exec -- cat /bindings/backend-postgrescluster-hippo/pgImage

Example output:

  1. registry.developers.crunchydata.com/crunchydata/crunchy-postgres-ha:centos8-13.4-0

odo registry

odo uses the portable devfile format to describe the components. odo can connect to various devfile registries, to download devfiles for different languages and frameworks.

You can connect to publicly available devfile registries, or you can install your own Secure Registry.

You can use the odo registry command to manage the registries that are used by odo to retrieve devfile information.

Listing the registries

To list the registries currently contacted by odo, run the command:

  1. $ odo registry list

Example output:

  1. NAME                       URL                             SECURE
  2. DefaultDevfileRegistry     https://registry.devfile.io     No

DefaultDevfileRegistry is the default registry used by odo; it is provided by the devfile.io project.

Adding a registry

To add a registry, run the command:

  1. $ odo registry add

Example output:

  1. $ odo registry add StageRegistry https://registry.stage.devfile.io
  2. New registry successfully added

If you are deploying your own Secure Registry, you can specify the personal access token to authenticate to the secure registry with the --token flag:

  1. $ odo registry add MyRegistry https://myregistry.example.com --token <access_token>
  2. New registry successfully added

Deleting a registry

To delete a registry, run the command:

  1. $ odo registry delete

Example output:

  1. $ odo registry delete StageRegistry
  2. ? Are you sure you want to delete registry "StageRegistry" Yes
  3. Successfully deleted registry

Use the --force (or -f) flag to force the deletion of the registry without confirmation.

Updating a registry

To update the URL or the personal access token of a registry already registered, run the command:

  1. $ odo registry update

Example output:

  1.  $ odo registry update MyRegistry https://otherregistry.example.com --token <other_access_token>
  2.  ? Are you sure you want to update registry "MyRegistry" Yes
  3.  Successfully updated registry

Use the --force (or -f) flag to force the update of the registry without confirmation.

odo service

odo can deploy services with the help of Operators.

The list of available Operators and services available for installation can be found using the odo catalog command.

Services are created in the context of a component, so run the odo create command before you deploy services.

A service is deployed using two steps:

  1. Define the service and store its definition in the devfile.

  2. Deploy the defined service to the cluster, using the odo push command.

Creating a new service

To create a new service, run the command:

  1. $ odo service create

For example, to create an instance of a Redis service named my-redis-service, you can run the following command:

Example output

  1. $ odo catalog list services
  2. Services available through Operators
  3. NAME                      CRDs
  4. redis-operator.v0.8.0     RedisCluster, Redis
  6. $ odo service create redis-operator.v0.8.0/Redis my-redis-service
  7. Successfully added service to the configuration; do 'odo push' to create service on the cluster

This command creates a Kubernetes manifest in the kubernetes/ directory, containing the definition of the service, and this file is referenced from the devfile.yaml file.

  1. $ cat kubernetes/odo-service-my-redis-service.yaml

Example output

  1.  apiVersion: redis.redis.opstreelabs.in/v1beta1
  2.  kind: Redis
  3.  metadata:
  4.    name: my-redis-service
  5.  spec:
  6.    kubernetesConfig:
  7.      image: quay.io/opstree/redis:v6.2.5
  8.      imagePullPolicy: IfNotPresent
  9.      resources:
  10.        limits:
  11.          cpu: 101m
  12.          memory: 128Mi
  13.        requests:
  14.          cpu: 101m
  15.          memory: 128Mi
  16.      serviceType: ClusterIP
  17.    redisExporter:
  18.      enabled: false
  19.      image: quay.io/opstree/redis-exporter:1.0
  20.    storage:
  21.      volumeClaimTemplate:
  22.        spec:
  23.          accessModes:
  24.          - ReadWriteOnce
  25.          resources:
  26.            requests:
  27.              storage: 1Gi

Example command

  1. $ cat devfile.yaml

Example output

  1. [...]
  2. components:
  3. - kubernetes:
  4.     uri: kubernetes/odo-service-my-redis-service.yaml
  5.   name: my-redis-service
  6. [...]

Note that the name of the created instance is optional. If you do not provide a name, it will be the lowercase name of the service. For example, the following command creates an instance of a Redis service named redis:

  1. $ odo service create redis-operator.v0.8.0/Redis

Inlining the manifest

By default, a new manifest is created in the kubernetes/ directory, referenced from the devfile.yaml file. It is possible to inline the manifest inside the devfile.yaml file using the --inlined flag:

  1. $ odo service create redis-operator.v0.8.0/Redis my-redis-service --inlined
  2. Successfully added service to the configuration; do 'odo push' to create service on the cluster

Example command

  1. $ cat devfile.yaml

Example output

  1. [...]
  2. components:
  3. - kubernetes:
  4.     inlined: |
  5.       apiVersion: redis.redis.opstreelabs.in/v1beta1
  6.       kind: Redis
  7.       metadata:
  8.         name: my-redis-service
  9.       spec:
  10.         kubernetesConfig:
  11.           image: quay.io/opstree/redis:v6.2.5
  12.           imagePullPolicy: IfNotPresent
  13.           resources:
  14.             limits:
  15.               cpu: 101m
  16.               memory: 128Mi
  17.             requests:
  18.               cpu: 101m
  19.               memory: 128Mi
  20.           serviceType: ClusterIP
  21.         redisExporter:
  22.           enabled: false
  23.           image: quay.io/opstree/redis-exporter:1.0
  24.         storage:
  25.           volumeClaimTemplate:
  26.             spec:
  27.               accessModes:
  28.               - ReadWriteOnce
  29.               resources:
  30.                 requests:
  31.                   storage: 1Gi
  32.   name: my-redis-service
  33. [...]

Configuring the service

Without specific customization, the service will be created with a default configuration. You can use either command-line arguments or a file to specify your own configuration.

Using command-line arguments

Use the --parameters (or -p) flag to specify your own configuration.

The following example configures the Redis service with three parameters:

  1. $ odo service create redis-operator.v0.8.0/Redis my-redis-service \
  2.     -p kubernetesConfig.image=quay.io/opstree/redis:v6.2.5 \
  3.     -p kubernetesConfig.serviceType=ClusterIP \
  4.     -p redisExporter.image=quay.io/opstree/redis-exporter:1.0
  5. Successfully added service to the configuration; do 'odo push' to create service on the cluster

Example command

  1. $ cat kubernetes/odo-service-my-redis-service.yaml

Example output

  1. apiVersion: redis.redis.opstreelabs.in/v1beta1
  2. kind: Redis
  3. metadata:
  4.   name: my-redis-service
  5. spec:
  6.   kubernetesConfig:
  7.     image: quay.io/opstree/redis:v6.2.5
  8.     serviceType: ClusterIP
  9.   redisExporter:
  10.     image: quay.io/opstree/redis-exporter:1.0

You can obtain the possible parameters for a specific service using the odo catalog describe service command.

Using a file

Use a YAML manifest to configure your own specification. In the following example, the Redis service is configured with three parameters.

  1. Create a manifest:

    1. $ cat > my-redis.yaml <<EOF
    2. apiVersion: redis.redis.opstreelabs.in/v1beta1
    3. kind: Redis
    4. metadata:
    5.   name: my-redis-service
    6. spec:
    7.   kubernetesConfig:
    8.     image: quay.io/opstree/redis:v6.2.5
    9.     serviceType: ClusterIP
    10.   redisExporter:
    11.     image: quay.io/opstree/redis-exporter:1.0
    12. EOF

  2. Create the service from the manifest:

    1. $ odo service create --from-file my-redis.yaml
    2. Successfully added service to the configuration; do 'odo push' to create service on the cluster

Deleting a service

To delete a service, run the command:

  1. $ odo service delete

Example output

  1. $ odo service list
  2. NAME                       MANAGED BY ODO     STATE               AGE
  3. Redis/my-redis-service     Yes (api)          Deleted locally     5m39s
  1. $ odo service delete Redis/my-redis-service
  2. ? Are you sure you want to delete Redis/my-redis-service Yes
  3. Service "Redis/my-redis-service" has been successfully deleted; do 'odo push' to delete service from the cluster

Use the --force (or -f) flag to force the deletion of the service without confirmation.

Listing services

To list the services created for your component, run the command:

  1. $ odo service list

Example output

  1. $ odo service list
  2. NAME                       MANAGED BY ODO     STATE             AGE
  3. Redis/my-redis-service-1   Yes (api)          Not pushed
  4. Redis/my-redis-service-2   Yes (api)          Pushed            52s
  5. Redis/my-redis-service-3   Yes (api)          Deleted locally   1m22s

For each service, STATE indicates if the service has been pushed to the cluster using the odo push command, or if the service is still running on the cluster but removed from the devfile locally using the odo service delete command.

Getting information about a service

To get details of a service such as its kind, version, name, and list of configured parameters, run the command:

  1. $ odo service describe

Example output

  1. $ odo service describe Redis/my-redis-service
  2. Version: redis.redis.opstreelabs.in/v1beta1
  3. Kind: Redis
  4. Name: my-redis-service
  5. Parameters:
  6. NAME                           VALUE
  7. kubernetesConfig.image         quay.io/opstree/redis:v6.2.5
  8. kubernetesConfig.serviceType   ClusterIP
  9. redisExporter.image            quay.io/opstree/redis-exporter:1.0

odo storage

odo lets users manage storage volumes that are attached to the components. A storage volume can be either an ephemeral volume using an emptyDir Kubernetes volume, or a Persistent Volume Claim (PVC). A PVC allows users to claim a persistent volume (such as a GCE PersistentDisk or an iSCSI volume) without understanding the details of the particular cloud environment. The persistent storage volume can be used to persist data across restarts and rebuilds of the component.

Adding a storage volume

To add a storage volume to the cluster, run the command:

  1. $ odo storage create

Example output:

  1. $ odo storage create store --path /data --size 1Gi
  2. ✓  Added storage store to nodejs-project-ufyy
  4. $ odo storage create tempdir --path /tmp --size 2Gi --ephemeral
  5. ✓  Added storage tempdir to nodejs-project-ufyy
  7. Please use `odo push` command to make the storage accessible to the component

In the above example, the first storage volume has been mounted to the /data path and has a size of 1Gi, and the second volume has been mounted to /tmp and is ephemeral.

Listing the storage volumes

To check the storage volumes currently used by the component, run the command:

  1. $ odo storage list

Example output:

  1. $ odo storage list
  2. The component 'nodejs-project-ufyy' has the following storage attached:
  3. NAME      SIZE     PATH      STATE
  4. store     1Gi      /data     Not Pushed
  5. tempdir   2Gi      /tmp      Not Pushed

Deleting a storage volume

To delete a storage volume, run the command:

  1. $ odo storage delete

Example output:

  1. $ odo storage delete store -f
  2. Deleted storage store from nodejs-project-ufyy
  4. Please use `odo push` command to delete the storage from the cluster

In the above example, using the -f flag force deletes the storage without asking user permission.

Adding storage to specific container

If your devfile has multiple containers, you can specify which container you want the storage to attach to, using the --container flag in the odo storage create command.

The following example is an excerpt from a devfile with multiple containers :

  1. components:
  2.   - name: nodejs1
  3.     container:
  4.       image: registry.access.redhat.com/ubi8/nodejs-12:1-36
  5.       memoryLimit: 1024Mi
  6.       endpoints:
  7.         - name: "3000-tcp"
  8.           targetPort: 3000
  9.       mountSources: true
  10.   - name: nodejs2
  11.     container:
  12.       image: registry.access.redhat.com/ubi8/nodejs-12:1-36
  13.       memoryLimit: 1024Mi

In the example, there are two containers,nodejs1 and nodejs2. To attach storage to the nodejs2 container, use the following command:

  1. $ odo storage create --container

Example output:

  1. $ odo storage create store --path /data --size 1Gi --container nodejs2
  2. ✓  Added storage store to nodejs-testing-xnfg
  4. Please use `odo push` command to make the storage accessible to the component

You can list the storage resources, using the odo storage list command:

  1. $ odo storage list

Example output:

  1. The component 'nodejs-testing-xnfg' has the following storage attached:
  2. NAME      SIZE     PATH      CONTAINER     STATE
  3. store     1Gi      /data     nodejs2       Not Pushed

Common flags

The following flags are available with most odo commands:

Table 1. odo flags
CommandDescription

—context

Set the context directory where the component is defined.

—project

Set the project for the component. Defaults to the project defined in the local configuration. If none is available, then current project on the cluster.

—app

Set the application of the component. Defaults to the application defined in the local configuration. If none is available, then app.

—kubeconfig

Set the path to the kubeconfig value if not using the default configuration.

—show-log

Use this flag to see the logs.

-f, —force

Use this flag to tell the command not to prompt the user for confirmation.

-v, —v

Set the verbosity level. See Logging in odo for more information.

-h, —help

Output the help for a command.

Some flags might not be available for some commands. Run the command with the —help flag to get a list of all the available flags.

JSON output

The odo commands that output content generally accept a -o json flag to output this content in JSON format, suitable for other programs to parse this output more easily.

The output structure is similar to Kubernetes resources, with the kind, apiVersion, metadata, spec, and status fields.

List commands return a List resource, containing an items (or similar) field listing the items of the list, with each item also being similar to Kubernetes resources.

Delete commands return a Status resource; see the Status Kubernetes resource.

Other commands return a resource associated with the command, for example, Application, Storage, URL, and so on.

The full list of commands currently accepting the -o json flag is:

CommandsKind (version)Kind (version) of list itemsComplete content?

odo application describe

Application (odo.dev/v1alpha1)

n/a

no

odo application list

List (odo.dev/v1alpha1)

Application (odo.dev/v1alpha1)

?

odo catalog list components

List (odo.dev/v1alpha1)

missing

yes

odo catalog list services

List (odo.dev/v1alpha1)

ClusterServiceVersion (operators.coreos.com/v1alpha1)

?

odo catalog describe component

missing

n/a

yes

odo catalog describe service

CRDDescription (odo.dev/v1alpha1)

n/a

yes

odo component create

Component (odo.dev/v1alpha1)

n/a

yes

odo component describe

Component (odo.dev/v1alpha1)

n/a

yes

odo component list

List (odo.dev/v1alpha1)

Component (odo.dev/v1alpha1)

yes

odo config view

DevfileConfiguration (odo.dev/v1alpha1)

n/a

yes

odo debug info

OdoDebugInfo (odo.dev/v1alpha1)

n/a

yes

odo env view

EnvInfo (odo.dev/v1alpha1)

n/a

yes

odo preference view

PreferenceList (odo.dev/v1alpha1)

n/a

yes

odo project create

Project (odo.dev/v1alpha1)

n/a

yes

odo project delete

Status (v1)

n/a

yes

odo project get

Project (odo.dev/v1alpha1)

n/a

yes

odo project list

List (odo.dev/v1alpha1)

Project (odo.dev/v1alpha1)

yes

odo registry list

List (odo.dev/v1alpha1)

missing

yes

odo service create

Service

n/a

yes

odo service describe

Service

n/a

yes

odo service list

List (odo.dev/v1alpha1)

Service

yes

odo storage create

Storage (odo.dev/v1alpha1)

n/a

yes

odo storage delete

Status (v1)

n/a

yes

odo storage list

List (odo.dev/v1alpha1)

Storage (odo.dev/v1alpha1)

yes

odo url list

List (odo.dev/v1alpha1)

URL (odo.dev/v1alpha1)

yes