DEV Community: Philippe MARTIN

odo v3, a new version of odo based on devfiles

Philippe MARTIN — Mon, 02 May 2022 13:51:52 +0000

odo is a tool that aims to simplify the life of developers working on cloud-native applications.

Thanks to the emergence of the devfile open standard, which has been accepted as a CNCF Sandbox project recently (in January 2022), odo v3 is now entirely based on this open standard.

The goal of the devfile standard is to define the structure of applications and how developers can work on them.

A single devfile defines the smallest building block of an application, that a developer can build, run, test, debug and deploy. In a cloud-native environment, we generally talk about a micro-service.

Firstly, the devfile describes the container that is needed to be deployed on a cluster during the development phases, along with the commands to execute on this container to build, run, test and debug the program, assuming the sources have been synchronized into the container.

Secondly, the devfile provides the instructions to build the container image ready for production, along with the Kubernetes resources to deploy to the cluster.

An example of devfile

To illustrate, here is a simple yet complete devfile, usable for a NodeJS micro-service:

schemaVersion: 2.2.0
metadata:
  description: Stack with NodeJS 12
  displayName: NodeJS Runtime
  language: nodejs
  name: my-nodejs-app
  projectType: nodejs
variables:
  CONTAINER_IMAGE: quay.io/phmartin/myimage
components:
- name: runtime
  container:
    endpoints:
    - name: http-3000
      targetPort: 3000
    - name: debug-5858
      targetPort: 5858
    image: registry.access.redhat.com/ubi8/nodejs-14:latest
    memoryLimit: 1024Mi
    mountSources: true
    sourceMapping: /project
- name: outerloop-build
  image:
    dockerfile:
      buildContext: ${PROJECT_ROOT}
      rootRequired: false
      uri: ./Dockerfile
    imageName: "{{CONTAINER_IMAGE}}"
- name: outerloop-deployment
  kubernetes:
    inlined: |
      kind: Deployment
      apiVersion: apps/v1
      metadata:
        name: my-node
      spec:
        replicas: 1
        selector:
          matchLabels:
            app: node-app
        template:
          metadata:
            labels:
              app: node-app
          spec:
            containers:
              - name: my-node
                image: {{CONTAINER_IMAGE}}
                ports:
                  - name: http
                    containerPort: 3001
                    protocol: TCP
                resources:
                  limits:
                    memory: "1024Mi"
                    cpu: "500m"
- name: outerloop-service
  kubernetes:
    inlined: |
      apiVersion: v1
      kind: Service
      metadata:
        name: svc
      spec:
        ports:
        - name: "3000"
          port: 3000
          protocol: TCP
          targetPort: 3000
        selector:
          app: node-app
        type: ClusterIP
commands:
- id: install
  exec:
    commandLine: npm install
    component: runtime
    group:
      isDefault: true
      kind: build
    workingDir: /project
- id: run
  exec:
    commandLine: npm start
    component: runtime
    group:
      isDefault: true
      kind: run
    workingDir: /project
- id: debug
  exec:
    commandLine: npm run debug
    component: runtime
    group:
      isDefault: true
      kind: debug
    workingDir: /project
- id: test
  exec:
    commandLine: npm test
    component: runtime
    group:
      isDefault: true
      kind: test
    workingDir: /project
- id: deploy
  composite:
    commands:
    - build-image
    - k8s-deployment
    - k8s-service
    group:
      isDefault: true
      kind: deploy
- id: build-image
  apply:
    component: outerloop-build
- id: k8s-deployment
  apply:
    component: outerloop-deployment
- id: k8s-service
  apply:
    component: outerloop-service
starterProjects:
- name: nodejs-starter
  git:
    remotes:
      origin: https://github.com/odo-devfiles/nodejs-ex.git

The runtime component defines the container that will be deployed to support the program in development. Specifically, it will use the image registry.access.redhat.com/ubi8/nodejs-14:latest, and sources should be placed in the /project directory of the container. Two endpoints are also defined, one to access the micro-service, the other to help the debugger attach to the process, during debugging sessions.

The commands install, run, debug and test indicate which commands to execute to respectively build, execute, debug and test the application. For example, the npm install command will be executed in the container to build the application, then npm start will be executed to start the application.

To deploy the micro-service, the component outerloop-build indicates how to build the production image (by using ./Dockerfile, and creating an image whose name is defined by the variable CONTAINER_IMAGE defined at the beginning of the devfile). then, two other components outerloop-deployment and outerloop-service define the Kubernetes resources to deploy to the cluster. Note that the first one defines a Deployment that will help deploy a container using the image built with the previous outerloop-build component.

The starterProjects section at the end of the devfile indicates a list of starter projects, that can be downloaded to have an example of program deployable with this devfile.

