PSA/ee/docs/plans/2025-07-28-temporal-helm-chart-extraction.md

Temporal Worker Helm Chart Extraction Plan

Intro / Rationale

This plan outlines the extraction of temporal worker components from the main Alga PSA helm chart (helm/) into a separate, dedicated helm chart (ee/helm/temporal-worker/). This separation will:

• Improve modularity and maintainability by isolating temporal-specific deployments
• Enable independent versioning and deployment of temporal workers
• Simplify the main helm chart by removing optional enterprise components
• Allow for easier testing and development of temporal worker features

Success Criteria:

• Temporal worker components are fully extracted into a separate helm chart
• Main chart can optionally depend on the temporal chart via subchart mechanism
• Both charts deploy successfully with existing configurations
• No breaking changes to existing deployments

Phased Implementation Checklist

Phase 1: Create New Chart Structure

• Create directory structure at ee/helm/temporal-worker/
• Create Chart.yaml with appropriate metadata
  • Set chart name to temporal-worker
  • Set version to 0.1.0
  • Add description and maintainer information
• Create initial values.yaml with temporal-specific values
• Create templates/ directory
• Add .helmignore file

Phase 2: Extract Temporal Components

• Copy all files from helm/templates/temporal-worker/ to ee/helm/temporal-worker/templates/
  • configmap.yaml
  • deployment.yaml
  • hpa.yaml
  • pdb.yaml
  • secrets.yaml
  • service.yaml
  • serviceaccount.yaml
• Update template references to use local chart context
  • Replace .Values.temporalWorker with .Values in all templates
  • Update any global value references
• Extract temporal-specific helpers to ee/helm/temporal-worker/templates/_helpers.tpl

Phase 3: Update Values Structure

• Extract temporalWorker section from main helm/values.yaml
• Create comprehensive ee/helm/temporal-worker/values.yaml
  • Remove the temporalWorker parent key
  • Ensure all nested values are at root level
• Add any missing default values
• Document all configurable values with comments

Phase 4: Clean Up Main Chart

• Remove helm/templates/temporal-worker/ directory
• Remove temporalWorker section from helm/values.yaml
• Add optional dependency in helm/Chart.yaml:

  dependencies:
    - name: temporal-worker
      version: "0.1.0"
      repository: "file://../ee/helm/temporal-worker"
      condition: temporal-worker.enabled
  

• Update any documentation references

Phase 5: Integration Testing

• Test standalone temporal chart deployment:

  helm install temporal-test ee/helm/temporal-worker/ -f test-values.yaml
  

• Test main chart with temporal subchart disabled
• Test main chart with temporal subchart enabled
• Verify all resources are created correctly
• Check service connectivity and configuration

Phase 6: Documentation and Finalization

• Create ee/helm/temporal-worker/README.md with:
  • Installation instructions
  • Configuration options
  • Example values files
• Update main helm chart README if needed
• Create example values files for common scenarios
• Add upgrade notes for existing deployments

Background Details / Investigation / Implementation Advice

Current Structure

The temporal worker components are currently embedded in the main helm chart under helm/templates/temporal-worker/. The configuration uses a conditional flag .Values.temporalWorker.enabled to control deployment.

Key Considerations

1. Namespace Handling: The temporal worker may need to communicate with services in different namespaces. Ensure service discovery works correctly.

2. Value References: When extracting, be careful with references to global values or other chart components. These will need to be passed explicitly or configured separately.

3. Secret Management: The temporal worker uses both Vault and local secrets. Ensure the secret provider configuration is properly isolated.

4. Image Registry: The worker uses a private Harbor registry. Ensure image pull secrets are correctly configured in the new chart.

5. Resource Naming: Consider prefixing resources with the release name to avoid conflicts when both charts are deployed in the same namespace.

Testing Approach

1. Create a test values file that mirrors production configuration
2. Deploy in a test namespace first
3. Verify all pods start successfully
4. Check logs for configuration errors
5. Test actual workflow execution if possible

Rollback Strategy

If issues arise during migration:

1. The original chart remains unchanged until Phase 4
2. Can quickly revert by not using the subchart dependency
3. Keep backup of original temporal-worker templates until fully validated

Implementer's Scratch Pad

Notes and Observations

Issues Encountered and Resolutions

Deviations from Plan

Test Results

Questions for Review

Commands Used

# Example commands for reference
# helm dep update helm/
# helm template temporal-worker ee/helm/temporal-worker/
# kubectl get all -l app.kubernetes.io/name=temporal-worker