feat(kms): add KMS region override configuration

[crypt0fairy]

Add KMS Region Override Configuration

Summary

Adds support for a dedicated KMS region configuration (AWS_KMS_REGION) that can override the controller's default AWS region for KMS operations. This allows users to specify a different AWS region for KMS keys while using another region for general AWS services.

Motivation

Users may need to store their KMS keys in a specific AWS region that differs from the region where their other AWS resources (DynamoDB, S3, etc.) are located.

Previously, KMS operations used the same region as other AWS services (AWS_REGION). This change adds an optional override to specify a separate region specifically for KMS.

Changes

Configuration

Added:

• CONTROLLER_DISPERSER_KMS_REGION environment variable
• --controller-disperser-kms-region CLI flag
• KMSRegion field in DispersalRequestSignerConfig struct

Region Resolution Logic:

When creating KMS client:
  If KMSRegion is specified → use it for KMS operations
  Else → use Region for KMS operations (existing behavior)

Files Modified

1. api/clients/v2/dispersal_request_signer.go

   • Added KMSRegion optional field to DispersalRequestSignerConfig
   • Updated NewKMSDispersalRequestSigner to check KMSRegion first, fallback to Region
   • Updated error messages to include the actual region being used

2. disperser/cmd/controller/flags/flags.go

   • Added DisperserKMSRegionFlag for KMS region override
   • Added flag to optional flags list

3. disperser/cmd/controller/config.go

   • Wired new KMSRegion flag to DispersalRequestSignerConfig

4. api/clients/v2/dispersal_request_signer_test.go

   • Added TestKMSRegionOverride - Verifies KMSRegion overrides Region
   • Added TestKMSRegionDefault - Verifies default behavior when KMSRegion is not set

Usage Examples

Example 1: Using Different Regions for KMS and Other Services

# General AWS resources in us-east-1
export AWS_REGION=us-east-1

# KMS key stored in us-west-2
export CONTROLLER_DISPERSER_KMS_REGION=us-west-2
export CONTROLLER_DISPERSER_KMS_KEY_ID=arn:aws:kms:us-west-2:...

# Start controller
./controller --config controller.yaml

Example 2: Using Same Region (Default Behavior)

# Both AWS resources and KMS in us-east-1
export AWS_REGION=us-east-1
export CONTROLLER_DISPERSER_KMS_KEY_ID=arn:aws:kms:us-east-1:...

# No need to set CONTROLLER_DISPERSER_KMS_REGION
# KMS will automatically use AWS_REGION

# Start controller
./controller --config controller.yaml

Testing

Unit Tests

✅ All tests pass

• TestKMSRegionOverride - Verifies KMSRegion overrides Region
• TestKMSRegionDefault - Verifies default behavior when KMSRegion is not set

Backward Compatibility

✅ Fully backward compatible

• No breaking changes
• Existing configurations continue to work unchanged
• New setting is optional
• Default behavior: KMS uses AWS_REGION when override is not specified

Configuration Reference

Environment Variable	CLI Flag	Default	Description
AWS_REGION	N/A (from AWS config)	Required	Default AWS region for all services
CONTROLLER_DISPERSER_KMS_REGION	--controller-disperser-kms-region	Empty (uses AWS_REGION)	Override AWS region specifically for KMS operations
CONTROLLER_DISPERSER_KMS_KEY_ID	--controller-disperser-kms-key-id	Optional	KMS key ID for signing

Implementation Details

The implementation is straightforward:

// Determine which region to use for KMS operations
kmsRegion := config.Region
if config.KMSRegion != "" {
    kmsRegion = config.KMSRegion
}

// Create KMS client using the determined region

[codecov]

Codecov Report

❌ Patch coverage is 85.71429% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 39.45%. Comparing base (1f9bf9c) to head (5f42567).

Files with missing lines	Patch %	Lines
api/clients/v2/dispersal_request_signer.go	85.71%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #2478   +/-   ##
=======================================
  Coverage   39.44%   39.45%           
=======================================
  Files         552      552           
  Lines       51035    51038    +3     
=======================================
+ Hits        20133    20135    +2     
- Misses      28355    28358    +3     
+ Partials     2547     2545    -2     

Flag	Coverage Δ
litt-tests	32.99% <ø> (ø)
unit-tests	40.30% <85.71%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.