temporal-server validate-dynamic-config

Validate dynamic configuration files

The temporal-server validate-dynamic-config command validates dynamic configuration files for syntax errors, unknown keys, and type mismatches.

Synopsis

temporal-server validate-dynamic-config <file> [<file>...]

Description

Validates one or more dynamic configuration YAML files against known configuration keys and their expected types. This command helps catch configuration errors before deploying to production.

The validator checks:

• YAML syntax validity
• Known configuration keys
• Correct value types for each key
• Valid constraint names
• Proper constraint value types

Arguments

file

Path to one or more dynamic configuration files to validate.

• Type: String (file path)
• Required: Yes (at least one file)
• Multiple: Yes

# Validate single file
temporal-server validate-dynamic-config config/dynamicconfig/development.yaml

# Validate multiple files
temporal-server validate-dynamic-config \
  config/dynamicconfig/development.yaml \
  config/dynamicconfig/production.yaml

Output

For each file, the command prints:

• File name
• Any errors found
• Any warnings found

At the end, it prints a summary with the total error count.

Success Output

$ temporal-server validate-dynamic-config config/dynamicconfig/development.yaml
config/dynamicconfig/development.yaml

No output means the file is valid.

Error Output

$ temporal-server validate-dynamic-config config/dynamicconfig/production.yaml
config/dynamicconfig/production.yaml
  error: unknown key: "frontend.invalidKey"
  error: type mismatch for "history.maxAutoResetPoints": expected int, got string
  warning: key "matching.forwarderMaxRatePerSecond" has no value
3 total errors

Exit Codes

• 0: All files are valid (no errors)
• 1: One or more files contain errors

Common Errors

Unknown Key

# Invalid - typo in key name
frontend.namespacRPS:  # Should be "namespaceRPS"
  - value: 1000

Error: unknown key: "frontend.namespacRPS"

Type Mismatch

# Invalid - wrong type
history.maxAutoResetPoints:
  - value: "twenty"  # Should be int

Error: type mismatch for "history.maxAutoResetPoints": expected int, got string

Invalid Constraint

# Invalid - unknown constraint
frontend.namespaceRPS:
  - value: 1000
    constraints:
      invalidConstraint: "value"  # Not a valid constraint name

Error: unknown constraint: "invalidConstraint"

Missing Value

# Invalid - no value provided
frontend.namespaceRPS:
  - constraints:
      namespace: "my-namespace"

Warning: key "frontend.namespaceRPS" has no value

Valid Configuration Example

# Rate limiting
frontend.namespaceRPS:
  - value: 5000
    constraints:
      namespace: "high-throughput"
  - value: 1000  # default

# History limits
history.maxAutoResetPoints:
  - value: 50
    constraints:
      namespace: "long-running"
  - value: 20

history.historyCountLimitError:
  - value: 100000
    constraints:
      namespace: "special-namespace"
  - value: 50000

# Matching configuration
matching.numTaskqueueWritePartitions:
  - value: 16
    constraints:
      namespace: "prod-namespace"
      taskQueueName: "main-queue"
  - value: 4

# Boolean values
system.forceSearchAttributesCacheRefreshOnRead:
  - value: true

# Duration values
matching.longPollExpirationInterval:
  - value: 60s
    constraints:
      namespace: "my-namespace"

Validation in CI/CD

GitHub Actions

name: Validate Config

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Download Temporal Server
        run: |
          curl -sSf https://temporal.download/cli.sh | sh
          
      - name: Validate Dynamic Config
        run: |
          temporal-server validate-dynamic-config \
            config/dynamicconfig/*.yaml

GitLab CI

validate-config:
  image: temporalio/server:latest
  script:
    - temporal-server validate-dynamic-config config/dynamicconfig/*.yaml
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == "main"'

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

echo "Validating dynamic config..."
temporal-server validate-dynamic-config config/dynamicconfig/*.yaml

if [ $? -ne 0 ]; then
  echo "Dynamic config validation failed. Commit aborted."
  exit 1
fi

Makefile Integration

.PHONY: validate-config
validate-config:
	@echo "Validating dynamic configuration..."
	@temporal-server validate-dynamic-config config/dynamicconfig/*.yaml

.PHONY: validate-all
validate-all: validate-config
	@echo "Running all validations..."
	# Add other validation steps

Best Practices

1. Validate Before Deploy: Always validate configs before deploying to production
2. Automate Validation: Add validation to CI/CD pipelines
3. Version Control: Keep dynamic configs in version control
4. Comment Changes: Document why specific values were chosen
5. Test Changes: Test config changes in development first
6. Regular Review: Periodically review and update configurations

Troubleshooting

File Not Found

$ temporal-server validate-dynamic-config config.yaml
open config.yaml: no such file or directory

Verify the file path is correct and the file exists.

Permission Denied

$ temporal-server validate-dynamic-config /etc/temporal/config.yaml
open /etc/temporal/config.yaml: permission denied

Ensure you have read permissions for the file.

YAML Syntax Error

$ temporal-server validate-dynamic-config config.yaml
config.yaml
  error: yaml: line 5: found unexpected end of stream

Fix YAML syntax errors. Common issues:

• Missing colons
• Incorrect indentation
• Unclosed quotes
• Invalid characters

Examples

Validate Development Config

temporal-server validate-dynamic-config config/dynamicconfig/development.yaml

Validate All Environment Configs

temporal-server validate-dynamic-config \
  config/dynamicconfig/development.yaml \
  config/dynamicconfig/staging.yaml \
  config/dynamicconfig/production.yaml

Validate with Wildcard

temporal-server validate-dynamic-config config/dynamicconfig/*.yaml

Validate and Show Only Errors

temporal-server validate-dynamic-config config/dynamicconfig/*.yaml 2>&1 | grep -i error

See Also

• Dynamic Configuration Reference
• temporal-server start
• temporal-server render-config
• Server Configuration