Introduction to Temporal#

Temporal is a durable execution engine. You write workflows as ordinary code – if/else, loops, function calls – and Temporal guarantees that code runs to completion even when processes crash, machines fail, or deployments happen mid-execution. It eliminates the need to build retry logic, state machines, and recovery mechanisms by hand.

This article introduces the core concepts, architecture, and use cases. It is the first in a series that takes you from zero to running production workflows on Kubernetes.

Running Temporal Server on Minikube#

This guide deploys Temporal Server on a local Minikube cluster with PostgreSQL persistence. By the end, you will have the Temporal frontend, Web UI, and CLI all working against a real Kubernetes deployment.

If you need background on what Temporal is, start with Introduction to Temporal.

Prerequisites#

Your machine needs at least 4 CPU cores and 8 GB RAM available to Docker. For minikube driver details, see Minikube Setup and Drivers and Minikube Docker Driver.

Temporal High Availability#

A single-replica Temporal deployment works for development, but any pod going down takes the workflow engine offline. This guide configures a multi-replica cluster with proper resource allocation, Elasticsearch visibility, and health monitoring.

For the single-replica setup this builds on, see Running Temporal Server on Minikube.

Why HA Matters#

With multiple replicas, losing a pod triggers a brief rebalance (seconds), not an outage.

Temporal Namespaces and Task Queues#

Namespaces and task queues are Temporal’s two primary organizational mechanisms. Namespaces provide isolation – separate history, retention, and access. Task queues route work to specific workers. Together, they determine where workflows run and how long their history is kept.

For the underlying architecture, see Introduction to Temporal.

Namespaces#

A namespace is a logical isolation boundary. Every workflow belongs to exactly one namespace. Namespaces provide history isolation (workflows cannot see across boundaries), independent retention policies, per-namespace search attributes, and scoped access control.

Your First Temporal Workflow in Go#

This article establishes the patterns used throughout the Temporal series: dependency injection for testable activities, idempotency for safe retries, and a clean worker binary. Every subsequent article builds on these foundations.

All code lives in the companion repo at github.com/statherm/temporal-examples. For background, see Introduction to Temporal and Namespaces and Task Queues.

Project Structure#

The companion repo organizes code by domain:

temporal-examples/
  cmd/worker/main.go         # Worker binary
  cmd/starter/main.go        # Workflow starter CLI
  internal/container/
    activities.go             # Activity implementations with DI
    workflow.go               # Workflow definitions
    types.go                  # Interfaces and types
  Makefile

Workflows and Activities#

A workflow is a deterministic function that orchestrates work. It takes workflow.Context, must not perform side effects, and dispatches work through activities. Activities use standard context.Context and perform real I/O:

Testing Temporal Workflows#

Temporal workflows have a property that most distributed systems lack: determinism. A workflow function, given the same inputs and the same sequence of activity results, will always produce the same output. This makes workflows far more testable than you might expect for code that orchestrates long-running, multi-step processes.

Activities are the opposite. They talk to databases, call APIs, read files, and produce side effects. You do not want your unit tests doing any of that. The testing strategy follows directly: test workflows by mocking their activities, and test activities by injecting mock dependencies.

Multi-Stage Temporal Workflows#

The HelloWorkflow from Temporal Go Workflow Basics calls one activity and returns. Real workflows are not that simple. A deployment pipeline provisions infrastructure, configures networking, deploys the application, runs health checks, and updates DNS. Each step depends on the previous one. Any step can fail. Some failures require undoing earlier steps.

This article covers the patterns you need for production multi-stage workflows: sequential activities with data passing, retry policies, timeouts, child workflows, error propagation, and compensation.

Container Lifecycle Workflow#

This article builds a complete Temporal workflow that manages Docker container lifecycle operations: inspect a container, stop it if running, create a snapshot (commit), and handle failures by restarting the container. It demonstrates every pattern from Multi-Stage Temporal Workflows in a concrete, runnable example.

The full source is in the companion repo under container-lifecycle/.

The Use Case#

You need to automate container maintenance: take a snapshot of a running container for backup or migration purposes. The sequence is:

Temporal Signals#

Workflows often need input after they have started. A deployment workflow pauses for human approval. An expense workflow waits for a manager’s signature. An incident response workflow escalates after a timeout. Temporal signals are the mechanism for delivering external input to a running workflow.

A signal is a message sent to a workflow from outside – from another workflow, from a CLI command, from an HTTP endpoint, or from any system that has the Temporal client. The workflow receives the signal, processes it, and continues execution. Signals are durable: if the worker crashes after a signal is sent but before the workflow processes it, the signal is replayed when the worker restarts.

Temporal Signals for Automated Coordination#

In Temporal Signals for Manual Interaction, you learned how external systems and humans send signals to running workflows. Signals are not limited to human input. They are a general-purpose communication channel between workflows, and they become powerful coordination primitives when workflows signal each other programmatically.

This article covers automated signal patterns: cross-workflow signaling, distributed mutexes built on signals, blocking semantics, and the anti-patterns that will burn you.