Chalice 配置文件（.chalice/config.json）完全指南：阶段化部署、Lambda 函数级配置与 IAM/网络/自定义域名实战

后端ServerlessCLI【免费下载链接】chalicePython Serverless Microframework for AWS项目地址https://gitcode.com/gh_mirrors/ch/chalice点击查看免费下载导读本指南以 AWS 开源 Python Serverless 微框架 Chalice 的.chalice/config.json配置文件为绝对主线系统讲解如何通过该文件控制chalice deploy的全部行为从 stage 级与全局级配置的优先级规则、API Gateway 端点与自定义域名配置到 IAM 角色与策略管理、VPC 网络、环境变量、Lambda 函数级差异化配置等。读完本文你将能够不修改一行应用代码仅靠配置文件就完成多环境dev/beta/prod的差异化部署、为不同 Lambda 函数分配不同资源与权限、并把 API 挂载到自定义域名。配置文件是什么每次使用chalice new-project创建新项目时Chalice 都会为你生成一个.chalice目录其中包含一个config.json文件用来控制chalice deploy时的部署行为。项目目录结构如下$ tree -a . ├── .chalice │ └── config.json ├── app.py └── requirements.txt 1 directory, 3 files从源码看config.json的内容通过 chalice/config.py 中的Config类被加载与解析。该类将配置值来源划分为三层优先级Config.__init__与_chain_lookup方法体现用户显式传入的参数user_provided_params通常来自命令行例如--profile prod磁盘上的配置文件config_from_disk即.chalice/config.json的json.loads()结果默认值default_params。_chain_lookup依次在这几个字典中查找键取第一个非None的值。在 chalice/cli/factory.py 的create_config_obj中可以看到内置的默认参数api_gateway_stage使用默认 API Gateway 阶段名、api_gateway_endpoint_type使用DEFAULT_ENDPOINT_TYPE、autogen_policy默认为True。阶段Stage专属配置从 Chalice 0.7.0 开始你可以同时指定某个 chalice stage 专属的配置以及跨所有 stage 共享的全局配置。有关 chalice stage 概念的完整说明见 stages 文档。stages该键的值是一个从 chalice stage 名称到 stage 配置的映射。Chalice 默认的 stage 名为dev。如果你使用 0.7.0 及以上版本的chalice new-project该键及默认的dev键会自动创建。以下配置项既可以放在某个 stage 的配置中也可以作为不绑定具体 stage 的顶层键。当需要某个 stage 专属的配置值时Chalice优先检查stages映射若未找到再检查顶层键。这一查找顺序正是 config.py 中_chain_lookup的参数varies_per_chalice_stageTrue所实现的逻辑——凡是标注“随 stage 变化”的配置都会先把config_from_disk[stages][当前stage]插入查找链中。api_gateway_endpoint_type所部署 API Gateway 的端点配置决定了 API 的访问方式可选值为EDGE、REGIONAL、PRIVATE。注意该值只能作为顶层键设置默认值为EDGE。在 chalice/deploy/validate.py 的validate_endpoint_type中会对该值进行校验合法取值仅限上述三种否则部署时直接抛出ValueError。api_gateway_endpoint_vpce当配置 Private APIapi_gateway_endpoint_type为PRIVATE时必须指定一个 VPC Endpoint id用于在没有显式策略时为 API 配置默认资源策略。该值可以是单个字符串也可以是端点 id 的列表。在 appgraph.py 中可以看到若该值是字符串会被包装成单元素列表并最终传给RestAPI.vpce_ids。api_gateway_policy_file指向 REST API 的 IAM 资源策略文件。若未指定且端点类型为PRIVATEChalice 会自动生成该策略。该文件名相对于.chalice目录。在 appgraph.py 中该文件会被封装为FileBasedIAMPolicy其完整路径为os.path.join(config.project_dir, .chalice, policy_path)。注意 validate.py 的validate_resource_policy中有一组严格的互斥校验api_gateway_endpoint_vpce只能在端点类型为PRIVATE时指定否则报错api_gateway_policy_file与api_gateway_endpoint_vpce二者只能指定其一若端点类型为PRIVATE则必须提供api_gateway_policy_file或api_gateway_endpoint_vpce中的至少一个。api_gateway_stageAPI Gateway 阶段stage的名称。它同时也是 API 的 URL 前缀https://endpoint/prefix/your-api。autogen_policy布尔值表示 Chalice 是否基于应用源码分析自动生成 IAM 策略。默认值为true。若为falseChalice 会改为从磁盘加载.chalice/policy-stage-name.json作为 IAM 策略而不是通过源码分析自动生成。你可以通过iam_policy_file配置项更改该文件名。IAM 角色与策略的更多配置示例见下文“IAM Roles and Policies”。environment_variables键值对映射这些键值对会作为环境变量注入应用。所有环境变量的值必须是字符串——这一点在 validate.py 的validate_environment_variables_type中有强制校验非字符串值会直接抛错。如果该键同时出现在 stage 配置和顶层键中stage 专属的环境变量会合并进顶层键stage 覆盖同名顶层键。这一行为在源码中由_chain_merge方法config.py实现它按“默认值 → 顶层 → stage → 函数级 → 用户参数”的顺序逐一dict.update合并后出现的字典覆盖先出现的键。具体示例见下文“环境变量”部分。iam_policy_file当autogen_policy为false时Chalice 从磁盘加载 IAM 策略而不是基于源码分析自动生成。默认位置是.chalice/policy-stage-name.json例如.chalice/policy-dev.json、.chalice/policy-prod.json等。可以通过iam_policy_file更改文件名路径相对于.chalice目录。例如{ version: 2.0, app_name: app, stages: { dev: { autogen_policy: false, iam_policy_file: my-policy.json } } }上述配置会让 Chalice 使用.chalice/my-policy.json创建 IAM 角色。iam_role_arn当manage_iam_role为false时必须指定该值用于指明应用配置时使用的 IAM 角色 ARN。该值仅在manage_iam_role为false时生效。源码 validate.py 的_validate_manage_iam_role强制了这一约束如果manage_iam_role为假且未提供iam_role_arnchalice deploy会直接报错。lambda_memory_size整数表示 Lambda 函数分配的内存大小MB。AWS Lambda 会根据内存大小推断分配给函数的 CPU 资源。默认值为128且必须是 64 MB 的倍数。在 chalice/constants.py 中DEFAULT_LAMBDA_MEMORY_SIZE 128正是该默认值的来源。lambda_timeout整数表示 AWS Lambda 终止函数执行的超时时间秒。默认lambda_timeout为60秒。layersLambda Layers ARN 的列表。该值既可以按 stage 提供也可以按单个 Lambda 函数提供。automatic_layer布尔值表示 Chalice 是否自动为所有 Lambda 函数构建一个包含requirements.txt依赖库与 vendored 库的 stage 级 Layer。若不指定默认值为false。在 config.py 中该属性的默认处理是未配置None时返回False。依赖打包的更多细节见 packaging 文档。api_gateway_custom_domain键值对映射用于 REST API 的自定义域名。指定时必须包含以下必需键domain_name要关联到 REST API 的自定义域名如api.example.comcertificate_arn当前域名的 ACM 证书 ARN。若 API 使用REGIONAL端点类型ACM 证书必须与 API 在同一区域若使用EDGE端点类型证书必须在us-east-1。可选配置tls_version该域名安全策略的 TLS 版本。默认TLS_1_2REST API 也可使用TLS_1_0url_prefix自定义域名加url_prefixBasePathMapping标识了给定 stage 中部署的 REST API。设置自定义域名后你可以设定 API 的主机名并选择一个基础路径如myservice将替代 URL 映射到你的 API例如https://api.example.com/myservice。若不设置url_prefixAPI 的基础 URL 与自定义域名相同例如https://api.example.com/tags标签字典键为标签键值为标签值。自定义域名的完整配置指南见 domainname 文档。websocket_api_custom_domain与api_gateway_custom_domain完全对应的 WebSocket API 版本键值对映射指定时同样必须包含domain_name与certificate_arn可选配置与 REST API 版本一致tls_version、url_prefix、tags。从源码 config.py 可以看到两者分别对应独立的配置属性。manage_iam_roletrue/false。表示是否由 Chalice 创建并更新应用使用的 IAM 角色。默认值为true。如果你已有预先创建的角色可将其设为false此时 Chalice 不会创建或更新角色manage_iam_role: false意味着你需要自行管理该角色及其关联策略。若设为false必须指定iam_role_arn否则运行chalice deploy时会报错。minimum_compression_size整数表示应用到 API Gateway 的最小压缩大小。若该键同时出现在 stage 配置与顶层键中stage 专属值会覆盖顶层值。其取值范围在 validate.py 中校验必须位于MIN_COMPRESSION_SIZE0与MAX_COMPRESSION_SIZE10485760之间见 constants.py且必须是整数。reserved_concurrency整数表示每个函数的预留并发reserved concurrency。该值可以按 stage 提供也可以按单个 Lambda 函数提供。AWS Lambda 会为该 stage 中部署的每个 Lambda 预留该并发数。若设为0该函数的调用将被阻塞若未设置则不进行预留并发分配。subnet_idsVPC 配置的子网 id 列表。该值可以按 stage 提供也可以按单个 Lambda 函数提供。要使其生效必须同时提供security_group_ids。当两者都提供且autogen_policy为True时Chalice 会自动更新 IAM 角色加入创建、描述、删除 ENI弹性网络接口所需的权限。如果你自行管理 IAM 角色策略请务必相应更新权限。security_group_idsVPC 配置的安全组列表。该值可以按 stage 提供也可以按单个 Lambda 函数提供。要使其生效必须同时提供subnet_ids。tags键值对映射这些键值对会作为部署应用的运行资源的标签。所有标签键和值必须是字符串。与environment_variables类似如果某键同时出现在 stage 配置与顶层键中stage 专属标签会合并进顶层键。默认情况下Chalice 部署的所有资源都会被标记上aws-chalice键值为version{chalice-version}:stage{stage-name}:app{app-name}。目前只有 Lambda 函数会被打标签——这一默认标签的拼接逻辑可以直接在 config.py 的tags属性中看到。xray布尔值开启 AWS X-Ray 的 Active tracing 配置。开启后 X-Ray 将同时作用于 Lambda 函数和 API Gateway 阶段。log_retention_in_days整数表示应用到 Lambda 函数日志组的保留时间天。只有特定的值有效请参考 AWS CloudWatch Logs 的PutRetentionPolicy接口文档。警告如果你使用chalice package命令生成 CloudFormation 模板模板中会新增一个带配置的log_retention_in_days的 Log Group 资源。如果该 Log Group 资源已经存在例如相关 Lambda 函数此前已被调用Lambda 自动为函数创建了 Log Group部署会失败。因此该配置应放在 Lambda 函数的首次部署中。Lambda 函数级Per-Function配置除 chalice stage 之外还有一些配置值可以按单个 Lambda 函数指定。一个 chalice app 可以有多个 stage而一个 stage 可以包含多个 Lambda 函数。你可以选择为某个函数在所有 stage 中统一配置也可以为某个函数在特定 stage 中单独配置。要为特定 stage 下的某函数配置在 stage 配置中添加lambda_functions键{ version: 2.0, app_name: app, stages: { dev: { lambda_functions: { foo: { lambda_timeout: 120 } } } } }要为某函数跨所有 stage 配置添加顶层lambda_functions键{ version: 2.0, app_name: app, lambda_functions: { foo: { lambda_timeout: 120 } } }lambda_functions字典中的每个键是应用中某个 Lambda 函数的名称值是该函数要应用的配置字典。可以按函数应用的配置选项包括autogen_policyenvironment_variablesiam_policy_fileiam_role_arnlambda_memory_sizelambda_timeoutlayersmanage_iam_rolereserved_concurrencysecurity_group_idssubnet_idstagslog_retention_in_days这些选项的详细说明见上文“阶段专属配置”一节。函数级配置的查找顺序在 config.py 的_chain_lookup中有清晰的注释注释config[stages][stage][lambda_functions][function] config[stages][stage] config[lambda_functions][function] config顶层 默认值一般地Lambda 函数的名称对应应用中的函数名。例如app.lambda_function() def foo(event, context): pass要为该函数指定配置就在lambda_functions配置中使用键foo。唯一的例外是使用app.route()装饰器装饰的 Python 函数。Chalice 为 API Gateway 的所有请求使用单个Lambda 函数其名称为api_handler该名称即 constants.py 中的DEFAULT_HANDLER_NAME。例如有以下应用app.route(/) def index(): pass app.route(/foo/bar) def other_handler(): pass要为index()和other_handler()共享的底层 Lambda 函数指定配置值应这样写{ lambda_functions: { api_handler: { subnet_ids: [sn-1, sn-2], security_group_ids: [sg-10, sg-11], layers: [layer-arn-1, layer-arn-2] } } }配置示例以下示例展示了如何配置你的 chalice 应用。自定义域名为 REST API 的devstage 配置自定义域名的示例{ version: 2.0, app_name: app, stages: { dev: { autogen_policy: true, api_gateway_stage: dev, api_gateway_custom_domain: { domain_name: api.example.com, security_policy: TLS 1.2|TLS 1.0, certificate_arn: arn:aws:acm:example.com, url_prefixes: [foo, bar], tags: { key: tag1, key1: tag2 } } } } }该配置为 ApiGateway 指定了devstage。在devstage 中Chalice 会自动创建custom domain name并携带指定的url_prefixes该字段对应 AWS API Mapping key 信息。如果存在 WebSocket API应使用websocket_api_custom_domain而不是api_gateway_custom_domain。IAM 角色与策略跨 stage 配置 IAM 策略的示例{ version: 2.0, app_name: app, stages: { dev: { autogen_policy: true, api_gateway_stage: dev }, beta: { autogen_policy: false, iam_policy_file: beta-app-policy.json }, prod: { manage_iam_role: false, iam_role_arn: arn:aws:iam::...:role/prod-role } } }该配置指定了三个 stagedev、beta、prod。在devstageChalice 会基于应用源码分析自动生成 IAM 策略在betastageChalice 会加载.chalice/beta-app-policy.json文件将其作为该 stage 关联到 IAM 角色的策略在prodstageChalice 不会修改任何 IAM 角色只将 Lambda 函数的 IAM 角色设为arn:aws:iam::...:role/prod-role。下面是一个展示配置优先级的示例{ version: 2.0, app_name: app, api_gateway_stage: api, stages: { dev: { }, beta: { }, prod: { api_gateway_stage: prod, manage_iam_role: false, iam_role_arn: arn:aws:iam::...:role/prod-role } } }该配置中dev和betastage 的 API Gateway 阶段名都是api因为它们会默认使用顶层api_gateway_stage键而prodstage 的 API Gateway 阶段名是prod因为api_gateway_stage在{stages: {prod: ...}}映射中被单独指定了。环境变量下面的示例同时以顶层键和 stage 级指定了环境变量从而既能提供所有 stage 都应有的环境变量也能提供 stage 专属的环境变量{ version: 2.0, app_name: app, environment_variables: { SHARED_CONFIG: foo, OTHER_CONFIG: from-top }, stages: { dev: { environment_variables: { TABLE_NAME: dev-table, OTHER_CONFIG: dev-value } }, prod: { environment_variables: { TABLE_NAME: prod-table, OTHER_CONFIG: prod-value } } } }上述配置中devstage 将设置以下环境变量{ SHARED_CONFIG: foo, TABLE_NAME: dev-table, OTHER_CONFIG: dev-value }prodstage 将设置以下环境变量{ SHARED_CONFIG: foo, TABLE_NAME: prod-table, OTHER_CONFIG: prod-value }可以看到顶层键SHARED_CONFIG被所有 stage 继承而OTHER_CONFIG被 stage 级值覆盖dev-value/prod-value。这正是 config.py 中_chain_merge实现的合并语义与_chain_lookup的“取第一个非空值”行为形成了鲜明对比——environment_variables与tags属于合并型配置其余大多数配置属于覆盖型配置。Per Lambda 示例假设我们有如下 chalice 应用from chalice import Chalice app Chalice(app_namedemo) app.lambda_function() def foo(event, context): pass app.lambda_function() def bar(event, context): pass针对这两个函数我们希望实现如下配置目标两个函数都应有环境变量OWNER值为dev-teamfoo函数应使用由 chalice 管理的自动生成 IAM 策略foo函数应在 VPC 中运行子网 id 为sn-1和sn-2安全组为sg-10和sg-11且 Chalice 应自动在 IAM 策略中加入修改 EC2 网络接口的权限foo函数应挂载两个 Layerlayer-arn-1和layer-arn-2Chalice 应自动配置 IAM 策略bar函数应使用在 Chalice 之外预先创建的 IAM 角色Chalice 不应对bar函数执行 IAM 角色管理bar函数应有环境变量TABLE_NAME值为mytable。所有这些都可以通过如下配置文件实现{ stages: { dev: { environment_variables: { OWNER: dev-team }, api_gateway_stage: api, lambda_functions: { foo: { subnet_ids: [sn-1, sn-2], security_group_ids: [sg-10, sg-11], layers: [layer-arn-1, layer-arn-2] }, bar: { manage_iam_role: false, iam_role_arn: arn:aws:iam::my-role-name, environment_variables: {TABLE_NAME: mytable} } } } }, version: 2.0, app_name: demo }实战要点总结优先级铁律函数级配置 stage 级配置 顶层配置 内置默认值config.py 的_chain_lookup与_chain_merge是实现核心environment_variables、tags例外——它们是逐级合并而非覆盖。前置校验chalice deploy前会经 validate.py 的validate_configuration做“快速失败”校验包括端点类型合法性、Private API 资源策略互斥规则、manage_iam_rolefalse必须有iam_role_arn、环境变量值必须为字符串、压缩大小必须在 0~10485760 之间等。api_handler 特例所有app.route()视图函数共享同一个名为api_handler的 Lambda函数级配置需以api_handler为键。配置文件的版本字段version键标识配置文件 schema 版本1.0/2.0app_name必须与应用名一致二者是部署时的必填基础字段。通过本文的配置项速查表与示例组合你可以把环境差异、权限差异、网络差异全部沉淀到config.json中让同一份应用代码在不同 stage 上按需部署这也是 Chalice 多环境发布的最佳实践基础。相关配套文档可继续参阅 stages 文档、domainname 文档 与 packaging 文档。赞分享后端ServerlessCLI【免费下载链接】chalicePython Serverless Microframework for AWS项目地址https://gitcode.com/gh_mirrors/ch/chalice点击查看免费下载相关推荐AWS Chalice 项目如何为API配置自定义域名AWS Chalice 项目如何为API配置自定义域名 什么是自定义域名 在AWS Chalice项目中自定义域名是指为你的API提供的更简单、更直观的UR后端ServerlessCLI如何为Chalice API加安全锁IAM、Cognito与自定义Authorizer完全教程如何为Chalice API加安全锁IAM、Cognito与自定义Authorizer完全教程 Chalice 是 AWS 官方推出的 Python Serv后端ServerlessCLIXiaoMusic 配置文件方式实战config.json 完整配置指南pip 安装与 Docker Compose 部署XiaoMusic 配置文件方式实战config.json 完整配置指南pip 安装与 Docker Compose 部署 本篇技术指南面向使用小爱音箱播后端智能硬件音视频上一篇Kor输出格式详解Table、JSON与YAML哪种更适合你的监控需求下一篇OpenStatus批量导入监控目标API与CSV两种方式对比创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考