Amazon SAMCLI 配置文件 - Amazon Serverless Application Model
默认配置文件设置支持的配置文件格式指定配置文件配置文件基础参数值规则配置优先级创建和修改配置文件
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

Amazon SAMCLI 配置文件

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

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

默认配置文件设置

Amazon 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

指定配置文件

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

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

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

  3. samconfig.[yaml|yml] 文件 - 如果 samconfig.toml 不存在于项目的根目录中，则 Amazon SAM CLI 会查找此文件。

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

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

--config-file 参数必须相对于 Amazon SAM 模板文件的位置，因为 Amazon SAM CLI 需要确定配置所适用的上下文环境。samconfig.toml 文件管理您当前 Amazon SAM CLI 版本的配置设置，而 CLI 会在 template.yaml 文件所在的相对路径中查找 samconfig.toml 文件（或覆盖的配置文件参数）。

配置文件基础

环境

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

默认环境名称是 default。

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

命令

命令是要为其指定参数值的 Amazon SAM CLI 命令。

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

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

  • build

  • local_invoke

  • local_start_api

参数

参数指定为键值对。

  • 键是 Amazon 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:
    parameters:
        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 文件。您也可以手动创建配置文件。

修改配置文件

您可以手动修改配置文件。此外，在任何 Amazon SAM CLI 交互式流程中，配置的值都会显示在方括号 ([ ]) 中。如果您修改这些值，Amazon 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

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

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

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