Devfile registry

We can see through the previous example that a devfile is generic enough, with only a few specific values, like the endpoints and the image names. A devfile written for a specific language and framework can be used by most of the programs written using this language and framework, with minimum personalization.

A devfile registry is available at https://registry.devfile.io, containing devfiles for a large variety of languages and frameworks, and you can deploy your own registry to make accessible your own devfiles.

Introducing odo v3

You can find the instructions to install odo v3-alpha1 from this release page. The binaries are accessible here.

Initializing a project

The odo init command is the first command to use, before to start using odo with your project. The goal of this first step is to get a suitable devfile for your project.

odo init will search for devfiles into devfile registries. By default, odo is configured to access only one devfile registry (the one specified above), and you can modify the devfile registries odo is accessing using the command odo preference registry.

This odo init command offers two modes, either interactive, or manual. The interactive mode will help you discover the appropriate devfile. To use the interactive mode, you just need to enter odo init in your command line.

If you execute this command from a directory containing sources, odo will try to recognize the language and framework you are using, will search into the devfile registries you have configured the most appropriate devfile, and give you the choice to use this one, or to search for another one.

$ odo init
  __
 /  \__     Initializing new component
 \__/  \    Files: Source code detected, a Devfile will be determined based upon source code autodetection
 /  \__/    odo version: v3.0.0-alpha1
 \__/

Interactive mode enabled, please answer the following questions:
Based on the files in the current directory odo detected
Language: javascript
Project type: nodejs
The devfile "nodejs" from the registry "DefaultDevfileRegistry" will be downloaded.
? Is this correct? (Y/n)

If you answer No here, or if you run the odo init command from an empty directory, odo init will help you choose the appropriate devfile. The command will also help you make some personalization on the devfile, by personalizing the endpoints and the environment variables for the container that will be deployed during the development phase.

? Select language: javascript
? Select project type: Node.js Runtime
 ✓  Downloading devfile "nodejs" from registry "DefaultDevfileRegistry" [961ms]
Current component configuration:
Container "runtime":
  Opened ports:
   - 3000
  Environment variables:
? Select container for which you want to change configuration? NONE - configuration is correct
? Enter component name: my-nodejs-app

Your new component 'my-nodejs-app' is ready in the current directory.
To start editing your component, use 'odo dev' and open this folder in your favorite IDE.
Changes will be directly reflected on the cluster.

Finally, if you start the odo init command from an empty directory, it will give you the choice to download one of the starter projects listed in the devfile.

The development phase

Now that a devfile is present in the current directory, you can run your application in development mode, using the odo dev command. This command will create a Deployment in the cluster that will help start a container as defined in the devfile. Then, the sources present in the current directory will be synchronized into the container, and the commands to build and run the application will be exectued from inside the container.

At the same time, a port-forwarding will be done for each endpoint defined in the devfile, so you can access the container ports through local ports in your development machine.

Finally, odo will watch for changes in the current directory. When files are modified, added or deleted, odo will synchronize the changes to the container, and will restart the build and run commands from inside the container.

$ odo dev
  __
 /  \__     Developing using the my-nodejs-app Devfile
 \__/  \    Namespace: prj2
 /  \__/    odo version: v3.0.0-alpha1
 \__/

↪ Deploying to the cluster in developer mode
 ✓  Waiting for Kubernetes resources [6s]
 ✓  Syncing files into the container [439ms]
 ✓  Building your application in container on cluster [3s]
 ✓  Executing the application [1s]

Your application is now running on the cluster
 - Forwarding from 127.0.0.1:40001 -> 3000
 - Forwarding from 127.0.0.1:40002 -> 5858

Watching for changes in the current directory /home/phmartin/Documents/tests/devto-deploy
Press Ctrl+c to exit `odo dev` and delete resources from the cluster

To be able to debug the application, you will need to run the odo dev --debug command instead.

When you have finished the development session, you just need to hit Ctrl-c to stop the odo dev command. The command won't terminate immediately, as it will delete the resources it has deployed on the cluster before to exit.

The deployment phase

When you are satisfied with your program, you may want to deploy it by building the container image using a Dockerfile, instead of using a generic image as during the development phase, and by deploying into the cluster personalized resources, instead of the Deployment used during the development phase.

At the time of writing, no devfile of the default devfile registry contains instructions for the deployment phase. By using the devfile provided as example above, the command odo deploy will deploy a personalized Deployment and a Service into the cluster, after building the container image using the Dockerfile present in the directory.

$ odo deploy
  __
 /  \__     Deploying the application using my-nodejs-app Devfile
 \__/  \    Namespace: prj2
 /  \__/    odo version: v3.0.0-alpha1
 \__/

