Skip to content

Commit 08b5f9a

Browse files
tsurdilotsurdilo
authored
Adding support for secrets and globals (#382)
* Adding support for secrets and globals Signed-off-by: Tihomir Surdilovic <[email protected]> * fix expressions Signed-off-by: Tihomir Surdilovic <[email protected]> * adding workflow globals to spec TOC Signed-off-by: Tihomir Surdilovic <[email protected]> * fixing spelling errors Signed-off-by: Tihomir Surdilovic <[email protected]> * adding more description of globals property Signed-off-by: Tihomir Surdilovic <[email protected]> * adding more info to secrets section Signed-off-by: Tihomir Surdilovic <[email protected]> * fixing duplication Signed-off-by: Tihomir Surdilovic <[email protected]> * adding restriction to globals Signed-off-by: Tihomir Surdilovic <[email protected]> * update for globals Signed-off-by: Tihomir Surdilovic <[email protected]> * fixed typo Signed-off-by: Tihomir Surdilovic <[email protected]> * added immutable requirements and renamed globals to constants Signed-off-by: Tihomir Surdilovic <[email protected]> * added immutable aspect to secrets Signed-off-by: Tihomir Surdilovic <[email protected]>
1 parent e248c59 commit 08b5f9a

File tree

4 files changed

+212
-2
lines changed

4 files changed

+212
-2
lines changed

‎roadmap/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ _Status description:_
3232
| ✔️| Renamed `schemaVersion` to `specVersion` and it is now a required parameter | [spec doc](../specification.md) |
3333
| ✔️| Add GraphQL support for function definitions | [spec doc](../specification.md) |
3434
| ✔️| Added "dataOnly" property to Event Definitions (allow event data filters to access entire event) | [spec doc](../specification.md) |
35+
| ✔️| Added support for Secrets and Constants | [spec doc](../specification.md) |
3536
| 🚩 | Workflow invocation bindings | |
3637
| 🚩 | CE Subscriptions & Discovery | |
3738
| 🚩 | Error types | [issue](https://github.com/serverlessworkflow/specification/issues/200) |

‎schema/secrets.json

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
{
2+
"$id": "https://serverlessworkflow.org/core/secrets.json",
3+
"$schema": "http://json-schema.org/draft-07/schema#",
4+
"description": "Serverless Workflow specification - secrets schema",
5+
"type": "object",
6+
"secrets": {
7+
"oneOf": [
8+
{
9+
"type": "string",
10+
"format": "uri",
11+
"description": "URI to a resource containing secrets definitions (json or yaml)"
12+
},
13+
{
14+
"type": "array",
15+
"description": "Workflow Secrets definitions",
16+
"items": {
17+
"type": "string"
18+
},
19+
"minItems": 1
20+
}
21+
]
22+
},
23+
"required": [
24+
"secrets"
25+
]
26+
}

‎schema/workflow.json

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,22 @@
6767
}
6868
]
6969
},
70+
"secrets": {
71+
"$ref": "secrets.json#/secrets"
72+
},
73+
"constants": {
74+
"oneOf": [
75+
{
76+
"type": "string",
77+
"format": "uri",
78+
"description": "URI to a resource containing constants data (json or yaml)"
79+
},
80+
{
81+
"type": "object",
82+
"description": "Workflow constants data (object type)"
83+
}
84+
]
85+
},
7086
"start": {
7187
"$ref": "#/definitions/startdef"
7288
},

‎specification.md

