View a markdown version of this page

sam deploy - AWS Serverless Application Model

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

sam deploy

本页提供参考信息 AWS Serverless Application Model 命令行界面 (AWS SAM CLI) sam deploy 命令。

这个 sam deploy 命令将应用程序部署到 AWS Cloud 使用 AWS CloudFormation。

重要

别跑 sam deploy 在不可信的代码上。该命令使用你的 AWS 用于创建模板定义的资源(包括 IAM 角色和策略)的证书,并上传模板引用的本地文件。它还按写入的方式应用项目配置文件中的选项。在部署非您创作的项目之前,请先查看模板和配置文件。

用量

$ <environment variables> sam deploy <options>

环境变量

SAM_CLI_POLL_DELAY

设置 SAM_CLI_POLL_DELAY 环境变量,在 shell 中的值为秒,用于配置频率 AWS SAM CLI 会检查 CloudFormation 堆栈状态,这在查看来自的限制时很有用 CloudFormation。此 env 变量用于轮询 describe_stack API 调用,这些调用是在运行 sam deploy 时进行的。

以下是此变量的示例:

$ SAM_CLI_POLL_DELAY=5 sam deploy

选项

--capabilities LIST

必须指定才能允许的权能列表 CloudFormation 来创建特定的堆栈。一些堆栈模板可能包含影响您的权限的资源 AWS 账户,例如,通过创建新的 AWS Identity and Access Management (IAM) 用户。对于这些堆栈,您必须通过指定此选项来明确确认它们的功能。有效值仅为 CAPABILITY_IAM 和 CAPABILITY_NAMED_IAM。如果有 IAM 资源,则您可以指定任意一个功能。如果有具有自定义名称的 IAM 资源,则必须指定 CAPABILITY_NAMED_IAM。如果不指定此选项,则操作会返回 InsufficientCapabilities 错误。

部署包含嵌套应用程序的应用程序时,您必须使用 CAPABILITY_AUTO_EXPAND 来确认此应用程序包含嵌套应用程序。有关更多信息,请参阅 部署嵌套应用程序。

--config-env TEXT

在配置文件中指定要使用的默认参数值的环境名称。默认值为 default。有关配置文件的详细信息,请参阅 AWS SAMCLI 配置文件。

--config-file PATH

包含要使用的默认参数值的配置文件的路径和文件名。在项目目录的根目录中,默认值为 samconfig.toml。有关配置文件的详细信息,请参阅 AWS SAMCLI 配置文件。

--confirm-changeset | --no-confirm-changeset

提示您确认 AWS SAM CLI 是否部署了计算的变更集。

--debug

启用调试日志记录,以打印 AWS SAM CLI 生成的调试消息并显示时间戳。

--disable-rollback | --no-disable-rollback

指定是否回滚您的 CloudFormation 如果在部署期间发生错误,则堆栈。默认情况下,如果在部署期间出现错误,您的 CloudFormation 堆栈回滚到最后一个稳定状态。如果指定 --disable-rollback,当部署期间出现错误时,则在错误出现之前创建或更新的资源不会回滚。

--express | --no-express

指定是否使用 CloudFormation 快速模式。处于活动状态时,一旦应用资源配置,堆栈操作即完成。资源继续在后台准备就绪。部署时间最多可缩短 4 倍。

这个 AWS SAM CLI 将回滚行为传递给 CloudFormation DeploymentConfig 同时指定时的参数 --disable-rollback。

默认值为 --no-express。

--fail-on-empty-changeset | --no-fail-on-empty-changeset

指定在未对堆栈进行任何更改时是否要返回非零退出代码。默认行为是返回非零退出代码。

--force-upload

指定此选项可上传构件,即使要上传的构件与 Amazon S3 存储桶中的现有构件匹配。匹配的构件会被覆盖。

--guided, -g

指定此选项后, AWS SAM CLI 就会使用提示来指导您完成部署。

--help

显示此消息并退出。

--image-repositories TEXT

函数与其 Amazon ECR 存储库 URI 之间的映射。通过逻辑 ID 引用函数。以下是示例:

$ sam deploy --image-repositories Function1=123456789012.dkr.ecr.us-east-1.amazonaws.com/my-repo

您可以在单个命令中多次指定此选项。

--image-repository TEXT

此命令用于上传函数映像的 Amazon ECR 存储库的名称。对于使用 Image 包类型声明的函数,必须使用此选项。

--kms-key-id TEXT

一个 ID AWS Key Management Service (AWS KMS) 密钥用于加密存放在 Amazon S3 存储桶中的静态项目。如果你没有指定这个选项,那么 AWS SAM 使用亚马逊 S3-managed 加密密钥。

对于 AWS::Serverless::WebFunction 已上传到您指定的存储桶 --s3-bucket,密钥必须是密钥策略允许的客户管理的密钥 lambda.amazonaws.com 打电话 kms:Decrypt。

--metadata

要附加到模板中引用的所有构件的元数据的映射。

--no-execute-changeset

指示是否要应用变更集。如果要在应用变更集之前查看堆栈更改,请指定此选项。此命令会创建 CloudFormation 变更集,然后退出而不应用变更集。要应用变更集,请在不使用此选项的情况下运行同一命令。

--no-progressbar

