Skip to main content

Signed workflows and node tags

Full edition

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:

PartWhat it containsChanges
Plan (modules)the linked diagramsnever, after the start
Runtime statewhere each thread stands, the variables, waiting joinswith 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.

  1. Select the activity on the canvas.
  2. 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.

TagMeaning
run-signedThe activity may only run on a node that only runs signed plans.
anything elseA 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.

SettingEffect
Sign the plan of every run this node startsThe plan is signed when a run starts. If it cannot be signed (no key, service not reachable), the run does not start.
Signed onlyThe node only starts and continues runs whose plan has a valid signature. It then also offers the tag run-signed.
Tags this node offersThe setup of the node, e.g. gpu-pascal.
Signing serviceThe 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.

Create a key once
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.

VariablePurpose
APP_SIGNING_KEYPrivate key of the signing service (PKCS#8, Base64).
APP_SIGNING_PUBLIC_KEYOptional: its public key (X.509, Base64). It is derived from the private key if not set.
APP_SIGNING_OLD_PUBLIC_KEYSPublic keys of former keys, separated by commas, so plans signed before a change of the key still verify.
APP_SIGNING_NODE_TOKENSTokens of the other nodes that may have plans signed, separated by commas.
APP_SIGNING_NODE_TOKENThe 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:

  1. gets a token: create a long random value, e.g. openssl rand -hex 32, add it to APP_SIGNING_NODE_TOKENS of the signing service and set it as APP_SIGNING_NODE_TOKEN of the node;
  2. 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.

EndpointPurpose
POST /api/v1/sign/planSigns a plan; needs a node token in the Authorization header.
GET /api/v1/sign/public-keyThe current public key.
GET /api/v1/sign/public-key/{keyId}The current or a former public key.

Change the key​

  1. Create a new key as above.
  2. Put the public key of the former key into APP_SIGNING_OLD_PUBLIC_KEYS and the new private key into APP_SIGNING_KEY. Restart.
  3. 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.