v21.3.0

Migration Notes

Please complete the following steps before upgrading Cumulus.

• CUMULUS-4459 New index added to the granules table to improve Dashboard performance

  • The fix introduced in CUMULUS-4459 requires a manual database update in the production environment.
    This step ensures the new index is created successfully, even in the unlikely event that the database-migration
    Lambda function did not complete the index creation before timing out.

  Please follow the standard procedures for running a production database migration, and execute the following SQL to create the index:

  CREATE INDEX CONCURRENTLY IF NOT EXISTS granules_collection_updated_idx ON granules (collection_cumulus_id, updated_at);
  

• CUMULUS-4313

  • Update Async Operation container to new version 55, cumuluss/async-operation:55. Users should update their references to async-operation with the new version.
  • Updated lerna dev-dependency to v8
  • Added CI shim script to allow lerna publish to work with tar pinned to ^7.5.3

Notable Changes

• CUMULUS-4459
  • Added new index to the granules table to improve Dashboard performance.
• CUMULUS-4446
  • Updated all node lambdas/Core build environments to utilize node v22.
  • Updated cma-js dependency to 2.4.0
• CUMULUS-3574
  • Granule file writes are now atomic. Previously, some granule files could be written even if others failed;
    now, if any granule file fails, none are written.
• CUMULUS-4272
  • The tf-modules/cumulus-rds-tf module now allows specifying an existing security group.
    This enhancement enables DAACs to migrate their existing RDS deployments to Aurora while
    reusing their existing security group, ensuring compatibility with existing
    data-persistence-tf and cumulus-tf modules.

Added

• CUMULUS-4300
  • Added a new rate-limited consumer class in the Node/TypeScript code to control how many executions are submitted per second across multiple queues - helping improve and smooth out step function submission.
    • Created a new ConsumerRateLimited class that is able to submit executions at a specified, even maximum rate as defined by rateLimitPerSecond. In order to enforce this limit across all throttled queues, this class accepts a list of queue URLs instead of a single throttled queue URL. Unlike its non-rate-limited counterpart, to simplify configuration, this new class does not limit the number of messages staged - that can now be indirectly controlled by increasing or decreasing the rate.
    • Added calls to the new ConsumerRateLimited class in sf-starter.js in the handleRateLimitedEvent function. This uses the incrementAndDispatch dispatcher.
    • Added a new Lambda named "sqs2sfThrottleRateLimited" that can be called with a list of queueURLs in an EventBridge scheduled rule.
    • Added sqs2sfThrottleRateLimited_lambda_function_arn outputs to both ingest and cumulus modules.
• CUMULUS-4411
  • The tf-modules/cumulus-rds-tf module now supports enabling RDS slow query logging in CloudWatch.
    By setting db_log_min_duration_ms to a positive value (in milliseconds) and enabled_cloudwatch_logs_exports
    to ["postgresql"], RDS will log and export any database queries that take longer than that threshold.
    The module also configures the required RDS extensions and parameters necessary for slow query instrumentation.

Changed

• CSD-82
  • Updated /workflows/list endpoint to accept countOnly, prefix, infix, fields, limit, and order query string params
• CUMULUS-4374
  • Updated example python Lambdas to utilize uv as their package manager. This change removes references to
    pipenv. Developers should migrate to using uv to manage python dependencies and virtual envs which may
    require reinstalling python libraries. This change also updates the names of the example python task services
    because of a deployment race condition. These services are only used for integration tests.
• CUMULUS-4387
  • Updated linting scripts to include ruff and mypy and enable lint rules in repo level
    pyproject.toml file.
• CUMULUS-4406
  • Changed the limit variable inside the pdr-status-check task from an input variable to a config variable
• CUMULUS-4430
  • Updated GitHub Actions to run ruff linting on PRs.
  • Updated GitHub Actions to run eslint, markdownlint, and npm-package-json-lint on PRs.