将构件上传到 Amazon S3 时不显示进度条。

--notification-arns LIST

亚马逊简单通知服务 (Amazon SNS) 主题 ARN 列表 CloudFormation 与堆栈关联。

--on-failure [ROLLBACK | DELETE | DO_NOTHING]

指定堆栈创建失败时要采取的操作。

以下选项可用:

  • ROLLBACK - 将堆栈回滚到上一个已知良好状态。

  • DELETE - 将堆栈回滚到上一个已知良好状态(如果存在)。否则,删除堆栈。

  • DO_NOTHING - 既不回滚堆栈,也不删除堆栈。其效果与 --disable-rollback 相同。

默认行为是 ROLLBACK。

注意

您可以指定 --disable-rollback 选项或 --on-failure 选项,但不能同时指定两者。

--output [ text | json ]

命令输出的格式:

  • text — 打印常规的、人类可读的输出。这是默认值。

  • json — 打印结构化、机器可读的输出。当你想以编程方式使用输出时,请使用此格式,例如在 CI/CD 管道、IDE 扩展以及 AI-assisted 工具。

部署会在一段时间内运行。当你指定时 --output json,那个 AWS SAM CLI 随着部署的进行打印 JSON 对象流,每行一个。每个对象都包含一个 type 用于标识其包含的信息种类的字段,例如变更集、部署事件、堆栈输出和最终结果。失败时,最终对象包括 error 描述出了什么问题的对象。

注意

这个 --output json 选项与需要交互式提示的选项不兼容,例如 --guided 和 --confirm-changeset。

--parameter-overrides LIST

一个包含以下内容的字符串 CloudFormation 参数替换编码为键值对。每个覆盖项均采用 ParameterKey=name,ParameterValue=value 格式。多个覆盖项以空格分隔。以下是两个示例:

$ sam deploy --parameter-overrides ParameterKey=value1,ParameterValue=value2
$ sam deploy --parameter-overrides ParameterKey=value1,ParameterValue=value2 ParameterKey=hello,ParameterValue=world ParameterKey=apple,ParameterValue=banana
--profile TEXT

您的凭证文件中获取的特定个人资料 AWS 证书。

--region TEXT

这个 AWS 区域 部署到。例如,us-east-1。

--resolve-image-repos

自动创建 Amazon ECR 存储库,用于打包和部署非指导式部署。此选项仅适用于指定了 PackageType: Image 的函数和层。如果指定 --guided 选项,则 AWS SAM CLI 会忽略 --resolve-image-repos。

注意

如果 AWS SAM 使用此选项自动为函数或层创建任何 Amazon ECR 存储库,稍后您会将这些函数或层从您的存储库中删除 AWS SAM 模板,则相应的亚马逊 ECR 存储库将被自动删除。

--resolve-s3

自动创建 Amazon S3 存储桶,用于打包和部署非指导式部署。如果指定 --guided 选项,则 AWS SAM CLI 会忽略 --resolve-s3。如果同时指定 --s3-bucket 和 --resolve-s3 选项,则会出现错误。

使用此选项或 --guided,一个的代码 AWS::Serverless::WebFunction 上传到属于堆栈的代码存储桶,而不是托管存储桶。有关更多信息,请参阅 构建和部署 Lambda Web 函数。

--role-arn TEXT

IAM 角色的亚马逊资源名称 (ARN) CloudFormation 在应用变更集时假定。

--s3-bucket TEXT

此命令用于上传您的 Amazon S3 存储桶的名称 CloudFormation 模板。如果模板大于 51,200 字节,则需要 --s3-bucket 或 --resolve-s3 选项。如果同时指定 --s3-bucket 和 --resolve-s3 选项,则会出现错误。

一个的代码 AWS::Serverless::WebFunction 还会上传到此存储桶,该存储桶必须启用版本控制并允许 Lambda 读取代码。有关更多信息,请参阅 构建和部署 Lambda Web 函数。

--s3-prefix TEXT

上传到 Amazon S3 存储桶的构件的名称中添加的前缀。前缀名称是 Amazon S3 存储桶的路径名称(文件夹名称)。

--save-params

将您在命令行中提供的参数保存到 AWS SAM 配置文件。

--signing-profiles LIST

用于签署部署包的签名配置文件的列表。此选项采用键值对列表,其中密钥是要签名的函数或层的名称,值是签名配置文件,可选的配置文件所有者用 : 分隔。例如 FunctionNameToSign=SigningProfileName1 LayerNameToSign=SigningProfileName2:SigningProfileOwner。

--stack-name TEXT

(必填)的名称 CloudFormation 你要部署到的堆栈。如果指定现有堆栈,则该命令将更新堆栈。如果指定新堆栈,则该命令将创建它。

--tags LIST

与创建或更新的堆栈关联的标签列表。 CloudFormation 还会将这些标签传播到堆栈中支持它的资源。

--template-file, --template, -t PATH

你所在的路径和文件名 AWS SAM 模板已找到。

注意

如果你指定这个选项,那么 AWS SAM 仅部署模板及其指向的本地资源。

--use-json

的输出 JSON CloudFormation 模板。默认输出为 YAML。

示例

有关使用 sam deploy 子命令的详细示例和深入演练,请参阅使用部署简介 AWS SAM。