企业官网建设流程全解析

Apache Airflow Amazon Provider 配置参考：airflow.cfg 配置项与环境变量完全指南

【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow

Apache Airflow 的 Amazon Provider（apache-airflow-providers-amazon）是 Airflow 生态中规模最大、集成最广的提供方之一，覆盖 S3、Redshift、EMR、ECS、Batch、Lambda 等数十个 AWS 服务。本指南围绕 providers/amazon/docs/configurations-ref.rst 这份 Configuration Reference 展开，系统讲解该 Provider 在airflow.cfg文件与环境变量中可用的全部配置项：从[aws]通用集成设置，到[aws_batch_executor]、[aws_lambda_executor]、[aws_ecs_executor]三大云原生执行器的专属配置，再到[aws_auth_manager]认证管理器配置。读完本文，你将能够准确理解每个配置项的类型、默认值、适用场景，并掌握AIRFLOW__SECTION__OPTION环境变量命名规则与敏感配置的三段式管理方式。

配置参考页面从何而来：一份由模板与数据自动生成的文档

configurations-ref.rst本身并不直接书写配置内容，而是通过 Sphinx 的.. include::指令引入两个共享模板，再借助 Jinja 渲染上下文config_ctx在文档构建时生成完整的配置清单：

• providers/amazon/docs/configurations-ref.rst：页面入口，说明"本页面列出 Amazon Provider 所有可在airflow.cfg或环境变量中设置的配置"；
• devel-common/src/sphinx_exts/includes/providers-configurations-ref.rst：提供 "Configuration Reference" 页面标题与说明性导语；
• devel-common/src/sphinx_exts/includes/sections-and-options.rst：核心渲染模板，遍历每个配置 section 与 option，输出完整的参考条目；
• devel-common/src/docs/provider_conf.py：构建时通过retrieve_configuration_description()与get_configs_and_deprecations()组装config_ctx，注入configs、deprecated_options与package_name三个变量。

真正承载配置数据的，是 Provider 的元数据文件 providers/amazon/src/airflow/providers/amazon/get_provider_info.py（其 YAML 源为 providers/amazon/provider.yaml）。该文件中名为config的字段以嵌套字典的形式定义了 5 个配置 section，每个 section 内再以options字典定义各个配置项的description、type、default、example、version_added等元信息。文档构建时，模板逐条渲染这些元信息，最终形成你看到的 Configuration Reference 页面。

配置条目的通用结构：Type、Default 与环境变量

sections-and-options.rst模板定义了每个配置项条目的统一渲染格式，理解这套格式有助于你快速阅读参考文档与源码：

• versionadded：该配置项引入的 Provider 版本号（例如8.10、9.9.0）；
• 描述（description）：配置项的作用、是否必填、使用前提；
• Type：配置值的类型，Amazon Provider 中主要出现string、integer、boolean三种；
• Default：默认值，未设置时通常为None；
• Example：可直接套用的示例值；
• Environment Variable：对应的环境变量名；
• deprecated：废弃信息，标注废弃版本与迁移去向；
• seealso：相关参考链接。

环境变量命名规则与敏感配置的三段式覆盖

模板对环境变量的渲染体现了 Airflow 配置系统的重要约定。对于非敏感选项，仅生成一个环境变量：

AIRFLOW__{{ section_name | replace(".", "_") | upper }}__{{ option_name | upper }}

即AIRFLOW__前缀 + section 名 + option 名，全部转大写、点号替换为下划线。例如[aws_batch_executor]section 中的job_queue选项，其环境变量为AIRFLOW__AWS_BATCH_EXECUTOR__JOB_QUEUE。

而对于标记了sensitive的选项，模板会同时生成三个环境变量，提供"明文值 / 命令输出 / 密钥后端"三种取值方式：

AIRFLOW__SECTION__OPTION # 直接提供值 AIRFLOW__SECTION__OPTION_CMD # 通过执行命令获取值 AIRFLOW__SECTION__OPTION_SECRET # 从密钥后端（如 AWS Secrets Manager）获取值

_CMD变体适用于不希望明文落盘、而由命令动态产出的场景；_SECRET变体则对接 Airflow 的 Secrets Backend 机制。这是配置敏感信息（如认证密钥）时推荐的安全做法。

废弃选项（Deprecated Options）的呈现

模板在 section 末尾还会渲染deprecated_options：每个废弃条目标注since_version，若新配置项仍属于本 Provider，则给出指向新位置的交叉引用；否则注明该选项被移动至哪个 section/option。在实际使用中，遇到标注为 "(Deprecated)" 的配置项时应优先迁移到新名称。

[aws]：AWS 通用集成配置

[aws]section 描述为 "This section contains settings for Amazon Web Services (AWS) integration."，是 Amazon Provider 的基础配置区，包含 3 个选项：

