Skip to content

Commit 820254d

Browse files
gabriel-rhgabriel-rh
authored
RHDEVDOCS-2668: Document top-level attribute definition in a devfile (#161)
* RHDEVDOCS-2668: Document top-level attribute definition in a devfile Signed-off-by: Gabriel McGoldrick <[email protected]> * RHDEVDOCS-2668: Document top-level attribute definition in a devfile - writing review Signed-off-by: Gabriel McGoldrick <[email protected]> * RHDEVDOCS-2668: Document top-level attribute definition in a devfile - Vale issue Signed-off-by: Gabriel McGoldrick <[email protected]>
1 parent 4930ec5 commit 820254d

10 files changed

+141
-65
lines changed

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -900,7 +900,7 @@ <h3 class="panel-title">Devfile schema - Version 2.2.0-alpha</h3>
900900
<span class="json-property-required"></span>
901901
</dt>
902902
<dd>
903-
<p>The port number should be unique.</p>
903+
<p>Port number to be used within the container component. The same port cannot be used by two different container components.</p>
904904

905905
<div class="json-inner-schema">
906906

@@ -1627,7 +1627,7 @@ <h3 class="panel-title">Devfile schema - Version 2.2.0-alpha</h3>
16271627
<span class="json-property-required"></span>
16281628
</dt>
16291629
<dd>
1630-
<p>The port number should be unique.</p>
1630+
<p>Port number to be used within the container component. The same port cannot be used by two different container components.</p>
16311631

16321632
<div class="json-inner-schema">
16331633

@@ -1880,7 +1880,7 @@ <h3 class="panel-title">Devfile schema - Version 2.2.0-alpha</h3>
18801880
<span class="json-property-required"></span>
18811881
</dt>
18821882
<dd>
1883-
<p>The port number should be unique.</p>
1883+
<p>Port number to be used within the container component. The same port cannot be used by two different container components.</p>
18841884

18851885
<div class="json-inner-schema">
18861886

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

32983298
</dt>
32993299
<dd>
3300-
<p>The port number should be unique.</p>
3300+
<p>Port number to be used within the container component. The same port cannot be used by two different container components.</p>
33013301

33023302
<div class="json-inner-schema">
33033303

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

40164016
</dt>
40174017
<dd>
4018-
<p>The port number should be unique.</p>
4018+
<p>Port number to be used within the container component. The same port cannot be used by two different container components.</p>
40194019

40204020
<div class="json-inner-schema">
40214021

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

42664266
</dt>
42674267
<dd>
4268-
<p>The port number should be unique.</p>
4268+
<p>Port number to be used within the container component. The same port cannot be used by two different container components.</p>
42694269

42704270
<div class="json-inner-schema">
42714271

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

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,8 @@
2323
**** xref:defining-endpoints.adoc[]
2424
**** xref:defining-kubernetes-resources.adoc[]
2525
26-
*** xref:adding-attributes-to-a-devfile.adoc[]
26+
*** xref:defining-variables.adoc[]
27+
*** xref:defining-attributes.adoc[]
2728
*** xref:adding-event-bindings.adoc[]
2829
*** xref:referring-to-a-parent-devfile-in-a-devfile.adoc[]
2930

@@ -44,8 +45,11 @@
4445
** xref:devfile-registry.adoc[]
4546
*** xref:understanding-a-devfile-registry.adoc[]
4647
*** xref:building-a-custom-devfile-registry.adoc[]
48+
*** xref:installation-of-incluster-offline-devfile-registry.adoc[]
4749
*** xref:deploying-a-devfile-registry.adoc[]
4850
*** xref:adding-a-registry-schema.adoc[]
51+
*** xref:creating-a-devfile-stack.adoc[]
52+
*** xref:adding-a-stack-yaml-file.adoc[]
4953

5054
* xref:api-reference.adoc[]
5155
* xref:devfile-resources.adoc[]

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

Lines changed: 0 additions & 6 deletions
This file was deleted.

‎docs/modules/user-guide/pages/defining-attributes.adoc

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
:description: Defining attributes
2+
:navtitle: {description}
3+
:keywords: authoring, stack, attributes
4+
:page-aliases:
5+
6+
include::partial$proc_defining-attributes.adoc[]

‎docs/modules/user-guide/pages/defining-variables.adoc

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
:description: Defining variables
2+
:navtitle: {description}
3+
:keywords: authoring, stack, variables
4+
5+
:page-aliases:
6+
7+
include::partial$proc_defining-variables.adoc[]

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

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,14 +12,15 @@ endif::[]
1212
:context: assembly_authoring-devfiles
1313

1414
[role="_abstract"]
15-
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:
15+
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

1717
* xref:adding-schema-version-to-a-devfile.adoc[]
1818
* xref:adding-a-name-to-a-devfile.adoc[]
1919
* xref:adding-projects-to-a-devfile.adoc[]
2020
* xref:adding-commands-to-a-devfile.adoc[]
2121
* xref:adding-components-to-a-devfile.adoc[]
22-
* xref:adding-attributes-to-a-devfile.adoc[]
22+
* xref:defining-variables.adoc[]
23+
* xref:defining-attributes.adoc[]
2324
* xref:adding-event-bindings.adoc[]
2425
* xref:referring-to-a-parent-devfile-in-a-devfile.adoc[]
2526

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

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,16 +13,15 @@ endif::[]
1313

1414

1515
[role="_abstract"]
16-
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 use a devfile based on your development needs:
16+
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 use a devfile based on your development needs:
1717

18-
* xref:adding-schema-version-to-a-devfile.adoc[]
19-
* xref:adding-a-name-to-a-devfile.adoc[]
2018
* xref:adding-schema-version-to-a-devfile.adoc[]
2119
* xref:adding-a-name-to-a-devfile.adoc[]
2220
* xref:adding-projects-to-a-devfile.adoc[]
2321
* xref:adding-commands-to-a-devfile.adoc[]
2422
* xref:adding-components-to-a-devfile.adoc[]
25-
* xref:adding-attributes-to-a-devfile.adoc[]
23+
* xref:defining-variables.adoc[]
24+
* xref:defining-attributes.adoc[]
2625
* xref:referring-to-a-parent-devfile-in-a-devfile.adoc[]
2726
2827
// [role="_additional-resources"]

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

Lines changed: 0 additions & 46 deletions
This file was deleted.

‎docs/modules/user-guide/partials/proc_defining-attributes.adoc

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
[id="proc_defining-attributes_{context}"]
2+
= Defining attributes
3+
4+
[role="_abstract"]
5+
As a developer, you can use devfile attributes to configure various features and properties according to the needs of users and tools. Attributes are implementation-dependent and written in free-form YAML.
6+
7+
Attributes can be defined at the top level of the devfile, or in the following objects:
8+
9+
10+
* `components`
11+
* `commands`
12+
* `projects`
13+
* `starterProjects`
14+
* `metadata`: Attributes in metadata are deprecated. Use top-level attributes instead.
15+
16+
.Prerequisites
17+
18+
* xref:adding-schema-version-to-a-devfile.adoc[]
19+
* xref:adding-a-name-to-a-devfile.adoc[]
20+
21+
22+
.Procedure
23+
24+
. Define attributes in a component:
25+
+
26+
.Java Quarkus example
27+
====
28+
[source,yaml]
29+
----
30+
schemaVersion: 2.2.0
31+
metadata:
32+
name: java-quarkus
33+
...
34+
components:
35+
- name: outerloop-deploy
36+
attributes:
37+
deployment/replicas: 1
38+
deployment/cpuLimit: "100m"
39+
deployment/cpuRequest: 10m
40+
deployment/memoryLimit: 250Mi
41+
deployment/memoryRequest: 100Mi
42+
deployment/container-port: 8081
43+
kubernetes:
44+
uri: outerloop-deploy.yaml
45+
----
46+
====
47+
. Define a custom attribute in the `metadata` object.
48+
+
49+
When no editor is specified, a default editor is provided. To represent this user-defined example, use the `editorFree` attribute as shown in the following example:
50+
+
51+
.A devfile without an editor
52+
====
53+
[source,yaml]
54+
----
55+
schemaVersion: 2.2.0
56+
metadata:
57+
name: petclinic-dev-environment
58+
attributes:
59+
editorFree: true
60+
components:
61+
- name: myapp
62+
kubernetes:
63+
uri: my-app.yaml
64+
----
65+
====
66+
67+
[role="_additional-resources"]
68+
.Additional resources
69+
70+
* xref:api-reference.adoc[]
71+
* xref:devfile-resources.adoc[]

‎docs/modules/user-guide/partials/proc_defining-variables.adoc

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
[id="proc_defining-variables_{context}"]
2+
= Defining variables
3+
4+
[role="_abstract"]
5+
The `variables` object is a map of variable name-value pairs that are used for string replacement in the devfile. Variables are referenced using the syntax `+{{variable-name}}+` to insert the corresponding value in string fields in the devfile.
6+
7+
Variables can be defined at the top level of the devfile or in the `parent` object. String replacement with variables cannot be used for:
8+
9+
* `schemaVersion`, `metadata`, or `parent` source
10+
* Element identifiers such as `command.id`, `component.name`, `endpoint.name`, and `project.name`
11+
* References to identifiers, for example, when binding commands by name to events, when specifiying a command's component, or when specifying the volume mount name for a container
12+
* String enumerations such as command `group.kind` or endpoint exposure
13+
14+
.Procedure
15+
16+
. Add a variable definition at the top level in your devfile:
17+
+
18+
[source,yaml]
19+
----
20+
schemaVersion: 2.2.0
21+
metadata:
22+
name: java-maven
23+
version: 1.1.1
24+
variables:
25+
javaVersion: 11
26+
...
27+
----
28+
. Reference the variable by name later in the devfile:
29+
+
30+
[source,yaml]
31+
----
32+
...
33+
components:
34+
- name: tools
35+
container:
36+
image: quay.io/eclipse/che-java{{javaVersion}}-maven:nightly
37+
...
38+
----
39+
40+
If you reference a variable that is not defined, a non-blocking warning is issued.

0 commit comments

Comments
 (0)