Documentation
¶
Overview ¶
Package temporal contains Temporal-version-aware helpers: the supported version compatibility matrix and the server config-template renderer.
The matrix data lives in versions_gen.go, which is generated from hack/version-matrix.yaml by `make gen-version-matrix`. Edit the YAML, not the generated Go.
Index ¶
- Variables
- func AdminToolsImage(version string) string
- func CanUpgrade(from, to string) (bool, error)
- func DefaultServicePorts() map[string]ServicePort
- func DefaultUIVersion(serverVersion string) string
- func IsSupported(version string) bool
- func RenderClusterConfig(cluster *temporalv1alpha1.TemporalCluster, opts BuildOptions) (string, error)
- func RenderConfig(data *ConfigData) (string, error)
- func RenderDynamicConfig(spec *temporalv1alpha1.DynamicConfigSpec, version string) (rendered string, warnings []string, err error)
- func ResolveLatestPatch(minor string) (string, error)
- func ServerImage(version string) string
- func SupportedVersions() []string
- func ValidateUpgradePath(from, to string) error
- type ArchivalConfig
- type AuthConfig
- type BuildOptions
- type ConfigData
- type DatastoreConfig
- type DatastoreTLS
- type IntervalParams
- type MTLSConfig
- type MetricsConfig
- type NamespaceClient
- type NamespaceClientFactory
- type NamespaceInfo
- type NamespaceParams
- type RangeParams
- type RetryParams
- type ScheduleClient
- type ScheduleClientFactory
- type ScheduleInfo
- type ScheduleParams
- type SchedulePolicyParams
- type ScheduleSpecParams
- type ScheduleStateParams
- type SearchAttributeClient
- type SearchAttributeClientFactory
- type ServicePort
- type StartWorkflowParams
- type StructuredCalendarParams
- type VersionInfo
Constants ¶
This section is empty.
Variables ¶
var ErrNamespaceNotFound = errors.New("namespace not found")
ErrNamespaceNotFound is returned by Describe when the namespace does not exist.
var ErrScheduleNotFound = errors.New("schedule not found")
ErrScheduleNotFound is returned by Describe when the schedule does not exist.
Functions ¶
func AdminToolsImage ¶
AdminToolsImage returns the Temporal admin-tools image for a version, used to run schema setup and migrations.
func CanUpgrade ¶
CanUpgrade reports whether a cluster may move from version `from` to version `to`.
func DefaultServicePorts ¶
func DefaultServicePorts() map[string]ServicePort
DefaultServicePorts returns the default ports for each Temporal service keyed by the service's component name (frontend, history, matching, worker, internal-frontend).
func DefaultUIVersion ¶
DefaultUIVersion returns the known-good UI version for a server version, or an empty string when the server version is unknown.
func IsSupported ¶
IsSupported reports whether the exact patch version is in the support matrix.
func RenderClusterConfig ¶
func RenderClusterConfig(cluster *temporalv1alpha1.TemporalCluster, opts BuildOptions) (string, error)
RenderClusterConfig is a convenience that builds and renders in one step.
func RenderConfig ¶
func RenderConfig(data *ConfigData) (string, error)
RenderConfig renders the resolved ConfigData into a Temporal server config YAML.
func RenderDynamicConfig ¶
func RenderDynamicConfig(spec *temporalv1alpha1.DynamicConfigSpec, version string) (rendered string, warnings []string, err error)
RenderDynamicConfig renders a Temporal dynamicconfig.yaml document from the spec's dynamic config values. Keys are emitted in sorted order for deterministic output. Unknown keys (relative to the target version's matrix) are returned as warnings; keys removed in the target version cause an error.
func ResolveLatestPatch ¶
ResolveLatestPatch returns the highest supported patch version for a minor.
func ServerImage ¶
ServerImage returns the default Temporal server image for a version.
func SupportedVersions ¶
func SupportedVersions() []string
SupportedVersions returns the sorted list of supported exact patch versions.
func ValidateUpgradePath ¶
ValidateUpgradePath returns nil if a cluster may move from version `from` to version `to` (both may be minor or exact).
Types ¶
type ArchivalConfig ¶
ArchivalConfig holds resolved archival settings.
type AuthConfig ¶
AuthConfig holds resolved authorization settings.
type BuildOptions ¶
type BuildOptions struct {
// BindOnIP is the address services bind to. Defaults to "0.0.0.0".
BindOnIP string
// BroadcastAddress is the membership broadcast address (typically the pod IP).
BroadcastAddress string
// DynamicConfigPath overrides the default dynamic config file path.
DynamicConfigPath string
// DefaultStorePassword / VisibilityStorePassword are the resolved passwords.
DefaultStorePassword string
VisibilityStorePassword string
// DefaultStorePasswordCommand / VisibilityStorePasswordCommand are used for
// Temporal 1.31+ IAM auth instead of a static password.
DefaultStorePasswordCommand string
VisibilityStorePasswordCommand string
// PublicClientHostPort overrides the publicClient host:port.
PublicClientHostPort string
}
BuildOptions carries runtime-resolved values that are not derivable from the CR alone (resolved secret values and pod-network details).
type ConfigData ¶
type ConfigData struct {
Version string
LogLevel string
NumHistoryShards int32
DefaultStoreName string
VisibilityStoreName string
DefaultStore DatastoreConfig
VisibilityStore DatastoreConfig
BindOnIP string
BroadcastAddress string
MTLS MTLSConfig
Metrics MetricsConfig
Authorization *AuthConfig
Services map[string]ServicePort
UseInternalFrontend bool
EnableGlobalNamespace bool
CurrentClusterName string
MasterClusterName string
DynamicConfigPath string
Archival *ArchivalConfig
PublicClient string
}
ConfigData is the fully-resolved input to the config template.
func BuildConfigData ¶
func BuildConfigData(cluster *temporalv1alpha1.TemporalCluster, opts BuildOptions) (*ConfigData, error)
BuildConfigData resolves a TemporalCluster CR plus runtime options into a ConfigData ready for rendering.
type DatastoreConfig ¶
type DatastoreConfig struct {
// Kind is "sql", "cassandra", or "elasticsearch".
Kind string
// SQL fields.
PluginName string
DatabaseName string
ConnectAddr string
User string
Password string
PasswordCommand string
MaxConns int32
MaxIdleConns int32
MaxConnLifetime string
// Cassandra fields.
Hosts string
Keyspace string
Port int32
Datacenter string
// Elasticsearch fields.
ESVersion string
URLScheme string
URLHost string
VisibilityIndex string
TLS *DatastoreTLS
}
DatastoreConfig is a fully-resolved datastore configuration.
type DatastoreTLS ¶
type DatastoreTLS struct {
Enabled bool
CAFile string
CertFile string
KeyFile string
EnableHostVerification bool
ServerName string
}
DatastoreTLS holds TLS file paths for a datastore connection.
type IntervalParams ¶ added in v0.5.0
IntervalParams is an interval-based fire spec.
type MTLSConfig ¶
type MTLSConfig struct {
Enabled bool
RefreshInterval string
RequireClientAuth bool
InternodeServerCert string
InternodeServerKey string
InternodeClientCA string
InternodeServerName string
FrontendServerCert string
FrontendServerKey string
FrontendServerName string
SystemWorkerCert string
SystemWorkerKey string
SystemWorkerCA string
SystemWorkerName string
}
MTLSConfig holds resolved mTLS file paths and settings.
type MetricsConfig ¶
MetricsConfig holds resolved Prometheus settings.
type NamespaceClient ¶
type NamespaceClient interface {
Describe(ctx context.Context, name string) (*NamespaceInfo, error)
Register(ctx context.Context, params NamespaceParams) error
Update(ctx context.Context, params NamespaceParams) error
Delete(ctx context.Context, name string) error
Close() error
}
NamespaceClient manages namespaces in a Temporal cluster.
func NewNamespaceClient ¶
func NewNamespaceClient(_ context.Context, address string, tlsConfig *tls.Config) (NamespaceClient, error)
NewNamespaceClient dials the frontend and returns a NamespaceClient.
type NamespaceClientFactory ¶
type NamespaceClientFactory func(ctx context.Context, address string, tlsConfig *tls.Config) (NamespaceClient, error)
NamespaceClientFactory builds a NamespaceClient connected to a frontend address. A nil tlsConfig means an insecure connection.
type NamespaceInfo ¶
type NamespaceInfo struct {
ID string
Description string
OwnerEmail string
RetentionPeriod time.Duration
}
NamespaceInfo is the observed state of a Temporal namespace.
type NamespaceParams ¶
type NamespaceParams struct {
Name string
Description string
OwnerEmail string
RetentionPeriod time.Duration
}
NamespaceParams describes the desired state of a Temporal namespace.
type RangeParams ¶ added in v0.5.0
RangeParams is an inclusive [Start,End] range with Step.
type RetryParams ¶ added in v0.5.0
type RetryParams struct {
InitialInterval *time.Duration
BackoffCoefficient float64
MaximumInterval *time.Duration
MaximumAttempts int32
NonRetryableErrorTypes []string
}
RetryParams is the started workflow's retry policy.
type ScheduleClient ¶ added in v0.5.0
type ScheduleClient interface {
Describe(ctx context.Context, namespace, scheduleID string) (*ScheduleInfo, error)
Create(ctx context.Context, params ScheduleParams) error
Update(ctx context.Context, params ScheduleParams) error
Pause(ctx context.Context, namespace, scheduleID, notes string) error
Unpause(ctx context.Context, namespace, scheduleID, notes string) error
Delete(ctx context.Context, namespace, scheduleID string) error
Close() error
}
ScheduleClient manages schedules in a Temporal cluster.
func NewScheduleClient ¶ added in v0.5.0
func NewScheduleClient(_ context.Context, address string, tlsConfig *tls.Config) (ScheduleClient, error)
NewScheduleClient dials the frontend and returns a ScheduleClient.
type ScheduleClientFactory ¶ added in v0.5.0
type ScheduleClientFactory func(ctx context.Context, address string, tlsConfig *tls.Config) (ScheduleClient, error)
ScheduleClientFactory builds a ScheduleClient connected to a frontend address. A nil tlsConfig means an insecure connection.
type ScheduleInfo ¶ added in v0.5.0
type ScheduleInfo struct {
Paused bool
Notes string
NextActionTimes []time.Time
RunningWorkflows int
}
ScheduleInfo is the observed state of a Temporal schedule.
type ScheduleParams ¶ added in v0.5.0
type ScheduleParams struct {
ScheduleID string
Namespace string
Spec ScheduleSpecParams
Action StartWorkflowParams
Policies SchedulePolicyParams
State ScheduleStateParams
}
ScheduleParams is the operator-domain description of a Temporal schedule.
type SchedulePolicyParams ¶ added in v0.5.0
type SchedulePolicyParams struct {
OverlapPolicy string
CatchupWindow *time.Duration
PauseOnFailure bool
KeepOriginalWorkflowID bool
}
SchedulePolicyParams tunes overlap/catchup behavior.
type ScheduleSpecParams ¶ added in v0.5.0
type ScheduleSpecParams struct {
CronStrings []string
Intervals []IntervalParams
Calendars []StructuredCalendarParams
ExcludeCalendars []StructuredCalendarParams
StartTime *time.Time
EndTime *time.Time
Jitter *time.Duration
TimezoneName string
}
ScheduleSpecParams is when a schedule fires.
type ScheduleStateParams ¶ added in v0.5.0
type ScheduleStateParams struct {
Paused bool
Notes string
LimitedActions bool
RemainingActions int64
}
ScheduleStateParams controls pause and action-limit state.
type SearchAttributeClient ¶
type SearchAttributeClient interface {
// List returns the custom search attributes for a namespace, keyed by name
// with the CR-style type string as the value.
List(ctx context.Context, namespace string) (map[string]string, error)
Add(ctx context.Context, namespace, name, attrType string) error
Remove(ctx context.Context, namespace, name string) error
Close() error
}
SearchAttributeClient manages custom search attributes in a Temporal cluster.
func NewSearchAttributeClient ¶
func NewSearchAttributeClient(ctx context.Context, address string, tlsConfig *tls.Config) (SearchAttributeClient, error)
NewSearchAttributeClient dials the frontend and returns a SearchAttributeClient.
type SearchAttributeClientFactory ¶
type SearchAttributeClientFactory func(ctx context.Context, address string, tlsConfig *tls.Config) (SearchAttributeClient, error)
SearchAttributeClientFactory builds a SearchAttributeClient.
type ServicePort ¶
ServicePort holds the ports for a single Temporal service.
type StartWorkflowParams ¶ added in v0.5.0
type StartWorkflowParams struct {
WorkflowType string
TaskQueue string
WorkflowID string
Args [][]byte
ExecutionTimeout *time.Duration
RunTimeout *time.Duration
TaskTimeout *time.Duration
IDReusePolicy string
Retry *RetryParams
Memo map[string][]byte
SearchAttributes map[string][]byte
}
StartWorkflowParams describes the workflow to start. Args/Memo/SearchAttributes hold raw JSON bytes that are encoded into json/plain payloads.
type StructuredCalendarParams ¶ added in v0.5.0
type StructuredCalendarParams struct {
Second []RangeParams
Minute []RangeParams
Hour []RangeParams
DayOfMonth []RangeParams
Month []RangeParams
Year []RangeParams
DayOfWeek []RangeParams
Comment string
}
StructuredCalendarParams is a field-range calendar spec.
type VersionInfo ¶
type VersionInfo struct {
// Version is the minor version, e.g. "1.31".
Version string
// PatchVersions are the exact supported patch releases, e.g. "1.31.1".
PatchVersions []string
// MinSchemaSQL is the minimum SQL schema version required.
MinSchemaSQL string
// MinSchemaCassandra is the minimum Cassandra schema version required.
MinSchemaCassandra string
// MinSchemaES is the minimum Elasticsearch schema/index template version.
MinSchemaES string
// AllowedFromVersions are the minor versions a cluster may upgrade from.
AllowedFromVersions []string
// UISeries is the compatible temporal-ui minor series, e.g. "2.34".
UISeries string
// DefaultUIVersion is the known-good exact temporal-ui version to pair with.
DefaultUIVersion string
// CassandraVisibilitySupported reports whether Cassandra may be used as a
// visibility store on this version.
CassandraVisibilitySupported bool
// RemovedDynamicConfig lists dynamic config keys removed in this version.
RemovedDynamicConfig []string
// AddedDynamicConfig lists dynamic config keys added in this version.
AddedDynamicConfig []string
}
VersionInfo describes a single supported Temporal minor version.
func Get ¶
func Get(version string) (VersionInfo, bool)
Get returns the VersionInfo covering an exact patch version.
func LookupVersion ¶
func LookupVersion(version string) (*VersionInfo, error)
LookupVersion returns the VersionInfo for a version, which may be a minor ("1.31") or an exact patch ("1.31.1").