session_factory：自定义 boto3 会话工厂

session_factory允许你传入自定义类来替代默认的boto3.session.Session创建流程，典型场景包括注入自定义凭证链、代理配置或 STS 会话逻辑。示例如下：

[aws] session_factory = my_company.aws.MyCustomSessionFactory

该机制与 AWS 连接（Connection）的 session factory 配置遥相呼应，详见 providers/amazon/docs/connections/aws.rst 中对aws:session-factory的说明。

cloudwatch_task_handler_json_serializer：日志序列化策略

该配置项控制 CloudWatch 任务日志处理器对非 JSON 对象的序列化行为。默认值json_serialize_legacy会将所有非 JSON 对象记录为null（datetime对象除外，会被 ISO 格式化）；可替换为airflow.providers.amazon.aws.log.cloudwatch_task_handler.json_serialize使用repr序列化，也可提供自定义序列化函数。自定义序列化器必须满足Callable[[Any], str | None]签名，其中返回None表示序列化为null。由于它位于日志路径上且可能伴随异常处理，官方特别强调序列化器内部必须优雅失败、不得抛出新异常。

s3_task_handler_acl_policy：跨账户日志的 ACL 控制

[aws]区最新引入的选项（9.34.0），为 S3 远程日志处理器上传的日志对象指定 ACL，例如bucket-owner-full-control。典型场景是跨账户远程日志：Airflow 运行在账户 A，日志桶归属账户 B 时，S3 默认将对象所有者设为写入方，导致桶所有者无法读取/管理日志；设置bucket-owner-full-control后桶所有者获得完全控制权。未设置时不发送 ACL，遵循桶的默认对象所有权配置。

[aws_batch_executor]：AWS Batch 执行器配置

[aws_batch_executor]section 仅在 Airflow[core]中配置了AwsBatchExecutor时生效（即executor = airflow.providers.amazon.aws.executors.batch.batch_executor.AwsBatchExecutor）。其实现位于 providers/amazon/src/airflow/providers/amazon/aws/executors/batch/batch_executor.py，执行器将每个 Airflow 任务作为 AWS Batch 作业提交运行。该 section 共 8 个选项：

一个最小可用的airflow.cfg示例：

[core] executor = airflow.providers.amazon.aws.executors.batch.batch_executor.AwsBatchExecutor [aws_batch_executor] conn_id = aws_default region_name = us-east-1 job_queue = airflow-batch-executor-job-queue job_definition = airflow-batch-executor-job-definition

submit_job_kwargs用于补充submit_job的参数，例如：

submit_job_kwargs = {"Tags": [{"Key": "key", "Value": "value"}]}

max_submit_job_attempts与check_health_on_startup是执行器层面的容错与自检开关；region_name为必填项，未配置时执行器将无法定位 Batch 服务端点。对应实现细节可在 providers/amazon/tests/unit/amazon/aws/executors/batch/test_batch_executor.py 中查看。

[aws_lambda_executor]：AWS Lambda 执行器配置

[aws_lambda_executor]section 仅在[core.executor]配置了AwsLambdaExecutor时生效（即executor = airflow.providers.amazon.aws.executors.aws_lambda.lambda_executor.AwsLambdaExecutor）。该执行器将 Airflow 任务作为 Lambda 函数调用执行，并通过 SQS 队列回收任务结果，实现近乎无服务器的执行方式。实现位于 providers/amazon/src/airflow/providers/amazon/aws/executors/aws_lambda/。该 section 共 9 个选项，全部在 9.9.0 引入：

一个最小可用的配置示例：

[core] executor = airflow.providers.amazon.aws.executors.aws_lambda.lambda_executor.AwsLambdaExecutor [aws_lambda_executor] conn_id = aws_default region_name = us-east-1 queue_url = airflow-lambda-executor-results-queue dead_letter_queue_url = airflow-lambda-executor-dlq function_name = airflow-lambda-executor-function

其中queue_url、dead_letter_queue_url、function_name三个为必填项：Lambda 函数负责执行任务，结果与异常分别写入结果队列和死信队列，执行器通过轮询这两个 SQS 队列获知任务终态。end_wait_timeout建议根据任务耗时设置合理上限，避免 Scheduler 关闭时无限阻塞。

[aws_ecs_executor]：Amazon ECS 执行器配置

[aws_ecs_executor]section 仅在[core]配置了AwsEcsExecutor时生效（即executor = airflow.providers.amazon.aws.executors.ecs.ecs_executor.AwsEcsExecutor）。执行器为每个任务在 ECS 上运行一个容器（支持 EC2 启动类型或 Fargate），容器通过接收 airflow CLI 命令参数来执行任务。实现位于 providers/amazon/src/airflow/providers/amazon/aws/executors/ecs/ecs_executor.py。该 section 共 14 个选项：

