From 5f7f576f11bb0479dd552577c15c702543dae546 Mon Sep 17 00:00:00 2001 From: jc-berger <> Date: Wed, 9 Dec 2020 15:09:58 -0500 Subject: [PATCH] removed references to che from devfile docs omitted eclipse references fixed typo and omitted unneeded lines added needed context ascii changes --- .../proc_adding-a-name-to-a-devfile.adoc | 18 +++------ .../proc_adding-commands-to-a-devfile.adoc | 38 ++++++------------- ...ding-container-component-to-a-devfile.adoc | 8 +--- ..._adding-plugin-component-to-a-devfile.adoc | 4 +- .../partials/proc_defining-endpoints.adoc | 2 +- .../proc_defining-environment-variables.adoc | 3 +- .../proc_limiting-resources-usage.adoc | 23 ++++++----- .../proc_migrating-schema-version.adoc | 7 ++-- .../proc_specifying-persistent-storage.adoc | 4 +- 9 files changed, 39 insertions(+), 68 deletions(-) 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 38884b63..f019e30d 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 @@ -10,39 +10,33 @@ Adding a name to a devfile is mandatory. Both `name` and `generateName` are opti .Procedure -. To specify a static name for the workspace, define the `name` attribute. +. To specify a static name for the workspace, define the `name` attribute. + .Adding a static name to a devfile -==== + [source,yaml] ---- schemaVersion: 2.0.0 metadata: name: devfile-sample ---- -==== -. To specify a prefix for automatically generated workspace names, define the `generateName` attribute and don't define the `name` attribute. The workspace name will be in the `YYYYY` format (for example, `che-2y7kp`). `Y` is random `[a-z0-9]` character. +. To specify a prefix for automatically generated workspace names, define the `generateName` attribute and don't define the `name` attribute. The workspace name will be in the `YYYYY` format (for example, `devfile-sample-2y7kp`). `Y` is random `[a-z0-9]` character. + .Adding a generated name to a devfile -==== + [source,yaml] ---- schemaVersion: 2.0.0 metadata: - generateName: che- + generateName: devfile-sample- ---- -==== - [NOTE] -==== -For workspaces created using a factory, defining `name` or `generateName` has the same effect. The defined value is used as the name prefix: `YYYYY` or `YYYYY`. When both `generateName` and `name` are defined, `generateName` takes precedence. -==== +For workspaces created using a factory, defining `name` or `generateName` has the same effect. The defined value is used as the name prefix: `YYYYY` or `YYYYY`. When both `generateName` and `name` are defined, `generateName` takes precedence. [role="_additional-resources"] .Additional resources * xref:api-reference.adoc[] - 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 9568e394..e6a8dd88 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 @@ -20,7 +20,6 @@ A devfile allows to specify commands to be available for execution in a workspac . For each command, define a mandatory type of one of the following types: `exec` or `vscode-tasks`. + .Sample command -==== [source,yaml] ---- commands: @@ -30,14 +29,12 @@ A devfile allows to specify commands to be available for execution in a workspac commandLine: mvn clean workingDir: /projects/spring-petclinic ---- -==== . Define attributes for the `exec` command to run using the default shell in the container. + * A `commandLine` attribute that is a command to execute. * A `component` attribute that specifies the container in which to execute the command. + -==== [source,yaml] ---- schemaVersion: 2.0.0 @@ -58,31 +55,28 @@ components: command: ['sleep', 'infinity'] env: - name: GOPATH - value: $(CHE_PROJECTS_ROOT)/go + value: $(PROJECTS_ROOT)/go - name: GOCACHE value: /tmp/go-cache commands: - id: compile and run exec: component: go-cli - commandLine: “go get -d && go run main.go” - workingDir: “${CHE_PROJECTS_ROOT}/src/github.com/acme/my-go-project” + commandLine: "go get -d && go run main.go" + workingDir: "${PROJECTS_ROOT}/src/github.com/acme/my-go-project" runAsUser: root ---- -==== + [NOTE] -==== -* Any component on which commands are executed must define a `name` attribute. This name is used to reference the component in the command definition. Example: `name: go-cli` in the component definition and `component: go-cli` in the command definition. This ensures that {che-prod} can find the correct container to run the command in. + +* Any component on which commands are executed must define a `name` attribute. This name is used to reference the component in the command definition. Example: `name: go-cli` in the component definition and `component: go-cli` in the command definition. * A command can have only one action, though you can use `composite` commands to execute several commands either sequentially or in parallel. -==== . Define attributes for the `vscode-task` or `vscode-launch` command to run using the Editor. + -If the editor in the workspace supports it, the devfile can specify additional configuration in the editor-specific format. This is dependent on the integration code present in the workspace editor itself and so is not a generic mechanism. However, the default Che-Theia editor within {che-prod} is equipped to understand the `tasks.json` and `launch.json` files provided in the devfile. +If the editor in the workspace supports it, the devfile can specify additional configuration in the editor-specific format. This is dependent on the integration code present in the workspace editor itself and so is not a generic mechanism. + -==== [source,yaml] ---- schemaVersion: 2.0.0 @@ -111,14 +105,12 @@ commands: } ---- -This example shows association of a `tasks.json` file with a devfile. Notice the `vscode-task` type that instructs the Che-Theia editor to interpret this command as a tasks definition and `referenceContent` attribute that contains the contents of the file itself. You can also save this file separately from the devfile and use `reference` attribute to specify a relative or absolute URL to it. -==== +This example shows association of a `tasks.json` file with a devfile. Notice the `vscode-task` type that instructs the editor to interpret this command as a tasks definition and `referenceContent` attribute that contains the contents of the file itself. You can also save this file separately from the devfile and use `reference` attribute to specify a relative or absolute URL to it. . Command group + A given command can be assigned to one or more groups that represents the nature of the command. The support groups are: `build`, `run`, `test` and `debug`. For each of the groups, one default command can be defined in each group by specifying the `isDefault` value. + -==== [source,yaml] ---- schemaVersion: 2.0.0 @@ -140,24 +132,22 @@ commands: - id: package exec: component: maven - commandLine: “mvn package” + commandLine: "mvn package" group: kind: build - id: install exec: component: maven - commandLine: “mvn install” + commandLine: "mvn install" group: kind: build isDefault: true ---- -==== . Composite command + A composite command can be defined to chain multiple commands together. The individual commands that are called from a composite command can be referenced by the `name` of the command. A `parallel` boolean can be specified to determine if the commands within a composite command are being executed sequentially or in parallel. + -==== [source,yaml] ---- schemaVersion: 2.0.0 @@ -179,13 +169,13 @@ commands: - id: package exec: component: maven - commandLine: “mvn package” + commandLine: "mvn package" group: kind: build - id: install exec: component: maven - commandLine: “mvn install” + commandLine: "mvn install" group: kind: build isDefault: true @@ -196,13 +186,11 @@ commands: - package parallel: false ---- -==== . Command preview URL + It is possible to specify a preview URL for commands that expose web UI. This URL is offered for opening when the command is executed. + -==== [source,yaml] ---- commands: @@ -213,14 +201,12 @@ commands: path: /myweb <2> component: go-cli commandLine: "go run webserver.go" - workingDir: ${CHE_PROJECTS_ROOT}/webserver + workingDir: ${PROJECTS_ROOT}/webserver ---- <1> TCP port where the application listens. Mandatory parameter. <2> The path part of the URL to the UI. Optional parameter. The default is root (`/`). The example above opens `++http://____/myweb++`, where `__` is the URL to the dynamically created Kubernetes Ingress or OpenShift Route. -==== - [role="_additional-resources"] .Additional resources diff --git a/docs/modules/user-guide/partials/proc_adding-container-component-to-a-devfile.adoc b/docs/modules/user-guide/partials/proc_adding-container-component-to-a-devfile.adoc index 5a5130ef..11a73e7e 100644 --- a/docs/modules/user-guide/partials/proc_adding-container-component-to-a-devfile.adoc +++ b/docs/modules/user-guide/partials/proc_adding-container-component-to-a-devfile.adoc @@ -15,7 +15,6 @@ A component type that allows to define a container image-based configuration of . Define a component using the type `container`. + .A `container` component -==== [source,yaml] ---- components: @@ -41,10 +40,8 @@ A component type that allows to define a container image-based configuration of command: ['tail'] args: ['-f', '/dev/null'] ---- -==== + .A minimal `container` component* -==== [source,yaml] ---- schemaVersion: 2.0.0 @@ -57,7 +54,6 @@ components: memoryLimit: 512Mi command: ['sleep', 'infinity'] ---- -==== + It specifies the type of the component, `container` and the `image` attribute names the image to be used for the component using the usual Docker naming conventions, that is, the above `image` attribute is equal to `docker.io/library/golang:latest`. + @@ -67,7 +63,6 @@ A `container` component has many features that enable augmenting the image with + For the `container` component to have access to the project sources, you must set the `mountSources` attribute to `true`. + -==== [source,yaml] ---- schemaVersion: 2.0.0 @@ -81,9 +76,8 @@ components: mountSources: true command: ['sleep', 'infinity'] ---- -==== + -The sources is mounted on a location stored in the `CHE_PROJECTS_ROOT` environment variable that is made available in the running container of the image. This location defaults to `/projects`. If `sourceMapping` is defined in the container, it overrides the 'CHE_PROJECT_ROOT' value if present and mounts the source to the path defined by `sourceMapping`. +The sources is mounted on a location stored in the `PROJECTS_ROOT` environment variable that is made available in the running container of the image. This location defaults to `/projects`. If `sourceMapping` is defined in the container, it overrides the 'PROJECT_ROOT' value if present and mounts the source to the path defined by `sourceMapping`. . Container Entrypoint + diff --git a/docs/modules/user-guide/partials/proc_adding-plugin-component-to-a-devfile.adoc b/docs/modules/user-guide/partials/proc_adding-plugin-component-to-a-devfile.adoc index fbc046dd..d84b8f51 100644 --- a/docs/modules/user-guide/partials/proc_adding-plugin-component-to-a-devfile.adoc +++ b/docs/modules/user-guide/partials/proc_adding-plugin-component-to-a-devfile.adoc @@ -23,7 +23,7 @@ This section describes how to add a `plugin` component to a devfile. components: - name: exec-plugin plugin: - id: eclipse/che-machine-exec-plugin/0.0.1 + id: machine-exec-plugin/0.0.1 ---- ==== @@ -36,7 +36,7 @@ This section describes how to add a `plugin` component to a devfile. components: - name: exec-plugin plugin: - id: eclipse/che-machine-exec-plugin/0.0.1 + id: machine-exec-plugin/0.0.1 registryUrl: https://my-customregistry.com ---- ==== diff --git a/docs/modules/user-guide/partials/proc_defining-endpoints.adoc b/docs/modules/user-guide/partials/proc_defining-endpoints.adoc index bc50289b..620ae39f 100644 --- a/docs/modules/user-guide/partials/proc_defining-endpoints.adoc +++ b/docs/modules/user-guide/partials/proc_defining-endpoints.adoc @@ -30,7 +30,7 @@ components: command: ['sleep', 'infinity'] env: - name: GOPATH - value: $(CHE_PROJECTS_ROOT)/go + value: $(PROJECTS_ROOT)/go - name: GOCACHE value: /tmp/go-cache endpoints: diff --git a/docs/modules/user-guide/partials/proc_defining-environment-variables.adoc b/docs/modules/user-guide/partials/proc_defining-environment-variables.adoc index c7025b49..879d6555 100644 --- a/docs/modules/user-guide/partials/proc_defining-environment-variables.adoc +++ b/docs/modules/user-guide/partials/proc_defining-environment-variables.adoc @@ -25,7 +25,7 @@ components: command: ['sleep', 'infinity'] env: - name: GOPATH - value: $(CHE_PROJECTS_ROOT)/go + value: $(PROJECTS_ROOT)/go ---- ==== @@ -55,4 +55,3 @@ metadata: * The predefined variables are available for use in custom definitions. ==== - diff --git a/docs/modules/user-guide/partials/proc_limiting-resources-usage.adoc b/docs/modules/user-guide/partials/proc_limiting-resources-usage.adoc index 13d6e30d..4e110302 100644 --- a/docs/modules/user-guide/partials/proc_limiting-resources-usage.adoc +++ b/docs/modules/user-guide/partials/proc_limiting-resources-usage.adoc @@ -17,7 +17,7 @@ To specify a container(s) memory limit for `container`, `plugin`, use the `memor components: - name: exec-plugin plugin: - id: eclipse/che-machine-exec-plugin/0.0.1 + id: eclipse/machine-exec-plugin/0.0.1 memoryLimit: 1Gi - name: maven container: @@ -30,8 +30,6 @@ This limit will be applied to every container of the given component. + For `plugin` components, RAM limits can be described in the plug-in descriptor file, typically named `meta.yaml`. + -If none of them are specified, system-wide defaults will be applied (see description of `pass:[CHE_WORKSPACE_SIDECAR_DEFAULT__MEMORY__LIMIT__MB]` system property). - . Specify container memory request for components + @@ -44,7 +42,7 @@ To specify a container(s) memory request for `plugin` use the `memoryRequest` pa components: - name: exec-plugin plugin: - id: eclipse/che-machine-exec-plugin/0.0.1 + id: eclipse/machine-exec-plugin/0.0.1 memoryLimit: 1Gi memoryRequest: 512M - name: maven @@ -59,8 +57,8 @@ This limit will be applied to every container of the given component. + For `plugin` components, RAM requests can be described in the plug-in descriptor file, typically named `meta.yaml`. + -If none of them are specified, system-wide defaults are applied (see description of `pass:[CHE_WORKSPACE_SIDECAR_DEFAULT__MEMORY__REQUEST__MB]` system property). - +If they are not specified, the values are undetermined: they may or may not be inferred from the application that consumes the devfile or from Kubernetes. ++ . Specify container CPU limit for components + @@ -73,7 +71,7 @@ To specify a container(s) CPU limit for `plugin` or `container` use the `cpuLimi components: - name: exec-plugin plugin: - id: eclipse/che-machine-exec-plugin/0.0.1 + id: eclipse/machine-exec-plugin/0.0.1 cpuLimit: 1.5 - name: maven container: @@ -86,8 +84,8 @@ This limit will be applied to every container of the given component. + For the `plugin` components, CPU limits can be described in the plug-in descriptor file, typically named `meta.yaml`. + -If none of them are specified, system-wide defaults are applied (see description of `pass:[CHE_WORKSPACE_SIDECAR_DEFAULT__CPU__LIMIT__CORES]` system property). - +If they are not specified, the values are undetermined: they may or may not be inferred from the application that consumes the devfile or from Kubernetes. ++ . Specify container CPU request for components + @@ -100,7 +98,7 @@ To specify a container(s) CPU request for `plugin` or `container` use the `cpuRe components: - name: exec-plugin plugin: - id: eclipse/che-machine-exec-plugin/0.0.1 + id: eclipse/machine-exec-plugin/0.0.1 cpuLimit: 1.5 cpuRequest: 0.225 - name: maven @@ -113,6 +111,7 @@ To specify a container(s) CPU request for `plugin` or `container` use the `cpuRe + This limit will be applied to every container of the given component. + -For the `pugin` component type, CPU requests can be described in the plug-in descriptor file, typically named `meta.yaml`. +For the `plugin` component type, CPU requests can be described in the plug-in descriptor file, typically named `meta.yaml`. ++ +If they are not specified, the values are undetermined: they may or may not be inferred from the application that consumes the devfile or from Kubernetes. + -If none of them are specified, system-wide defaults are applied (see description of `pass:[CHE_WORKSPACE_SIDECAR_DEFAULT__CPU__REQUEST__CORES]` system property). diff --git a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc index 21ee0c2a..cf8d7dc2 100644 --- a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc @@ -10,14 +10,14 @@ This section describes how to migrate schema version. [cols="1a,1a"] |==== -| +| [source,yaml] ---- v1.0 --- apiVersion: 1.0.0 metadata: - name: che-in-che-out + name: devfile-sample ---- | [source,yaml] @@ -26,7 +26,7 @@ v2.0 --- schemaVersion: 2.0.0 metadata: - name: che-in-che-out + name: devfile-sample ---- |==== @@ -35,4 +35,3 @@ metadata: [role="_additional-resources"] .Additional resources * See link:https://github.com/che-incubator/devworkspace-api/issues/7[corresponding issue] - diff --git a/docs/modules/user-guide/partials/proc_specifying-persistent-storage.adoc b/docs/modules/user-guide/partials/proc_specifying-persistent-storage.adoc index c6e37f44..82c105a9 100644 --- a/docs/modules/user-guide/partials/proc_specifying-persistent-storage.adoc +++ b/docs/modules/user-guide/partials/proc_specifying-persistent-storage.adoc @@ -43,7 +43,7 @@ components: id: eclipse/che-theia/next env: - name: HOME - value: $(CHE_PROJECTS_ROOT) + value: $(PROJECTS_ROOT) volumeMounts: - name: cache path: /.cache @@ -67,4 +67,4 @@ components: - name: mongo-persistent-storage path: /data/db ---- -==== \ No newline at end of file +====