↪ Building & Pushing Container: quay.io/phmartin/myimage
 •  Building image locally  ...
STEP 1/7: FROM docker.io/library/node:17
STEP 2/7: WORKDIR /usr/src/app
[...]
STEP 7/7: CMD [ "node", "server.js" ]
COMMIT quay.io/phmartin/myimage
 ✓  Building image locally [6s]
 •  Pushing image to container registry  ...
[...]
Writing manifest to image destination
Storing signatures
 ✓  Pushing image to container registry [8s]

↪ Deploying Kubernetes Component: my-node
 ✓  Searching resource in cluster 
 ✓  Creating kind Deployment [50ms]

↪ Deploying Kubernetes Component: svc
 ✓  Searching resource in cluster 
 ✓  Creating kind Service [57ms]

Your Devfile has been successfully deployed

At any moment, you can check if a component has been deployed, using the odo list command.

$ odo list
 ✓  Listing components from namespace 'prj2' [61ms]
 NAME             PROJECT TYPE  RUNNING IN  MANAGED 
 * my-nodejs-app  nodejs        Deploy      odo

When you are done with this application, or if you want to undeploy it to work on development mode again, you can use the odo delete component to undeploy the component from the cluster.

$ odo delete component
Searching resources to delete, please wait...
This will delete "my-nodejs-app" from the namespace "prj2".
 •  The component contains the following resources that will get deleted:
    - Deployment: my-node
    - Service: svc
? Are you sure you want to delete "my-nodejs-app" and all its resources? Yes
The component "my-nodejs-app" is successfully deleted from namespace "prj2"

Binding a service to a micro-service using odo

Philippe MARTIN — Sun, 05 Sep 2021 16:02:31 +0000

In this article, we will see how to bind a service to a micro-service, using the odo development tool.

We will first see how the Service Binding Operator can be used to bind to a PostgreSQL instance started from a standalone Deployment, then to a PostgreSQL instance started from an Operator.

Next, we will see how to start the Operator backed PostgreSQL service from odo, and how to bind our micro-service to this PostgreSQL service using odo.

The Service Binding Operator

The Service Binding Operator is an operator that helps the developer get the values of the different parameters exposed by a service.

For example, when you have a PostgreSQL service deployed, you need to know its host, database name, user and password to work with the service. If the service provides which information are to be exposed, the Service Binding Operator is able to get the exposed values and provide them to your micro-service.

Installing the Service Binding Operator

You can install this operator with the help of the Operator Lifecycle Manager. For this, first install, if necessary, this manager with the command:

$ curl -sL https://github.com/operator-framework/operator-lifecycle-manager/releases/download/v0.18.3/install.sh | bash -s v0.18.3

Then, install the Service Binding Operator with the command:

$ kubectl create -f https://operatorhub.io/install/service-binding-operator.yaml

Deploying a standalone PostgreSQL instance

Let's deploy a single PostgreSQL instance using the official postgres image, available at https://hub.docker.com/_/postgres.

We can deploy an instance by defining our own database name, user and password with the following manifest:

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: postgres
  name: postgres
spec:
  replicas: 1
  selector:
    matchLabels:
      app: postgres
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
      - image: postgres
        name: postgres
        env:
        - name: POSTGRES_PASSWORD
          value: a-super-secret
        - name: POSTGRES_USER
          value: user1
        - name: POSTGRES_DB
          value: db1
        volumeMounts:
        - mountPath: /var/lib/postgresql/data
          name: pgdata
      volumes:
      - name: pgdata
        emptyDir: {}

---

apiVersion: v1
kind: Service
metadata:
  name: postgres-svc
spec:
  selector:
    app: postgres
  ports:
  - port: 5432
    targetPort: 5432

When the service is running, you can run another container that will be ready to connect to it using psql, with the manifest:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: client
spec:
  selector:
    matchLabels:
      app: client
  template:
    metadata:
      labels:
        app: client
    spec:
      containers:
      - name: client
        image: postgres
        command: ["bash", "-c", "sleep $((10**10))"]
        env:
        - name: PGPASSWORD
          value: a-super-secret
        - name: PGHOST
          value: postgres-svc
        - name: PGDATABASE
          value: db1
        - name: PGUSER
          value: user1

Note that we have defined the environment variables supported by psql to define the host, database name, username and password.

You finally can connect to the database with the command:

kubectl exec -it deployment/client psql

The environment variables defined into the manifest for the container will be used by psql to connect to the desired service.

But with this method, the developer needs to know the values for these different parameters, when running the client. Let's see how these variables can be automatically injected into the pod, using the Service Binding Operator.

Annotating the service resource

The first step is to annotate the postgres Deployment, to indicate which parameters should be exposed:

apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    service.binding/pguser: path={.spec.template.spec.containers[0].env[?(@.name=="POSTGRES_USER")].value}
    service.binding/pgpassword: path={.spec.template.spec.containers[0].env[?(@.name=="POSTGRES_PASSWORD")].value}
    service.binding/pgdatabase: path={.spec.template.spec.containers[0].env[?(@.name=="POSTGRES_DB")].value}
  labels:
    app: postgres
  name: postgres
spec:
  replicas: 1
  selector:
    matchLabels:
      app: postgres
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
      - image: postgres
        name: postgres
        env:
        - name: POSTGRES_PASSWORD
          value: a-super-secret
        - name: POSTGRES_USER
          value: user1
        - name: POSTGRES_DB
          value: db1
        volumeMounts:
          - mountPath: /var/lib/postgresql/data
            name: pgdata
      volumes:
      - name: pgdata
        emptyDir: {}

---

apiVersion: v1
kind: Service
metadata:
  name: postgres-svc
spec:
  selector:
    app: postgres
  ports:
  - port: 5432
    targetPort: 5432

Linking to the annotated service

Then, you can create a client2 deployment, which does not define the database name, user and password:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: client2
spec:
  selector:
    matchLabels:
      app: client2
  template:
    metadata:
      labels:
        app: client2
    spec:
      containers:
      - name: client2
        image: postgres
        command: ["bash", "-c", "sleep $((10**10))"]
        env:
        - name: PGHOST
          value: postgres-svc

Finally, you can create a servicebinding resource, to define a link between the Postgres service and the client2 deployment:

apiVersion: binding.operators.coreos.com/v1alpha1
kind: ServiceBinding
metadata:
  name: binding-request
spec:
  bindAsFiles: false
  namingStrategy: '{{ .name | upper }}'
  application:
    name: client2
    group: apps
    version: v1
    resource: deployments
  services:
  - group: apps
    version: v1
    kind: Deployment
    name: postgres

By applying this manifest, the client2 pod will be restarted, and environment variables will be injected through a secretRef, by the Service Binding Operator:

$ kubectl get deployment client2 -o yaml
[...]
spec:
  containers:
  - command:
    - bash
    - -c
    - sleep $((10**10))
    env:
    - name: PGHOST
      value: postgres-svc
    envFrom:
    - secretRef:
        name: binding-request-703eda68

$ kubectl get secret binding-request-703eda68 -o yaml
apiVersion: v1
kind: Secret
metadata:
  name: binding-request-703eda68
data:
  PGDATABASE: ZGIx
  PGPASSWORD: YS1zdXBlci1zZWNyZXQ=
  PGUSER: dXNlcjE=
type: Opaque

Now, you can connect to the service from the client2 deployment, without the need to know the credentials.

Deploying an Operator backed PostgreSQL service

Operator backed services are services managed by a Kubernetes operator.

You can find such Operator backed services on https://operatorhub.io/. For this example, we won't use operatorhub, but deploy manually the operator found at https://github.com/operator-backing-service-samples/postgresql-operator.

To deploy the PostgreSQL operator using the OLM framework, we first need to declare the catalog containing the Operator, then subscribe to this specific Operator:

kubectl apply -f - << EOD
--------
apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
    name: sample-db-operators
    namespace: olm
spec:
    sourceType: grpc
    image: quay.io/redhat-developer/sample-db-operators-olm:v1
    displayName: Sample DB Operators

--------

apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: pg
  namespace: operators
spec:
  channel: stable
  name: db-operators
  source: sample-db-operators
  sourceNamespace: olm
  installPlanApproval: Automatic
EOD

Examining the annotations on the Database custom resource

The PostgreSQL operator comes with a custom resource definition (CRD): Database. Let's examine the definition of this resource with the command:

$ kubectl get crd databases.postgresql.baiju.dev -o yaml
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: databases.postgresql.baiju.dev
  annotations:
    service.binding/db.host: path={.status.dbConfigMap},objectType=ConfigMap
    service.binding/db.name: path={.status.dbConfigMap},objectType=ConfigMap
    service.binding/db.password: path={.status.dbConfigMap},objectType=ConfigMap
    service.binding/db.port: path={.status.dbConfigMap},objectType=ConfigMap
    service.binding/db.user: path={.status.dbConfigMap},objectType=ConfigMap
    service.binding/dbConnectionIP: path={.status.dbConnectionIP}
    service.binding/dbConnectionPort: path={.status.dbConnectionPort}
    service.binding/dbName: path={.spec.dbName}
    service.binding/password: path={.status.dbCredentials},objectType=Secret
    service.binding/user: path={.status.dbCredentials},objectType=Secret
[...]

We can find that the CRD get a list of service.binding annotations, that will be used by the Service Binding Operator to bind instances of this resource to micro-services.

