Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit b1fd3bf

Browse files
cdragecdrage
committedJul 10, 2020
Adds documentation on Devfile file reference
**What type of PR is this?** > Uncomment only one ` /kind` line, and delete the rest. > For example, `> /kind bug` would simply become: `/kind bug` > Documentation changes: Please include [skip ci] in your commit message as well /kind documentation [skip ci] **What does does this PR do / why we need it**: This PR adds documentation regarding each section of Devfile and what we support / do not support **Which issue(s) this PR fixes**: N/A **How to test changes / Special notes to the reviewer**: N/A Signed-off-by: Charlie Drage <[email protected]>
1 parent 20f84de commit b1fd3bf

File tree

2 files changed

+616
-4
lines changed

2 files changed

+616
-4
lines changed
 

Diff for: ‎docs/file-reference/index.md

+613
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,613 @@
1+
---
2+
title: Odo Devfile Reference
3+
4+
language_tabs:
5+
- yaml
6+
7+
toc_footers:
8+
- <a href='https://odo.dev'>Odo Homepage</a>
9+
- <a href='https://devfile.github.io/devfile/index.html'>Devfile GitHub Page</a>
10+
11+
search: true
12+
---
13+
14+
# Introduction
15+
16+
> A full odo Devfile example using Spring Boot
17+
18+
```yaml
19+
20+
schemaVersion: 2.0.0
21+
metadata:
22+
name: springBoot
23+
version: 1.0.0
24+
projects:
25+
- name: springbootproject
26+
git:
27+
location: "https://github.com/odo-devfiles/springboot-ex.git"
28+
components:
29+
- container:
30+
name: tools
31+
image: maysunfaisal/springbootbuild
32+
memoryLimit: 768Mi
33+
command: ['tail']
34+
args: [ '-f', '/dev/null']
35+
mountSources: true
36+
volumeMounts:
37+
- name: springbootpvc
38+
path: /data
39+
- container:
40+
name: runtime
41+
image: maysunfaisal/springbootruntime
42+
memoryLimit: 768Mi
43+
command: ['tail']
44+
args: [ '-f', '/dev/null']
45+
endpoints:
46+
- name: '8080/tcp'
47+
exposure: public
48+
targetPort: 8080
49+
protocol: https
50+
secure: true
51+
mountSources: false
52+
volumeMounts:
53+
- name: springbootpvc
54+
path: /data
55+
commands:
56+
- exec:
57+
id: devBuild
58+
commandLine: "/artifacts/bin/build-container-full.sh"
59+
component: tools
60+
workingDir: /projects/springbootproject
61+
group:
62+
kind: build
63+
isDefault: true
64+
- exec:
65+
id: devRun
66+
commandLine: "/artifacts/bin/start-server.sh"
67+
component: runtime
68+
workingDir: /
69+
group:
70+
kind: run
71+
isDefault: true
72+
```
73+
74+
> Download the application
75+
76+
```sh
77+
$ odo create nodejs --starter
78+
```
79+
80+
> Create a URL and push the service
81+
82+
```sh
83+
$ odo url create
84+
85+
$ odo push
86+
```
87+
88+
**odo**
89+
90+
odo is a fast, iterative, and straightforward CLI tool for developers who write, build, and deploy applications on Kubernetes and OpenShift.
91+
92+
Existing tools such as oc are more operations-focused and require a deep-understanding of Kubernetes and OpenShift concepts. odo abstracts away complex Kubernetes and OpenShift concepts for the developer.
93+
94+
**Devfile**
95+
96+
What is a devfile?
97+
98+
A devfile is a portable file that describes your development environment. It allows reproducing a portable developmental environment without the need of reconfiguration.
99+
100+
With a devfile you can describe:
101+
102+
* Development components such as container definition for build and application runtimes
103+
* A list of pre-defined commands that can be run
104+
* Projects to initially clone
105+
106+
Odo takes this devfile and transforms it into a workspace of multiple containers running on OpenShift, Kubernetes or Docker.
107+
108+
Devfiles are YAML files with a defined schema.
109+
110+
## Unsupported features
111+
112+
**PLEASE NOTE:** Devfile v2 is still in its early stages and there are some parts of the schema that have not yet been implemented.
113+
114+
Please refer to the below table for a list of features which are *not yet* implemented:
115+
116+
| Key | Key Description | Status | Description |
117+
|------------------------------------|-------------------------------------------|-------------|-------------------------------------------------------------------------------------------------|
118+
| projects[].github.startPoint | [githubObject](#githubObject) | IN PROGRESS | Refer to issue: https://github.com/openshift/odo/issues/3002 |
119+
| projects[].git.startPoint | [gitObject](#gitObject) | IN PROGRESS | Refer to issue: https://github.com/openshift/odo/issues/3002 |
120+
| projects[].zip | [zipObject](#zipobject) | IN PROGRESS | Entire object not yet implemented. Refer to issue: https://github.com/openshift/odo/issues/3442 |
121+
| parent | [parentObject](#parent-object) | IN PROGRESS | Refer to issue: https://github.com/openshift/odo/issues/2936 |
122+
| events | [eventObject](#event-object) | IN PROGRESS | Refer to issue: https://github.com/openshift/odo/issues/2919 |
123+
| component[].kubernetes | [kubernetesObject](#kubernetesobject) | IN PROGRESS | |
124+
| component[].openshift | [openshiftObject](#openshiftobject) | IN PROGRESS | |
125+
| component[].volume | [volumeObject](#volumeobject) | IN PROGRESS | Refer to: https://github.com/openshift/odo/issues/3407 |
126+
| component[].plugin | [pluginObject](#pluginobject) | IN PROGRESS | Refer to: https://github.com/openshift/odo/issues/3407 |
127+
| component[].container.endpoints | [endpointObject](#endpointobject) | IN PROGRESS | Refer to: https://github.com/openshift/odo/issues/3544 |
128+
| component[].container.dedicatedPod | [containerObject](#containerobject) | UNKNOWN | In schema but not yet implemented. |
129+
| commands[].apply | [applyObject](#applyobject) | UNKNOWN | In schema but not yet implemented. |
130+
| commands[].composite | [compositeObject](#compositeobject) | IN PROGRESS | Refer to: https://github.com/openshift/odo/issues/3338 |
131+
| commands[].vscodeLaunch | [vscodeLaunchObject](#vscodeLaunchobject) | N/A | Not applicable to odo. |
132+
| commands[].vscodeTask | [vscodeTaskObject](#vscodeTaskobject) | N/A | Not applicable to odo. |
133+
134+
135+
136+
## Installation
137+
138+
Installing odo can be found at our [installation page](https://odo.dev/docs/installing-odo/).
139+
140+
## Quick Start
141+
142+
If you haven't used odo yet, we recommend going through our [Deploying a devfile using odo guide](https://odo.dev/docs/deploying-a-devfile-using-odo/).
143+
144+
145+
# Devfile Properties
146+
147+
> All defineable Devfile properties
148+
149+
```yaml
150+
schemaVersion: <string>
151+
metadata: <metadataObject>
152+
projects:
153+
- <projectObject>
154+
components:
155+
- <componentObject>
156+
commands:
157+
- <commandObject>
158+
```
159+
160+
| Key | Type | Required | Description |
161+
|---------------|-----------------------------------------------|----------|-----------------------------------------------------------------------------------|
162+
| schemaVersion | string | yes | Schema version of Devfile |
163+
| metadata | [metadataObject](#metadataobject) | no | Metadata information that describes the project |
164+
| projects | array of [projectObject](#project-object) | no | List of projects that Devfile will use when creating your development environment |
165+
| components | array of [componentObject](#component-object) | no | List of components to be used within your development environment |
166+
| commands | array of [commandObject](#commandobject) | no | List of commands to be executed |
167+
168+
169+
## schemaVersion
170+
171+
```yaml
172+
schemaVersion: 2.0.0
173+
```
174+
175+
| Key | Type | Required | Description |
176+
|---------------|--------|----------|---------------------|
177+
| schemaVersion | string | yes | 2.0.0 of the schema |
178+
179+
180+
## metadata
181+
182+
```yaml
183+
metadata:
184+
name: nodejs
185+
version: 1.0.0
186+
```
187+
188+
| Key | Type | Required | Description |
189+
|---------|--------|----------|-----------------------------------------------------------------------------------|
190+
| name | string | yes | Name of your devfile. This name will propagate to the Devfile registry if listed. |
191+
| version | string | yes | Version of your devfile |
192+
193+
## projects
194+
195+
> Pulling from a git location
196+
197+
```yaml
198+
projects:
199+
- name: nodejs-web-app
200+
git:
201+
location: https://github.com/odo-devfiles/nodejs-ex.git
202+
branch: master
203+
sparseCheckoutDir: /app/ # optional checkout dir
204+
startPoint: 1.0.0 # tag or commit to start at
205+
```
206+
207+
> Pulling from a GitHub location
208+
209+
```yaml
210+
projects:
211+
- name: nodejs-web-app
212+
github:
213+
location: https://github.com/odo-devfiles/nodejs-ex.git
214+
branch: master
215+
sparseCheckoutDir: /app/ # optional checkout dir
216+
startPoint: 1.0.0 # tag or commit to start at
217+
```
218+
219+
> Pulling from a zip
220+
221+
```yaml
222+
projects:
223+
- name: nodejs-web-app
224+
zip:
225+
location: https://github.com/odo-devfiles/nodejs-ex/archive/0.0.1.zip
226+
sparseCheckoutDir: /app/ # optional checkout dir
227+
```
228+
229+
| Key | Type | Description |
230+
|---------------|----------------------------------|-----------------------------|
231+
| projectObject | [projectObject](#project-object) | List of projects to be used |
232+
233+
## components
234+
235+
> Example using an [OpenLiberty](https://github.com/odo-devfiles/registry/blob/master/devfiles/openLiberty/devfile.yaml) container
236+
237+
```yaml
238+
components:
239+
- container:
240+
name: appsodyrun
241+
image: 'ajymau/java-openliberty-dev:latest'
242+
memoryLimit: 1512Mi
243+
mountSources: true
244+
endpoints:
245+
- name: 9080/tcp
246+
exposure: public
247+
public: true
248+
protocol: http
249+
targetPort: 9080
250+
env:
251+
- name: MODE2
252+
value: TEST2
253+
- name: myprop2
254+
value: myval2
255+
```
256+
257+
| Key | Type | Description |
258+
|-----------------|--------------------------------------|-------------------------------|
259+
| componentObject | [componentObject](#component-object) | List of components to be used |
260+
261+
262+
## commands
263+
264+
> Example using the exec command
265+
266+
```yaml
267+
commands:
268+
- exec:
269+
id: devBuild
270+
commandLine: "/artifacts/bin/build-container-full.sh"
271+
component: tools
272+
workingDir: /projects/springbootproject
273+
group:
274+
kind: build
275+
isDefault: true
276+
- exec:
277+
id: devRun
278+
commandLine: "/artifacts/bin/start-server.sh"
279+
component: runtime
280+
workingDir: /
281+
group:
282+
kind: run
283+
isDefault: true
284+
```
285+
286+
| Key | Type | Description |
287+
|---------------|----------------------------------|-----------------------------------------------------------|
288+
| commandObject | [commandObject](#command-object) | Command to be executed in an existing component container |
289+
290+
291+
# Project Object
292+
293+
> Pulling from a git location
294+
295+
```yaml
296+
projects:
297+
- name: nodejs-web-app
298+
git:
299+
location: https://github.com/odo-devfiles/nodejs-ex.git
300+
branch: master
301+
sparseCheckoutDir: /app/ # optional checkout dir
302+
startPoint: 1.0.0 # tag or commit to start at
303+
```
304+
305+
> Pulling from a GitHub location
306+
307+
```yaml
308+
projects:
309+
- name: nodejs-web-app
310+
github:
311+
location: https://github.com/odo-devfiles/nodejs-ex.git
312+
branch: master
313+
sparseCheckoutDir: /app/ # optional checkout dir
314+
startPoint: 1.0.0 # tag or commit to start at
315+
```
316+
317+
> Pulling from a zip
318+
319+
```yaml
320+
projects:
321+
- name: nodejs-web-app
322+
zip:
323+
location: https://github.com/odo-devfiles/nodejs-ex/archive/0.0.1.zip
324+
sparseCheckoutDir: /app/ # optional checkout dir
325+
```
326+
327+
Each project may contain three different objects, `git`, `github` or `zip`.
328+
329+
330+
331+
| Key | Type | Description |
332+
|-----------|-------------------------------|------------------------------------------------------------------------------------|
333+
| name | string | Name of your devfile |
334+
| clonePath | string | Path relative the root of your projects to which the project should be cloned into |
335+
| git | [gitObject](#gitobject) | Pull from a Git location |
336+
| github | [githubObject](#githubobject) | Pull from GitHub |
337+
| zip | [zipObject](#zipobject) | Get from a zip location |
338+
339+
## gitObject
340+
341+
> Using the gitObject
342+
343+
```yaml
344+
projects:
345+
- name: nodejs-web-app
346+
git:
347+
location: https://github.com/odo-devfiles/nodejs-ex.git
348+
branch: master
349+
sparseCheckoutDir: /app/ # optional checkout dir
350+
startPoint: 1.0.0 # tag or commit to start at
351+
```
352+
353+
| Key | Type | Description |
354+
|------------------|--------|------------------------------------|
355+
| location | string | Location of the git repository |
356+
| branch | string | What branch to use |
357+
| spareCheckoutDir | string | What directory to use when pulling |
358+
| startPoint | string | Tag or commit to start from |
359+
360+
## githubObject
361+
362+
> Using the githubObject
363+
364+
```yaml
365+
projects:
366+
- name: nodejs-web-app
367+
github:
368+
location: https://github.com/odo-devfiles/nodejs-ex.git
369+
branch: master
370+
sparseCheckoutDir: /app/ # optional checkout dir
371+
startPoint: 1.0.0 # tag or commit to start at
372+
```
373+
374+
| Key | Type | Description |
375+
|------------------|--------|------------------------------------|
376+
| location | string | Location of the git repository |
377+
| branch | string | What branch to use |
378+
| spareCheckoutDir | string | What directory to use when pulling |
379+
| startPoint | string | Tag or commit to start from |
380+
381+
## zipObject
382+
383+
> Using the zipObject
384+
385+
```yaml
386+
projects:
387+
- name: nodejs-web-app
388+
zip:
389+
location: https://github.com/odo-devfiles/nodejs-ex/archive/0.0.1.zip
390+
sparseCheckoutDir: /app/ # optional checkout dir
391+
```
392+
393+
| Key | Type | Description |
394+
|------------------|--------|------------------------------------|
395+
| location | string | Location of the zip |
396+
| spareCheckoutDir | string | What directory to use when pulling |
397+
398+
399+
400+
# Component Object
401+
402+
> Example using a container using the minimum amount of keys
403+
404+
```yaml
405+
components:
406+
- container:
407+
name: appsodyrun
408+
image: 'ajymau/java-openliberty-dev:latest'
409+
```
410+
411+
Each component must use the `container` object.
412+
413+
414+
| Key | Type | Description |
415+
|-----------|-------------------------------------|-------------------------------|
416+
| container | [containerObject](#containerobject) | List of containers to be used |
417+
418+
419+
## containerObject
420+
421+
> Example using an [OpenLiberty](https://github.com/odo-devfiles/registry/blob/master/devfiles/openLiberty/devfile.yaml) container
422+
423+
```yaml
424+
components:
425+
- container:
426+
name: appsodyrun
427+
image: 'ajymau/java-openliberty-dev:latest'
428+
memoryLimit: 1512Mi
429+
mountSources: true
430+
endpoints:
431+
- name: 9080/tcp
432+
exposure: public
433+
public: true
434+
protocol: http
435+
targetPort: 9080
436+
env:
437+
- name: MODE2
438+
value: TEST2
439+
- name: myprop2
440+
value: myval2
441+
```
442+
443+
| Key | Type | Required | Description |
444+
|----------------|-----------------------------------------|----------|-------------------------------------------------------------------------------------------------------------|
445+
| name | string | yes | Name of your container |
446+
| image | string | yes | Image version |
447+
| memoryLimit | string | no | Memory limit to be used with your container |
448+
| mountSources | boolean | no | Mount the source or not |
449+
| sourceMapping | string | no | Path in the container where project sources should be transferred / mounted when mountSource is set to true |
450+
| endpoints[] | [endpointObject](#endpointobject) | no | List of endpoints to use |
451+
| volumeMounts[] | [volumeMountsObject](#volumemountsobject) | no | List of volumes to mount |
452+
| env[] | [envObject](#envobject) | no | List of environment variables to use |
453+
454+
455+
456+
## endpointObject
457+
458+
> Example using an endpoint
459+
460+
```yaml
461+
components:
462+
- container:
463+
name: appsodyrun
464+
image: 'ajymau/java-openliberty-dev:latest'
465+
endpoints:
466+
- name: 9080/tcp
467+
exposure: public
468+
public: true
469+
protocol: http
470+
targetPort: 9080
471+
```
472+
473+
| Key | Type | Required | Description |
474+
|------------|---------|----------|------------------------------------------------------------------------------------------------------------------------------------------------|
475+
| name | string | yes | Name of your endpoint |
476+
| targetPort | integer | yes | Port number that you are targeting |
477+
| exposure | string | no | `public`, `internal` or `none`. Describes how the endpoint should be exposed on the network |
478+
| path | string | no | Path to the endpoint URL |
479+
| protocol | string | no | `http`, `https`, `ws`, `wss`, `tcp`, `udp`. Describes the application and transport protocols of the traffic that will go through the endpoint |
480+
| secure | boolean | no | Whether or not the endpoint is defined as secure |
481+
482+
483+
## volumeMountsObject
484+
485+
> Example using a volume with a container
486+
487+
```yaml
488+
components:
489+
- container:
490+
name: tools
491+
image: maysunfaisal/springbootbuild
492+
memoryLimit: 768Mi
493+
command: ['tail']
494+
args: [ '-f', '/dev/null']
495+
mountSources: true
496+
volumeMounts:
497+
- name: springbootpvc
498+
path: /data
499+
```
500+
501+
| Key | Type | Required | Description |
502+
|------|--------|----------|----------------------------------------------------------------------------------------------------|
503+
| name | string | yes | Name of the volume |
504+
| path | string | no | Path in the component container where the volume should be mounted. Defaults to `/<name>` if blank |
505+
506+
507+
# Command Object
508+
509+
> Example using an exec command within a command object
510+
511+
```yaml
512+
commands:
513+
- exec:
514+
id: devBuild
515+
component: tools
516+
commandLine: "/artifacts/bin/build-container-full.sh"
517+
workingDir: /projects/springbootproject
518+
group:
519+
kind: build
520+
isDefault: true
521+
```
522+
523+
Each command must use the `exec` object.
524+
525+
| Key | Type | Description |
526+
|------|---------------------------|---------------------------|
527+
| exec | [execObject](#execobject) | The CLI command to be ran |
528+
529+
## execObject
530+
531+
> Example using exec command within a command object
532+
533+
```yaml
534+
commands:
535+
- exec:
536+
id: devBuild
537+
commandLine: "/artifacts/bin/build-container-full.sh"
538+
component: tools
539+
workingDir: /projects/springbootproject
540+
group:
541+
kind: build
542+
isDefault: true
543+
env:
544+
- name: FOO
545+
value: BAR
546+
```
547+
548+
| Key | Type | Required | Description |
549+
|-------------|-----------------------------|----------|--------------------------------------------------------|
550+
| id | string | yes | ID of the command |
551+
| commandLine | string | yes | Command to be ran |
552+
| component | string | no | What component that the actions relate to |
553+
| label | string | no | Optional label to be used to describe the command |
554+
| workingDir | string | no | Working directory where the command should be executed |
555+
| group | [groupObject](#groupObject) | no | Group that the command is part of |
556+
| env | [envObject](#envObject) | no | List of environment variables used |
557+
558+
## groupObject
559+
560+
> Example using the group object within exec
561+
562+
```yaml
563+
commands:
564+
- exec:
565+
id: devBuild
566+
commandLine: "/artifacts/bin/build-container-full.sh"
567+
group:
568+
kind: build
569+
isDefault: true
570+
```
571+
572+
| Key | Type | Required | Description |
573+
|-----------|---------|----------|--------------------------------------------------------------------------------|
574+
| kind | string | yes | Kind of group the command is part of. Options: `build`, `run`, `test`, `debug` |
575+
| isDefault | boolean | no | Identifies that it is the default command to be ran |
576+
577+
# Universal objects
578+
579+
List of objects which are found in multiple parts of Devfile. For example, the [envObject](#envobject) is found within [containerObject](#containerobject) and [execObject](#execobject).
580+
581+
## envObject
582+
583+
> Example using environment variables with a container
584+
585+
```yaml
586+
components:
587+
- container:
588+
name: appsodyrun
589+
image: 'ajymau/java-openliberty-dev:latest'
590+
targetPort: 9080
591+
env:
592+
- name: MODE2
593+
value: TEST2
594+
- name: myprop2
595+
value: myval2
596+
```
597+
598+
> Example using environment variables within the exec command
599+
600+
```yaml
601+
commands:
602+
- exec:
603+
id: devBuild
604+
commandLine: "/artifacts/bin/build-container-full.sh"
605+
env:
606+
- name: FOO
607+
value: BAR
608+
```
609+
610+
| Key | Type | Required | Description |
611+
|-------|--------|----------|-----------------------------------|
612+
| name | string | yes | Name of the environment variable |
613+
| value | string | yes | Value of the environment variable |

Diff for: ‎docs/public/deploying-a-devfile-using-odo.adoc

+3-4
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,11 @@
22

33
What is a devfile?
44

5-
A https://redhat-developer.github.io/devfile/[devfile] is a portable file that describes your development environment. It allows for a _portable_ developmental environment without the need of reconfiguration.
5+
A https://redhat-developer.github.io/devfile/[devfile] is a portable file that describes your development environment. It allows reproducing a _portable_ developmental environment without the need of reconfiguration.
66

77
With a devfile you can describe:
88

9-
* The source code being used
10-
* Development components such as IDE tools (VSCode) and application runtimes (Yarn / NPM)
9+
* Development components such as container definition for build and application runtimes
1110
* A list of pre-defined commands that can be run
1211
* Projects to initially clone
1312
@@ -410,4 +409,4 @@ Docker volumes are created for the project source, and any other volumes defined
410409
? Are you sure you want to delete the devfile component: java-spring-boot? Yes
411410
✓ Deleting devfile component java-spring-boot [139ms]
412411
✓ Successfully deleted component
413-
----
412+
----

0 commit comments

Comments
 (0)
Please sign in to comment.