Skip to main content

Getting Started with Temporal Nexus

Temporal Nexus Public Preview is available within your Temporal Cloud account, with support in the Temporal Go SDK.

Calls across existing Namespaces can be enabled by creating a Nexus Endpoint in the Nexus API Registry, creating a Nexus Service in a Worker in the handler Namespace, and then using the Nexus Service from a caller Workflow in a different Namespace. Monolithic Namespaces can be decomposed into multiple Namespaces, by hiding service implementations behind a Nexus Endpoint in the monolithic Namespace, pointing all consumers at the new Nexus Endpoint, and then changing the Endpoint’s target Namespace to a different Namespace. Multiple Nexus Endpoints can target a single monolithic Namespace.

Cross-Namespace​

Follow these steps to enable calls across existing Namespaces:

  1. Add Nexus Services to the same Workers as the Temporal primitives being abstracted.
  2. Add a Nexus Endpoint that:
    1. Targets the handler Namespace.
    2. Allows the caller Namespace.
  3. Make Nexus calls from a caller Workflow in a different Namespace.
    1. Use workflow.NewNexusClient(endpointName, serviceName).
    2. Execute a Nexus Operation with nexusClient.ExecutionOperation(...)

Decompose a Monolithic Namespace​

Multiple Nexus Endpoints can target a single monolithic Namespace, and then each Endpoint can be updated, one at a time, to target separate Namespaces, for an incremental migration.

Once Nexus Endpoints are in place, targeting a new Namespace can be done with config changes and zero downtime, as new Nexus requests will be routed to the new target Namespace, and existing Nexus requests will be completed in the previous Namespace.

Steps to decompose a large monolithic Namespace:

  1. Hide service implementations behind a Nexus Endpoint.
    1. Add Nexus Services to the same Workers as the Temporal primitives being abstracted.
    2. Add Nexus Endpoints to the Nexus API Registry, with monolithic Namespace as the target.
  2. Service consumers use the Nexus Endpoint instead of the underlying implementation.
    1. This can be done incrementally, until there are no direct caller dependencies on the underlying service implementations (the underlying Temporal primitives).
  3. Move service implementations to a different Namespace.
    1. Create a new Namespace.
    2. Add a Worker deployment with the Nexus Service.
    3. Update the Nexus Endpoint target to the new Namespace.
    4. Configure the Endpoint allowlist to allow calls from the original monolithic Namespace.
    5. New Nexus Operations will be routed from callers in the monolithic Namespace to the new Namespace.
  4. Quiesce Nexus Operations on the previous target Namespace.
    1. Leave the previous Worker deployment running until all existing Nexus Operations in the previous Namespace have completed (and their underlying Workflows, if any).
    2. Previous Workers in the monolithic Namespace can have the service implementation removed, since it is now being served from the new Endpoint target Namespace.

Please note the following points:

  • For long-lived entity Workflows, new Nexus requests will be routed to the new target Namespace and the long-lived entity-Workflow will still be running on the previous Namespace.
  • If using Signal-with-Start behind a Nexus Operation, then a new entity-Workflow will be started in the new target Namespace.
  • A cancel Nexus Operation request from a caller Workflow will be routed through the Nexus Endpoint to the new target Namespace, which may not have the underlying Workflow.

In these scenarios, Temporal can provide guidance on different migration strategies.