Note that, earlier in this article, annotations were placed in the Deployment instance itself; annotations are now placed in the definition of the Database resource (if you are an object-oriented developer, think about Classes and Instances in place of Definition and Instance).

Creating a Database instance with odo

The odo tool can create instances of Operator backend services.

You can get the list of available Operators on your cluster with the command:

$ odo catalog list services
Services available through Operators
NAME                                CRDs
postgresql-operator.v0.0.9          Database
service-binding-operator.v0.9.1     ServiceBinding, ServiceBinding

Note that this command displays the list of ClusterServiceVersions resources contained in the current namespace in the Succeeded phase. The Succeeded phase can take a few minutes to appear, please be patient; you can check with the command:

$ kubectl get csv 
NAME                              DISPLAY                    VERSION   REPLACES                          PHASE
postgresql-operator.v0.0.9        PostgreSQL Database        0.0.9                                       Succeeded
service-binding-operator.v0.9.1   Service Binding Operator   0.9.1     service-binding-operator.v0.9.0   Succeeded

With odo, services are attached to components; before to deploy a service, you need to create a component. You can follow this article to create your component, and get an example of sources in the repository https://github.com/feloy/nest-odo-example.

Now, you can create an instance of a PostgreSQL database with:

$ odo service create postgresql-operator.v0.0.9/Database db1
Successfully added service to the configuration; do 'odo push' to create service on the cluster

This will create an instance with the default parameters. If you want to use a specific configuration, you can get the possible parameters with the command:

$ odo catalog describe service postgresql-operator.v0.0.9/Database
Kind: Database
Version: v1alpha1
Description: Describes how an application component is built and deployed.
Parameters:

 PATH       DISPLAYNAME                     DESCRIPTION                    

 image      PostgreSQL database image       PostgreSQL database image      
 imageName  PostgreSQL database image name  PostgreSQL database image name 
 dbName     DB name                         Desired database name. If      
                                            not provided, default value    
                                            'postgres' will be used.

You can now create an instance with a specific database name with the command:

$ odo service create postgresql-operator.v0.0.9/Database db1 -p dbName=mydb -p imageName=postgresql -p image=postgres

Finally, you can deploy the service into the Kubernetes cluster:

odo push

Binding the service with odo

This odo command will create the Service Binding resource necessary to bind the PostgreSQL service to your micro-service:

$ odo link Database/db1 --name dblink
 ✓  Successfully created link between component "nodejs-prj1-api-hjtd" and service "Database/db1"

$ odo push

$ kubectl get sbr dblink -o yaml 
kind: ServiceBinding
metadata:
  name: dblink
  [...]
spec:
  application:
    group: apps
    name: nodejs-prj1-api-hjtd-app
    resource: deployments
    version: v1
  bindAsFiles: false
  detectBindingResources: true
  services:
  - group: postgresql.baiju.dev
    kind: Database
    name: db1
    version: v1alpha1
[...]

You can examine that the environment variables have been defined into your micro-service:

$ odo exec -- bash -c export | grep DATABASE_
declare -x DATABASE_CLUSTERIP="10.107.65.179"
declare -x DATABASE_DBCONNECTIONIP="10.107.65.179"
declare -x DATABASE_DBCONNECTIONPORT="5432"
declare -x DATABASE_DBNAME="mydb"
declare -x DATABASE_PASSWORD="password"
declare -x DATABASE_USER="postgres"

The developer can now use these variables into the code of the micro-service, and does not need to declare the values for these variables when deploying the micro-service, as the injection of the environment variables will be managed by the Service Binding Operator.

odo, a tool to simplify development on Kubernetes

Philippe MARTIN — Mon, 10 May 2021 08:00:35 +0000

In this article, we will see how to use the odo tool to develop cloud native applications, without the need for developers to manipulate containers and Kubernetes resources.

The odo tool is based on the deployment of pre-defined containers embedding all the environment to build and execute the developed programs. This way, the developers do not need to write any Dockerfile or Kubernetes manifests.

In the article, we will use quoted text, as for this paragraph, and a different narrative, to describe what happens in the Kubernetes cluster, generally using the kubectl command. This helps to clearly separate what are the commands executed by developers on a daily basis, and what are the commands executed only to illustrate in the article what happens when developers execute the commands, and what an experienced Kubernetes user can expect to see in the cluster.

Installing `odo`

The odo tool is composed of a single binary. Developers can install the binary either from the Golang source available at github.com/openshift/odo, or can download a binary from https://mirror.openshift.com/pub/openshift-v4/clients/odo/. The detailed instructions to install odo are available at https://odo.dev/docs/installing-odo/.

Auto-completion

Developers can activate auto-completion for the odo command using:

$ odo --complete

