This is an automated email from the ASF dual-hosted git repository.
vincbeck pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new 6b90003fe27 Document override semantics for EcsRunTaskOperator (#73860)
6b90003fe27 is described below
commit 6b90003fe27ab9cd0e20d5f689c80fdb8889ef18
Author: Meghana Gangarapu <[email protected]>
AuthorDate: Tue Sep 29 10:47:26 2026 -0500
Document override semantics for EcsRunTaskOperator (#73860)
The `overrides` argument is passed to the ECS RunTask API unchanged, and
that API does not treat every container override field the same way:
`environment` is merged into the environment the task definition already
defines, while `command`, `cpu`, `memory`, `memoryReservation`,
`resourceRequirements` and `environmentFiles` replace the task
definition's value.
---
providers/amazon/docs/operators/ecs.rst | 35 ++++++++++++++++++++++
.../airflow/providers/amazon/aws/operators/ecs.py | 3 ++
2 files changed, 38 insertions(+)
diff --git a/providers/amazon/docs/operators/ecs.rst
b/providers/amazon/docs/operators/ecs.rst
index 1f5bb72e98b..ee46902373b 100644
--- a/providers/amazon/docs/operators/ecs.rst
+++ b/providers/amazon/docs/operators/ecs.rst
@@ -138,6 +138,41 @@ The parameters you need to configure for this Operator
will depend upon which ``
:start-after: [START howto_operator_ecs]
:end-before: [END howto_operator_ecs]
+Overriding the task definition
+""""""""""""""""""""""""""""""
+
+``overrides`` is passed to the ECS ``RunTask`` API unchanged, so it follows
that API's rules.
+Those rules are not the same for every field: within a container override,
``environment`` is
+merged into the environment the task definition already defines, while the
other fields replace
+the task definition's value.
+
+.. code-block:: python
+
+ overrides = {
+ "containerOverrides": [
+ {
+ "name": container_name,
+ "command": ["run", "--mode", "backfill"],
+ "environment": [{"name": "MODE", "value": "backfill"}],
+ },
+ ],
+ }
+
+For the container above, ``command`` replaces the task definition's command
outright, while
+``MODE`` is added to (or overrides) the variables the task definition already
sets. Every other
+variable defined in the task definition is still passed to the container.
+
+.. note::
+
+ ``environment`` cannot be used to *unset* a variable. A variable that is
no longer wanted has
+ to be removed from the task definition itself: omitting it from
``overrides`` leaves the task
+ definition's value in place.
+
+``cpu``, ``memory``, ``memoryReservation``, ``resourceRequirements`` and
``environmentFiles``
+all replace the task definition's value rather than adding to it. See
+`ContainerOverride
<https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerOverride.html>`__
+in the Amazon ECS API reference for the full list of fields.
+
Stream logs to AWS CloudWatch
"""""""""""""""""""""""""""""
diff --git a/providers/amazon/src/airflow/providers/amazon/aws/operators/ecs.py
b/providers/amazon/src/airflow/providers/amazon/aws/operators/ecs.py
index be6c171a56a..aad4678df5a 100644
--- a/providers/amazon/src/airflow/providers/amazon/aws/operators/ecs.py
+++ b/providers/amazon/src/airflow/providers/amazon/aws/operators/ecs.py
@@ -345,6 +345,9 @@ class EcsRunTaskOperator(EcsBaseOperator):
:param cluster: the cluster name on Elastic Container Service
:param overrides: the same parameter that boto3 will receive (templated):
https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ecs.html#ECS.Client.run_task
+ Note that ``containerOverrides[].environment`` is merged into the
environment defined by
+ the task definition, while the other container override fields replace
the task
+ definition's value. See :ref:`howto/operator:EcsRunTaskOperator`.
:param aws_conn_id: connection id of AWS credentials / region name. If
None,
credential boto3 strategy will be used
(https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html).
