Signed workflows and node tags
Signed plans and node tags are part of the full edition. In the community edition nothing is signed or checked, and a workflow whose activities need node tags is not started.
When a workflow starts, all its diagrams (the diagram itself and every module it uses) are linked once. This is the plan of the run. While the run goes on, waits for a reply or is continued days later, it keeps exactly this plan: a module that is changed in the meantime does not change a run that is already under way.
A run therefore consists of two parts:
| Part | What it contains | Changes |
|---|---|---|
Plan (modules) | the linked diagrams | never, after the start |
| Runtime state | where each thread stands, the variables, waiting joins | with every step |
The plan can be signed. A node that continues the run can then check that the plan is still the one that was started, and refuse it otherwise.
Node tags​
Some activities need a particular setup: a GPU, a certain Python environment, a node that only runs signed plans. Such requirements are written as tags on the activity.
- Select the activity on the canvas.
- Unfold Tags below its properties and enter the tags, separated by commas, e.g.
gpu-pascal, pytorch-11.x.
Tags are written in lower case and may contain letters, digits, ., _ and -. They describe the setup of a node,
not single libraries: pytorch-11.x is a good tag, numpy is not.
The diagram itself has no tags. Its properties show the required tags: the tags of all its activities, including those of its modules. A node that offers all of them can run the whole diagram.
| Tag | Meaning |
|---|---|
run-signed | The activity may only run on a node that only runs signed plans. |
| anything else | A setup the node offers, as its administrator configured it. |
Tags and the AI assistant​
The assistant sees the tags too. diagram_tags tells it which tags a diagram needs (all activities, including those of
modules), which tags this node offers and whether the diagram can run here. It writes tags like any other activity
parameter, tags=gpu-pascal,run-signed; an invalid tag is refused with a message, it is never dropped silently. The
assistant sets a tag only for a requirement you name. In the community edition it cannot set tags.
When a run is refused, the assistant is told why (for example which tags the node lacks), so it can tell you what to change.
Configure the node​
Open Settings → System settings → Workflow node.
| Setting | Effect |
|---|---|
| Sign the plan of every run this node starts | The plan is signed when a run starts. If it cannot be signed (no key, service not reachable), the run does not start. |
| Signed only | The node only starts and continues runs whose plan has a valid signature. It then also offers the tag run-signed. |
| Tags this node offers | The setup of the node, e.g. gpu-pascal. |
| Signing service | The address of the signing service of another installation. Empty: this installation signs with its own key. |
The settings can also be given as properties when the server starts, e.g. settings.node.validate=true.
When a node does not accept a run​
A node does not take a job it cannot fulfil:
- Missing tags: the activities need a tag the node does not offer. A new run does not start; the message names the missing tags.
- Signed only: the plan is not signed, was changed after it was signed, or was signed with a key the node does not know. A new run does not start.
A stored run that a node does not accept is not continued and not deleted: it stays as it is, so a node that can fulfil it may continue it later.
Signing key (administrator)​
The signing service signs with an Ed25519 key that is taken from the environment of the server and never stored in the database.
openssl genpkey -algorithm ed25519 -outform DER | base64 -w0
Set the result as the environment variable APP_SIGNING_KEY and restart the server. The settings page then shows
Signing key: set with the id of the key.
| Variable | Purpose |
|---|---|
APP_SIGNING_KEY | Private key of the signing service (PKCS#8, Base64). |
APP_SIGNING_PUBLIC_KEY | Optional: its public key (X.509, Base64). It is derived from the private key if not set. |
APP_SIGNING_OLD_PUBLIC_KEYS | Public keys of former keys, separated by commas, so plans signed before a change of the key still verify. |
APP_SIGNING_NODE_TOKENS | Tokens of the other nodes that may have plans signed, separated by commas. |
APP_SIGNING_NODE_TOKEN | The token this node sends to a signing service elsewhere. |
Several nodes​
One installation runs the signing service (it has APP_SIGNING_KEY). Every other node:
- gets a token: create a long random value, e.g.
openssl rand -hex 32, add it toAPP_SIGNING_NODE_TOKENSof the signing service and set it asAPP_SIGNING_NODE_TOKENof the node; - enters the address of the signing service in Signing service.
The node then sends the plan of a run it starts to the service and stores the signature with the run. To check a signature it fetches the public key from the service; the key is identified by its id, so a node fetches it only once.
| Endpoint | Purpose |
|---|---|
POST /api/v1/sign/plan | Signs a plan; needs a node token in the Authorization header. |
GET /api/v1/sign/public-key | The current public key. |
GET /api/v1/sign/public-key/{keyId} | The current or a former public key. |
Change the key​
- Create a new key as above.
- Put the public key of the former key into
APP_SIGNING_OLD_PUBLIC_KEYSand the new private key intoAPP_SIGNING_KEY. Restart. - Runs signed with the former key still verify. Remove a former key only when no stored run uses it any more.
If the key is lost, runs that were signed with it can no longer be verified; a node that runs signed plans only does not continue them.
Search running workflows​
The plan stays a plain JSON object in the stored run, next to it the signature:
{ "apiLevel": 2, "root": "...", "modules": { ... },
"planSignature": { "alg": "Ed25519", "keyId": "...", "sig": "..." }, "threads": { ... } }
Stored runs can therefore still be searched with SQL, e.g. model_state->'modules'. The signature covers a canonical
form of modules, so it stays valid although PostgreSQL stores the JSON in its own order; a change of modules in
the database makes it invalid.