Skip to content

Commit de33e73

Browse files
maysunfaisalyangcao77
maysunfaisal
and
yangcao77
authored
Update Authoring Documents (#150)
* Add apply command authoring page Signed-off-by: Maysun J Faisal <[email protected]> * Update to 2.2.0, add deploy kind, add event to nav Signed-off-by: Maysun J Faisal <[email protected]> * update kubernetes component to include deployByDefault information, update container component on sprcifying a volumeMount, update parent id reference with version specified Signed-off-by: Stephanie <[email protected]> * Add image component authoring doc Signed-off-by: Maysun J Faisal <[email protected]> * Update caption for image component Signed-off-by: Maysun J Faisal <[email protected]> Co-authored-by: Stephanie <[email protected]>
1 parent 6d66967 commit de33e73

26 files changed

+246
-29
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
.DS_Store
1616
.vale.ini
1717
.yarnrc
18+
.idea/
1819
/build/
1920
/out/
2021
/node_modules/

‎docs/modules/user-guide/attachments/api-reference/next/index.html

Lines changed: 17 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1327,7 +1327,7 @@ <h3 class="panel-title">Devfile schema - Version 2.2.0-alpha</h3>
13271327

13281328
</dt>
13291329
<dd>
1330-
<p>Path of source directory to establish build context. Defaults to ${PROJECT_ROOT} in the container</p>
1330+
<p>Path of source directory to establish build context. Defaults to ${PROJECT_SOURCE} in the container</p>
13311331

13321332
<div class="json-inner-schema">
13331333

@@ -3734,7 +3734,7 @@ <h3 class="panel-title">Devfile schema - Version 2.2.0-alpha</h3>
37343734

37353735
</dt>
37363736
<dd>
3737-
<p>Path of source directory to establish build context. Defaults to ${PROJECT_ROOT} in the container</p>
3737+
<p>Path of source directory to establish build context. Defaults to ${PROJECT_SOURCE} in the container</p>
37383738

37393739
<div class="json-inner-schema">
37403740

@@ -4787,6 +4787,21 @@ <h3 class="panel-title">Devfile schema - Version 2.2.0-alpha</h3>
47874787
<div class="json-inner-schema">
47884788

47894789

4790+
</div>
4791+
</dd>
4792+
<dt data-property-name="version">
4793+
<span class="json-property-name">version:</span>
4794+
4795+
<span class="json-property-type">string</span>
4796+
<span class="json-property-range" title="Value limits"></span>
4797+
4798+
<span class="json-property-pattern" title="String pattern">, must match <span class="json-schema--regex">^(latest)|(([1-9])\.([0-9]+)\.([0-9]+)(\-[0-9a-z-]+(\.[0-9a-z-]+)*)?(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?)$</span></span>
4799+
</dt>
4800+
<dd>
4801+
<p>Specific stack/sample version to pull the parent devfile from, when using id in the parent reference. To specify <code>version</code>, <code>id</code> must be defined and used as the import reference source. <code>version</code> can be either a specific stack version, or <code>latest</code>. If no <code>version</code> specified, default version will be used.</p>
4802+
4803+
<div class="json-inner-schema">
4804+
47904805
</div>
47914806
</dd>
47924807
</dl>

‎docs/modules/user-guide/nav.adoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,12 @@
1010
**** xref:adding-a-command-section-to-a-devfile.adoc[]
1111
**** xref:adding-a-command-group-to-a-devfile.adoc[]
1212
**** xref:adding-exec-commands-to-a-devfile.adoc[]
13+
**** xref:adding-apply-commands-to-a-devfile.adoc[]
1314
**** xref:adding-composite-commands-to-a-devfile.adoc[]
1415
*** xref:adding-components-to-a-devfile.adoc[]
1516
**** xref:adding-a-kubernetes-or-openshift-component-to-a-devfile.adoc[]
1617
**** xref:adding-a-container-component-to-a-devfile.adoc[]
18+
**** xref:adding-a-image-component-to-a-devfile.adoc[]
1719
**** xref:adding-a-volume-component-to-a-devfile.adoc[]
1820
**** xref:specifying-persistent-storage.adoc[]
1921
**** xref:limiting-resources-usage.adoc[]

‎docs/modules/user-guide/pages/adding-a-image-component-to-a-devfile.adoc

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
:description: Adding an image component to a devfile
2+
:navtitle: Adding an image component
3+
:keywords: authoring, stack, components
4+
:page-aliases:
5+
6+
include::partial$proc_adding-a-image-component-to-a-devfile.adoc[]

‎docs/modules/user-guide/pages/adding-apply-commands-to-a-devfile.adoc

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
:description: Adding apply commands to a devfile
2+
:navtitle: Adding apply commands to a devfile
3+
:keywords: command, devfile
4+
5+
6+
include::partial$proc_adding-apply-commands-to-a-devfile.adoc[]

‎docs/modules/user-guide/partials/assembly_adding-commands-to-a-devfile.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ You can use a devfile to specify commands to run in a workspace. Every command c
1616
* xref:adding-a-command-section-to-a-devfile.adoc[]
1717
* xref:adding-a-command-group-to-a-devfile.adoc[]
1818
* xref:adding-exec-commands-to-a-devfile.adoc[]
19+
* xref:adding-apply-commands-to-a-devfile.adoc[]
1920
* xref:adding-composite-commands-to-a-devfile.adoc[]
2021
2122
[role="_additional-resources"]

‎docs/modules/user-guide/partials/assembly_authoring-devfiles.adoc

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,14 +14,13 @@ endif::[]
1414
[role="_abstract"]
1515
A devfile is a `yaml` file. After you include it in your local environment, the devfile provides ways to automate your processes. Tools like `odo` run the devfile and apply its guidelines to your environment. You can configure the devfile based on your unique development needs. See the following documents to help you author a devfile based on your development needs:
1616

17-
* xref:adding-schema-version-to-a-devfile.adoc[]
18-
* xref:adding-a-name-to-a-devfile.adoc[]
1917
* xref:adding-schema-version-to-a-devfile.adoc[]
2018
* xref:adding-a-name-to-a-devfile.adoc[]
2119
* xref:adding-projects-to-a-devfile.adoc[]
2220
* xref:adding-commands-to-a-devfile.adoc[]
2321
* xref:adding-components-to-a-devfile.adoc[]
2422
* xref:adding-attributes-to-a-devfile.adoc[]
23+
* xref:adding-event-bindings.adoc[]
2524
* xref:referring-to-a-parent-devfile-in-a-devfile.adoc[]
2625
2726
// [role="_additional-resources"]

‎docs/modules/user-guide/partials/proc_adding-a-command-group-to-a-devfile.adoc

Lines changed: 45 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,12 +19,13 @@ Create command groups to help automate your devfile.
1919
* `run`
2020
* `test`
2121
* `debug`
22+
* `deploy`
2223
+
2324
. At most, there can only be one default command for each group kind. Set the default command by specifying a `true` value for `isDefault`.
2425
+
2526
[source,yaml]
2627
----
27-
schemaVersion: 2.1.0
28+
schemaVersion: 2.2.0
2829
metadata:
2930
name: mydevfile
3031
projects:
@@ -54,3 +55,46 @@ commands:
5455
kind: build
5556
isDefault: true
5657
----
58+
+
59+
. Use the `deploy` kind to reference a deploy command for an outerloop scenario.
60+
+
61+
[source,yaml]
62+
----
63+
schemaVersion: 2.2.0
64+
metadata:
65+
name: python
66+
version: 1.0.0
67+
provider: Red Hat
68+
supportUrl: https://github.com/devfile-samples/devfile-support#support-information
69+
attributes:
70+
alpha.dockerimage-port: 8081
71+
parent:
72+
id: python
73+
registryUrl: "https://registry.devfile.io"
74+
components:
75+
- name: outerloop-build
76+
image:
77+
imageName: python-image:latest
78+
dockerfile:
79+
uri: docker/Dockerfile
80+
buildContext: .
81+
rootRequired: false
82+
- name: outerloop-deploy
83+
kubernetes:
84+
uri: outerloop-deploy.yaml
85+
commands:
86+
- id: build-image
87+
apply:
88+
component: outerloop-build
89+
- id: deployk8s
90+
apply:
91+
component: outerloop-deploy
92+
- id: deploy
93+
composite:
94+
commands:
95+
- build-image
96+
- deployk8s
97+
group:
98+
kind: deploy
99+
isDefault: true
100+
----

‎docs/modules/user-guide/partials/proc_adding-a-container-component-to-a-devfile.adoc

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ A devfile can contain one or more components of the `container` type. The `compo
4646
.A minimal `container` component
4747
[source,yaml]
4848
----
49-
schemaVersion: 2.1.0
49+
schemaVersion: 2.2.0
5050
metadata:
5151
name: mydevfile
5252
components:
@@ -67,7 +67,7 @@ For the `container` component to have access to the project sources, you must se
6767
+
6868
[source,yaml]
6969
----
70-
schemaVersion: 2.1.0
70+
schemaVersion: 2.2.0
7171
metadata:
7272
name: mydevfile
7373
components:
@@ -81,6 +81,26 @@ components:
8181
+
8282
The sources are 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 and mounts the source to the path defined by `sourceMapping`.
8383

84+
. Specify a volume
85+
+
86+
For the `container` component to have a shared volume. You must define a volume component in the devfile, and reference the volume using `volumeMount` in container component. For more information on volume component, see xref:adding-a-volume-component-to-a-devfile.adoc[]
87+
+
88+
[source,yaml]
89+
----
90+
components:
91+
- name: mycontainer
92+
container:
93+
image: java11-maven:next
94+
memoryLimit: 768Mi
95+
mountSources: true
96+
volumeMounts:
97+
- name: m2
98+
path: /home/user/.m2
99+
- name: m2
100+
volume:
101+
size: 1Gi
102+
----
103+
84104
. Container Entrypoint
85105
+
86106
Use the `command` attribute of the `container` type to modify the `entrypoint` command of the container created from the image. The availability of the `sleep` command and the support for the `infinity` argument depend on the base image used in the particular images.

‎docs/modules/user-guide/partials/proc_adding-a-image-component-to-a-devfile.adoc

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
[id="proc_adding-a-image-component-to-a-devfile_{context}"]
2+
= Adding an image component to a devfile
3+
4+
[role="_abstract"]
5+
You can add an `image` component to a devfile.
6+
7+
.Prerequisites
8+
9+
* xref:adding-schema-version-to-a-devfile.adoc[]
10+
* xref:adding-a-name-to-a-devfile.adoc[]
11+
* xref:adding-components-to-a-devfile.adoc[]
12+
13+
.Procedure
14+
15+
. Define a component using the type `image`.
16+
+
17+
Specify the location of the Dockerfile using the `uri` property. Specify arguments to be passed during the build with `args`. `buildContext` is the path of source directory to establish build context. If `rootRequired` is set to true, a privileged builder pod is required. The built container will be stored in the image provided by `imageName`.
18+
+
19+
.An `image` dockerfile component
20+
[source,yaml]
21+
----
22+
components:
23+
- name: outerloop-build
24+
image:
25+
imageName: python-image:latest
26+
autoBuild: true
27+
dockerfile:
28+
uri: docker/Dockerfile
29+
args:
30+
- "MY_ENV=/home/path"
31+
buildContext: .
32+
rootRequired: false
33+
----
34+
+
35+
Alternatively, specify `git` and `devfileRegistry` as the image source.
36+
+
37+
When specifying `git`, `fileLocation` refers to the location of the Dockerfile in the git repository. Specify the `remotes` for the git repository and a `checkoutFrom` to indicate which `revision` to check the source from.
38+
+
39+
.An `image` dockerfile component with git source
40+
[source,yaml]
41+
----
42+
components:
43+
- name: outerloop-build
44+
image:
45+
imageName: python-image:latest
46+
dockerfile:
47+
git:
48+
fileLocation: "uri/Dockerfile"
49+
checkoutFrom:
50+
revision: "main"
51+
remote: "origin"
52+
remotes:
53+
"origin": "https://github.com/myorg/myrepo"
54+
buildContext: .
55+
----
56+
+
57+
When specifying `devfileRegistry`, `id` refers to the Id in a devfile registry that contains a Dockerfile. `registryUrl` refers to the Devfile Registry URL to pull the Dockerfile from
58+
+
59+
.An `image` dockerfile component with devfileRegistry source
60+
[source,yaml]
61+
----
62+
components:
63+
- name: outerloop-build
64+
image:
65+
imageName: python-image:latest
66+
dockerfile:
67+
devfileRegistry:
68+
id: python
69+
registryUrl: myregistry.devfile.com
70+
buildContext: .
71+
----

‎docs/modules/user-guide/partials/proc_adding-a-kubernetes-or-openshift-component-to-a-devfile.adoc

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,5 +52,7 @@ You can add either a `kubernetes` or `openshift` component to a devfile.
5252
+
5353
. Specify the endpoint through the endpoint property with `kubernetes` or `openshift` components.
5454

55-
. Associate `kubernetes` or `openshift` components with `Apply` commands. If you do not associate `Apply` commands, they are assumed to be applied at start up.
55+
. By default `kubernetes` or `openshift` components are not going to be deployed. Specify `deployByDefault=true` if you want to apply the component at start up.
56+
57+
. Associate `kubernetes` or `openshift` components with `Apply` commands wth `deploy` command group kind. If the `kubernetes` or `openshift` component uses an image built by an image component defined in the devfile, you can create a composite `deploy` command to build the image and deploy the Kubernetes or openshift component. For more information on `deploy` commands, see xref:adding-a-command-group-to-a-devfile.adoc[]
5658
+

‎docs/modules/user-guide/partials/proc_adding-a-name-to-a-devfile.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ Adding a name to a devfile is mandatory. Use the `name` attribute to define the
3131

3232
[source,yaml]
3333
----
34-
schemaVersion: 2.1.0
34+
schemaVersion: 2.2.0
3535
metadata:
3636
name: devfile-sample
3737
version: 2.0.0

‎docs/modules/user-guide/partials/proc_adding-a-volume-component-to-a-devfile.adoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ You can use a `volume` component to share files among container components and c
1818

1919
[source,yaml]
2020
----
21-
schemaVersion: 2.1.0
21+
schemaVersion: 2.2.0
2222
metadata:
2323
name: mydevfile
2424
components:
@@ -33,7 +33,7 @@ components:
3333

3434
[source,yaml]
3535
----
36-
schemaVersion: 2.1.0
36+
schemaVersion: 2.2.0
3737
metadata:
3838
name: mydevfile
3939
components:

‎docs/modules/user-guide/partials/proc_adding-apply-commands-to-a-devfile.adoc

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
[id="proc_adding-apply-commands-to-a-devfile_{context}"]
2+
= Adding apply commands to a devfile
3+
[role="_abstract"]
4+
5+
Use the the `apply` command to apply a given component definition, usually a `kubernetes`, `openshift` or an `image` component. Apply commands are also typically bound to `preStart` and `postStop` events.
6+
7+
. Define the `apply` command to apply a given component. In the following example, two apply commands reference an `image` component and a `kubernetes` component to build a docker image and to apply the deployment YAML for an outerloop scenario.
8+
+
9+
[source,yaml]
10+
----
11+
schemaVersion: 2.2.0
12+
metadata:
13+
name: python
14+
version: 1.0.0
15+
provider: Red Hat
16+
supportUrl: https://github.com/devfile-samples/devfile-support#support-information
17+
attributes:
18+
alpha.dockerimage-port: 8081
19+
parent:
20+
id: python
21+
registryUrl: "https://registry.devfile.io"
22+
components:
23+
- name: outerloop-build
24+
image:
25+
imageName: python-image:latest
26+
dockerfile:
27+
uri: docker/Dockerfile
28+
buildContext: .
29+
rootRequired: false
30+
- name: outerloop-deploy
31+
kubernetes:
32+
uri: outerloop-deploy.yaml
33+
commands:
34+
- id: build-image
35+
apply:
36+
component: outerloop-build
37+
- id: deployk8s
38+
apply:
39+
component: outerloop-deploy
40+
- id: deploy
41+
composite:
42+
commands:
43+
- build-image
44+
- deployk8s
45+
group:
46+
kind: deploy
47+
isDefault: true
48+
----

‎docs/modules/user-guide/partials/proc_adding-attributes-to-a-devfile.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ When no editor is specified, a default editor is provided. To represent this use
2727
====
2828
[source,yaml]
2929
----
30-
schemaVersion: 2.1.0
30+
schemaVersion: 2.2.0
3131
metadata:
3232
name: petclinic-dev-environment
3333
attributes:

‎docs/modules/user-guide/partials/proc_adding-components-to-a-devfile.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,6 +160,7 @@ Each component in a single devfile must have a unique name and use one of the ob
160160
. xref:adding-a-kubernetes-or-openshift-component-to-a-devfile.adoc[]
161161
. xref:adding-a-container-component-to-a-devfile.adoc[]
162162
. xref:adding-a-volume-component-to-a-devfile.adoc[]
163+
. xref:adding-a-image-component-to-a-devfile.adoc[]
163164
. xref:specifying-persistent-storage.adoc[]
164165
. xref:limiting-resources-usage.adoc[]
165166
. xref:defining-environment-variables.adoc[]

‎docs/modules/user-guide/partials/proc_adding-composite-commands-to-a-devfile.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Connect multiple commands together by defining a composite command.
1818
+
1919
[source,yaml]
2020
----
21-
schemaVersion: 2.1.0
21+
schemaVersion: 2.2.0
2222
metadata:
2323
name: mydevfile
2424
projects:

‎docs/modules/user-guide/partials/proc_adding-exec-commands-to-a-devfile.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Use the the `exec` command to automate the container actions.
1111
+
1212
[source,yaml]
1313
----
14-
schemaVersion: 2.1.0
14+
schemaVersion: 2.2.0
1515
metadata:
1616
name: mydevfile
1717
projects:

0 commit comments

Comments
 (0)