DOCSEARCHbyAlgolia
Submit Docs

Temporal Operator

repository·main·Indexed 42 days ago

https://github.com/alexandrevilain/temporal-operator

A Kubernetes Operator designed to simplify the deployment and management of Temporal clusters. It provides the TemporalCluster CRD (apiVersion: temporal.io/v1beta1) to configure Temporal versions, history shards, persistence stores (SQL, Cassandra), archival (S3, GCS, Filestore), mTLS, and JWT authorization.

Tokens
22.1K
Snippets
48
Records
99
Agent score
52%

What's inside Temporal Operator

  2. Override Temporal service manifests with ServiceSpecOverride

    main

    Use ServiceSpecOverride to modify the generated Kubernetes manifests for a specific service. This is useful for applying custom configurations that bypass the standard ServiceSpec fields.

    ServiceSpecOverride can be applied at two levels:

    1. Global level: Via spec.services.overrides in ServicesSpec to apply to all services.
    2. Service level: Via spec.services.<serviceName>.overrides to target a specific service. Service-level overrides take precedence over global overrides.

  4. Upgrade Temporal clusters via desired version updates

    main
    Upgrading a Temporal cluster is simplified by defining a desired Temporal version in your configuration. To perform an upgrade, you simply update the desired version in your resource definition, and the operator handles the upgrade process automatically without requiring manual scripts or intervention.

  5. Use ScheduleIntervalSpec for interval-based scheduling

    main

    The ScheduleIntervalSpec matches times that can be expressed using the formula: Epoch + (n * every) + offset (where n is any integer ≥ 0).

    Fields

    • every: Kubernetes meta/v1.Duration. Describes the period to repeat the interval.
    • offset: Kubernetes meta/v1.Duration (Optional). A fixed offset added to the interval's period. Defaults to 0.

    Examples

    • Every hour on the hour: every: 1h, offset: 0
    • Every hour at minute 19: every: 1h, offset: 19m
    • Every 28 days starting from a specific epoch: every: 28d, offset: 0

  6. Configure Schedule timing and constraints

    main

    The ScheduleSpec within a Schedule allows for fine-grained control over when tasks are triggered using calendars, intervals, and time constraints.

    Timing Fields:

    • calendars ([]ScheduleCalendarSpec, optional): Calendar-based specifications.
    • intervals ([]ScheduleIntervalSpec, optional): Interval-based specifications.
    • excludeCalendars ([]ScheduleCalendarSpec, optional): Times that will be skipped. All fields (including seconds) must match exactly.
    • startAt (Kubernetes meta/v1.Time, optional): The start of the schedule. Times before this are skipped.
    • endAt (Kubernetes meta/v1.Time, optional): The end of the schedule. Times after this are skipped.
    • jitter (Kubernetes meta/v1.Duration, optional): A duration used to apply random jitter (0 to the specified amount) to scheduled times.
    • timezoneName (string, optional): IANA time zone name (e.g., US/Pacific).

    Important Note on Timezones and DST: Calendar matching is a literal clock time match. It does not handle Daylight Saving Time (DST) transitions specially:

    • If a spec fires at 2:30am and DST causes that time to be skipped, the action is not triggered.
    • If a spec fires at 1:30am and DST causes that time to occur twice, the action will be triggered twice.

  8. Define time ranges with ScheduleDayOfMonthRange, ScheduleDayOfWeekRange, ScheduleHourRange, ScheduleMonthRange, and ScheduleSecondMinuteRange

    main

    These range types are used within ScheduleCalendarSpec to define specific windows of time.

    Behavioral Note: If end < start, the end value is interpreted as being equal to start. This allows you to represent a single specific value by setting start and leaving end and step unset.

    Common Fields

    • start: The beginning of the range (inclusive). Defaults vary by type (e.g., 0 for hour, 1 for dayOfMonth).
    • end: The end of the range (inclusive). Defaults to start if unset.
    • step: The increment between values. Defaults to 1.

  9. Configure mTLS for Frontend and Internode communication

    main

    The MTLSSpec allows you to enable encryption in transit using mTLS for different parts of the cluster.

    Frontend mTLS

    Defined via FrontendMTLSSpec for public endpoints:

    • enabled (bool, Optional): Enables mTLS for the cluster's public endpoints.
    • extraDnsNames ([]string): Additional DNS names to be added to the TLS certificate for external service access.

    Internode mTLS

    Defined via InternodeMTLSSpec for cluster node communication:

    • enabled (bool, Optional): Enables mTLS for the network traffic between cluster nodes.

  10. How resource overrides work in TemporalCluster

    main

    The TemporalCluster resource allows you to override properties of the Temporal components (pods/deployments) created by the operator. This is useful for setting custom resource limits, adding sidecars or init containers, mounting extra volumes, or injecting environment variables.

    There are two ways to apply overrides:

    1. StrategicPatchMerge: The default method where you provide a partial YAML structure that is merged into the existing resource.
    2. RFC6902 JSON patches: Used via the jsonPatch field when working with fields that StrategicPatchMerge cannot handle correctly (such as specific array manipulations).

    You can apply overrides at two scopes:

    • Global: For all services using spec.services.overrides.
    • Per-service: For a specific service (e.g., frontend, history, matching, or worker) using spec.services.[service_name].overrides.
    # Global override example
apiVersion: temporal.io/v1beta1
kind: TemporalCluster
spec:
  services:
    overrides:
      deployment:
        spec:
          template:
            spec:
              containers:
                - name: service
                  # your overrides here

  12. Configure Archival for Temporal clusters

    main

    Archival allows for backing up Workflow Execution Event Histories and Visibility data. You can configure this via the archival field in a TemporalCluster or TemporalNamespace.

    ArchivalSpec

    Controls the archival behavior for a specific persistence type (history or visibility):

    • enabled (bool): Enables archival by default.
    • paused (bool): Pauses the archival process.
    • enableRead (bool): Allows Temporal to read from the archived Event History.
    • path (string): The storage path.

    ArchivalProvider

    Defines the type of archiver to use:

    • filestore: Uses a FilestoreArchiver.
    • s3: Uses an S3Archiver.
    • gcs: Uses a GCSArchiver.
    spec:
  archival:
    enabled: true
    provider:
      s3: 
        # S3 specific configuration