Temporal Nexus on self-hosted clusters

Treat each Nexus endpoint as a contract between the team that exposes an operation and the teams that call it, and settle ownership before the first caller is wired up. Record the owning team, the namespace that hosts the handling workflows, the task queue those workflows run on, and an on-call contact in your internal service catalog. Confirm in the official Temporal Nexus documentation for your server version how endpoints are registered and which namespace and task queue an endpoint targets, because that binding decides who can change the handler without affecting callers. On a self-hosted cluster, also confirm how your ClaimMapper roles and Authorizer rules are scoped to the handling namespace, so that the team that owns the handler also controls who may call into it.

Inputs and outputs are the part of the contract that breaks callers silently, so version them deliberately. Prefer additive changes such as new optional fields, and avoid renaming or removing fields that callers already read. When a breaking change cannot be avoided, publish a new operation name or a new endpoint and keep the old one running until every caller has moved and the deprecation window you agreed has closed. Payloads pass through data converters and, if you use one, a custom codec with a codec server. Callers and handlers must share the same codec configuration, so record it in the contract and test it explicitly, since a mismatch will only appear at runtime.

Name endpoints after the business capability they provide, such as a billing statement operation exposed by a billing endpoint (illustrative), not after the workflow type, queue name, service hostname or internal stage that happens to implement it. Implementation names change during refactors, and once callers embed them, every rename becomes a coordinated release. Use the same endpoint names in every environment so that one caller configuration works across development, staging and production namespaces, with only the connection details varying. Check the naming constraints in the server version you run, including allowed characters and length, before you publish a naming standard across teams.

Endpoint design determines how painful ownership handover and handler changes will be. If callers depend only on the published contract, the handling team can change its workflows without coordinating every caller. If callers depend on internal workflow types, timings or signal names, a routine change becomes an outage risk. The blast radius of a change is the set of callers bound to one handler namespace and task queue, so a single endpoint shared by many teams concentrates risk. Test contracts in each caller's pipeline against the handler's published schemas, run the new handler version in a staging namespace first, and confirm the official documentation for how in-flight operations behave during handler deployments and retries. Re-check endpoint targets if the handling namespace is later placed under multi-cluster failover.

The first thing a team must establish is whether a Nexus endpoint, and the calls already in flight through it, survive a planned handover and a forced failover. These are different events. A planned handover gives operators time to drain work and switch the active side, while a forced failover happens when the active region is lost and calls may be partway through execution. Do not assume the answer from the general Nexus concept. For the server version you intend to run, confirm whether the endpoint registration is available on the standby cluster, and what happens to an operation that started before the switch. Write these answers down before design work begins, because they determine what your runbook has to cover.

Endpoint behavior depends on how namespaces are replicated. A Nexus call connects a caller in one namespace to a handler in another, so the failover plan has to account for both. Global namespaces and their active cluster decide which side accepts writes, and the endpoint must resolve to a namespace that is active after the switch. Confirm whether the endpoint definition replicates with the namespace or must be created on the standby cluster ahead of time. If it has to be created manually, that step belongs in the runbook and in every failover drill, not in an incident response. Also confirm how the handler namespace behaves while it is in a standby role.

Replication is also where the main risk sits. The sibling page on multi-cluster replication and failover covers the experimental status of global namespace replication, planned handover and forced failover procedures, and conflict resolution. Treat its findings as binding for any Nexus design. A cross-namespace call inherits the replication risks of both namespaces, so a conflict or an experimental replication behavior on either side affects the call. This section does not repeat that analysis. Instead, ask the vendor how Nexus state is replicated and whether any Nexus behavior falls outside the guarantees described on that sibling page.

Verification must happen against the documentation for the exact server version you plan to run, and in a non-production replica that mirrors your namespace layout, endpoint definitions and worker deployment. Build a test that starts a cross-namespace call, runs a planned handover, and then runs a forced failover in a separate exercise. Record what happens to the caller, the handler and any retries, and check the final state of each workflow. Record timings as well. Do not allow a Nexus-dependent workflow into production until the people who own the failover runbook have reviewed those results and signed off on them.

Put the following questions to the vendor and to your own platform team before you commit: (1) Does an endpoint definition replicate with its namespace, or must it be created on the standby cluster? (2) Do in-flight Nexus operations complete, fail or resume after a planned handover? (3) What happens to pending operations after a forced failover, and how is the original active cluster reconciled when it returns? (4) Which Nexus state is covered by replication guarantees, and which is excluded? (5) Which conflict cases for Nexus calls are documented for this version? (6) What test procedure does the vendor recommend, and what evidence should your team collect from it?

Running Temporal Nexus on a self-hosted cluster is ongoing work, and most of the risk sits in the upgrade cycle. Upgrade the Temporal Server one minor version at a time, and move to the latest patch of the current minor before stepping to the next minor. The upgrade documentation states that backward compatibility is guaranteed only between two successive minor versions, so skipping a minor line removes that guarantee. Before each server upgrade, check whether the release notes call for a schema upgrade, and if they do, run the schema upgrade first. Treat the Nexus-specific notes for each target version as a separate review item, because general server notes may not describe changes to the HTTP API or callback settings that your endpoints depend on. Confirm those notes in the release notes for every version on your path.

After each upgrade step, retest every Nexus endpoint your teams call, not only the endpoints in the service that changed. Use a small set of representative operations per endpoint, covering a successful call, a call that fails on a deliberate input error, and a call made during a rolling restart of the worker fleet. Record the results against the version pair so that a later rollback has a known-good reference. If a step fails, stop the sequence, return to the last verified version, and resolve the failure before moving on. Schedule these retests in the same change window as the server step so that the test evidence and the version record stay together.

Monitoring is what tells you whether an endpoint is working for its callers after the upgrade is finished. Track call volume, error rate and latency for each endpoint, grouped by the calling namespace and the owning team, and alert on sustained changes in any of them. Watch for callers that stop calling an endpoint, since a silent drop can indicate a broken client rather than reduced demand. Confirm with your platform team which metrics and visibility queries your current server version exposes for Nexus operations, and which need custom instrumentation. Keep the alert thresholds in version control next to the endpoint definitions so that a reviewer can see what changed in each release.

Ownership and deprecation need the same discipline as the server. Each endpoint should have a named owning team, a named backup contact, and a written record of the contract it exposes, including input and output shape, error behavior and the namespaces allowed to call it. When a team changes or moves, update the owner record before the handover is complete, not after an incident. To deprecate an endpoint, announce a removal date to known callers, keep the endpoint running until call volume reaches zero or the agreed date passes, and remove the endpoint only after monitoring confirms that no caller remains. Store the contract registry and deprecation notices in the same repository as your platform documentation, so that ownership questions have one answer.

Ask the implementation partner, or your own platform team, to confirm three things before the first production upgrade: the Nexus upgrade notes for each target minor and patch version, the schema upgrade requirement for each step, and the Helm chart version that matches each server image if you deploy with Kubernetes. The Helm chart requirement matters because the deployment documentation states that chart versions below 0.73.1 do not work with server images 1.30 and later. Put the answers in the upgrade runbook with a date and the name of the person who checked them, so the next person upgrading the cluster starts from verified facts rather than memory.