On Linux, this command will add the following line at your ~/.bashrc file:
complete -C /path/to/your/odo odo

To effectively activate the completion without restarting a new terminal, developers need to reload the .bashrc file, with:

$ source ~/.bashrc

Creating a new project

An application developed with odo is contained into a project. Developers can create a new project with the following command:

$ odo project create prj1

On the cluster, this command creates a Kubernetes namespace of the same name into the current cluster:
$ kubectl get namespaces
NAME              STATUS   AGE
[...]
prj1              Active   5s
It also sets this newly created namespace as the current namespace of the current Kubernetes context:
$ kubectl ns -c
prj1

Creating a new micro-service

As an example of micro-service, we will create an API, using the Nest framework:

$ nest new prj1-api
$ cd prj1-api

You can test the API locally, by running the following commands:
$ npm install
$ npm start
Executing these commands, and if you are lucky enough (if the port 3000 is not already in use for example), the API will start listening for HTTP requests on the port 3000 of your host.

You can test the result of a request with the command from a new terminal:
$ curl http://localhost:3000
Hello World!

Deploying the micro-service

Instead of building and running the API locally, developers can deploy the API into the Kubernetes cluster using specific odo commands.

First, developers need to add the API as a component of the project, with the command:

$ odo create nodejs prj1-api
Devfile Object Validation
 ✓  Checking devfile existence [51789ns]
 ✓  Creating a devfile component from registry: DefaultDevfileRegistry [82276ns]
Validation
 ✓  Validating if devfile name is correct [93222ns]

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

Within this command, developers indicate that the component uses the nodejs environment. This way, odo knows it has to deploy a pre-defined container containing all the tools necessary to build and execute such applications (for example npm and node). odo also knows how to build and start the application (here with npm install, npm start).

The effect of this command is to create a devfile.yaml file, describing the project and its components. At this point, nothing has been deployed into the cluster, and the developer has to run the following command to deploy the component just defined:

$ odo push
Validation
 ✓  Validating the devfile [20769ns]

Creating Kubernetes resources for component prj1-api
 ✓  Waiting for component to start [2m]
 ✓  Waiting for component to start [4ms]
 ⚠  Unable to create ingress, missing host information for Endpoint http-3000, please check instructions on URL creation (refer `odo url create --help`)


Applying URL changes
 ✓  URLs are synced with the cluster, no changes are required.

Syncing to component prj1-api
 ✓  Checking files for pushing [453118ns]
 ✓  Syncing files to the component [113ms]

Executing devfile commands for component prj1-api
 ✓  Waiting for component to start [1ms]
 ✓  Executing install command "npm install" [32s]
 ✓  Executing run command "npm start" [1s]

Pushing devfile component "prj1-api"
 ✓  Changes successfully pushed to component

On the cluster, a pod will be deployed, containing a container in which the API will be built and started.
$ kubectl get pods
NAME                        READY   STATUS    RESTARTS   AGE
prj1-api-7d58fcf4f4-4m727   1/1     Running   0          2m41s
A Kubernetes Service has been created, and you can try to access the API through the service address:
$ kubectl port-forward svc/prj1-api 3000 > /dev/null &
$  curl http://localhost:3000/
Hello World!

Developers can examine the logs of the component with the command:

$ odo log
[...]
[Nest] 108   - 05/07/2021, 11:16:06 AM   [NestApplication] Nest application successfully started

Working on the micro-service

After editing the code of the API, developers can restart the API into the cluster with:

$ odo push

This command will synchronize the sources into the container, and will rebuild and restart the application in the container.

If developers want to automate this process, they can run the command odo watch, and this process will be done every time they save modifications into the API sources:

$ odo watch

If developers want to undeploy the API from the cluster, keeping the information into the devfile.yaml file, they can run:

$ odo delete prj1-api

Debugging the micro-service

To debug the process executed into the container, the developer can run odo push with the --debug flag.

First, the default package.json file created by Nest must be modified to adapt to the devfile.yaml and to odo.

Looking at the debug command in the devfile.yml file, we can see that the command to be executed by odo to run the process in debug mode is npm run debug:

commands:
- id: debug
  exec:
    component: runtime
    commandLine: npm run debug
    workingDir: /project

Also, it is good to know that odo will try to access the debugger inside the container on the port 5858.

Let's adapt the package.json file to define the command debug instead of start:debug, and specify the debug port:

{
  [...]
  "scripts": {
    "debug": "nest start --debug 5858 --watch",
    [...]
  }
}

The developer can now run:

$ odo push --debug
$ odo debug port-forward

Using vscode, the debugger can be launched with this configuration:

