feat: Conditional Artifacts and Parameters (#4987)

argoproj · Mar 4, 2021 · 78ec644 · 78ec644
1 parent 1a8ce1f
commit 78ec644
Show file tree

Hide file tree

Showing 28 changed files with 1,571 additions and 552 deletions.
diff --git a/api/jsonschema/schema.json b/api/jsonschema/schema.json
@@ -2707,6 +2707,10 @@
  "description": "From allows an artifact to reference an artifact from a previous step",
  "type": "string"
  },
+ "fromExpression": {
+ "description": "FromExpression, if defined, is evaluated to specify the value for the artifact",
+ "type": "string"
+ },
  "gcs": {
  "$ref": "#/definitions/io.argoproj.workflow.v1alpha1.GCSArtifact",
  "description": "GCS contains GCS artifact location details"
@@ -2830,6 +2834,10 @@
  "description": "From allows an artifact to reference an artifact from a previous step",
  "type": "string"
  },
+ "fromExpression": {
+ "description": "FromExpression, if defined, is evaluated to specify the value for the artifact",
+ "type": "string"
+ },
  "gcs": {
  "$ref": "#/definitions/io.argoproj.workflow.v1alpha1.GCSArtifact",
  "description": "GCS contains GCS artifact location details"
@@ -5190,6 +5198,10 @@
  "description": "Selector (https://github.com/antonmedv/expr) that is evaluated against the event to get the value of the parameter. E.g. `payload.message`",
  "type": "string"
  },
+ "expression": {
+ "description": "Expression, if defined, is evaluated to specify the value for the parameter",
+ "type": "string"
+ },
  "jqFilter": {
  "description": "JQFilter expression against the resource object in resource templates",
  "type": "string"

diff --git a/api/openapi-spec/swagger.json b/api/openapi-spec/swagger.json
@@ -6129,6 +6129,10 @@
  "description": "From allows an artifact to reference an artifact from a previous step",
  "type": "string"
  },
+ "fromExpression": {
+ "description": "FromExpression, if defined, is evaluated to specify the value for the artifact",
+ "type": "string"
+ },
  "gcs": {
  "description": "GCS contains GCS artifact location details",
  "$ref": "#/definitions/io.argoproj.workflow.v1alpha1.GCSArtifact"
@@ -6252,6 +6256,10 @@
  "description": "From allows an artifact to reference an artifact from a previous step",
  "type": "string"
  },
+ "fromExpression": {
+ "description": "FromExpression, if defined, is evaluated to specify the value for the artifact",
+ "type": "string"
+ },
  "gcs": {
  "description": "GCS contains GCS artifact location details",
  "$ref": "#/definitions/io.argoproj.workflow.v1alpha1.GCSArtifact"
@@ -8605,6 +8613,10 @@
  "description": "Selector (https://github.com/antonmedv/expr) that is evaluated against the event to get the value of the parameter. E.g. `payload.message`",
  "type": "string"
  },
+ "expression": {
+ "description": "Expression, if defined, is evaluated to specify the value for the parameter",
+ "type": "string"
+ },
  "jqFilter": {
  "description": "JQFilter expression against the resource object in resource templates",
  "type": "string"

diff --git a/docs/conditional-artifacts-parameters.md b/docs/conditional-artifacts-parameters.md
@@ -0,0 +1,72 @@
+# Conditional Artifacts and Parameters
+
+> v3.1 and after
+
+The Conditional Artifacts and Parameters feature enables to assign the Step/DAG level artifacts or parameters based on
+expression. This introduces a new field `fromExpression: ...` under Step/DAG level output artifact and `expression: ...`
+under step/DAG level output parameter. Both use the
+[expr](https://github.com/antonmedv/expr/blob/master/docs/Language-Definition.md) syntax.
+
+## Conditional Artifacts
+
+```yaml
+
+- name: coinflip
+ steps:
+ - - name: flip-coin
+ template: flip-coin
+ - - name: heads
+ template: heads
+ when: "{{steps.flip-coin.outputs.result}} == heads"
+ - name: tails
+ template: tails
+ when: "{{steps.flip-coin.outputs.result}} == tails"
+ outputs:
+ artifacts:
+ - name: result
+ fromExpression: "steps['flip-coin'].outputs.result == 'heads' ? steps.heads.outputs.artifacts.headsresult : steps.tails.outputs.artifacts.tailsresult"
+
+```
+
+* [Steps artifacts example](examples/conditional-artifacts.yaml)
+* [DAG artifacts example](examples/dag-conditional-artifacts.yaml)
+
+## Conditional Parameters
+
+```yaml 
+ - name: coinflip
+ steps:
+ - - name: flip-coin
+ template: flip-coin
+ - - name: heads
+ template: heads
+ when: "{{steps.flipcoin.outputs.result}} == heads"
+ - name: tails
+ template: tails
+ when: "{{steps.flipcoin.outputs.result}} == tails"
+ outputs:
+ parameters:
+ - name: stepresult
+ valueFrom:
+ expression: "steps.flipcoin.outputs.result == 'heads' ? steps.heads.outputs.result : steps.tails.outputs.result"
+```
+
+* [Steps parameter example](examples/conditional-parameters.yaml)
+* [DAG parameter example](examples/dag-conditional-parameters.yaml)
+
+## Build-In Functions
+
+Convenient functions added to support more use cases:
+
+1. `asInt` - convert the string to integer (e.g: `asInt('1')`)
+2. `asFloat` - convert the string to Float (e.g: `asFloat('1.23')`)
+3. `string` - convert the int/float to string (e.g: `string(1)`)
+4. `jsonpath` - Extract the element from Json using jsonpath (
+ e.g: `jsonpath('{"employee":{"name":"sonoo","salary":56000,"married":true}}", "$.employee.name" )` )
+5. [Sprig](http:https://masterminds.github.io/sprig/) - Support all `sprig` functions
+
+* [Advanced example: fibonacci Sequence](examples/fibonacci-seq-conditional-param.yaml)
+
+!!! NOTE 
+ Expressions will decode the `-` as operator if template name has `-`, it will fail the expression. So here solution
+ for template name which has `-` in its name. `step['one-two-three'].outputs.artifacts`