Chapter 3. Developer CLI (odo)

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

$ odo catalog list components

 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
 [...]

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

* 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

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

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

$ odo catalog list services

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

 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.

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

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

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

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.

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.

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.

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.

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

APP     NAME        PROJECT       TYPE       STATE      MANAGED BY ODO
app     backend     myproject     spring     Pushed     Yes

$ odo service list

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

 ✓  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:

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:

$ odo unlink PostgresCluster/hippo

 ✓  Successfully unlinked component "backend" from service "PostgresCluster/hippo"

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:

$ ls kubernetes
odo-service-hippo.yaml

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

$ odo link PostgresCluster/hippo --inlined

 ✓  Successfully created link between component "backend" and service "PostgresCluster/hippo"

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:

 kubernetes:
    inlined: |
      apiVersion: binding.operators.coreos.com/v1alpha1
      kind: ServiceBinding
      metadata:
        creationTimestamp: null
        name: backend-postgrescluster-hippo
      spec:
        application:
          group: apps
          name: backend-app
          resource: deployments
          version: v1
        bindAsFiles: false
        detectBindingResources: true
        services:
        - group: postgres-operator.crunchydata.com
          id: hippo
          kind: PostgresCluster
          name: hippo
          version: v1beta1
      status:
        secret: ""
  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.

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:

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

$ odo exec -- env | grep pgVersion

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:

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

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

pgVersion=13
pgImage=registry.developers.crunchydata.com/crunchydata/crunchy-postgres-ha:centos8-13.4-0

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

$ odo link PostgresCluster/hippo --bind-as-files
$ odo push

$ odo describe

Component Name: backend
Type: spring
Environment Variables:
 · PROJECTS_ROOT=/projects
 · PROJECT_SOURCE=/projects
 · DEBUG_PORT=5858
 · SERVICE_BINDING_ROOT=/bindings
 · SERVICE_BINDING_ROOT=/bindings
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
   Files:
    · /bindings/backend-postgrescluster-hippo/pgbackrest_instance.conf
    · /bindings/backend-postgrescluster-hippo/user
    · /bindings/backend-postgrescluster-hippo/ssh_known_hosts
    · /bindings/backend-postgrescluster-hippo/clusterIP
    · /bindings/backend-postgrescluster-hippo/password
    · /bindings/backend-postgrescluster-hippo/patroni.yaml
    · /bindings/backend-postgrescluster-hippo/pgbouncer-frontend.crt
    · /bindings/backend-postgrescluster-hippo/pgbouncer-host
    · /bindings/backend-postgrescluster-hippo/root.key
    · /bindings/backend-postgrescluster-hippo/pgbouncer-frontend.key
    · /bindings/backend-postgrescluster-hippo/pgbouncer.ini
    · /bindings/backend-postgrescluster-hippo/uri
    · /bindings/backend-postgrescluster-hippo/config-hash
    · /bindings/backend-postgrescluster-hippo/pgbouncer-empty
    · /bindings/backend-postgrescluster-hippo/port
    · /bindings/backend-postgrescluster-hippo/dns.crt
    · /bindings/backend-postgrescluster-hippo/pgbouncer-uri
    · /bindings/backend-postgrescluster-hippo/root.crt
    · /bindings/backend-postgrescluster-hippo/ssh_config
    · /bindings/backend-postgrescluster-hippo/dns.key
    · /bindings/backend-postgrescluster-hippo/host
    · /bindings/backend-postgrescluster-hippo/patroni.crt-combined
    · /bindings/backend-postgrescluster-hippo/pgbouncer-frontend.ca-roots
    · /bindings/backend-postgrescluster-hippo/tls.key
    · /bindings/backend-postgrescluster-hippo/verifier
    · /bindings/backend-postgrescluster-hippo/ca.crt
    · /bindings/backend-postgrescluster-hippo/dbname
    · /bindings/backend-postgrescluster-hippo/patroni.ca-roots
    · /bindings/backend-postgrescluster-hippo/pgbackrest_repo.conf
    · /bindings/backend-postgrescluster-hippo/pgbouncer-port
    · /bindings/backend-postgrescluster-hippo/pgbouncer-verifier
    · /bindings/backend-postgrescluster-hippo/id_ecdsa
    · /bindings/backend-postgrescluster-hippo/id_ecdsa.pub
    · /bindings/backend-postgrescluster-hippo/pgbouncer-password
    · /bindings/backend-postgrescluster-hippo/pgbouncer-users.txt
    · /bindings/backend-postgrescluster-hippo/sshd_config
    · /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:

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

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

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

hippo

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

10.101.78.56

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.

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:

$ odo link PostgresCluster/hippo --map pgVersion='{{ .hippo.spec.postgresVersion }}' --map pgImage='{{ .hippo.spec.image }}' --bind-as-files
$ 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:

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

13

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

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

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:

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

$ cat devfile.yaml

[...]
components:
- kubernetes:
    inlined: |
      apiVersion: redis.redis.opstreelabs.in/v1beta1
      kind: Redis
      metadata:
        name: my-redis-service
      spec:
        kubernetesConfig:
          image: quay.io/opstree/redis:v6.2.5
          imagePullPolicy: IfNotPresent
          resources:
            limits:
              cpu: 101m
              memory: 128Mi
            requests:
              cpu: 101m
              memory: 128Mi
          serviceType: ClusterIP
        redisExporter:
          enabled: false
          image: quay.io/opstree/redis-exporter:1.0
        storage:
          volumeClaimTemplate:
            spec:
              accessModes:
              - ReadWriteOnce
              resources:
                requests:
                  storage: 1Gi
  name: my-redis-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.

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

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

apiVersion: redis.redis.opstreelabs.in/v1beta1
kind: Redis
metadata:
  name: my-redis-service
spec:
  kubernetesConfig:
    image: quay.io/opstree/redis:v6.2.5
    serviceType: ClusterIP
  redisExporter:
    image: quay.io/opstree/redis-exporter:1.0