Skip to content

Commit 134da5f

Browse files
sriumcpsriumcp
authored
gitops helmex-update task and documentation (#878)
* gitops helmex-update task and documentation Signed-off-by: Srinivasan Parthasarathy <[email protected]> * gitops helmex update task description Signed-off-by: Srinivasan Parthasarathy <[email protected]>
1 parent e0b9ede commit 134da5f

File tree

5 files changed

+198
-1
lines changed

5 files changed

+198
-1
lines changed

‎install/core/iter8-handler/handler.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ spec:
99
containers:
1010
- name: iter8-handler
1111
# to change handler version, edit the line below
12-
image: iter8/handler:0.1.21
12+
image: iter8/handler:0.1.22
1313
command: ["handler"]
1414
args: ["run", "-a", "$(ACTION)"]
1515
env:

‎mkdocs/docs/reference/helmex-schema.md

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
template: main.html
3+
---
4+
5+
# Helmex Schema
6+
7+
The Helmex schema is described below. This schema is intended for applications that are templated using Helm and use Iter8 experiments during releases.
8+
9+
## Top-level fields
10+
| Field name | Field type | Description | Required |
11+
| ----- | ------------ | ----------- | -------- |
12+
| baseline | [Version](#version) | Information about the baseline version of the application. The baseline version typically corresponds to the stable version of the application. | Yes |
13+
| candidate | [Version](#version) | Information about the candidate version. Iter8 experiment resource will be created only if this field is present. If this field is modified, any existing experiment for the application will be replaced by a new experiment. | No |
14+
15+
### Version
16+
17+
| Field name | Field type | Description | Required |
18+
| ----- | ------------ | ----------- | -------- |
19+
| dynamic | [Dynamic](#dynamic) | Information associated with a specific version. For example, each time the baseline version of the application changes, the `baseline.dynamic` field in the Helm values file should change. | Yes |
20+
21+
#### Dynamic
22+
| Field name | Field type | Description | Required |
23+
| ----- | ------------ | ----------- | -------- |
24+
| id | string | Alpha-numeric string that uniquely identifies a version. This optional field is strongly recommended for every version. | No. |
25+
26+
## Example
27+
The following Helm values file is an instance of the Helmex schema.
28+
29+
```yaml
30+
# values meant for both baseline and candidate versions of the application;
31+
common:
32+
application: hello
33+
repo: "gcr.io/google-samples/hello-app"
34+
serviceType: ClusterIP
35+
servicePortInfo:
36+
port: 8080
37+
regularLabels:
38+
app.kubernetes.io/managed-by: Iter8
39+
selectorLabels:
40+
app.kubernetes.io/name: hello
41+
42+
# values meant for baseline version of the application only;
43+
# baseline version is required by Helmex schema
44+
baseline:
45+
name: hello
46+
selectorLabels:
47+
app.kubernetes.io/track: baseline
48+
# required field for baseline version
49+
dynamic:
50+
# unique alpha-numeric version ID is strongly recommended
51+
id: "mn82l82"
52+
tag: "1.0"
53+
54+
# values meant for candidate version of the application only;
55+
# optional section; Iter8 experiment will be deployed if this section is present
56+
candidate:
57+
name: hello-candidate
58+
selectorLabels:
59+
app.kubernetes.io/track: candidate
60+
# required field for candidate version
61+
# if candidate is promoted, the dynamic field from candidate will be copied over to baseline, and candidate will be set to null
62+
dynamic:
63+
# unique alpha-numeric version ID is strongly recommended
64+
id: "8s72oa"
65+
tag: "2.0"
66+
67+
# this section is used in the creation of the Iter8 experiment
68+
# the specific experiment section below is used in the context of an SLO validation experiment
69+
experiment:
70+
# The SLO validation experiment will collect Iter8's built-in latency and error metrics.
71+
# There will be 8.0 * 5 = 40 queries sent during metrics collection.
72+
# time is the duration over which queries are sent during metrics collection.
73+
time: 5s
74+
# QPS is number of queries per second sent during metrics collection.
75+
QPS: 8.0
76+
# (msec) acceptable limit for mean latency of the application
77+
limitMeanLatency: 500.0
78+
# (msec) acceptable error rate for the application (1%)
79+
limitErrorRate: 0.01
80+
# (msec) acceptable limit for 95th percentile latency of the application
81+
limit95thPercentileLatency: 1000.0
82+
```

‎mkdocs/docs/reference/tasks/gitops-helmex-update.md

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
template: main.html
3+
---
4+
5+
# `gitops/helmex-update`
6+
The `github/helmex-update` task can be used to update Helm values file in a GitHub repo. This task requires the Helm values file to conform to the [Helmex schema](../helmex-schema.md). This task is intended to be included in the finish action of an experiment.
7+
8+
## Example
9+
The following is an experiment snippet with a `gitops/helmex-update` task.
10+
11+
```yaml
12+
...
13+
spec:
14+
strategy:
15+
actions:
16+
finish:
17+
- task: gitops/helmex-update
18+
with:
19+
# GitHub repo containing the values.yaml file
20+
gitRepo: "https://github.com/ghuser/iter8.git"
21+
# Path to values.yaml file
22+
filePath: "samples/second-exp/values.yaml"
23+
# GitHub username
24+
username: "ghuser"
25+
# Branch modified by this task
26+
branch: "gitops-test"
27+
# Secret containing the personal access token needed for git push
28+
secretName: "my-secret"
29+
# Namespace containing the above secret
30+
secretNamespace: "default"
31+
```
32+
33+
## Inputs
34+
| Field name | Field type | Description | Required |
35+
| ----- | ------------ | ----------- | -------- |
36+
| gitRepo | string | GitHub repo containing the `values.yaml` file. The repo needs to begin with the prefix `https://`. | Yes |
37+
| filePath | string | Path to the Helm values file, relative to the root of this repo. | Yes |
38+
| username | string | GitHub username. For organization account, this can also be an org name. | Yes |
39+
| branch | string | Branch to be updated by this task. Default value is `main`. | No |
40+
| secretName | string | This task requires [a personal access token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) in order to modify the GitHub repo. `secretName` is the name of the Kubernetes secret which contains this token. Default value is `ghtoken`. | No |
41+
| secretNamespace | string | Namespace where the above secret is located. Default value is the namespace of the experiment. | No |
42+
43+
**Note:** The task above expects to find a key named `token` within the secret's `Data` section; i.e., `secret.Data["token"]` needs to be the GitHub personal access token. In addition, the `iter8-handler` service account in the `iter8-system` namespace needs to be given read permissions using RBAC rules for this secret.
44+
45+
## Result
46+
The [version recommended for promotion](../../concepts/buildingblocks.md#version-promotion) by Iter8 will be promoted as the new baseline in the `values.yaml` file. Suppose the `values.yaml` file in the GitHub repo is the same as the one in [this example](../helmex-schema.md#example).
47+
48+
=== "Baseline is promoted"
49+
Assuming baseline is recommended for promotion by Iter8, the new `values.file` in the GitHub repo after this task executes, will look as follows. Notice how the `dynamic` field differs between the two scenarios.
50+
51+
```yaml
52+
common:
53+
application: hello
54+
repo: "gcr.io/google-samples/hello-app"
55+
serviceType: ClusterIP
56+
servicePortInfo:
57+
port: 8080
58+
regularLabels:
59+
app.kubernetes.io/managed-by: Iter8
60+
selectorLabels:
61+
app.kubernetes.io/name: hello
62+
63+
baseline:
64+
name: hello
65+
selectorLabels:
66+
app.kubernetes.io/track: baseline
67+
dynamic:
68+
id: "mn82l82"
69+
tag: "1.0"
70+
71+
# even though there is an experiment section below, there will be
72+
# no Iter8 experiment in the cluster, since there is no candidate version
73+
experiment:
74+
time: 5s
75+
QPS: 8.0
76+
limitMeanLatency: 500.0
77+
limitErrorRate: 0.01
78+
limit95thPercentileLatency: 1000.0
79+
```
80+
81+
=== "Candidate is promoted"
82+
Assuming candidate is recommended for promotion by Iter8, the new `values.file` in the GitHub repo after this task executes, will look as follows. Notice how the `dynamic` field differs between the two scenarios.
83+
84+
```yaml
85+
common:
86+
application: hello
87+
repo: "gcr.io/google-samples/hello-app"
88+
serviceType: ClusterIP
89+
servicePortInfo:
90+
port: 8080
91+
regularLabels:
92+
app.kubernetes.io/managed-by: Iter8
93+
selectorLabels:
94+
app.kubernetes.io/name: hello
95+
96+
baseline:
97+
name: hello
98+
selectorLabels:
99+
app.kubernetes.io/track: baseline
100+
dynamic:
101+
id: "8s72oa"
102+
tag: "2.0"
103+
104+
# even though there is an experiment section below, there will be
105+
# no Iter8 experiment in the cluster, since there is no candidate version
106+
experiment:
107+
time: 5s
108+
QPS: 8.0
109+
limitMeanLatency: 500.0
110+
limitErrorRate: 0.01
111+
limit95thPercentileLatency: 1000.0
112+
```

‎mkdocs/docs/reference/tasks/overview.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ Tasks are an extension mechanism for enhancing the behavior of Iter8 experiments
99
- [`common/bash`](common-bash.md): Execute a bash script.
1010
- [`common/exec`](common-readiness.md) (deprecated): Execute a shell command.
1111
- [`metrics/collect`](metrics-collect.md): Generate GET/POST requests for the application versions and collect latency and error metrics. This task supports Iter8's built-in metrics feature.
12+
- [`gitops/helmex-update`](gitops-helmex-update.md): Update Helm values in a GitHub repo using `git push`. The Helm values file must satisfy the [Helmex schema](../helmex-schema.md).
1213
- [`notification/http`](notification-http.md): Send a HTTP request to a specified target.
1314
- [`notification/slack`](notification-slack.md): Send a slack notification with a summary of the experiment.
1415

‎mkdocs/mkdocs.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -167,12 +167,14 @@ nav:
167167
- Reference:
168168
- Experiment resource: reference/experiment.md
169169
- Metric resource: reference/metrics.md
170+
- Helmex schema: reference/helmex-schema.md
170171
- Task overview: reference/tasks/overview.md
171172
- Task descriptions:
172173
- common/readiness: reference/tasks/common-readiness.md
173174
- common/bash: reference/tasks/common-bash.md
174175
- common/exec: reference/tasks/common-exec.md
175176
- metrics/collect: reference/tasks/metrics-collect.md
177+
- gitops/helmex-update: reference/tasks/gitops-helmex-update.md
176178
- notification/http: reference/tasks/notification-http.md
177179
- notification/slack: reference/tasks/notification-slack.md
178180
- Contributing:

0 commit comments

Comments
 (0)