Apache Airflow Amazon Provider 配置参考airflow.cfg 配置项与环境变量完全指南【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflowApache Airflow 的 Amazon Providerapache-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默认值未设置时通常为NoneExample可直接套用的示例值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_factorystringNone3.1.1自定义 boto3 session 工厂类的完整导入路径用于定制boto3.session.Session的创建逻辑cloudwatch_task_handler_json_serializerstringairflow.providers.amazon.aws.log.cloudwatch_task_handler.json_serialize_legacy8.7.2CloudWatch 任务日志处理器对非字符串消息的 JSON 序列化策略s3_task_handler_acl_policystringNone9.34.0S3 远程日志处理器上传日志对象时应用的 ACL 策略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 对象记录为nulldatetime对象除外会被 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 个选项配置项类型默认值引入版本说明conn_idstringaws_default8.11Batch 执行器调用 AWS Batch API 所用的 Airflow 连接凭证region_namestringNone8.11AWS Batch 所在区域必填max_submit_job_attemptsinteger38.11提交 Batch 作业的最大尝试次数check_health_on_startupbooleanTrue8.11启动时是否检查执行器健康状态job_namestringNone8.11提交给 AWS Batch 的作业名最长 128 字符首字符须为字母数字可含-与_job_queuestringNone8.11作业提交到的队列名或 ARNjob_definitionstringNone8.11使用的作业定义名或 ARN可带 revision缺省用最新活跃 revisionsubmit_job_kwargsstringNone8.11透传给 Batchsubmit_job方法的额外参数JSON 字符串一个最小可用的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-definitionsubmit_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 引入配置项类型默认值说明conn_idstringaws_defaultLambda 执行器调用 AWS API 所用连接region_namestringNoneAWS Lambda 所在区域check_health_on_startupbooleanTrue启动时是否检查执行器健康状态max_invoke_attemptsinteger3启动 Airflow 任务的最大调用尝试次数queue_urlstringNone任务结果轮询队列 URL必填dead_letter_queue_urlstringNone死信队列 URL用于接收超时/异常的任务结果必填function_namestringNone要调用的 Lambda 函数名必填qualifierstringNoneLambda 函数的版本或别名缺省使用最新版本end_wait_timeoutinteger0终止执行器/Scheduler 时等待所有调用完成的秒数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 个选项配置项类型默认值引入版本说明conn_idstringaws_default8.10ECS 执行器调用 AWS ECS API 所用连接region_namestringNone8.10Amazon ECS 所在区域必填assign_public_ipbooleanFalse8.10是否为容器分配公网 IPclusterstringNone8.10ECS 集群名必填capacity_provider_strategystringNone8.17容量提供者策略JSON 列表container_namestringNone8.10任务定义中执行 Airflow 任务的容器名必填launch_typestringNone8.10启动类型FARGATE或EC2platform_versionstringLATEST8.10Fargate 任务平台版本security_groupsstringNone8.10安全组 ID逗号分隔最多 5 个subnetsstringNone8.10子网 ID逗号分隔最多 16 个task_definitionstringNone8.10任务定义family:revision或完整 ARN缺省 revision 用最新 ACTIVE 版本max_run_task_attemptsinteger38.10运行任务的最大尝试次数run_task_kwargsstringNone8.10透传给 ECSrun_taskAPI 的额外参数JSON 字符串check_health_on_startupbooleanTrue8.11启动时是否检查执行器健康状态一个典型的 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 Typelaunch_typeEC2执行器会优先将任务放置到空闲 EC2 实例若无可用实例则本次心跳不放置任务下个心跳重试launch_typeFARGATE任务运行在 AWS Fargate 上platform_version缺省为LATESTrun_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.AwsAuthManagerAwsAuthManager 将 Airflow 的用户认证与授权委托给 AWS Identity CenterSAML SSO与 Amazon Verified PermissionsAVP 策略存储实现基于 AWS 身份体系的统一访问控制。该 section 共 4 个选项配置项类型默认值引入版本说明conn_idstringaws_default8.12.0AwsAuthManager 调用 AWS Identity Center 与 Amazon Verified Permissions API 所用连接region_namestringNone8.10Amazon Verified Permissions 所在区域必填saml_metadata_urlstringNone8.12.0AWS Identity Center 提供的 SAML metadata XML 文件 URL可在 Identity Center 控制台获取必填avp_policy_store_idstringNone8.12.0存储 Airflow 用户权限策略的 Amazon Verified Permissions 策略存储 ID必填配置示例[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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考