Lines changed: 169 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,9 @@ You can find the specification roadmap [here](roadmap/README.md).
2929
- [Defining Errors](#Defining-Errors)
3030
- [Defining Retries](#Defining-Retries)
3131
- [Workflow Compensation](#Workflow-Compensation)
32-
- [Workflow Versioning](#Workflow-Versioning)
32+
- [Workflow Versioning](#Workflow-Versioning)
33+
- [Workflow Constants](#Workflow-Constants)
34+
- [Workflow Secrets](#Workflow-Secrets)
3335
- [Workflow Metadata](#Workflow-Metadata)
3436
- [Extensions](#Extensions)
3537
- [Use Cases](#Use-Cases)
@@ -1539,6 +1541,8 @@ definition "id" must be a constant value.
15391541
| version | Workflow version | string | no |
15401542
| annotations | List of helpful terms describing the workflows intended purpose, subject areas, or other important qualities | string | no |
15411543
| dataInputSchema | Used to validate the workflow data input against a defined JSON Schema| string or object | no |
1544+
| [constants](#Workflow-Constants) | Workflow constants | string or object | no |
1545+
| [secrets](#Workflow-Secrets) | Workflow secrets | string or array | no |
15421546
| [start](#Start-Definition) | Workflow start definition | string | yes |
15431547
| specVersion | Serverless Workflow specification release version | string | yes |
15441548
| expressionLang | Identifies the expression language used for workflow expressions. Default value is "jq" | string | no |
@@ -1624,6 +1628,7 @@ for example "machine learning", "monitoring", "networking", etc
16241628
The `dataInputSchema` property can be used to validate the workflow data input against a defined JSON Schema.
16251629
This check should be done before any states are executed. `dataInputSchema` can have two different types.
16261630
If it is an object type it has the following definition:
1631+
16271632
```json
16281633
"dataInputSchema": {
16291634
"schema": "URL_to_json_schema",
@@ -1642,6 +1647,48 @@ In this case the `failOnValidationErrors` default value of `true` is assumed.
16421647
The `dataInputSchema` property validates the [workflow data input](#Workflow-Data-Input). In case of
16431648
a starting [Event state](#Event-state), it is not used to validate its event payloads.
16441649

1650+
The `secrets` property allows you to use sensitive information such as passwords, OAuth tokens, ssh keys, etc. inside your
1651+
Workflow expressions.
1652+
1653+
It has two possible types, `string` or `array`.
1654+
If `string` type, it is an URI pointing to a JSON or YAML document
1655+
which contains an array of names of the secrets, for example:
1656+
1657+
```json
1658+
"secrets": "file://workflowsecrets.json"
1659+
```
1660+
1661+
If `array` type, it defines an array (of string types) which contains the names of the secrets, for example:
1662+
1663+
```json
1664+
"secrets": ["MY_PASSWORD", "MY_STORAGE_KEY", "MY_ACCOUNT"]
1665+
```
1666+
1667+
For more information about Workflow secrets, reference the [Workflow Secrets section](#Workflow-Secrets).
1668+
1669+
The `constants` property can be used to define Workflow constants values
1670+
which are accessible in [Workflow Expressions](#Workflow-Expressions).
1671+
1672+
It has two possible types, `string` or `object`.
1673+
If `string` type, it is an URI pointing to a JSON or YAML document
1674+
which contains an object of global definitions, for example:
1675+
1676+
```json
1677+
"constants": "file://workflowconstants.json"
1678+
```
1679+
1680+
If `object` type, it defines a JSON object which contains the constants definitions, for example:
1681+
1682+
```json
1683+
{
1684+
"AGE": {
1685+
"MIN_ADULT": 18
1686+
}
1687+
}
1688+
```
1689+
1690+
For more information see the [Workflow Constants](#Workflow-Constants) section.
1691+
16451692
The `start` property defines the workflow starting information. For more information see the [start definition](#Start-Definition) section.
16461693

16471694
The `specVersion` property is used to set the Serverless Workflow specification release version
@@ -5024,7 +5071,127 @@ for your workflow definitions especially in production environments.
50245071

50255072
To enhance portability when using versioning of your workflow and sub-workflow definitions,
50265073
we recommend using an existing versioning standard such as [SemVer](https://semver.org/) for example.
5027-
5074+
5075+
### Workflow Constants
5076+
5077+
Workflow constants are used to define static, and immutable, data which is available to [Workflow Expressions](#Workflow-Expressions).
5078+
5079+
Constants can be defined via the [Workflow top-level "constants" property](#Workflow-Definition-Structure),
5080+
for example:
5081+
5082+
```json
5083+
"constants": {
5084+
"Translations": {
5085+
"Dog": {
5086+
"Serbian": "pas",
5087+
"Spanish": "perro",
5088+
"French": "chien"
5089+
}
5090+
}
5091+
}
5092+
```
5093+
5094+
Constants can only be accessed inside Workflow expressions via the $CONST namespace.
5095+
Runtimes must make constants available to expressions under that namespace.
5096+
5097+
Here is an example of using constants in Workflow expressions:
5098+
5099+
```json
5100+
{
5101+
...,
5102+
"constants": {
5103+
"AGE": {
5104+
"MIN_ADULT": 18
5105+
}
5106+
},
5107+
...
5108+
"states":[
5109+
{
5110+
"name":"CheckApplicant",
5111+
"type":"switch",
5112+
"dataConditions": [
5113+
{
5114+
"name": "Applicant is adult",
5115+
"condition": "${ .applicant | .age >= $CONST.AGE.MIN_ADULT }",
5116+
"transition": "ApproveApplication"
5117+
},
5118+
{
5119+
"name": "Applicant is minor",
5120+
"condition": "${ .applicant | .age < $CONST.AGE.MIN_ADULT }",
5121+
"transition": "RejectApplication"
5122+
}
5123+
],
5124+
...
5125+
},
5126+
...
5127+
]
5128+
}
5129+
```
5130+
Note that constants can also be used in [expression functions](#Using-Functions-for-Expression-Evaluation),
5131+
for example:
5132+
5133+
```json
5134+
{
5135+
"functions": [
5136+
{
5137+
"name": "isAdult",
5138+
"operation": ".applicant | .age >= $CONST.AGE.MIN_ADULT",
5139+
"type": "expression"
5140+
},
5141+
{
5142+
"name": "isMinor",
5143+
"operation": ".applicant | .age < $CONST.AGE.MIN_ADULT",
5144+
"type": "expression"
5145+
}
5146+
]
5147+
}
5148+
```
5149+
5150+
Workflow constants values should only contain static data, meaning that their value should not
5151+
contain Workflow expressions.
5152+
Workflow constants data must be immutable.
5153+
Workflow constants should not have access to [Workflow secrets definitions](#Workflow-Secrets).
5154+
5155+
### Workflow Secrets
5156+
5157+
Secrets allow you access sensitive information, such as passwords, OAuth tokens, ssh keys, etc
5158+
inside your [Workflow Expressions](#Workflow-Expressions).
5159+
5160+
You can define the names of secrets via the [Workflow top-level "secrets" property](#Workflow-Definition-Structure),
5161+
for example:
5162+
5163+
```json
5164+
"secrets": ["MY_PASSWORD", "MY_STORAGE_KEY", "MY_ACCOUNT"]
5165+
```
5166+
5167+
If secrets are defined in a Workflow definition, runtimes must assure to provide their values
5168+
during Workflow execution.
5169+
5170+
Secrets can be used only in [Workflow expressions](#Workflow-Expressions) under the `SECRETS` namespace.
5171+
This is reserved namespace that should only be allowed for values defined by the `secrets` property.
5172+
5173+
Here is an example on how to use secrets and pass them as arguments to a function invocation:
5174+
5175+
```json
5176+
"secrets": ["AZURE_STORAGE_ACCOUNT", "AZURE_STORAGE_KEY"],
5177+
5178+
...
5179+
5180+
{
5181+
"refName": "uploadToAzure",
5182+
"arguments": {
5183+
"account": "${ $SECRETS.AZURE_STORAGE_ACCOUNT }",
5184+
"account-key": "${ $SECRETS.AZURE_STORAGE_KEY }",
5185+
...
5186+
}
5187+
5188+
}
5189+
```
5190+
5191+
Note that secrets can also be used in [expression functions](#Using-Functions-for-Expression-Evaluation).
5192+
5193+
Secrets are immutable, meaning that workflow expressions are not allowed to change their values.
5194+
50285195
### Workflow Metadata
50295196

50305197
Metadata enables you to enrich the serverless workflow model with information beyond its core definitions.

0 commit comments

Comments
 (0)