• CUMULUS-4433
  • Adds pre-commit config and hooks to the repository. Developers are encouraged to install pre-commit and read
    the pre-commit setup docs to ensure they have the correct setup.
• CUMULUS-4438
  • Made min_capacity and max_capacity configurable in example/rds-cluster-tf
  • Made archive_api_users configurable in example/cumulus-tf
• CSD-61
  • Updated writeGranuleFromApi() endpoint to allow createdAt and updatedAt fields to be null.
• CUMULUS-4436
  • Created new documentation files for language best practices docs/development/python-best-practices.md and docs/development/typescript-best-practices.md.
  • Updated documentation file docs/development/quality-and-coverage.md to be more repo wide and reference language best practices.
  • Updated docs/adding-a-task.md to include instructions and expectations when adding a task.
• OTHER
  • Corrected misspelling in README.md related to installing uv.
  • Added override for tar in package.json.

Fixed

• CUMULUS-4486
  • Fixed a small bug with rulesHelpers in which rule.rule.meta.allowProviderMismatchOnRuleFilter was erroring due to
    database validation errors to instead refer to rule.meta.allowProviderMismatchOnRuleFilter
  • Added allowProviderMismatchOnRuleFilter to the meta field of rules in /api/lib/schemass
• CUMULUS-4458
  • Fixed a small bug with message_consumer lambda env and function variable names to match so the lambda env var allowProviderMismatchOnRuleFilter can be properly used when set

v21.3.1-alpha.0

Release v21.3.1-alpha.0

Release for Cumulus Dashboard Cypress testing using localApi.

v21.2.0

Migration Notes

• This release updates all core integration deployments to target cumulus-message-adapter v1.5.0. It is suggested that users update their deployment to utilize the updated CMA. Updates are not required for compatibility in custom lambdas.

Notable Changes

• CUMULUS-3574

  • Granule file writes are now atomic. Previously, some granule files could be written even if others failed;
    now, if any granule file fails, none are written.

• CUMULUS-4124
  When these changes are deployed, if no action is taken to reconfigure the cron, it will run once per day in the early morning, archiving

  • 100k granules
  • 100k executions
  • that are more than 1 year old.

  Being archived changes nothing about the record except to set a boolean flag (archived=true). this behavior can be reconfigured or turned off entirely. see features/record_archival.md for more details.

• CUMULUS-4272

  • The tf-modules/cumulus-rds-tf module now allows specifying an existing security group.
    This enhancement enables DAACs to migrate their existing RDS deployments to Aurora while
    reusing their existing security group, ensuring compatibility with existing
    data-persistence-tf and cumulus-tf modules.

Added

• CUMULUS-4032
  • Added S3 jitter functionality to prevent AWS S3 SlowDown errors during high-concurrency operations
  • Added sync_granule_s3_jitter_max_ms Terraform variable to configure random jitter delay (0-59000ms) for SyncGranule task
  • S3 operations in @cumulus/aws-client now support optional jitter via S3_JITTER_MAX_MS environment variable
  • Jitter is applied to: headObject, putObject, copyObject, getObject, downloadS3File, promiseS3Upload, and multipartCopyObject
• CUMULUS-4124
  • Add api endpoint granules/archive to archive granules
  • Add api endpoint executions/archive to archive executions
  • Task lambda to call above api endpoints with configuration
  • Add cron scheduler to call above endpoints and archive old records
• CUMULUS-4272
  • Added input_security_group_id variable to tf-modules/cumulus-rds-tf module to allow
    specifying an existing security group when creating or restoring an Aurora PostgreSQL RDS cluster.
