diff --git a/docs/modules/user-guide/partials/proc_adding-a-name-to-a-devfile.adoc b/docs/modules/user-guide/partials/proc_adding-a-name-to-a-devfile.adoc index 3997f24d..fc4ada20 100644 --- a/docs/modules/user-guide/partials/proc_adding-a-name-to-a-devfile.adoc +++ b/docs/modules/user-guide/partials/proc_adding-a-name-to-a-devfile.adoc @@ -2,7 +2,22 @@ = Adding a name to a devfile [role="_abstract"] -Adding a name to a devfile is mandatory. Use the `name` or `generateName` attributes (or both) to define the name. +Adding a name to a devfile is mandatory. Use the `name` attribute to define the name. See the following table for metadata properties in a devfile: + +[cols="1,1,1,1"] +|=== +|Key |Type| Required| Description + +|name +|string +|yes +|The name of your devfile. This name links you to the devfile registry if listed. + +|version +|string +|yes +|The version of your devfile. +|=== .Prerequisites @@ -22,23 +37,6 @@ metadata: version: 2.0.0 ---- -. To specify a prefix for automatically generated workspace names, define the `generateName` attribute and not the `name` attribute. -** The workspace name is in the `YYYYY` format, for example, `devfile-sample-2y7kp`. `Y` is a random charater, `[a-z0-9]`. -+ -.Adding a generated name to a devfile - -[source,yaml] ----- -schemaVersion: 2.1.0 -metadata: - generateName: devfile-sample - version: 2.0.0 ----- - -[NOTE] - -Defining `name` or `generateName` has the same effect when creating workspaces using a factory. The value forms the name prefix: `YYYYY` or `YYYYY`. When defining both `generateName` and `name`, `generateName` takes precedence. - [role="_additional-resources"] .Additional resources diff --git a/docs/modules/user-guide/partials/proc_adding-commands-to-a-devfile.adoc b/docs/modules/user-guide/partials/proc_adding-commands-to-a-devfile.adoc index bada60d6..8a089dee 100644 --- a/docs/modules/user-guide/partials/proc_adding-commands-to-a-devfile.adoc +++ b/docs/modules/user-guide/partials/proc_adding-commands-to-a-devfile.adoc @@ -2,7 +2,111 @@ = Adding commands to a devfile [role="_abstract"] -A devfile allows to specify commands to be available for execution in a workspace. Every command can contain a subset of actions. These subsets are related to specific components and are executed in the component containers. +A devfile allows you to specify commands to be available for execution in a workspace. Every command can contain a subset of actions. These subsets are related to specific components and are executed in the component containers. See the following tables for command properties in a devfile: + +.commandObject +[cols="1,1,1,1"] +|=== +|Key |Type| Required| Description + +|exec +|execObject +|no +|The exec command to run. + +|composite +|compositeObject +|no +|The composite command to run. +|=== + +.execObject +[cols="1,1,1,1"] +|=== +|Key |Type| Required| Description + +|id +|string +|yes +|The ID of the command. + +|commandLine +|string +|yes +|The command to run. + +|component +|string +|no +|The component to which the action relates. + +|label +|string +|no +|The optional label to describe the command. + +|workingDir +|string +|no +|The working directory where you execute the command. + +|group +|groupObject +|no +|The group to which the command belongs. + +|environment +|envObject +|no +|The list of environment variables you use. +|=== + +.compositeObject +[cols="1,1,1,1"] +|=== +|Key |Type| Required| Description + +|id +|string +|yes +|The ID of the command. + +|commands +|string +|no +|The exec commands that constitute the composite command and chains multiple commands together. + +|parallel +|boolean +|no +|The flag that indicates if commands are executed in parallel. + +|label +|string +|no +|The optional label to describe the command. + +|group +|groupObject +|no +|The group to which the composite command belongs. The composite command cannot be of the `run` kind. +|=== + +.groupObject +[cols="1,1,1,1"] +|=== +|Key |Type| Required| Description + +|kind +|string +|yes +|The group to which the command belongs, such as: `build`, `run`, `test`, and `debug`. + +|isDefault +|boolean +|no +|Identifies if it is the default command to run. Only one default command can be defined for each group. +|=== .Prerequisites @@ -22,7 +126,6 @@ A devfile allows to specify commands to be available for execution in a workspac * `exec` * `apply` * `composite` -* `vscode-tasks` + .Sample command diff --git a/docs/modules/user-guide/partials/proc_adding-components-to-a-devfile.adoc b/docs/modules/user-guide/partials/proc_adding-components-to-a-devfile.adoc index 02382dac..f0aa02a0 100644 --- a/docs/modules/user-guide/partials/proc_adding-components-to-a-devfile.adoc +++ b/docs/modules/user-guide/partials/proc_adding-components-to-a-devfile.adoc @@ -2,7 +2,127 @@ = Adding components to a devfile [role="_abstract"] -Each component in a single devfile must have a unique name. +Each component in a single devfile must have a unique name and use one of the objects: `container`, `kubernetes`, `openshift`, or `volume`. See the following tables for component properties in a devfile: + +.Component object +[cols="1,1,1,1"] +|=== +|Key |Type| Required| Description + +|container +|componentObject +|no +|The list of containers that you use. +|=== + +.container object +[cols="1,1,1,1"] +|=== +|Key |Type| Required| Description + +|name +|string +|yes +|The name of your container. + +|image +|string +|yes +|The image version. + +|memoryLimit +|string +|no +|The memory limit that you use with your container. + +|mountSources +|boolean +|no +|Choose to mount the source or not. + +|sourceMapping +|string +|no +|The path in the container where you transfer and mount the project sources. This path is available in the container through the environment, `PROJECTS_ROOT`. + +|endpoints +|endpointObject +|no +|The list of endpoints to use. + +|volumeMounts +|volumeMountsObject +|no +|The list of volumes to mount. + +|environment +|envObject +|no +|The list of environment variables to use. +|=== + +.endpoint object +[cols="1,1,1,1"] +|=== +|Key |Type| Required| Description + +|name +|string +|yes +|The name of your endpoint. + +|targetPort +|integer +|yes +|The port number that you target. + +|exposure +|string +|no +|Use the following attributes to describe how to expose the endpoints on the network: `public`, `internal`, `none`. If not specified, the default attribute is `public`. + +|path +|string +|no +|The path to the endpoint URL. + +|protocol +|string +|no +|Use the following attributes to describe the application and transport protocols of the traffic that goes through the endpoint: `http`, `https`, `ws`, `wss`, `tcp`, `udp`. If not specified, the default attribute is `http`. + +|secure +|boolean +|no +|Choose to define the endpoint as secure or not. +|=== + +.volume object +[cols="1,1,1,1"] +|=== +|Key |Type| Required| Description + +|name +|string +|yes +|The name of the volume components that you use. + +|path +|string +|no +|The path in the component container where you mount the volume. + +|name +|string +|yes +|The name of the volume component. + +|size +|string +|no +|The size of the storage you create. +|=== + .Prerequisites diff --git a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc index 039fcbd7..dc331120 100644 --- a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc +++ b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc @@ -2,7 +2,38 @@ = Adding event bindings [role="_abstract"] -This section describes how to add an event to a v2.x devfile. An event specified in a v1.x devfile still works in a v2.x devfile. +This section describes how to add an event to a v2.x devfile. An event can have three different type of objects: + +. preStartObject +. postStartObject +. preStopObject + +.preStartObject +You can execute preStart events as init containers for the project pod in the order you specify the preStart events. The devfile `commandLine` and `workingDir` are the commands for the init container. As a result, the init container overwrites either the devfile or the container image `command` and `args`. If you use a composite command with `parallel: true`, the composite command executes as Kubernetes init containers. + +.postStartObject +When you create the Kubernetes deployment for the `odo` component, execute the postStart events. + +.preStopObject +Before you delete the Kubernetes deployment for the `odo` component, execute the preStop events. + +See the following list for event properties in a devfile: + +.envObject +[cols="1,1,1,1"] +|=== +|Key |Type| Required| Description + +|name +|string +|yes +|The name of the environment variable. + +|value +|string +|yes +|The value of the environment variable. +|=== .Procedure diff --git a/docs/modules/user-guide/partials/proc_adding-projects-to-a-devfile.adoc b/docs/modules/user-guide/partials/proc_adding-projects-to-a-devfile.adoc index b2e95ce5..b20a606f 100644 --- a/docs/modules/user-guide/partials/proc_adding-projects-to-a-devfile.adoc +++ b/docs/modules/user-guide/partials/proc_adding-projects-to-a-devfile.adoc @@ -2,8 +2,56 @@ = Adding projects to a devfile [role="_abstract"] -This section describes how to add one or more projects to a devfile. - +This section describes how to add one or more projects to a devfile. Each starter project can contain either a `git` or `zip` object. See the following tables for project properties in a devfile: + +.starterProject object +[cols="1,1,1,1"] +|=== +|Key |Type| Required| Description + +|name +|string +|yes +|The name of your devfile. + +|description +|string +|no +|The description of your starterProject. + +|clonePath +|string +|no +|The path relative to the root of your projects. Clone your projects into this path. +|=== + + +.git object +[cols="1,1,1,1"] +|=== +|Key |Type| Required| Description + +|checkoutFrom +|string +|no +|The location of your git repository. + +|remotes +|string +|yes +|The branch that you use. +|=== + +.zip object +[cols="1,1,1,1"] +|=== +|Key |Type| Required| Description + +|location +|string +|no +|The location of your zip. +|=== .Prerequisites diff --git a/docs/modules/user-guide/partials/proc_adding-schema-version-to-a-devfile.adoc b/docs/modules/user-guide/partials/proc_adding-schema-version-to-a-devfile.adoc index 221c42da..38dfec33 100644 --- a/docs/modules/user-guide/partials/proc_adding-schema-version-to-a-devfile.adoc +++ b/docs/modules/user-guide/partials/proc_adding-schema-version-to-a-devfile.adoc @@ -2,8 +2,17 @@ = Adding schema version to a devfile [role="_abstract"] -The `schemaVersion` attribute is mandatory in a devfile. +The `schemaVersion` attribute is mandatory in a devfile. See the following table for `schemaVersion` properties in a devfile: +[cols="1,1,1,1"] +|=== +|Key |Type| Required| Description + +|schemaVersion +|string +|yes +|The version of the devfile schema that the devfile uses. +|=== .Procedure