You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* documentation for common/bash task
Signed-off-by: Michael Kalantar <[email protected]>
* move variable substitution to tasks
Signed-off-by: Michael Kalantar <[email protected]>
* modify format of links
Signed-off-by: Michael Kalantar <[email protected]>
Copy file name to clipboardExpand all lines: mkdocs/docs/reference/tasks.md
+30-5Lines changed: 30 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,14 +4,39 @@ template: main.html
4
4
5
5
# Tasks
6
6
7
-
Tasks are an extension mechanism for enhancing the behavior of Iter8 experiments and can be specified within the [spec.strategy.actions](../experiment/#strategy) field of the experiment.
7
+
Tasks are an extension mechanism for enhancing the behavior of Iter8 experiments and can be specified within the [spec.strategy.actions](experiment.md#strategy) field of the experiment.
8
+
9
+
## Task Libraries
8
10
9
11
Tasks are grouped into libraries. The following task libraries are available.
10
12
11
-
-`common`[library](common/#common-tasks)
12
-
*Task for executing a shell command.
13
-
-`metrics`[library](metrics/#metrics-tasks)
13
+
-`common`[library](tasks/common.md#common-tasks)
14
+
*Tasks that have wide applicability such as executing shell commands.
Inputs to tasks may contain placeholders, or template variables, which will be dynamically substituted when the task is executed by Iter8. For example, in the task:
24
+
25
+
```bash
26
+
- task: common/bash # promote the winning version
27
+
with:
28
+
script: |
29
+
kubectl apply -f {{ .promoteManifest }}
30
+
```
31
+
32
+
`{{ .promotionManifest}}` is a placeholder.
33
+
34
+
Placeholders are specified using the Go language specification for data-driven [templates](https://golang.org/pkg/html/template/). In particular, placeholders are specified between double curly braces.
35
+
36
+
Iter8 supports placeholders for:
37
+
38
+
- Values of variables of the version recommended for promotion. To specify such placeholders, use the name of the variable as defined in the [`versionInfo` section](experiment.md#versioninfo) of the experiment definition. For example, in the above example, `{{ .promotionManifest }}` is a placeholder for the value of the variable with the name `promotionManifest` of the version Iter8 recommends for promotion (see [`.status.versionRecommendedForPromotion`](experiment.md#status)).
39
+
40
+
- Values defined in the experiment itself. To specify such placeholders, use the prefix `.this`. For example, `{{ .this.metadata.name }}` is a placeholder for the name of the experiment.
41
+
42
+
If Iter8 cannot evaluate a placeholder expression, a blank value ("") will be substituted. This may occur, for example, in an start tasks when Iter8 has not yet defined a version recommended for promotion.
Copy file name to clipboardExpand all lines: mkdocs/docs/reference/tasks/common.md
+61-19Lines changed: 61 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,15 +4,69 @@ template: main.html
4
4
5
5
# Common Tasks
6
6
7
-
## `common/exec`
7
+
## `common/bash`
8
8
9
9
### Overview
10
10
11
-
The `common/exec` task executes a shell command with arguments. Arguments are specified using placeholders that are dynamically substituted at runtime. The `common/exec` task can be used as part of a finish action to promote the winning version at the end of an experiment.
11
+
The `common/bash` task executes a bash script. The script can be written to use placeholders that are [dynamically substituted at runtime](../tasks.md#dynamic-variable-substitution). For example, the `common/bash` task can be used as part of a finish action to promote the winning version at the end of an experiment.
12
12
13
13
### Example
14
14
15
-
The following (partially-specified) experiment executes `kubectl apply` using a YAML manifest at the end of the experiment. The URL for the manifest contains a placeholder `.promote`, which is dynamically substituted at the end of the experiment.
15
+
The following (partially-specified) experiment executes the one line script `kubectl apply` using a YAML manifest at the end of the experiment. The URL for the manifest contains a placeholder `{{ .promotionManifest }}`, which is dynamically substituted at the end of the experiment.
16
+
17
+
```yaml
18
+
kind: Experiment
19
+
...
20
+
spec:
21
+
...
22
+
strategy:
23
+
...
24
+
actions:
25
+
finish: # run the following sequence of tasks at the end of the experiment
26
+
- task: common/bash # promote the winning version
27
+
with:
28
+
script: |
29
+
kubectl apply -f {{ .promotionManifest }}
30
+
...
31
+
versionInfo:
32
+
# information about app versions used in this experiment
| Field name | Field type | Description | Required |
48
+
| ----- | ---- | ----------- | -------- |
49
+
| script | string | The bash script that will be executed | Yes |
50
+
51
+
### Result
52
+
53
+
The script will be executed.
54
+
55
+
In the example above, a YAML file corresponding to the baseline or candidate version will be applied to the cluster.
56
+
57
+
If this task exits with a non-zero error code, the experiment to which it belongs will fail.
58
+
59
+
## `common/exec` (Deprecated)
60
+
61
+
### Overview
62
+
63
+
The `common/exec` task executes a shell command with arguments. Arguments may be specified using placeholders that are dynamically substituted at runtime. The `common/exec` task can be used as part of a finish action to promote the winning version at the end of an experiment.
64
+
65
+
`common/exec`is deprecated; use `common/bash` instead.
66
+
67
+
### Example
68
+
69
+
The following (partially-specified) experiment executes `kubectl apply` using a YAML manifest at the end of the experiment. The URL for the manifest contains a placeholder `{{ .promote }}`, which is dynamically substituted at the end of the experiment.
16
70
17
71
```yaml
18
72
kind: Experiment
@@ -57,24 +111,12 @@ spec:
57
111
58
112
The command with the supplied arguments will be executed.
59
113
60
-
In the [example above](#example), a YAML file corresponding to the baseline or candidate version will be applied to the cluster.
114
+
In the example above, a YAML file corresponding to the baseline or candidate version will be applied to the cluster.
61
115
62
116
If this task exits with a non-zero error code, the experiment to which it belongs will fail.
63
117
64
-
### Dynamic placeholder substitution
65
-
66
-
Inputs to tasks can contain placeholders, or template variables, which will be dynamically substituted when the task is executed by Iter8. In the [example above](#example), one input is:
In this case, the placeholder is `{{ .promote }}`.
71
-
72
-
Placeholder substitution in task inputs works as follows.
73
-
74
-
Iter8 will find the version recommended for promotion which is determined by Iter8 during the course of the experiment, and stored in the `status.versionRecommendedForPromotion` field of the experiment resource. The version recommended for promotion is the winner, if a winner has been found in the experiment. Otherwise, it is the baseline version supplied in the `spec.versionInfo` field of the experiment.
75
-
76
-
If the placeholder is `{{ .name }}`, Iter8 will substitute it with the name of the version recommended for promotion. If it is any other variable, Iter8 will substitute it with the value of the corresponding variable for the version recommended for promotion. Variable values are specified in the variables field of the version detail when the experiment is created.
118
+
### Dynamic Variable Substitution
77
119
78
-
### Disabling placeholder substitution
120
+
The `common/exec` task only supports [dynamic variable subsitution](../tasks.md#dynamic-variable-substitution) for variables of the version recommended for promotion.
79
121
80
-
By default, the `common/exec` task will attempt to find the version recommended for promotion, and use the values defined for it (in the spec.versionInfo portion of the experiment). However, this behavior will lead to task failure when the version recommended for promotion is not available. This is usually the case when a start task is executed. To use the `common/exec` task as part of an experiment start action, set `disableInterpolation` to true.
122
+
Instead of defaulting to a blank value when Iter8 has not determined a version to recommend for promotion (that is, in start tasks), this task supports the `disableInterpolation` option to prevent dynamic variable substitution.
0 commit comments