• CUMULUS-4354
  • Added an optional terraform-configurable lambda level env variable allow_provider_mismatch_on_rule_filter to message-consumer and sqs-message-consumer to check
    whether to consider rule/message provider mismatches
  • Added a rule.meta.allowProviderMismatchOnRuleFilter check to filterRulesByRuleParams as a rule-level fallback to check whether to consider rule/message provider mismatches for the specific rule
  • (Small note as of 12-17-2025): There is a Cumulus-side bug with this in the way terraform and lambda reads the environment variable, so users will need to set allow_provider_mismatch_on_rule_filter = true in the appropriate message-consumer's lambda environment variables in the AWS console for this to work, this has been fixed in CUMULUS-4458 and released in the future)

Changed

• CUMULUS-3574
  • Updated @cumulus/api/lib/writeRecords/write-granules to write all granule files in a single batch.
• CUMULUS-4188
  • Updated example/cumulus-tf/orca.tf to use v10.1.5
• CUMULUS-4244
  • Improve logging for Ingest Granules
    • Upgrade log level from debug to error for 403/401 errors
    • Add detailed error context (status code, error type, bucket, key)
    • Add actionable remediation suggestions for permission issues
    • Add try-catch in write-granules.js for better error context
• CUMULUS-4271
  • Updated release instructions to include schema updates
• CUMULUS-4155
  • Update Cumulus integration tests to utilize:
    • Cumulus Message Adapter: v2.0.5
    • Cumulus Message Adapter-py: v2.4.0
    • Cumulus Process: 1.6.0
  • Update all Python dependencies to use boto >=1.40.29
  • Update all Core integration lambdas to use Python 3.12
  • Update external CNM lambdas to run on Java 21 in integration
• CUMULUS-4191
  • Updated messageConsumer and sqsMessageConsumer Lambdas to apply rule filtering
    based on the provider from the record message.
  • Updated messageConsumer lambda handler to async/await style
• CUMULUS-4200
  • updated metrics_es_host terraform variable description and validation
  • Users should ensure that the metrics_es_host does not include https://
• CUMULUS-4252
  • Fixed @aws-client/S3 unit test failures caused by stricter validation introduced in
    @aws-sdk/lib-storage@3.896.0
• CUMULUS-4242
  • Updated @cumulus/lizards-api-client to include configured provider via lzards_provider env var in all queries
  • Updated LZARDS integration tests to work with updated API client query requirements for API version 1.5.25
• CUMULUS-4232
  • Update MoveGranules CUMULUS-4078 behavior such that it no longer defaults to throwing on an orphan (S3 file record not in database) situation when checking cross-collection file collisions.
  • Added configuration crossCollectionThrowOnObjectNotFound to allow setting MoveGranules to fail in a collision/orphan situation
  • Added collectionCheckRetryCount to allow configuration of the retry count for the MoveGranules crossCollection lookup
• CUMULUS-4254
  • Moved @cumulus/api/lib/utils.errorify function to @cumulus/errors and updated it to remove circular reference
  • Used errorify instead of JSON.stringify for AWS errors
  • Added required collection field to lzards api request in LzardsBackupSpec integration test to fix the bug in CUMULUS-4242

Fixed

• CUMULUS-4346
  • Updated package overrides for dev env to use glob "^11.1.0" to address reported CVE
• CUMULUS-4279
  • Updated the ProvisionPostgresDatabase Lambda to grant create and usage privileges
    on the public schema of the user database to the database user.
    This change is required because, starting with PostgreSQL 15, new databases assign ownership
    of the public schema to the pg_database_owner role. Existing clusters upgraded from versions
    prior to v15 preserve the previous ownership of the public schema.
• CUMULUS-4275
  • Fixed unit tests broken by updated HTTP error messages in got
• CUMULUS-4325
  • Fixed ECHO10 XML DataGranule element ordering to comply with CMR XSD schema requirements
    • Updated @cumulus/cmrjs to use Map for guaranteed element ordering in
      updateEcho10XMLGranuleUrAndGranuleIdentifier
    • Modified integration test helpers to use js2xmlparser instead of xml2js.Builder
      for correct XML serialization
    • Added unit tests to verify ECHO10 schema element ordering
    • Resolves CMR validation error when ProducerGranuleId appears out of sequence

