AWS SAM CLI 配置文件 - AWS Serverless Application Model
默认配置文件设置支持的配置文件格式指定配置文件配置文件基础参数值规则配置优先级创建和修改配置文件

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

AWS SAM CLI 配置文件

AWS Serverless Application Model 命令行界面 (AWS SAM CLI) 支持可用于配置的项目级配置文件 AWS SAM CLI 命令参数值。

有关创建和使用配置文件的文档，请参阅配置 AWS SAM CLI。

默认配置文件设置

AWS SAM 使用以下默认配置文件设置：

  • 名称 – samconfig。

  • 位置 - 位于项目的根目录中。此位置与 template.yaml 文件的位置相同。

  • 格式 – TOML。要了解更多信息 TOML，请参阅 TOML 文档。

以下是一个包含默认配置文件名和位置的示例项目结构：

sam-app
├── README.md
├── __init__.py
├── events
├── hello_world
├── samconfig.toml
├── template.yaml
└── tests

以下是 samconfig.toml 文件示例：

...
version = 0.1

[default]
[default.global]
[default.global.parameters]
stack_name = "sam-app"

[default.build.parameters]
cached = true
parallel = true

[default.deploy.parameters]
capabilities = "CAPABILITY_IAM"
confirm_changeset = true
resolve_s3 = true

[default.sync.parameters]
watch = true

[default.local_start_api.parameters]
warm_containers = "EAGER"

[prod]
[prod.sync]
[prod.sync.parameters]
watch = false

支持的配置文件格式

支持 TOML 和 [YAML|YML] 格式。请参阅以下基本语法：

TOML

version = 0.1
[environment]
[environment.command]
[environment.command.parameters]
option = parameter value

YAML

version: 0.1
environment:
  command:
    parameters:
      option: parameter value

指定配置文件

默认情况下， AWS SAM CLI 按以下顺序查找配置文件：

  1. 自定义配置文件-如果使用--config-file选项来指定文件名和位置，则 AWS SAM CLI 先查找此文件。

  2. 默认 samconfig.toml 文件 - 这是默认配置文件名和格式，位于项目的根目录中。如果您未指定自定义配置文件，则 AWS SAM CLI 接下来要寻找这个文件。

  3. samconfig.[yaml|yml]file — 如果项目根目录中samconfig.toml不存在，则 AWS SAM CLI 正在寻找这个文件。

以下示例说明了如何使用 --config-file 选项指定自定义配置文件：

$ sam deploy --config-file myconfig.yaml
注意

该--config-file参数必须相对于 AWS SAM 模板文件的位置，因为 AWS SAM CLI 需要确定应用配置的上下文。该samconfig.toml文件管理您的版本的配置设置 AWS SAM CLI，然后在samconfig.toml文件的相对文件夹中CLI查找文件（或覆盖的配置文件参数）。template.yaml

配置文件基础

环境

环境是包含一组唯一配置设置的命名标识符。你可以在一个 AWS SAM 应用程序中拥有多个环境。

默认环境名称是 default。

使用 AWS SAM CLI --config-env选项来指定要使用的环境。

命令

命令是 AWS SAM CLI 命令为其指定参数值。

要为所有命令指定参数值，请使用 global 标识符。

当引用 AWS SAM CLI 命令，将空格 ( ) 和连字符 () 替换为下划线 (–_)。请参阅以下示例：

  • build

  • local_invoke

  • local_start_api

参数

参数指定为键值对。

  • 关键是 AWS SAM CLI 命令选项名称。

  • 值是要指定的值。

指定键时，请使用长格式的命令选项名称，并将连字符 (–) 替换为下划线 (_)。示例如下：

  • region

  • stack_name

  • template_file

参数值规则

TOML

  • 布尔值可以是 true 或 false。例如，confirm_changeset = true。

  • 对于字符串值，请使用引号 ("")。例如，region = "us-west-2"。

  • 对于列表值，请使用引号 ("")，并使用空格 ( ) 分隔每个值。例如：capabilities = "CAPABILITY_IAM CAPABILITY_NAMED_IAM"。

  • 对于包含键值对列表的值，这些键值对以空格分隔 ( )，并且每对的值用编码的引号 (\" \") 括起。例如，tags = "project=\"my-application\" stage=\"production\""。

  • 对于可以多次指定的参数值，值是参数数组。例如：image_repositories = ["my-function-1=image-repo-1", "my-function-2=image-repo-2"]。

YAML

  • 布尔值可以是 true 或 false。例如，confirm_changeset: true。

  • 对于包含单个字符串值的条目，引号 ("") 是可选的。例如，region: us-west-2。这包括包含以单个字符串形式提供的多个键值对的条目。以下是示例：

    $ sam deploy --tags "foo=bar hello=world"
    default:
  deploy:
    parameters:
      tags: foo=bar hello=world

  • 对于包含值列表的条目或可在单个命令中多次使用的条目，请将其指定为字符串列表。

    以下是示例：

    $ sam remote invoke --parameter "InvocationType=Event" --parameter "LogType=None"
    default:
  remote_invoke:
    parameter:
    - InvocationType=Event
    - LogType=None

配置优先级

配置值时，以下优先级适用：

  • 在命令行中提供的参数值优先于配置文件和模板文件 Parameters 部分中相应的值。

  • 如果在命令行或带有 parameter_overrides 键的配置文件中使用 --parameter-overrides 选项，则其值优先于模板文件 Parameters 部分中的值。

  • 在配置文件中，为特定命令提供的条目优先于全局条目。在以下示例中，sam deploy 命令使用堆栈名称 my-app-stack。

    TOML
    [default.global.parameters]
stack_name = "common-stack"

[default.deploy.parameters]
stack_name = "my-app-stack"
    YAML
    default:
  global:
    parameters:
      stack_name: common-stack
  deploy:
    parameters:
      stack_name: my-app-stack

创建和修改配置文件

创建配置文件

使用 sam init 创建应用程序时，系统会创建默认 samconfig.toml 文件。您也可以手动创建配置文件。

修改配置文件

您可以手动修改配置文件。另外，在任何 AWS SAM CLI 交互式流程，配置的值将显示在方括号 ([ ]) 中。如果您修改这些值， AWS SAM CLI 将更新您的配置文件。

以下是使用 sam deploy --guided 命令的交互式流程的示例：

$ sam deploy --guided

Configuring SAM deploy
======================

    Looking for config file [samconfig.toml] :  Found
    Reading default arguments  :  Success

    Setting default arguments for 'sam deploy'
    =========================================
    Stack Name [sam-app]: ENTER
    AWS Region [us-west-2]: ENTER
    #Shows you resources changes to be deployed and require a 'Y' to initiate deploy
    Confirm changes before deploy [Y/n]: n
    #SAM needs permission to be able to create roles to connect to the resources in your template
    Allow SAM CLI IAM role creation [Y/n]: ENTER
    #Preserves the state of previously provisioned resources when an operation fails
    Disable rollback [y/N]: ENTER
    HelloWorldFunction may not have authorization defined, Is this okay? [y/N]: y
    Save arguments to configuration file [Y/n]: ENTER
    SAM configuration file [samconfig.toml]: ENTER
    SAM configuration environment [default]: ENTER

修改配置文件时， AWS SAM CLI 按如下方式处理全局值：

  • 如果参数值存在于配置文件的global部分中，则 AWS SAM CLI 不会将值写入特定的命令部分。

  • 如果参数值同时存在于global和特定的命令部分中，则 AWS SAM CLI 删除特定条目以使用全局值。