{
  "version": "0.2.0",
  "configurations": [ { 
    "name": "Attach to remote 5858",
    "type": "node",
    "request": "attach",
    "address": "localhost",
    "port": 5858,
    "localRoot": "${workspaceFolder}",
    "remoteRoot": "/project"
  } ]
}

One final step is to build the micro-service locally:

npm install
npm run build

The developer is now ready to debug the application from vscode.

Configuration

Micro-services generally need some configuration, and this configuration is generally done through environment variables.

To pass environment variables to a component, developers can use the odo config set --env command:

$ odo config set --env PORT=3000 --env LOG_LEVEL=debug
 ✓  Environment variables were successfully updated

Run `odo push` command to apply changes to the cluster

$ odo push

With this example, two environment variables PORT and LOG_LEVEL will be defined into the container running the API.

These environment variables are defined in the Pod spec template, as we can see by looking at the definition of the Deployment resource created by odo:
$ kubectl get deployments.apps prj1-api -o yaml
   [...]
   containers:
   - name: runtime
     env:
     - name: PORT
       value: "3000"
     - name: LOG_LEVEL
       value: debug
   [...]        

Conclusion

In this article, we have introduced the odo tool and how developers can use it to develop and test their micro-services in a Kubernetes cluster without the need to write Dockerfile or Kubernetes manifests.

The complete documentation of odo is available at https://odo.dev/.

The odo tool permits many more things, and also provides IDEs integrations, for Visual Studio Code and IntelliJ. More articles are coming with these features.

Deploying an i18n Angular app with angular-cli

Philippe MARTIN — Sat, 29 Jun 2019 16:48:56 +0000

I will explain in this article how to create from scratch an internationalized (i18n) Angular app with the use of the Angular CLI and how to deploy it on an Apache or NGINX web server.

The following versions are used:

angular-cli: 8.0.4
angular: 8.0.4
Apache 2.4
NGINX 1.17

The described sample app is available at: https://github.com/feloy/angular-cli-i18n-sample

A fresh i18n app

We first create a fresh Angular app with the help of the Angular CLI:

$ ng new angular-cli-i18n-sample

We make some changes to add some translatable text, in
app.component.html:

<h1 i18n>Hello world!</h1>

We need now to create an xlf file with the translatable strings. We can generate the file src/i18n/messages.xlf with the following command:

$ ng xi18n --output-path src/i18n

We now create translations for different languages, here in english with a fresh file src/i18n/messages.en.xlf copied from src/i18n/messages.xlf:

[...]
      <trans-unit id="[...]" datatype="html">
        <source>Hello World!</source>
        <target>Hello World!</target>
        [...]
      </trans-unit>
[...]

in french with src/i18n/messages.fr.xlf:

[...]
      <trans-unit id="[...]" datatype="html">
        <source>Hello World!</source>
        <target>Salut la foule !</target>
        [...]
      </trans-unit>
[...]

and in spanish with src/i18n/messages.es.xlf:

[...]
      <trans-unit id="[...]" datatype="html">
        <source>Hello World!</source>
        <target>¿hola, qué tal?</target>
        [...]
      </trans-unit>
[...]

It is now possible to make Angular CLI build the app with the language of your choice, here in spanish:

$ ng build --aot \
           --i18n-file=src/i18n/messages.es.xlf \
           --i18n-locale=es \
           --i18n-format=xlf

Prepare the app for production

In production, we would like the app to be accessible in different subdirectories, depending on the language; for example the spanish version would be accessible at http://myapp.com/es/ and the french one at http://myapp.com/fr/. We also would like to be redirected from the base url http://myapp.com/ to the url of our preferred language.

For this, we guess that we need to change the base href to es, en or fr, depending on the target language. Angular CLI has a special command-line option for this, --base-href which permits to declare the base href at compile time from command line.

Linux/macOS users

Here is the shell command we can use to create the different bundles for the different languages:

$ for lang in es en fr; do \
    ng build --output-path=dist/$lang \
             --aot \
             --prod \
             --base-href /$lang/ \
             --i18n-file=src/i18n/messages.$lang.xlf \
             --i18n-format=xlf \
             --i18n-locale=$lang; \
  done

We can create a script definition in package.json for this command and execute it with npm run build-i18n:

{
  [...]
  "scripts": {
    [...]
    "build-i18n": "for lang in en es fr; do ng build --output-path=dist/$lang --aot --prod --base-href /$lang/ --i18n-file=src/i18n/messages.$lang.xlf --i18n-format=xlf --i18n-locale=$lang; done"
  }
  [...]
}

At this point we get three directories en/, es/ and fr/ into the dist/ directory, containing the different bundles.

Windows users

As a Windows user, you can use these commands to build your different bundles for different languages:

> ng build --output-path=dist/fr --aot --prod --base-href /fr/ --i18n-file=src/i18n/messages.fr.xlf --i18n-format=xlf --i18n-locale=fr

> ng build --output-path=dist/es --aot --prod --base-href /es/ --i18n-file=src/i18n/messages.es.xlf --i18n-format=xlf --i18n-locale=es

> ng build --output-path=dist/en --aot --prod --base-href /en/ --i18n-file=src/i18n/messages.en.xlf --i18n-format=xlf --i18n-locale=en

We can create script definitions in package.json for these commands and a supplementary one to run all these commands at once and execute the last one with npm run build-i18n:

"scripts": {
    "build-i18n:fr": "ng build --output-path=dist/fr --aot --prod --base-href /fr/ --i18n-file=src/i18n/messages.fr.xlf --i18n-format=xlf --i18n-locale=fr",
    "build-i18n:es": "ng build --output-path=dist/es --aot --prod --base-href /es/ --i18n-file=src/i18n/messages.es.xlf --i18n-format=xlf --i18n-locale=es",
    "build-i18n:en": "ng build --output-path=dist/en --aot --prod --base-href /en/ --i18n-file=src/i18n/messages.en.xlf --i18n-format=xlf --i18n-locale=en",
    "build-i18n": "npm run build-i18n:en && npm run build-i18n:es && npm run build-i18n:fr"
  }

Apache2 configuration

Here is a virtual host configuration which will serve your different bundles from the /var/www directory: you will have to copy in this directory the three directories en/, es/ and fr/ previously generated.

With this configuration, the url http://www.myapp.com is redirected to the subdirectory of the preferred language defined in your browser configuration (or en if your preferred language is not found) and you still have access to the other languages by accessing the other subdirectories.

<VirtualHost *:80>
  ServerName www.myapp.com
  DocumentRoot /var/www
  <Directory "/var/www">
    RewriteEngine on
    RewriteBase /
    RewriteRule ^../index\.html$ - [L]
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule (..) $1/index.html [L]
    RewriteCond %{HTTP:Accept-Language} ^fr [NC]
    RewriteRule ^$ /fr/ [R]
    RewriteCond %{HTTP:Accept-Language} ^es [NC]
    RewriteRule ^$ /es/ [R]
    RewriteCond %{HTTP:Accept-Language} !^es [NC]
    RewriteCond %{HTTP:Accept-Language} !^fr [NC]
    RewriteRule ^$ /en/ [R]
  </Directory>
</VirtualHost>

NGINX configuration

Here is an NGINX configuration that will give you the same behaviour: an access to http://www.myapp.com will redirect to the preferred language defined in the browser (or en if your preferred language is not found) and the other languages are still accessible.

server {
    listen       80;
    server_name  localhost;

    location /en/ {
        alias   /usr/share/nginx/html/en/;
        try_files $uri$args $uri$args/ /en/index.html;
    }
    location /es/ {
        alias   /usr/share/nginx/html/es/;
        try_files $uri$args $uri$args/ /es/index.html;
    }
    location /fr/ {
        alias   /usr/share/nginx/html/fr/;
        try_files $uri$args $uri$args/ /fr/index.html;
    }

    set $first_language $http_accept_language;
    if ($http_accept_language ~* '^(.+?),') {
        set $first_language $1;
    }

    set $language_suffix 'en';
    if ($first_language ~* 'es') {
        set $language_suffix 'es';
    }
    if ($first_language ~* 'fr') {
        set $language_suffix 'fr';
    }

    location / {
        rewrite ^/$ http://localhost:4200/$language_suffix/index.html permanent;
    }
}

Bonus: add links to the different languages

It would be interesting to have some links in the app so the user can navigate to another languages by clicking these links. The links will point to /en/, /es/ and /fr/.

One trick to know, the current language is available in the LOCALE_ID token.

Here is how you can get the LOCALE_ID value and display the list of languages, differentiating the current language:

// app.component.ts
import { Component, LOCALE_ID, Inject } from '@angular/core';
@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  languages = [
    { code: 'en', label: 'English'},
    { code: 'es', label: 'Español'},
    { code: 'fr', label: 'Français'}
  ];
  constructor(@Inject(LOCALE_ID) protected localeId: string) {}
}
<!-- app.component.html -->
<h1 i18n>Hello World!</h1>
<ng-template ngFor let-lang [ngForOf]="languages">
  <span *ngIf="lang.code !== localeId">
    <a href="/{{lang.code}}/">{{lang.label}}</a> </span>
  <span *ngIf="lang.code === localeId">{{lang.label}} </span>
</ng-template>

Bonus 2: Angular Translator application

For the 2017 AngularAttack, I've created an application that can definitely help you translate your Angular applications. It is still in development, feedbacks are welcome: http://angular-translator.elol.fr/.

Good translations!