v20.3.2

[v20.3.2] 2025-12-04 [Backport]

Please note changes in 20.3.2 may not yet be released in future versions, as this is a backport and patch release on the 20.3.x series of releases. Updates that are included in the future will have a corresponding CHANGELOG entry in future releases.

Added

• CUMULUS-4354
  • Added an optional terraform-configurable lambda level env variable allow_provider_mismatch_on_rule_filter to message-consumer and sqs-message-consumer to check
    whether to consider rule/message provider mismatches
  • Added a rule.meta.allowProviderMismatchOnRuleFilter check to filterRulesByRuleParams as a rule-level fallback to check
    whether to consider rule/message provider mismatches for the specific rule
  • (Small note as of 12-17-2025): There is a Cumulus-side bug with this in the way terraform and lambda reads the environment variable, so users will need to set allow_provider_mismatch_on_rule_filter = true in the appropriate message-consumer's lambda environment variables in the AWS console for this to work, this has been fixed in CUMULUS-4458 and will be included in a future release)

Changed

• CUMULUS-4272
  • The tf-modules/cumulus-rds-tf module now allows specifying an existing security group.
    This enhancement enables DAACs to migrate their existing RDS deployments to Aurora while
    reusing their existing security group, ensuring compatibility with existing
    data-persistence-tf and cumulus-tf modules.

Fixed

• CUMULUS-4279
  • Updated the ProvisionPostgresDatabase Lambda to grant create and usage privileges
    on the public schema of the user database to the database user.
    This change is required because, starting with PostgreSQL 15, new databases assign ownership
    of the public schema to the pg_database_owner role. Existing clusters upgraded from versions
    prior to v15 preserve the previous ownership of the public schema.
• CUMULUS-4275
  • Fixed unit tests broken by updated HTTP error messages in got

v20.2.3

[v20.2.3] 2025-12-02

Notable Changes

• CUMULUS-4272
  • The tf-modules/cumulus-rds-tf module now allows specifying an existing security group.
    This enhancement enables DAACs to migrate their existing RDS deployments to Aurora while
    reusing their existing security group, ensuring compatibility with existing
    data-persistence-tf and cumulus-tf modules.

Fixed

• CUMULUS-4279
  • Updated the ProvisionPostgresDatabase Lambda to grant create and usage privileges
    on the public schema of the user database to the database user.
    This change is required because, starting with PostgreSQL 15, new databases assign ownership
    of the public schema to the pg_database_owner role. Existing clusters upgraded from versions
    prior to v15 preserve the previous ownership of the public schema.
• CUMULUS-4275
  • Fixed unit tests broken by updated HTTP error messages in got

Added

• CUMULUS-4272

  • Added input_security_group_id variable to tf-modules/cumulus-rds-tf module to allow
    specifying an existing security group when creating or restoring an Aurora PostgreSQL RDS cluster.

• CUMULUS-4354

  • Added an optional terraform-configurable lambda level env variable allow_provider_mismatch_on_rule_filter to message-consumer and sqs-message-consumer to check
    whether to consider rule/message provider mismatches
  • Added a rule.meta.allowProviderMismatchOnRuleFilter check to filterRulesByRuleParams as a rule-level fallback to check
    whether to consider rule/message provider mismatches for the specific rule
  • (Small note as of 12-17-2025): There is a Cumulus-side bug with this in the way terraform and lambda reads the environment variable, so users will need to set allow_provider_mismatch_on_rule_filter = true in the appropriate message-consumer's lambda environment variables in the AWS console for this to work, this has been fixed in CUMULUS-4458 and will be included in a future release)

v21.0.0-echo10

[v21.0.0-echo10] 2025-11-19

Migration Notes

Please note that this release is an out-of-cycle release, you cannot upgrade from it to the next release in the v21.0.x release series due to CUMULUS-4325 not being present in v21.0.1+. Upgrades from this release should be done with care to ensure the target release includes these updates, either to a release following 21.1.0 or a release in 21.0.x series that includes CUMULUS-4325.

