From dbab2e01399dc459adbd665da6749acd8bf5a0e8 Mon Sep 17 00:00:00 2001 From: jc-berger Date: Mon, 1 Mar 2021 12:27:58 -0500 Subject: [PATCH 1/3] modified docs to adhere to schema more content changes to align with schema more source.yaml changes to align with schema more changes to yamls tweaks to yamls. more changes to come major change to adding kubernetes doc. changed yaml for event bindings doc more content and yaml changes minor tweaks and adjusted tab spacing in yaml addressed doc review comments more language review fixed capitalization error --- .../proc_adding-a-name-to-a-devfile.adoc | 2 +- .../proc_adding-commands-to-a-devfile.adoc | 68 +--------- .../partials/proc_adding-event-bindings.adoc | 52 ++++---- ...ing-kubernetes-component-to-a-devfile.adoc | 121 ++++-------------- ..._adding-plugin-component-to-a-devfile.adoc | 55 +------- .../proc_adding-projects-to-a-devfile.adoc | 26 ++-- .../partials/proc_defining-endpoints.adoc | 82 +++--------- .../proc_defining-environment-variables.adoc | 35 +---- .../proc_specifying-persistent-storage.adoc | 50 +------- 9 files changed, 103 insertions(+), 388 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 f019e30d..0e01d931 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 @@ -29,7 +29,7 @@ metadata: ---- schemaVersion: 2.0.0 metadata: - generateName: devfile-sample- + name: devfile-sample ---- [NOTE] 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 e6a8dd88..6176745b 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 @@ -17,7 +17,7 @@ A devfile allows to specify commands to be available for execution in a workspac . For each command, define an unique value for the mandatory `id` attribute. -. For each command, define a mandatory type of one of the following types: `exec` or `vscode-tasks`. +. For each command, define a mandatory type of one of the following types: `exec`, `apply`, `composite`, or `vscode-tasks`. + .Sample command [source,yaml] @@ -39,7 +39,7 @@ A devfile allows to specify commands to be available for execution in a workspac ---- schemaVersion: 2.0.0 metadata: - name: MyDevfile + name: mydevfile projects: - name: my-go-project clonePath: go/src/github.com/acme/my-go-project @@ -64,49 +64,12 @@ commands: component: go-cli 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. - * 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. -+ -[source,yaml] ----- -schemaVersion: 2.0.0 -metadata: - name: MyDevfile -projects: - - name: my-go-project - clonePath: go/src/github.com/acme/my-go-project - git: - remotes: - origin: "https://github.com/acme/my-go-project.git" -commands: - - id: task - vscode-task: - name: tasks - referenceContent: > - { - "version": "2.0.0", - "tasks": [ - { - "label": "create test file", - "type": "shell", - "command": "touch ${workspaceFolder}/test.file" - } - ] - } ----- - -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. @@ -115,7 +78,7 @@ A given command can be assigned to one or more groups that represents the nature ---- schemaVersion: 2.0.0 metadata: - name: MyDevfile + name: mydevfile projects: - name: my-maven-project clonePath: maven/src/github.com/acme/my-maven-project @@ -152,7 +115,7 @@ A composite command can be defined to chain multiple commands together. The indi ---- schemaVersion: 2.0.0 metadata: - name: MyDevfile + name: mydevfile projects: - name: my-maven-project clonePath: maven/src/github.com/acme/my-maven-project @@ -179,7 +142,7 @@ commands: group: kind: build isDefault: true - - id: installAndPackage + - id: installandpackage composite: commands: - install @@ -187,27 +150,6 @@ commands: 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: - - id: tasks - exec: - previewUrl: - port: 8080 <1> - path: /myweb <2> - component: go-cli - commandLine: "go run webserver.go" - 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-event-bindings.adoc b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc index cdfac090..a013f442 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,7 @@ = Adding event bindings [role="_abstract"] -Adding event bindings. +Commands can be bound to events to form four different types of events: `preStart`, `postStart`, `preStop`, and `postStop`. .Prerequisites @@ -17,41 +17,33 @@ Adding event bindings. ---- # v2.0 --- -components: - - container: - name: "copier" - image: '' - - container: - name: "maven" - image: '' - - plugin: - id: theia -Commands: -containerBuild: -reference: -composite: - - - exec: - name: "copyNeededFiles" - component: "copier" - commandLine: "cp somefile" - - exec: - name: "buildAll" - component: "maven" - commandLine: "mvn ..." - - vsCodeTask: - name: "openFile" - component: "theia" +commands: + - id: init-project + apply: + component: tools + - id: copy-artifacts + exec: + component: tools + commandLine: "cp files" + workingDir: $PROJECTS_ROOT + - id: init-cache + exec: + component: tools + commandLine: "init cache" + workingDir: /.m2 + - id: pre-compile-cmd + composite: + commands: + - copy-artifacts + - init-cache events: preStart: - - "copyNeededFiles" + - init-project postStart: - - "buildAll" - - "openFile" + - pre-compile-cmd ---- ==== [role="_additional-resources"] .Additional resources * See https://github.com/che-incubator/devworkspace-api/issues/32[corresponding issue]. - diff --git a/docs/modules/user-guide/partials/proc_adding-kubernetes-component-to-a-devfile.adoc b/docs/modules/user-guide/partials/proc_adding-kubernetes-component-to-a-devfile.adoc index f7e79bc8..35a27e7c 100644 --- a/docs/modules/user-guide/partials/proc_adding-kubernetes-component-to-a-devfile.adoc +++ b/docs/modules/user-guide/partials/proc_adding-kubernetes-component-to-a-devfile.adoc @@ -1,8 +1,8 @@ [id="proc_adding-kubernetes-component-to-a-devfile_{context}"] -= Adding `kubernetes` component to a devfile += Adding a `kubernetes` or `openshift` component to a devfile [role="_abstract"] -This section describes how to add a `kubernetes` component to a devfile. A complex component type that allows to apply configuration from a list of Kubernetes or OpenShift components. +This section describes how to add either a `kubernetes` or `openshfit` component to a devfile. You can apply configurations to your devfile with `kubernetes` or `openshift` components. .Prerequisites @@ -12,116 +12,45 @@ This section describes how to add a `kubernetes` component to a devfile. A compl .Procedure -. Define a component using the type `kubernetes`. +. Define a component using the type `kubernetes` or `openshift`. -. The content can be provided through the `reference` attribute, which points to the file with the component content. +. Provide the content through the `uri` or `inlined` property. + -.Adding `kubernetes` component using the `reference` attribute +.Adding `openshift` component using the `uri` property ==== [source,yaml] ---- components: - name: mysql - kubernetes: - reference: petclinic.yaml - selector: - app.kubernetes.io/name: mysql - app.kubernetes.io/component: database - app.kubernetes.io/part-of: petclinic + openshift: + uri: petclinic.yaml ---- ==== - -. Alternatively, to post a devfile with such components to REST API, the contents of the Kubernetes or OpenShift list can be embedded into the devfile using the `referenceContent` field: -+ -.Adding `kubernetes` component using the `referenceContent` attribute -==== -[source,yaml] ----- - components: - - name: mysql - kubernetes: - reference: petclinic.yaml - referenceContent: | - kind: List - items: - - - apiVersion: v1 - kind: Pod - metadata: - name: ws - spec: - containers: - ... etc ----- -==== - -. Overriding container entrypoints. As with the xref:component-type-container{context}[`container` component], it is possible to override the entrypoint of the containers contained in the Kubernetes or OpenShift list using the `command` and `args` properties (as link:https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#notes[understood] by Kubernetes). + -There can be more containers in the list (contained in Pods or Pod templates of deployments). It is therefore necessary to select which containers to apply the entrypoint changes to as follows: -+ -.Overriding container entrypoints +.Adding a `kubernetes` component using the `inlined` property ==== [source,yaml] ---- components: - - name: appDeployment - kubernetes: - reference: app-deployment.yaml - entrypoints: - - parentName: mysqlServer - command: ['sleep'] - args: ['infinity'] - - parentSelector: - app: prometheus - args: ['-f', '/opt/app/prometheus-config.yaml'] + - name: myk8deploy + kubernetes: + inlined: | + apiVersion: batch/v1 + kind: Job + metadata: + name: pi + spec: + template: + spec: + containers: + - name: job + image: myimage + command: ["some", "command"] + restartPolicy: Never ---- ==== + -The `entrypoints` list contains constraints for picking the containers along with the `command` and `args` parameters to apply to them. In the example above, the constraint is `parentName: mysqlServer`, which will cause the command to be applied to all containers defined in any parent object called `mysqlServer`. The parent object is assumed to be a top level object in the list defined in the referenced file, which is `app-deployment.yaml` in the example above. -+ -Other types of constraints (and their combinations) are possible: -+ -`containerName`:: the name of the container -`parentName`:: the name of the parent object that (indirectly) contains the containers to override -`parentSelector`:: the set of labels the parent object needs to have -+ -A combination of these constraints can be used to precisely locate the containers inside the referenced Kubernetes list. +. Specify the endpoint through the endpoint property with `kubernetes` or `openshift` components. -. Overriding container environment variables -+ -To provision or override entrypoints in a Kubernetes or OpensShift component, configure it in the following way: -+ -.Overriding container environment variables -==== -[source,yaml] ----- - components: - - name: appDeployment - kubernetes: - reference: app-deployment.yaml - env: - - name: ENV_VAR - value: value ----- -==== -+ -This is useful for temporary content or without access to editing the referenced content. The specified environment variables are provisioned into each init container and containers inside all Pods and Deployments. - -. Specifying mount-source option -+ -To specify a project sources directory mount into container(s), use the `mountSources` parameter: -+ -.Specifying mount-source option -==== -[source,yaml] ----- - components: - - name: appDeployment - kubernetes: - reference: app-deployment.yaml - mountSources: true ----- -==== +. Associate `kubernetes` or `openshift` components with `Apply` commands. If you do not associate `Apply` commands, they are assumed to be applied at start up. + -If enabled, project sources mounts will be applied to every container of the given component. -This parameter is also applicable for `plugin` type components. 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 d84b8f51..4c95084b 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 @@ -14,74 +14,33 @@ This section describes how to add a `plugin` component to a devfile. . Define a component using the type `plugin`. -. Define the `id` attribute. It is slash-separated publisher, name and version of plug-in from the Plug-in registry. List of available {prod-short} plug-ins and more information about registry can be found in the link:https://github.com/eclipse/che-plugin-registry[{prod-short} plug-in registry] GitHub repository. +. Define the `id` attribute. It is the stack name in a devfile v2 registry. Devfile v2 registry should follow the convention according to the link:https://github.com/devfile/api/blob/master/docs/proposals/registry/index-server-REST-API.md[proposal]. + .A devfile defining a plug-in `id` ==== [source,yaml] ---- components: - - name: exec-plugin + - name: plugin-name plugin: - id: machine-exec-plugin/0.0.1 + id: nodejs ---- ==== -. Optionally, specify an alternative component registry using the `registryUrl` parameter: +. Optional: Specify an alternative devfile registry using the `registryUrl` parameter: + -.A devfile defining a plug-in `id` and an alternative component registry +.Defining a plugin `id` and an alternative devfile registry ==== [source,yaml] ---- components: - - name: exec-plugin + - name: plugin-name plugin: - id: machine-exec-plugin/0.0.1 + id: nodejs registryUrl: https://my-customregistry.com ---- ==== -. Optionally, provide a direct link to the component descriptor (typically named `meta.yaml`) using the `reference` attribute, instead of using the `id`. -+ -.A devfile defining a plug-in with a direct link to the component descriptor -==== -[source,yaml] ----- - components: - - name: exec-plugin - plugin: - reference: https://raw.githubusercontent.com.../plugin/1.0.1/meta.yaml ----- -==== -+ -NOTE: It is impossible to mix the `id` and `reference` fields in a single component definition; they are mutually exclusive. - - -. Optionally, provide plugin component configuration using the `preferences` attribute -+ -.Configuring JVM using plug-in preferences -==== -[source,yaml] ----- - id: redhat/java/0.38.0 - plugin: - preferences: - java.jdt.ls.vmargs: '-noverify -Xmx1G -XX:+UseG1GC -XX:+UseStringDeduplication' ----- -==== -+ -.Configuring preferences as an array: -==== -[source,yaml] ----- - id: redhat/java/0.38.0 - plugin: - preferences: - go.lintFlags: ["--enable-all", "--new"] ----- -==== - - [role="_additional-resources"] .Additional resources 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 f9a1b7b0..731f8971 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 @@ -26,8 +26,10 @@ metadata: projects: - name: petclinic git: - location: 'https://github.com/spring-projects/spring-petclinic.git' - branch: master + remotes: + origin: "https://github.com/spring-projects/spring-petclinic.git" + checkoutFrom: + revision: master ---- ==== + @@ -41,10 +43,12 @@ metadata: projects: - name: frontend git: - location: https://github.com/acmecorp/frontend.git + remotes: + origin: "https://github.com/acmecorp/frontend.git" - name: backend git: - location: https://github.com/acmecorp/backend.git + remotes: + origin: "https://github.com/acmecorp/backend.git" ---- ==== @@ -52,9 +56,9 @@ projects: -. For each project, define a mandatory source of one of the following types: `git`, `github` and `zip`. +. For each project, define a mandatory source of either the `git` or `zip` type. -`git`:: Projects with sources in Git. The location points to a clone link. +`git`:: Projects with sources in Git. `checkoutFrom` refers to the branch being used. + .Project-source type: git ==== @@ -67,16 +71,10 @@ projects: origin: "https://github.com/my-org/project1.git" checkoutFrom: revision: master <1> - tag: 7.2.0 - commitId: 36fe587 - branch: master ---- -<1> `startPoint` is the general value for `tag`, `commitId`, and `branch`. The `startPoint`, `tag`, `commitId`, and `branch` parameters are mutually exclusive. When more than one is supplied, the following order is used: `startPoint`, `tag`, `commitId`, `branch`. ==== -`github`:: Same as `git` but for projects hosted on link:https://github.com/[GitHub] only. Use `git` for projects that do not use GitHub-specific features. - -`zip`:: Projects with sources in a ZIP archive. Location points to a ZIP file. +`zip`:: Projects with sources in a ZIP archive. `location` refers to the URL of a ZIP file. + .Project-source type: zip ==== @@ -102,7 +100,7 @@ projects: - name: my-project-resource clonePath: resources/my-project zip: - location: http://host.net/path/project-res.zip + location: http://host.net/path/project-res.zip - name: my-project2 git: remotes: diff --git a/docs/modules/user-guide/partials/proc_defining-endpoints.adoc b/docs/modules/user-guide/partials/proc_defining-endpoints.adoc index 620ae39f..212e84eb 100644 --- a/docs/modules/user-guide/partials/proc_defining-endpoints.adoc +++ b/docs/modules/user-guide/partials/proc_defining-endpoints.adoc @@ -8,13 +8,13 @@ Components of any type can specify the endpoints that the container exposes. The . Specify endpoints properties as shown in the following example: + -.Specify endpoints properties +.Specifying endpoint properties ==== [source,yaml] ---- schemaVersion: 2.0.0 metadata: - name: MyDevfile + name: mydevfile projects: - name: my-go-project clonePath: go/src/github.com/acme/my-go-project @@ -29,113 +29,73 @@ components: mountSources: true command: ['sleep', 'infinity'] env: - - name: GOPATH + - name: gopath value: $(PROJECTS_ROOT)/go - - name: GOCACHE + - name: gocache value: /tmp/go-cache endpoints: - name: web targetPort: 8080 - configuration: - discoverable: false - public: true - protocol: tcp - scheme: http + exposure: public - name: postgres container: image: postgres memoryLimit: 512Mi env: - - name: POSTGRES_USER + - name: postgres_user value: user - - name: POSTGRES_PASSWORD + - name: postgres_password value: password - - name: POSTGRES_DB + - name: postgres_db value: database endpoints: - name: postgres targetPort: 5432 - configuration: - discoverable: true - public: false + exposure: none ---- ==== -Here, there are two container, each defining a single endpoint. Endpoint is an accessible port that can be made accessible inside the workspace or publicly (example, from the UI). Each endpoint has a name and port, which is the port on which certain server running inside the container is listening. The following are a few attributes that you can set on the endpoint: +Here, there are two container, each defining a single endpoint. Endpoint is an accessible port that can be made accessible inside the workspace or publicly from the UI. Each endpoint has a name and port, which is the port on which certain server running inside the container is listening. The following are a few attributes that you can set on the endpoint: -* `discoverable`: If an endpoint is discoverable, it means that it can be accessed using its name as the host name within the workspace containers (in the Kubernetes parlance, a Service is created for it with the provided name). +* `exposure`: When its value is `public`, the endpoint is accessible outside the workspace. Users can access such an endpoint from the {prod-short} user interface and is always exposed on port `80` or `443` depending on whether `tls` is enabled in {prod-short}. -* `public`: The endpoint will also be accessible outside of the workspace: such endpoint can be accessed from the {prod-short} user interface and is always exposed on port `80` or `443` (depending on whether `tls` is enabled in {prod-short}). +* `protocol`: For public endpoints, the protocol is a hint to the UI on how to construct the URL for the endpoint access. Typical values are `http`, `https`, `ws`, `wss`. -* `protocol`: For public endpoints the protocol is a hint to the UI on how to construct the URL for the endpoint access. Typical values are `http`, `https`, `ws`, `wss`. - -* `secure`: A boolean (defaulting to `false`) specifying whether the endpoint is put behind a JWT proxy requiring a JWT workspace token to grant access. The JWT proxy is deployed in the same Pod as the server and assumes the server listens solely on the local loopback interface, such as `127.0.0.1`. +* `secure`: A boolean defaulting to `false` that specifies whether the endpoint is put behind a JWT proxy requiring a JWT workspace token to grant access. The JWT proxy is deployed in the same Pod as the server and assumes the server listens solely on the local loopback interface, such as `127.0.0.1`. + WARNING: Listening on any other interface than the local loopback poses a security risk because such server is accessible without the JWT authentication within the cluster network on the corresponding IP addresses. * `path`: The URL of the endpoint. -* `unsecuredPaths`: A comma-separated list of endpoint paths that are to stay unsecured even if the `secure` attribute is set to `true`. - -* `cookiesAuthEnabled`: When set to `true` (the default is `false`), the JWT workspace token is automatically fetched and included in a workspace-specific cookie to allow requests to pass through the JWT proxy. -+ -WARNING: This setting potentially allows a link:https://en.wikipedia.org/wiki/Cross-site_request_forgery[CSRF] attack when used in conjunction with a server using POST requests. +When starting a new server within a component, {prod-short} autodetects this, and the UI offers to automatically expose this port as an `exposure` port. This exposure is useful for debugging a web application. It is impossible to do this for servers that autostart with the container, for example, a database server. For such components, specify the endpoints explicitly. -When starting a new server within a component, {prod-short} autodetects this, and the UI offers to automatically expose this port as a `public` port. This is useful for debugging a web application, for example. It is impossible to do this for servers that autostart with the container (for example, a database server). For such components, specify the endpoints explicitly. - -Example specifying endpoints for `kubernetes`/`openshift` and `plugin` types: +.Specifying endpoints for `kubernetes` or `openshift` types: [source,yaml] ---- schemaVersion: 2.0.0 metadata: - name: MyDevfile + name: mydevfile components: - name: theia-editor - plugin: - id: eclipse/che-theia/next - endpoints: - - name: 'theia-extra-endpoint' - targetPort: 8880 - configuration: - discoverable: true - public: true - - - plugin: - id: redhat/php/latest - memoryLimit: 1Gi - endpoints: - - name: 'php-endpoint' - targetPort: 7777 - - - plugin: - name: theia-editor - id: eclipse/che-theia/next endpoints: - name: 'theia-extra-endpoint' targetPort: 8880 - configuration: - discoverable: true - public: true + exposure: public - openshift: name: webapp - reference: webapp.yaml + uri: webapp.yaml endpoints: - name: 'web' targetPort: 8080 - configuration: - discoverable: false - public: true - protocol: http + exposure: public - openshift: name: mongo - reference: mongo-db.yaml + uri: mongo-db.yaml endpoints: - name: 'mongo-db' targetPort: 27017 - configuration: - discoverable: true - public: false + exposure: public ---- 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 879d6555..7eb02cc2 100644 --- a/docs/modules/user-guide/partials/proc_defining-environment-variables.adoc +++ b/docs/modules/user-guide/partials/proc_defining-environment-variables.adoc @@ -2,20 +2,20 @@ = Defining environment variables [role="_abstract"] -Environment variables are supported by the following component types: `container`, `plugin`, `kubernetes`, `openshift`. +Environment variables are supported by the `container` component and `exec` command. If the component has multiple containers, environment variables will be provisioned for each container. .Procedure . Specify environment variables for `container` components + -.Specify environment variables for a `container` components +.Specifying environment variables for a `container` component ==== [source,yaml] ---- schemaVersion: 2.0.0 metadata: - name: MyDevfile + name: mydevfile components: - name: go container: @@ -24,34 +24,7 @@ components: mountSources: true command: ['sleep', 'infinity'] env: - - name: GOPATH + - name: gopath value: $(PROJECTS_ROOT)/go ---- ==== - -. Specify environment variables for `plugin` components -+ -.Specify environment variables for a `plugin` component -==== -[source,yaml] ----- -schemaVersion: 2.0.0 -metadata: - name: MyDevfile - - name: theia-editor - plugin: - id: eclipse/che-theia/next - memoryLimit: 2Gi - env: - - name: HOME - value: $(CHE_PROJECTS_ROOT) ----- -==== - - -[NOTE] -==== -* The variable expansion works between the environment variables, and it uses the Kubernetes convention for the variable references. - -* The predefined variables are available for use in custom definitions. -==== 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 82c105a9..b86b8fec 100644 --- a/docs/modules/user-guide/partials/proc_specifying-persistent-storage.adoc +++ b/docs/modules/user-guide/partials/proc_specifying-persistent-storage.adoc @@ -2,7 +2,7 @@ = Specifying persistent storage [role="_abstract"] -Components of any type can specify the custom volumes to be mounted on specific locations within the image. Note that the volume names are shared across all components and therefore this mechanism can also be used to share file systems between components. +A `container` component can specify the volumes to be mounted on specific locations within the image. If the `container` component mounts the volume, then the volume needs a corresponding volume component of the same name. Volume names are shared across all components. Shared volume names can be used to share file systems among components. .Procedure @@ -14,9 +14,9 @@ Components of any type can specify the custom volumes to be mounted on specific ---- schemaVersion: 2.0.0 metadata: - name: MyDevfile + name: mydevfile components: - - name: MyDevfile + - name: mydevfile container: image: golang memoryLimit: 512Mi @@ -25,46 +25,8 @@ components: volumeMounts: - name: cache path: /.cache ----- -==== - -. Specify volumes for `plugin` type: -+ -.Specifying volumes for `plugin` type: -==== -[source,yaml] ----- -scheamVersion: 2.0.0 -metadata: - name: MyDevfile -components: - - name: theia-editor - plugin: - id: eclipse/che-theia/next - env: - - name: HOME - value: $(PROJECTS_ROOT) - volumeMounts: - - name: cache - path: /.cache ----- -==== - -. Specify volumes for `kubernetes`/`openshift` type: -+ -.Specifying volumes for `kubernetes`/`openshift` type: -==== -[source,yaml] ----- -schemaVersion: 2.0.0 -metadata: - name: MyDevfile -components: - - name: mongo - openshift: - reference: mongo-db.yaml - volumeMounts: - - name: mongo-persistent-storage - path: /data/db + - name: cache + volume: + size: 2Gi ---- ==== From a9caad0c12d502637a314d07ebcd8ace58878a17 Mon Sep 17 00:00:00 2001 From: jc-berger <70717303+jc-berger@users.noreply.github.com> Date: Wed, 31 Mar 2021 13:22:38 -0400 Subject: [PATCH 2/3] Update docs/modules/user-guide/partials/proc_defining-endpoints.adoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Krátký --- docs/modules/user-guide/partials/proc_defining-endpoints.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/user-guide/partials/proc_defining-endpoints.adoc b/docs/modules/user-guide/partials/proc_defining-endpoints.adoc index 212e84eb..8670ddf4 100644 --- a/docs/modules/user-guide/partials/proc_defining-endpoints.adoc +++ b/docs/modules/user-guide/partials/proc_defining-endpoints.adoc @@ -57,7 +57,7 @@ components: Here, there are two container, each defining a single endpoint. Endpoint is an accessible port that can be made accessible inside the workspace or publicly from the UI. Each endpoint has a name and port, which is the port on which certain server running inside the container is listening. The following are a few attributes that you can set on the endpoint: -* `exposure`: When its value is `public`, the endpoint is accessible outside the workspace. Users can access such an endpoint from the {prod-short} user interface and is always exposed on port `80` or `443` depending on whether `tls` is enabled in {prod-short}. +* `exposure`: When its value is `public`, the endpoint is accessible outside the workspace. Users can access such an endpoint from the {prod-short} user interface and is always exposed on port `80` or `443` depending on whether TLS is enabled in {prod-short}. * `protocol`: For public endpoints, the protocol is a hint to the UI on how to construct the URL for the endpoint access. Typical values are `http`, `https`, `ws`, `wss`. From f3141deff8c8cbbfaa68893cbfe9a9469dc3ea1c Mon Sep 17 00:00:00 2001 From: jc-berger <70717303+jc-berger@users.noreply.github.com> Date: Wed, 31 Mar 2021 13:22:47 -0400 Subject: [PATCH 3/3] Update docs/modules/user-guide/partials/proc_adding-plugin-component-to-a-devfile.adoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Krátký --- .../partials/proc_adding-plugin-component-to-a-devfile.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 4c95084b..acefafa4 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 @@ -29,7 +29,7 @@ This section describes how to add a `plugin` component to a devfile. . Optional: Specify an alternative devfile registry using the `registryUrl` parameter: + -.Defining a plugin `id` and an alternative devfile registry +.Defining a plug-in `id` and an alternative devfile registry ==== [source,yaml] ----