一个典型的 Fargate 部署示例：

[core] executor = airflow.providers.amazon.aws.executors.ecs.ecs_executor.AwsEcsExecutor [aws_ecs_executor] conn_id = aws_default region_name = us-east-1 cluster = ecs_executor_cluster container_name = ecs_executor_container launch_type = FARGATE platform_version = 1.4.0 security_groups = sg-XXXX,sg-YYYY subnets = subnet-XXXXXXXX,subnet-YYYYYYYY task_definition = executor_task_definition:LATEST assign_public_ip = False

使用要点：

• launch_type与capacity_provider_strategy二选一：指定capacity_provider_strategy时必须省略launch_type，反之亦然；两者都不指定时使用集群的默认 Capacity Provider 策略（若存在）。使用集群自动扩缩时，必须指定 Capacity Provider 策略而非 Launch Type；
• launch_type=EC2：执行器会优先将任务放置到空闲 EC2 实例；若无可用实例则本次心跳不放置任务，下个心跳重试；
• launch_type=FARGATE：任务运行在 AWS Fargate 上，platform_version缺省为LATEST；
• run_task_kwargs可补充如{"tags": {"key": "schema", "value": "1.0"}}之类的run_task参数。

对应测试位于 providers/amazon/tests/unit/amazon/aws/executors/ecs/test_ecs_executor.py。

[aws_auth_manager]：AwsAuthManager 认证管理器配置

[aws_auth_manager]section 仅在 Airflow 使用AwsAuthManager时生效，即需要在 Airflow 配置中显式启用：

[core] auth_manager = airflow.providers.amazon.aws.auth_manager.aws_auth_manager.AwsAuthManager

AwsAuthManager 将 Airflow 的用户认证与授权委托给 AWS Identity Center（SAML SSO）与 Amazon Verified Permissions（AVP 策略存储），实现基于 AWS 身份体系的统一访问控制。该 section 共 4 个选项：

配置示例：

[core] auth_manager = airflow.providers.amazon.aws.auth_manager.aws_auth_manager.AwsAuthManager [aws_auth_manager] conn_id = aws_default region_name = us-east-1 saml_metadata_url = https://portal.sso.<region>.amazonaws.com/saml/metadata/XXXXXXXXXX avp_policy_store_id = <AVP_POLICY_STORE_ID>

其中region_name、saml_metadata_url、avp_policy_store_id三个选项均为必填，缺失将导致认证管理器无法完成 SAML 元数据加载与策略查询。

将配置应用到实际环境：airflow.cfg 与环境变量

方式一：airflow.cfg

以上所有 section 均可直接写入airflow.cfg（默认位于~/airflow/airflow.cfg）。修改后需重启 Scheduler、Webserver 等组件使配置生效。也可通过airflow config get-value <section> <key>校验当前生效值。

方式二：环境变量

每个配置项都可通过环境变量覆盖airflow.cfg，命名规则为：

AIRFLOW__<SECTION>__<OPTION>

例如[aws_batch_executor]的region_name对应AIRFLOW__AWS_BATCH_EXECUTOR__REGION_NAME。环境变量的优先级高于airflow.cfg。Airflow 核心的配置管理方式可参考 airflow-core/docs/howto/set-config.rst。

方式三：敏感值的_CMD与_SECRET变体

对于模板中标记为sensitive的选项，可以使用AIRFLOW__SECTION__OPTION_CMD（执行命令获取值）与AIRFLOW__SECTION__OPTION_SECRET（从 Secrets Backend 获取值）两种变体，避免将明文凭据写入配置文件或环境变量。

在源码中核对与发现新配置

若要确认某个配置项的最新定义（描述、默认值、示例、引入版本），可直接查阅 providers/amazon/src/airflow/providers/amazon/get_provider_info.py 中config字段，或查看其源文件 providers/amazon/provider.yaml。渲染模板 devel-common/src/sphinx_exts/includes/sections-and-options.rst 则定义了这些数据最终如何呈现为文档。

小结

Amazon Provider 的配置参考页由共享模板与get_provider_info.py中的元数据共同生成，覆盖[aws]、[aws_batch_executor]、[aws_lambda_executor]、[aws_ecs_executor]、[aws_auth_manager]五个 section 共约 38 个配置项。其中[aws]面向日志与会话定制等通用场景，后三者分别对应 Batch、Lambda、ECS 三种云原生执行器的任务运行参数，[aws_auth_manager]则面向基于 AWS Identity Center 与 Verified Permissions 的企业级认证。无论通过airflow.cfg还是AIRFLOW__SECTION__OPTION环境变量注入，正确理解每个选项的类型、默认值与必填约束，都是让 Amazon Provider 在 Airflow 3 中稳定运行的前提。

【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow