diff --git a/docs/file-reference/index.md b/docs/file-reference/index.md new file mode 100644 index 00000000000..26fc14a7810 --- /dev/null +++ b/docs/file-reference/index.md @@ -0,0 +1,613 @@ +--- +title: Odo Devfile Reference + +language_tabs: + - yaml + +toc_footers: + - Odo Homepage + - Devfile GitHub Page + +search: true +--- + +# Introduction + +> A full odo Devfile example using Spring Boot + +```yaml + +schemaVersion: 2.0.0 +metadata: + name: springBoot + version: 1.0.0 +projects: + - name: springbootproject + git: + location: "https://github.com/odo-devfiles/springboot-ex.git" +components: + - container: + name: tools + image: maysunfaisal/springbootbuild + memoryLimit: 768Mi + command: ['tail'] + args: [ '-f', '/dev/null'] + mountSources: true + volumeMounts: + - name: springbootpvc + path: /data + - container: + name: runtime + image: maysunfaisal/springbootruntime + memoryLimit: 768Mi + command: ['tail'] + args: [ '-f', '/dev/null'] + endpoints: + - name: '8080/tcp' + exposure: public + targetPort: 8080 + protocol: https + secure: true + mountSources: false + volumeMounts: + - name: springbootpvc + path: /data +commands: + - exec: + id: devBuild + commandLine: "/artifacts/bin/build-container-full.sh" + component: tools + workingDir: /projects/springbootproject + group: + kind: build + isDefault: true + - exec: + id: devRun + commandLine: "/artifacts/bin/start-server.sh" + component: runtime + workingDir: / + group: + kind: run + isDefault: true +``` + +> Download the application + +```sh +$ odo create nodejs --starter +``` + +> Create a URL and push the service + +```sh +$ odo url create + +$ odo push +``` + +**odo** + +odo is a fast, iterative, and straightforward CLI tool for developers who write, build, and deploy applications on Kubernetes and OpenShift. + +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. + +**Devfile** + +What is a devfile? + +A devfile is a portable file that describes your development environment. It allows reproducing a portable developmental environment without the need of reconfiguration. + +With a devfile you can describe: + +* Development components such as container definition for build and application runtimes +* A list of pre-defined commands that can be run +* Projects to initially clone + +Odo takes this devfile and transforms it into a workspace of multiple containers running on OpenShift, Kubernetes or Docker. + +Devfiles are YAML files with a defined schema. + +## Unsupported features + +**PLEASE NOTE:** Devfile v2 is still in its early stages and there are some parts of the schema that have not yet been implemented. + +Please refer to the below table for a list of features which are *not yet* implemented: + +| Key | Key Description | Status | Description | +|------------------------------------|-------------------------------------------|-------------|-------------------------------------------------------------------------------------------------| +| projects[].github.startPoint | [githubObject](#githubObject) | IN PROGRESS | Refer to issue: https://github.com/openshift/odo/issues/3002 | +| projects[].git.startPoint | [gitObject](#gitObject) | IN PROGRESS | Refer to issue: https://github.com/openshift/odo/issues/3002 | +| projects[].zip | [zipObject](#zipobject) | IN PROGRESS | Entire object not yet implemented. Refer to issue: https://github.com/openshift/odo/issues/3442 | +| parent | [parentObject](#parent-object) | IN PROGRESS | Refer to issue: https://github.com/openshift/odo/issues/2936 | +| events | [eventObject](#event-object) | IN PROGRESS | Refer to issue: https://github.com/openshift/odo/issues/2919 | +| component[].kubernetes | [kubernetesObject](#kubernetesobject) | IN PROGRESS | | +| component[].openshift | [openshiftObject](#openshiftobject) | IN PROGRESS | | +| component[].volume | [volumeObject](#volumeobject) | IN PROGRESS | Refer to: https://github.com/openshift/odo/issues/3407 | +| component[].plugin | [pluginObject](#pluginobject) | IN PROGRESS | Refer to: https://github.com/openshift/odo/issues/3407 | +| component[].container.endpoints | [endpointObject](#endpointobject) | IN PROGRESS | Refer to: https://github.com/openshift/odo/issues/3544 | +| component[].container.dedicatedPod | [containerObject](#containerobject) | UNKNOWN | In schema but not yet implemented. | +| commands[].apply | [applyObject](#applyobject) | UNKNOWN | In schema but not yet implemented. | +| commands[].composite | [compositeObject](#compositeobject) | IN PROGRESS | Refer to: https://github.com/openshift/odo/issues/3338 | +| commands[].vscodeLaunch | [vscodeLaunchObject](#vscodeLaunchobject) | N/A | Not applicable to odo. | +| commands[].vscodeTask | [vscodeTaskObject](#vscodeTaskobject) | N/A | Not applicable to odo. | + + + +## Installation + +Installing odo can be found at our [installation page](https://odo.dev/docs/installing-odo/). + +## Quick Start + +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/). + + +# Devfile Properties + +> All defineable Devfile properties + +```yaml +schemaVersion: +metadata: +projects: +- +components: +- +commands: +- +``` + +| Key | Type | Required | Description | +|---------------|-----------------------------------------------|----------|-----------------------------------------------------------------------------------| +| schemaVersion | string | yes | Schema version of Devfile | +| metadata | [metadataObject](#metadataobject) | no | Metadata information that describes the project | +| projects | array of [projectObject](#project-object) | no | List of projects that Devfile will use when creating your development environment | +| components | array of [componentObject](#component-object) | no | List of components to be used within your development environment | +| commands | array of [commandObject](#commandobject) | no | List of commands to be executed | + + +## schemaVersion + +```yaml +schemaVersion: 2.0.0 +``` + +| Key | Type | Required | Description | +|---------------|--------|----------|---------------------| +| schemaVersion | string | yes | 2.0.0 of the schema | + + +## metadata + +```yaml +metadata: + name: nodejs + version: 1.0.0 +``` + +| Key | Type | Required | Description | +|---------|--------|----------|-----------------------------------------------------------------------------------| +| name | string | yes | Name of your devfile. This name will propagate to the Devfile registry if listed. | +| version | string | yes | Version of your devfile | + +## projects + +> Pulling from a git location + +```yaml +projects: + - name: nodejs-web-app + git: + location: https://github.com/odo-devfiles/nodejs-ex.git + branch: master + sparseCheckoutDir: /app/ # optional checkout dir + startPoint: 1.0.0 # tag or commit to start at +``` + +> Pulling from a GitHub location + +```yaml +projects: + - name: nodejs-web-app + github: + location: https://github.com/odo-devfiles/nodejs-ex.git + branch: master + sparseCheckoutDir: /app/ # optional checkout dir + startPoint: 1.0.0 # tag or commit to start at +``` + +> Pulling from a zip + +```yaml +projects: + - name: nodejs-web-app + zip: + location: https://github.com/odo-devfiles/nodejs-ex/archive/0.0.1.zip + sparseCheckoutDir: /app/ # optional checkout dir +``` + +| Key | Type | Description | +|---------------|----------------------------------|-----------------------------| +| projectObject | [projectObject](#project-object) | List of projects to be used | + +## components + +> Example using an [OpenLiberty](https://github.com/odo-devfiles/registry/blob/master/devfiles/openLiberty/devfile.yaml) container + +```yaml +components: + - container: + name: appsodyrun + image: 'ajymau/java-openliberty-dev:latest' + memoryLimit: 1512Mi + mountSources: true + endpoints: + - name: 9080/tcp + exposure: public + public: true + protocol: http + targetPort: 9080 + env: + - name: MODE2 + value: TEST2 + - name: myprop2 + value: myval2 +``` + +| Key | Type | Description | +|-----------------|--------------------------------------|-------------------------------| +| componentObject | [componentObject](#component-object) | List of components to be used | + + +## commands + +> Example using the exec command + +```yaml +commands: + - exec: + id: devBuild + commandLine: "/artifacts/bin/build-container-full.sh" + component: tools + workingDir: /projects/springbootproject + group: + kind: build + isDefault: true + - exec: + id: devRun + commandLine: "/artifacts/bin/start-server.sh" + component: runtime + workingDir: / + group: + kind: run + isDefault: true +``` + +| Key | Type | Description | +|---------------|----------------------------------|-----------------------------------------------------------| +| commandObject | [commandObject](#command-object) | Command to be executed in an existing component container | + + +# Project Object + +> Pulling from a git location + +```yaml +projects: + - name: nodejs-web-app + git: + location: https://github.com/odo-devfiles/nodejs-ex.git + branch: master + sparseCheckoutDir: /app/ # optional checkout dir + startPoint: 1.0.0 # tag or commit to start at +``` + +> Pulling from a GitHub location + +```yaml +projects: + - name: nodejs-web-app + github: + location: https://github.com/odo-devfiles/nodejs-ex.git + branch: master + sparseCheckoutDir: /app/ # optional checkout dir + startPoint: 1.0.0 # tag or commit to start at +``` + +> Pulling from a zip + +```yaml +projects: + - name: nodejs-web-app + zip: + location: https://github.com/odo-devfiles/nodejs-ex/archive/0.0.1.zip + sparseCheckoutDir: /app/ # optional checkout dir +``` + +Each project may contain three different objects, `git`, `github` or `zip`. + + + +| Key | Type | Description | +|-----------|-------------------------------|------------------------------------------------------------------------------------| +| name | string | Name of your devfile | +| clonePath | string | Path relative the root of your projects to which the project should be cloned into | +| git | [gitObject](#gitobject) | Pull from a Git location | +| github | [githubObject](#githubobject) | Pull from GitHub | +| zip | [zipObject](#zipobject) | Get from a zip location | + +## gitObject + +> Using the gitObject + +```yaml +projects: + - name: nodejs-web-app + git: + location: https://github.com/odo-devfiles/nodejs-ex.git + branch: master + sparseCheckoutDir: /app/ # optional checkout dir + startPoint: 1.0.0 # tag or commit to start at +``` + +| Key | Type | Description | +|------------------|--------|------------------------------------| +| location | string | Location of the git repository | +| branch | string | What branch to use | +| spareCheckoutDir | string | What directory to use when pulling | +| startPoint | string | Tag or commit to start from | + +## githubObject + +> Using the githubObject + +```yaml +projects: + - name: nodejs-web-app + github: + location: https://github.com/odo-devfiles/nodejs-ex.git + branch: master + sparseCheckoutDir: /app/ # optional checkout dir + startPoint: 1.0.0 # tag or commit to start at +``` + +| Key | Type | Description | +|------------------|--------|------------------------------------| +| location | string | Location of the git repository | +| branch | string | What branch to use | +| spareCheckoutDir | string | What directory to use when pulling | +| startPoint | string | Tag or commit to start from | + +## zipObject + +> Using the zipObject + +```yaml +projects: + - name: nodejs-web-app + zip: + location: https://github.com/odo-devfiles/nodejs-ex/archive/0.0.1.zip + sparseCheckoutDir: /app/ # optional checkout dir +``` + +| Key | Type | Description | +|------------------|--------|------------------------------------| +| location | string | Location of the zip | +| spareCheckoutDir | string | What directory to use when pulling | + + + +# Component Object + +> Example using a container using the minimum amount of keys + +```yaml +components: + - container: + name: appsodyrun + image: 'ajymau/java-openliberty-dev:latest' +``` + +Each component must use the `container` object. + + +| Key | Type | Description | +|-----------|-------------------------------------|-------------------------------| +| container | [containerObject](#containerobject) | List of containers to be used | + + +## containerObject + +> Example using an [OpenLiberty](https://github.com/odo-devfiles/registry/blob/master/devfiles/openLiberty/devfile.yaml) container + +```yaml +components: + - container: + name: appsodyrun + image: 'ajymau/java-openliberty-dev:latest' + memoryLimit: 1512Mi + mountSources: true + endpoints: + - name: 9080/tcp + exposure: public + public: true + protocol: http + targetPort: 9080 + env: + - name: MODE2 + value: TEST2 + - name: myprop2 + value: myval2 +``` + +| Key | Type | Required | Description | +|----------------|-----------------------------------------|----------|-------------------------------------------------------------------------------------------------------------| +| name | string | yes | Name of your container | +| image | string | yes | Image version | +| memoryLimit | string | no | Memory limit to be used with your container | +| mountSources | boolean | no | Mount the source or not | +| sourceMapping | string | no | Path in the container where project sources should be transferred / mounted when mountSource is set to true | +| endpoints[] | [endpointObject](#endpointobject) | no | List of endpoints to use | +| volumeMounts[] | [volumeMountsObject](#volumemountsobject) | no | List of volumes to mount | +| env[] | [envObject](#envobject) | no | List of environment variables to use | + + + +## endpointObject + +> Example using an endpoint + +```yaml +components: + - container: + name: appsodyrun + image: 'ajymau/java-openliberty-dev:latest' + endpoints: + - name: 9080/tcp + exposure: public + public: true + protocol: http + targetPort: 9080 +``` + +| Key | Type | Required | Description | +|------------|---------|----------|------------------------------------------------------------------------------------------------------------------------------------------------| +| name | string | yes | Name of your endpoint | +| targetPort | integer | yes | Port number that you are targeting | +| exposure | string | no | `public`, `internal` or `none`. Describes how the endpoint should be exposed on the network | +| path | string | no | Path to the endpoint URL | +| protocol | string | no | `http`, `https`, `ws`, `wss`, `tcp`, `udp`. Describes the application and transport protocols of the traffic that will go through the endpoint | +| secure | boolean | no | Whether or not the endpoint is defined as secure | + + +## volumeMountsObject + +> Example using a volume with a container + +```yaml +components: + - container: + name: tools + image: maysunfaisal/springbootbuild + memoryLimit: 768Mi + command: ['tail'] + args: [ '-f', '/dev/null'] + mountSources: true + volumeMounts: + - name: springbootpvc + path: /data +``` + +| Key | Type | Required | Description | +|------|--------|----------|----------------------------------------------------------------------------------------------------| +| name | string | yes | Name of the volume | +| path | string | no | Path in the component container where the volume should be mounted. Defaults to `/` if blank | + + +# Command Object + +> Example using an exec command within a command object + +```yaml +commands: + - exec: + id: devBuild + component: tools + commandLine: "/artifacts/bin/build-container-full.sh" + workingDir: /projects/springbootproject + group: + kind: build + isDefault: true +``` + +Each command must use the `exec` object. + +| Key | Type | Description | +|------|---------------------------|---------------------------| +| exec | [execObject](#execobject) | The CLI command to be ran | + +## execObject + +> Example using exec command within a command object + +```yaml +commands: + - exec: + id: devBuild + commandLine: "/artifacts/bin/build-container-full.sh" + component: tools + workingDir: /projects/springbootproject + group: + kind: build + isDefault: true + env: + - name: FOO + value: BAR +``` + +| Key | Type | Required | Description | +|-------------|-----------------------------|----------|--------------------------------------------------------| +| id | string | yes | ID of the command | +| commandLine | string | yes | Command to be ran | +| component | string | no | What component that the actions relate to | +| label | string | no | Optional label to be used to describe the command | +| workingDir | string | no | Working directory where the command should be executed | +| group | [groupObject](#groupObject) | no | Group that the command is part of | +| env | [envObject](#envObject) | no | List of environment variables used | + +## groupObject + +> Example using the group object within exec + +```yaml +commands: + - exec: + id: devBuild + commandLine: "/artifacts/bin/build-container-full.sh" + group: + kind: build + isDefault: true +``` + +| Key | Type | Required | Description | +|-----------|---------|----------|--------------------------------------------------------------------------------| +| kind | string | yes | Kind of group the command is part of. Options: `build`, `run`, `test`, `debug` | +| isDefault | boolean | no | Identifies that it is the default command to be ran | + +# Universal objects + +List of objects which are found in multiple parts of Devfile. For example, the [envObject](#envobject) is found within [containerObject](#containerobject) and [execObject](#execobject). + +## envObject + +> Example using environment variables with a container + +```yaml +components: + - container: + name: appsodyrun + image: 'ajymau/java-openliberty-dev:latest' + targetPort: 9080 + env: + - name: MODE2 + value: TEST2 + - name: myprop2 + value: myval2 +``` + +> Example using environment variables within the exec command + +```yaml +commands: + - exec: + id: devBuild + commandLine: "/artifacts/bin/build-container-full.sh" + env: + - name: FOO + value: BAR +``` + +| Key | Type | Required | Description | +|-------|--------|----------|-----------------------------------| +| name | string | yes | Name of the environment variable | +| value | string | yes | Value of the environment variable | diff --git a/docs/public/deploying-a-devfile-using-odo.adoc b/docs/public/deploying-a-devfile-using-odo.adoc index ea8ed4de514..ed8a1280868 100644 --- a/docs/public/deploying-a-devfile-using-odo.adoc +++ b/docs/public/deploying-a-devfile-using-odo.adoc @@ -2,12 +2,11 @@ What is a devfile? -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. +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. With a devfile you can describe: -* The source code being used -* Development components such as IDE tools (VSCode) and application runtimes (Yarn / NPM) +* Development components such as container definition for build and application runtimes * A list of pre-defined commands that can be run * Projects to initially clone @@ -410,4 +409,4 @@ Docker volumes are created for the project source, and any other volumes defined ? Are you sure you want to delete the devfile component: java-spring-boot? Yes ✓ Deleting devfile component java-spring-boot [139ms] ✓ Successfully deleted component ----- \ No newline at end of file +----