From 52548d6ed75c7b3083828492f066255cd1a3224a Mon Sep 17 00:00:00 2001 From: jc-berger Date: Thu, 4 Mar 2021 08:36:59 -0500 Subject: [PATCH] modified docs to adhere to schema_3rd PR minor tweaks to yaml and content more content and yaml changes modified yaml in limiting resources doc more minor changes to grammar and word choice --- .../proc_defining-kubernetes-resources.adoc | 31 +------ .../proc_limiting-resources-usage.adoc | 82 ++----------------- .../partials/proc_migrating-components.adoc | 37 +++++---- 3 files changed, 31 insertions(+), 119 deletions(-) diff --git a/docs/modules/user-guide/partials/proc_defining-kubernetes-resources.adoc b/docs/modules/user-guide/partials/proc_defining-kubernetes-resources.adoc index 90b8a1db..01a759ed 100644 --- a/docs/modules/user-guide/partials/proc_defining-kubernetes-resources.adoc +++ b/docs/modules/user-guide/partials/proc_defining-kubernetes-resources.adoc @@ -21,7 +21,7 @@ Complex deployments can be described using Kubernetes or OpenShift resource list ---- schemaVersion: 2.0.0 metadata: - name: MyDevfile + name: mydevfile projects: - name: my-go-project clonePath: go/src/github.com/acme/my-go-project @@ -29,9 +29,9 @@ projects: remotes: origin: "https://github.com/acme/my-go-project.git" components: - - name: MyDevfile + - name: mydevfile kubernetes: - reference: ../relative/path/postgres.yaml + uri: ../relative/path/postgres.yaml ---- The preceding component references a file that is relative to the location of the devfile itself. Meaning, this devfile is only loadable by a {prod-short} factory to which you supply the location of the devfile and therefore it is able to figure out the location of the referenced Kubernetes resource list. @@ -82,8 +82,6 @@ items: ports: - port: 5432 targetPort: 5432 - selector: - app: postgres - apiVersion: v1 kind: PersistentVolumeClaim @@ -100,26 +98,3 @@ items: ---- For a basic example of a devfile with an associated Kubernetes or OpenShift list, see link:https://github.com/redhat-developer/devfile/tree/master/samples/web-nodejs-with-db-sample[web-nodejs-with-db-sample] on redhat-developer GitHub. - -If you use generic or large resource lists from which you will only need a subset of resources, you can select particular resources from the list using a selector (which, as the usual Kubernetes selectors, works on the labels of the resources in the list). - -[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" -components: - - name: MyDevfile - kubernetes: - reference: ../relative/path/postgres.yaml - selector: - app: postgres ----- - -Additionally, it is also possible to modify the entrypoints (command and arguments) of the containers present in the resource list. For details of the advanced use case, see the reference (TODO: link). 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 4e110302..afa0a0aa 100644 --- a/docs/modules/user-guide/partials/proc_limiting-resources-usage.adoc +++ b/docs/modules/user-guide/partials/proc_limiting-resources-usage.adoc @@ -6,45 +6,15 @@ .Procedure -. Specify container memory limit for components +. Specify container memory limit and memory request for components + -To specify a container(s) memory limit for `container`, `plugin`, use the `memoryLimit` parameter: +To specify a container memory limit for `container`, use the `memoryLimit` parameter, and to specify a container memory request, use the `memoryRequest` parameter: + -.Specify container memory limit for components +.Specify container memory limit and memory request for components ==== [source,yaml] ---- components: - - name: exec-plugin - plugin: - id: eclipse/machine-exec-plugin/0.0.1 - memoryLimit: 1Gi - - name: maven - container: - image: eclipe/maven-jdk8:latest - memoryLimit: 512M ----- -==== -+ -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`. -+ - -. Specify container memory request for components -+ -To specify a container(s) memory request for `plugin` use the `memoryRequest` parameter: -+ -.Specify container memory request for components -==== -[source,yaml] ----- - components: - - name: exec-plugin - plugin: - id: eclipse/machine-exec-plugin/0.0.1 - memoryLimit: 1Gi - memoryRequest: 512M - name: maven container: image: eclipe/maven-jdk8:latest @@ -53,54 +23,21 @@ To specify a container(s) memory request for `plugin` use the `memoryRequest` pa ---- ==== + -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 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. +This limit applies to every container of the given component. + -. Specify container CPU limit for components -+ -To specify a container(s) CPU limit for `plugin` or `container` use the `cpuLimit` parameter: -+ -.Specify container CPU limit for components -==== -[source,yaml] ----- - components: - - name: exec-plugin - plugin: - id: eclipse/machine-exec-plugin/0.0.1 - cpuLimit: 1.5 - - name: maven - container: - image: eclipe/maven-jdk8:latest - cpuLimit: 750m ----- -==== -+ -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 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 +. Specify container CPU limit and container CPU request for components + -To specify a container(s) CPU request for `plugin` or `container` use the `cpuRequest` parameter: +To specify a container CPU limit for `container`, use the `cpuLimit` parameter, and to specify a container CPU request for `container`, use the `cpuRequest` parameter: + -.Specify container CPU request for components +.Specify container CPU limit and CPU request for components ==== [source,yaml] ---- components: - - name: exec-plugin - plugin: - id: eclipse/machine-exec-plugin/0.0.1 - cpuLimit: 1.5 - cpuRequest: 0.225 - name: maven container: image: eclipe/maven-jdk8:latest @@ -109,9 +46,8 @@ 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 `plugin` component type, CPU requests can be described in the plug-in descriptor file, typically named `meta.yaml`. +This limit applies to every container of the given component. + + 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. + diff --git a/docs/modules/user-guide/partials/proc_migrating-components.adoc b/docs/modules/user-guide/partials/proc_migrating-components.adoc index 83a5281f..fc886947 100644 --- a/docs/modules/user-guide/partials/proc_migrating-components.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-components.adoc @@ -6,7 +6,7 @@ This section describes how to migrate components to devfile v2. There ARE major .Procedure -. Component is a polymophic type +. Component is a polymorphic type + For a better syntax validation component now is defined as a polymorphic type and can be implemented as `container`, `kubernetes`, `openshift`, `plugin` or `volume`. + @@ -15,6 +15,7 @@ For a better syntax validation component now is defined as a polymorphic type an v2.0 --- components: + - name: mydevfile - container: image: maven ... @@ -22,35 +23,35 @@ components: image: nodejs ... - kubernetes: - reference: https://.../mongo.yaml + uri: https://.../mongo.yaml ---- + -See https://github.com/che-incubator/devworkspace-api/issues/4[corresponding issue]. +See https://github.com/devfile/api/issues/4[corresponding issue]. -. Shared Volumes Across Components. See https://github.com/che-incubator/devworkspace-api/issues/19[corresponding issue]. +. Shared Volumes Across Components. See https://github.com/devfile/api/issues/19[corresponding issue]. -. Out of Main Pod Compoenents. See https://github.com/devfile/api/issues/48[corresponding issue]. +. Out of Main Pod Components. See https://github.com/devfile/api/issues/48[corresponding issue]. -. Replace Alias with Name. See https://github.com/che-incubator/devworkspace-api/issues/9[corresponding issue]. +. Replace Alias with Name. See https://github.com/devfile/api/issues/9[corresponding issue]. -. Renaming dockerimage component type. See https://github.com/che-incubator/devworkspace-api/issues/8[corresponding issue]. +. Renaming dockerimage component type. See https://github.com/devfile/api/issues/8[corresponding issue]. -. Specify sources path for containers. See https://github.com/che-incubator/devworkspace-api/issues/17[corresponding issue]. +. Specify sources path for containers. See https://github.com/devfile/api/issues/17[corresponding issue]. -. Specify size of volume for component. See https://github.com/che-incubator/devworkspace-api/issues/14[corresponding issue]. +. Specify size of volume for component. See https://github.com/devfile/api/issues/14[corresponding issue]. -. Containers endpoints (routes/ingresses). See https://github.com/che-incubator/devworkspace-api/issues/33[corresponding issue]. +. Containers endpoints (routes/ingresses). See https://github.com/devfile/api/issues/33[corresponding issue]. [role="_additional-resources"] .Additional resources -* Component is a polymophic type. See https://github.com/che-incubator/devworkspace-api/issues/4[corresponding issue]. -* Shared Volumes Across Components. See https://github.com/che-incubator/devworkspace-api/issues/19[corresponding issue]. -* Out of Main Pod Compoenents. See https://github.com/devfile/api/issues/48[corresponding issue]. -* Replace Alias with Name. See https://github.com/che-incubator/devworkspace-api/issues/9[corresponding issue]. -* Renaming dockerimage component type. See https://github.com/che-incubator/devworkspace-api/issues/8[corresponding issue]. -* Specify sources path for containers. See https://github.com/che-incubator/devworkspace-api/issues/17[corresponding issue]. -* Specify size of volume for component. See https://github.com/che-incubator/devworkspace-api/issues/14[corresponding issue]. -* Containers endpoints (routes/ingresses). See https://github.com/che-incubator/devworkspace-api/issues/33[corresponding issue]. \ No newline at end of file +* Component is a polymorphic type. See https://github.com/devfile/api/issues/4[corresponding issue]. +* Shared Volumes Across Components. See https://github.com/devfile/api/issues/19[corresponding issue]. +* Out of Main Pod Components. See https://github.com/devfile/api/issues/48[corresponding issue]. +* Replace Alias with Name. See https://github.com/devfile/api/issues/9[corresponding issue]. +* Renaming dockerimage component type. See https://github.com/devfile/api/issues/8[corresponding issue]. +* Specify sources path for containers. See https://github.com/devfile/api/issues/17[corresponding issue]. +* Specify size of volume for component. See https://github.com/devfile/api/issues/14[corresponding issue]. +* Containers endpoints (routes/ingresses). See https://github.com/devfile/api/issues/27[corresponding issue].