Deploy and run workflows

Availability and installation versions

Deploy a workflow through the CLI, the authenticated deployment API, or a CloudFormation custom resource. To run its DAG, the installation must also provide the authenticated Starter runtime.

Scoped publication requires installation 1.9.0 or newer and scoped-deployments-v1. Workflow execution additionally requires scoped-workflow-executions-v1. The CLI checks the actual advertised capabilities. A version override cannot enable an unavailable feature.

For supported 1.0.x–1.8.x installations, retain their frozen legacy deployment commands. New role and compute bindings are never silently downgraded to an older wire contract. The Controller remains a read-only catalog.

The authenticated runtime is undergoing candidate acceptance. Availability in a customer installation requires its reviewed release and advertised capabilities; this guide does not claim a published release or cross-account AWS certification.

Roles, tenant and namespace permissions

An installation administrator grants an authenticated IAM principal specific operations in a tenant and namespace, with exact approved role/target combinations. Deployment permission does not grant execution permission.

• deploy: publish approved definitions and bindings.
• execute: start the deployed workflow and authorize its phase bindings.
• read and inspect: read deployments and execution status.
• revoke: prevent new dispatch claims. cancel: request termination of a recorded Batch job.

Administrative grants are stored separately from execution data; the runtime can read them but cannot change them. Workflow input cannot replace tenant ownership, roles, function ARNs, job queues, or job definitions. Infrastructure roles are forbidden as workload bindings.

Deploy with the CLI

Configure the installation's deployment API URL and an approved AWS profile. The CLI signs API requests with AWS SigV4. Standard AWS credential environment variables are also supported; profile and SSO resolution uses AWS CLI v2.

export RIPPFLOW_DEPLOYMENT_URL="https://YOUR_API.execute-api.us-east-1.amazonaws.com/v1"
export AWS_PROFILE=orders-deployer
rippflow deploy workflow.json --tenant orders --namespace fulfillment --bindings bindings.json --json
rippflow deployments inspect "$DEPLOYMENT_ID" --json

The response includes an immutable deploymentId. Repeating the same document preserves its original identity, publisher, and publication time. Changed content produces a new ID. Keep the ID with the application version that will execute it.

{
  "name": "process-order",
  "version": "1.0.0",
  "phases": {
    "check": {"requires": [], "scope": "root", "service": "check"},
    "finish": {"requires": ["check"], "scope": "root", "service": "finish", "terminal": true}
  }
}

External Lambda and custom roles

A Lambda binding pins a published numeric function version, an invocation role, and the expected function execution role. Every phase needs exactly one approved binding.

{
  "check": {
    "type": "lambda",
    "functionArn": "arn:aws:lambda:us-east-1:123456789012:function:check:42",
    "invocationRoleArn": "arn:aws:iam::123456789012:role/invoke-check",
    "executionRoleArn": "arn:aws:iam::123456789012:role/check-workload"
  },
  "finish": {
    "type": "lambda",
    "functionArn": "arn:aws:lambda:us-east-1:123456789012:function:finish:7",
    "invocationRoleArn": "arn:aws:iam::123456789012:role/invoke-finish",
    "executionRoleArn": "arn:aws:iam::123456789012:role/finish-workload"
  }
}

The invocation role controls the AWS call. The function runs with its own configured execution role; caller credentials are not propagated into the workload. For a custom managed runner role, provision a dedicated Lambda with that execution role and bind its published version.

STS trust must allow the installation deployment service role and require the installation ID as ExternalId. The runtime narrows temporary sessions to the pinned target. Functions must be active with a timeout of at most 110 seconds for this adapter.

{"dispatchId":"...","context":{"installationId":"...","tenantId":"orders","namespace":"fulfillment","deploymentId":"...","phase":"check","requestId":"...","shard":""},"input":{"order":"123"}}

{"outcome":"completed","payload":{"order":"123","checked":"true"}}

Return a named outcome for declared outcome routing. A Lambda FunctionError becomes a failed phase. JSON output is limited to 64 KiB. Business handlers should deduplicate their side effects by dispatchId. Phase inputs are merged over the previous payload (or execution input for a root); a scalar payload is wrapped as value when phase inputs are present.

Run and inspect the deployed DAG

Use a separately authorized executor profile. Starter admits the exact published definition; the DAG engine handles dependencies, shard barriers, outcome routing and bounded retries. Users submit an execution ID and business input, never a replacement workflow or role list.

export AWS_PROFILE=orders-executor
rippflow deployments run "$DEPLOYMENT_ID" --execution-id order-123 --input input.json --json
rippflow deployments execution "$DEPLOYMENT_ID" --execution-id order-123 --json

# For per-shard phases, pass a JSON array of unique shard IDs:
rippflow deployments run "$DEPLOYMENT_ID" --execution-id order-124 --input input.json --shards shards.json --json

Start returns a durable QUEUED execution intent. Inspection then shows admission and the authoritative runtime status and stage. Wait for a terminal runtime status such as completed or failed; publication or admission alone does not prove successful execution.

The same execution ID and input are idempotent. Reusing the ID with different input is a conflict. IDs are scoped to the installation, tenant, namespace and deployment. Execution input is limited to 32 KiB; combined authenticated admission data is limited to 96 KiB. Use artifact pointers for larger data.

External AWS Batch work