v21.0.0 documentation should be used for this release.

Fixed

• CUMULUS-4356
  • Pin build-related lerna transitive dependency make-fetch-happen to 14.0.3 pending lerna upgrade/refactor
  • Pin npm-packlist/read-package-json glob dependency to 8.1.0 pending lerna upgrade/refactor
• CUMULUS-4325
  • Fixed ECHO10 XML DataGranule element ordering to comply with CMR XSD schema requirements
    • Updated @cumulus/cmrjs to use Map for guaranteed element ordering in
      updateEcho10XMLGranuleUrAndGranuleIdentifier
    • Modified integration test helpers to use js2xmlparser instead of xml2js.Builder
      for correct XML serialization
    • Added unit tests to verify ECHO10 schema element ordering
    • Resolves CMR validation error when ProducerGranuleId appears out of sequence
• CUMULUS-4275
  • Fixed unit tests broken by updated HTTP error messages in got
• CUMULUS-4242
  • Updated @cumulus/lizards-api-client to include configured provider via lzards_provider env var in all queries
  • Updated LZARDS integration tests to work with updated API client query requirements for API version 1.5.25

(DEPRECATED) v21.1.0

[v21.1.0] 2025-10-22

Migration Notes

• This release updates all core integration deployments to target cumulus-message-adapter v1.5.0. It is suggested that users update their deployment to utilize the updated CMA. Updates are not required for compatibility in custom lambdas.

Notable Changes

• CUMULUS-4124
  When these changes are deployed, if no action is taken to reconfigure the cron, it will run once per day in the early morning, archiving

  • 100k granules
  • 100k executions
  • that are more than 1 year old.

  Being archived changes nothing about the record except to set a boolean flag (archived=true). this behavior can be reconfigured or turned off entirely. see features/record_archival.md for more details.

Added

• CUMULUS-4124

  • Add api endpoint granules/archive to archive granules
  • Add api endpoint executions/archive to archive executions
  • Task lambda to call above api endpoints with configuration
  • Add cron scheduler to call above endpoints and archive old records

• CUMULUS-4032

  • Added S3 jitter functionality to prevent AWS S3 SlowDown errors during high-concurrency operations
  • Added sync_granule_s3_jitter_max_ms Terraform variable to configure random jitter delay (0-59000ms) for SyncGranule task
  • S3 operations in @cumulus/aws-client now support optional jitter via S3_JITTER_MAX_MS environment variable
  • Jitter is applied to: headObject, putObject, copyObject, getObject, downloadS3File, promiseS3Upload, and multipartCopyObject

Changed

• CUMULUS-4244

  • Improve logging for Ingest Granules
    • Upgrade log level from debug to error for 403/401 errors
    • Add detailed error context (status code, error type, bucket, key)
    • Add actionable remediation suggestions for permission issues
    • Add try-catch in write-granules.js for better error context

• CUMULUS-4155

  • Update Cumulus integration tests to utilize:
    • Cumulus Message Adapter: v2.0.5
    • Cumulus Message Adapter-py: v2.4.0
    • Cumulus Process: 1.6.0
  • Update all Python dependencies to use boto >=1.40.29
  • Update all Core integration lambdas to use Python 3.12
  • Update external CNM lambdas to run on Java 21 in integration

• CUMULUS-4191

  • Updated messageConsumer and sqsMessageConsumer Lambdas to apply rule filtering
    based on the provider from the record message.
  • Updated messageConsumer lambda handler to async/await style

• CUMULUS-4200

  • updated metrics_es_host terraform variable description and validation
  • Users should ensure that the metrics_es_host does not include https://

• CUMULUS-4242

  • Skipped lzards api response assertions from lzards integration tests due to lzards api changes

• CUMULUS-4252

  • Fixed @aws-client/S3 unit test failures caused by stricter validation introduced in
    @aws-sdk/lib-storage@3.896.0

