Temporal workflows on Diagrid
Diagrid can run workflows written with the Temporal SDKs. You keep your workflow and activity code, your workers and your clients. You point them at Diagrid instead of a Temporal server, and Diagrid runs the workflows and stores their history.
Temporal workflows on Diagrid are in preview. Features and behavior can change before general availability, and not every region supports them yet.
How it works
- A Diagrid App is your Temporal namespace. You create an App that uses the Temporal workflow API. Its name is the namespace your workers and clients use.
- Your code talks to Diagrid with the Temporal SDK. Workers poll Diagrid for tasks and clients start, signal, query and update workflows, as they would with a Temporal server.
- Diagrid runs the server side. There's no Temporal server, database or visibility store to run.
- You see your workflows in Diagrid. Temporal workflows appear in the workflows view of the Diagrid Web Console, with their history.
Diagrid is tested with the Temporal Go, Java, Python and TypeScript SDKs, and with the Temporal CLI.
Set up a Temporal App
You need the Diagrid CLI, logged in with diagrid login. On macOS and Linux you also need jq.
1. Create a project and an App
Create a project, then an App that uses the Temporal workflow API. Projects created with diagrid CLI 1.119.0 or later get the managed workflow store by default. With CLI 1.118.0 or older, the project has no workflow store, and diagrid app create --workflow-api temporal fails. Upgrade the CLI, or run diagrid project update my-project --enable-managed-workflow for a project that already exists:
diagrid project create my-project --use
diagrid app create orders --workflow-api temporal --wait
You choose the workflow API when you create the App, and you can't change it later. If your region doesn't support Temporal workflows yet, diagrid app create says so.
2. Set Temporal's connection settings
Temporal's SDKs and CLI read their connection settings from environment variables. Set them to your project's endpoint, the App's name and the App's API token:
- macOS/Linux
- Windows
export TEMPORAL_ADDRESS="$(diagrid project get my-project -o json | jq -r '.status.endpoints.grpc | "\(.host):\(.port)"')"
export TEMPORAL_NAMESPACE=orders
export TEMPORAL_API_KEY="$(diagrid appid get orders -o json | jq -r .status.apiToken)"
$grpc = (diagrid project get my-project -o json | ConvertFrom-Json).status.endpoints.grpc
$env:TEMPORAL_ADDRESS = "$($grpc.host):$($grpc.port)"
$env:TEMPORAL_NAMESPACE = "orders"
$env:TEMPORAL_API_KEY = (diagrid appid get orders -o json | ConvertFrom-Json).status.apiToken
Diagrid only accepts encrypted connections. Temporal's SDKs and CLI turn on TLS when an API key is set, so you don't need another setting.
3. Run your workers and clients
Start your worker and your client as you usually do. Your workflows now run on Diagrid.
Check on them with the Temporal CLI, which reads the same settings:
temporal workflow list
You can also use diagrid workflow list or the Diagrid Web Console.
If your code sets the connection itself
Code that loads Temporal's environment configuration needs no changes. Temporal's money transfer tutorials do this.
If your code passes a fixed address such as localhost:7233, load the environment configuration instead:
- Python
- Go
- TypeScript
from temporalio.client import Client
from temporalio.envconfig import ClientConfig
client = await Client.connect(**ClientConfig.load_client_connect_config())
import (
"go.temporal.io/sdk/client"
"go.temporal.io/sdk/contrib/envconfig"
)
c, err := client.Dial(envconfig.MustLoadDefaultClientOptions())
Pass config.namespace to the client. If you leave it out, the client uses the namespace default, and the call fails with NamespaceNotFoundError: 'default'.
import { Client, Connection } from "@temporalio/client";
import { loadClientConnectConfig } from "@temporalio/envconfig";
const config = loadClientConnectConfig();
const connection = await Connection.connect(config.connectionOptions);
const client = new Client({ connection, namespace: config.namespace });
These Temporal SDK versions load the environment configuration:
| SDK | Version | Note |
|---|---|---|
| Python | 1.14 or later | temporalio.envconfig |
| Go | 1.32.1 or later | The contrib/envconfig package |
| Java | 1.32.1 or later | A separate artifact. Version 1.32.0 needs a temporal.toml file |
| TypeScript | 1.13.2 or later | |
| .NET | 1.9 or later |
Older SDKs have no option for an API key. Pass the App's API token as the header authorization: Bearer <token> on the connection instead, and set the address, the namespace and TLS in your code. You can also do this on a current SDK instead of loading the environment configuration.