Bind an enabled job queue and active, revision-pinned job definition. The queue and definition must be in the same account and region. The single-container ECS/Fargate definition must use a digest-pinned image and the exact approved workload and container-agent roles.

{
  "type": "batch",
  "jobQueueArn": "arn:aws:batch:us-east-1:123456789012:job-queue/orders",
  "jobDefinitionArn": "arn:aws:batch:us-east-1:123456789012:job-definition/reconcile:7",
  "submissionRoleArn": "arn:aws:iam::123456789012:role/submit-reconcile",
  "jobRoleArn": "arn:aws:iam::123456789012:role/reconcile-workload",
  "executionRoleArn": "arn:aws:iam::123456789012:role/reconcile-agent",
  "timeoutSeconds": 300,
  "attempts": 1
}

Batch input is a map of string parameters. Command, environment and role overrides are forbidden. Parameter names beginning with rippflow are reserved. The runtime supplies installation, tenant, namespace, deployment, request, phase, shard and dispatch identifiers.

For a downstream JSON result, the job can write to the supplied rippflowResultBucket and rippflowResultKey, using its job role. Grant that role PutObject only on the installation result prefix. The optional result uses the same outcome/payload/pointer envelope as Lambda and is limited to 64 KiB.

A submitted job does not complete a phase. The runtime polls until Batch reports SUCCEEDED or FAILED and delivers an authenticated completion to the DAG engine. Missing optional output defaults to a completed result; malformed output fails the phase. EKS, multi-node and multi-container definitions are rejected by this adapter.

CloudFormation and direct API primitives

The installation provider exposes Custom::RippflowWorkflow. Its Deployment property uses the same definition and bindings as the API. For lossless numeric, boolean and business input types, supply the complete Deployment as a JSON object string. Object form adapts known CloudFormation string booleans and binding numbers while leaving business strings unchanged. No CLI or user access token is required in the stack.

AWSTemplateFormatVersion: '2010-09-09'
Parameters:
  DeploymentProviderArn: {Type: String}
  CheckPublishedVersion: {Type: String}
  InvokeCheckRoleArn: {Type: String}
  CheckWorkloadRoleArn: {Type: String}
Resources:
 OrderWorkflow:
  Type: Custom::RippflowWorkflow
  DeletionPolicy: Retain
  UpdateReplacePolicy: Retain
  Properties:
    ServiceToken: !Ref DeploymentProviderArn
    RetainDeployment: true
    Deployment:
      contract: scoped-deployments-v1
      installationId: production
      tenantId: orders
      namespace: fulfillment
      definition: # Complete workflow document
        name: process-order
        version: 1.0.0
        phases:
          check: {requires: [], scope: root, service: check, terminal: true}
      bindings:
        check:
          type: lambda
          functionArn: !Ref CheckPublishedVersion
          invocationRoleArn: !Ref InvokeCheckRoleArn
          executionRoleArn: !Ref CheckWorkloadRoleArn
Outputs:
  DeploymentId:
    Value: !GetAtt OrderWorkflow.DeploymentId

Ref of AWS::Lambda::Version returns the qualified version ARN. Retained versions allow rollback. Explicit RetainDeployment: false makes deletion revoke that physical deployment; external functions, roles and Batch resources remain customer-owned.

AWS SigV4 API clients use service execute-api in the endpoint region. Routes are relative to the installation API base URL:

• POST /v1/deployments: publish.
• POST /v1/deployments/{id}/executions: start with executionId, input and optional shards/correlationId.
• GET /v1/deployments/{id}/executions/{executionId}: inspect.
• DELETE /v1/deployments/{id}: revoke.

Only grant provider invocation to trusted stack execution roles; the provider's own scoped identity authorizes publication. A registered CloudFormation resource type with drift detection is not required for this custom-resource integration.

Failure, revocation and recovery

Scoped admission and completions are authenticated for their installation and execution. Runtime input and handler output cannot change deployment ownership or redirect completion delivery. Current grants and revocation are checked before new external dispatch claims.

Starter errors can follow partial admission. Recovery retries the identical execution request while it remains queued; inspect persistent errors and revoke or publish corrected input using a new execution ID. Publication records, execution intents, phase claims and completion outbox entries are durable. Stream replay and scheduled recovery reuse the same claim. An outbox retry does not repeat already-completed external work.

An explicit AWS HTTP 4xx rejection fails the phase. An ambiguous AWS response, HTTP 5xx or interrupted claimed worker becomes UNKNOWN. It does not advance the DAG and is not automatically retried. Execution inspection exposes needsAttention and scoped uncertainDispatches (up to 25, with a truncation flag). Inspect the provider and application idempotency records before creating a new logical attempt.

rippflow deployments status "$DEPLOYMENT_ID" --dispatch-id "$DISPATCH_ID" --json
rippflow deployments revoke "$DEPLOYMENT_ID" --json

# A running Batch job requires a separate cancellation request:
rippflow deployments cancel "$DEPLOYMENT_ID" --dispatch-id "$DISPATCH_ID" --json

Revocation is irreversible for that deployment identity and blocks later dispatch claims. It does not promise to stop an AWS call already authorized by an earlier claim. Poll Batch cancellation to terminal status. Publish a reviewed new version if a revoked workflow must be restored.

Operators should monitor the queued backlog, completion outbox, stream iterator age, worker errors and dispatch/orchestrator dead-letter queues. Recover delivery using the same IDs and preserve immutable verification evidence.