• CUMULUS-4242

  • Updated @cumulus/lizards-api-client to include configured provider via lzards_provider env var in all queries
  • Updated LZARDS integration tests to work with updated API client query requirements for API version 1.5.25

• CUMULUS-4232

  • Update MoveGranules CUMULUS-4078 behavior such that it no longer defaults to throwing on an orphan (S3 file record not in database) situation when checking cross-collection file collisions.
  • Added configuration crossCollectionThrowOnObjectNotFound to allow setting MoveGranules to fail in a collision/orphan situation
  • Added collectionCheckRetryCount to allow configuration of the retry count for the MoveGranules crossCollection lookup

• CUMULUS-4254

  • Moved @cumulus/api/lib/utils.errorify function to @cumulus/errors and updated it to remove circular reference
  • Used errorify instead of JSON.stringify for AWS errors
  • Added required collection field to lzards api request in LzardsBackupSpec integration test to fix the bug in CUMULUS-4242

v21.0.1

[v21.0.1] 2025-10-16

Changed

• CUMULUS-4191

  • Updated messageConsumer and sqsMessageConsumer Lambdas to apply rule filtering
    based on the provider from the record message.
  • Updated messageConsumer lambda handler to async/await style

• CUMULUS-4242

  • Updated @cumulus/lizards-api-client to include configured provider via lzards_provider env var in all queries
  • Updated LZARDS integration tests to work with updated API client query requirements for API version 1.5.25

• CUMULUS-4252

  • Fixed @aws-client/S3 unit test failures caused by stricter validation introduced in
    @aws-sdk/lib-storage@3.896.0

• CUMULUS-4254

  • Moved @cumulus/api/lib/utils.errorify function to @cumulus/errors and updated it to remove circular reference
  • Used errorify instead of JSON.stringify for AWS errors
  • Added required collection field to lzards api request in LzardsBackupSpec integration test to fix the bug in CUMULUS-4242

v20.3.1

[v20.3.1] 2025-10-14

Changed

• CUMULUS-4191

  • Updated messageConsumer and sqsMessageConsumer Lambdas to apply rule filtering
    based on the provider from the record message.
  • Updated messageConsumer lambda handler to async/await style

• CUMULUS-4242

  • Updated @cumulus/lizards-api-client to include configured provider via lzards_provider env var in all queries
  • Updated LZARDS integration tests to work with updated API client query requirements for API version 1.5.25

• CUMULUS-4252

  • Fixed @aws-client/S3 unit test failures caused by stricter validation introduced in
    @aws-sdk/lib-storage@3.896.0

• CUMULUS-4254

  • Moved @cumulus/api/lib/utils.errorify function to @cumulus/errors and updated it to remove circular reference
  • Used errorify instead of JSON.stringify for AWS errors
  • Added required collection field to lzards api request in LzardsBackupSpec integration test to fix the bug in CUMULUS-4242

v20.2.2

[v20.2.2] 2025-10-08

Changed

• CUMULUS-4191

  • Updated messageConsumer and sqsMessageConsumer Lambdas to apply rule filtering
    based on the provider from the record message.
  • Updated messageConsumer lambda handler to async/await style

• CUMULUS-4242

  • Updated @cumulus/lizards-api-client to include configured provider via lzards_provider env var in all queries
  • Updated LZARDS integration tests to work with updated API client query requirements for API version 1.5.25

• CUMULUS-4252

  • Fixed @aws-client/S3 unit test failures caused by stricter validation introduced in
    @aws-sdk/lib-storage@3.896.0

• CUMULUS-4254

  • Moved @cumulus/api/lib/utils.errorify function to @cumulus/errors and updated it to remove circular reference
  • Used errorify instead of JSON.stringify for AWS errors
  • Added required collection field to lzards api request in LzardsBackupSpec integration test to fix the bug in CUMULUS-4242