AWS Command Line Interface
用户指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

配置和证书文件

您可以将常用的配置设置和凭证保存在由 AWS CLI 维护的文件中。这些文件分为可按名称引用的多个部分。这称为“配置文件”。除非您另行指定,否则 CLI 将使用在名为 default 的配置文件中找到的设置。要使用备用设置,您可以创建和引用其他配置文件。您也可以通过设置某个支持的环境变量或使用命令行参数来覆盖个别设置。

配置设置存储在何处?

AWS CLI 将使用 aws configure 指定的凭证存储在主目录中名为 .aws 的文件夹中名为 credentials 的本地文件中。使用 aws configure 指定的其他配置选项存储在名为 config 的本地文件中,该文件也存储在主目录的 .aws 文件夹中。主目录位置因操作系统而异,但在 Windows 中使用环境变量 %UserProfile% 引用,在基于 Unix 的系统中使用 $HOME~(波形符)引用。

例如,下面的命令列出 .aws 文件夹的内容。

Linux, OS X, or Unix

$ ls ~/.aws

Windows

C:\> dir "%UserProfile%\.aws"

AWS CLI 使用两个文件将敏感的凭证信息(位于 ~/.aws/credentials 中)与不太敏感的配置选项(位于 ~/.aws/config 中)分开。

通过将 AWS_CONFIG_FILE 环境变量设置为另一个本地路径,可以为 config 文件指定非默认位置。有关更多信息,请参阅 环境变量

在 Config 文件中存储证书

AWS CLI 也可以从 config 文件读取凭证。您可以将所有配置文件设置保存在一个文件中。如果在一个配置文件的两个位置都有证书(假设您使用 aws configure 更新了配置文件密钥),则证书文件中的密钥有优先顺序。

这些文件也被各种语言软件开发工具包 (SDK) 使用。如果除 AWS CLI 外您还使用一个软件开发工具包,当证书不是存储在它自己的文件中时,您会收到其他警告。

CLI 为上一部分中配置的配置文件生成的文件如下所示。

~/.aws/credentials

[default] aws_access_key_id=AKIAIOSFODNN7EXAMPLE aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

~/.aws/config

[default] region=us-west-2 output=json

注意

上面的示例介绍具有单个默认配置文件的文件。有关具有多个命名配置文件的文件的示例,请参阅命名配置文件

当您使用共享配置文件指定 IAM 角色时,AWS CLI 将调用 AWS STS AssumeRole 操作来检索临时凭证。随后,这些凭证将存储起来(存储在 ~/.aws/cli/cache 中)。后续 AWS CLI 命令将使用缓存的临时凭证,直到它们过期,这时 AWS CLI 将自动刷新这些凭证。

支持的 config 文件设置

config 文件支持以下设置。将使用指定(或默认)配置文件中列出的值,除非它们被具有相同名称的环境变量或具有相同名称的命令行选项覆盖。

您可以通过直接使用文本编辑器编辑配置文件或使用 aws configure set 命令来配置这些设置。使用 --profile 设置指定要修改的配置文件。例如,以下命令设置名为 integ 的配置文件中的 region 设置。

aws configure set region us-west-2 --profile integ

您还可以使用 get 子命令检索任何设置的值。

$ aws configure get region --profile default us-west-2

如果输出为空,则不会显式设置该设置,并将使用默认值。

全局设置

aws_access_key_id

指定用作凭证一部分的对命令请求进行身份验证的 AWS 访问密钥。虽然它可以存储在 config 文件中,但我们建议您将其存储在 credentials 文件中。

可以被 AWS_ACCESS_KEY_ID 环境变量覆盖。请注意,您不能将访问密钥 ID 指定为命令行选项。

aws_access_key_id = 123456789012
aws_secret_access_key

指定用作凭证一部分的对命令请求进行身份验证的 AWS 私有密钥。虽然它可以存储在 config 文件中,但我们建议您将其存储在 credentials 文件中。

可以被 AWS_SECRET_ACCESS_KEY 环境变量覆盖。请注意,您不能将私有访问密钥指定为命令行选项。

aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
role_arn

指定要用于运行 AWS CLI 命令的 IAM 角色的 Amazon 资源名称 (ARN)。此外,还必须指定以下参数之一以标识有权代入此角色的凭证:

  • source_profile

  • credential_source

role_arn = arn:aws:iam::123456789012:role/role-name
source_profile

指定包含长期凭证的命名配置文件,AWS CLI 可使用这些凭证代入通过 role_arn 参数指定的角色。不能在同一配置文件中同时指定 source_profilecredential_source

source_profile = production-profile
credential_source

在 EC2 实例或 EC2 容器中使用,指定 AWS CLI 在何处可以找到要用于代入通过 role_arn 参数指定的角色的凭证。不能在同一配置文件中同时指定 source_profilecredential_source

此参数具有三个值:

  • Environment:从环境变量检索源凭证。

  • Ec2InstanceMetadata:将附加到 EC2 实例配置文件的 IAM 角色用作源凭证。

  • EcsContainer:将附加到 ECS 容器的 IAM 角色用作源凭证。

credential_source = Ec2InstanceMetadata
role_session_name

指定要附加到角色会话的名称。此值在 AWS CLI 调用 AssumeRole 操作时将提供给 RoleSessionName 参数,并成为代入角色用户 ARN 的一部分: arn:aws:sts::123456789012:assumed-role/role_name/role_session_name。此参数为可选参数。如果未提供此值,则将自动生成会话名称。此名称显示在与此会话关联的条目的 AWS CloudTrail 日志中。

role_session_name = maria_garcia_role
mfa_serial

代入角色时要使用的 MFA 设备的标识号。仅当代入角色的信任策略包含需要 MFA 身份验证的条件,此值才是必需的。该值可以是硬件设备(例如 GAHT12345678)的序列号,也可以是虚拟 MFA 设备(例如 arn:aws:iam::123456789012:mfa/user)的 Amazon 资源名称 (ARN)。

duration_seconds

指定角色会话的最大持续时间(以秒为单位)。该值的范围在 900 秒(15 分钟)到角色的最大会话持续时间设置之间。此参数为可选参数,默认情况下,该值设置为 3600 秒。

aws_session_token

指定 AWS 会话令牌。只有在手动指定临时安全凭证时才需要会话令牌。虽然它可以存储在 config 文件中,但我们建议您将其存储在 credentials 文件中。

可以被 AWS_SESSION_TOKEN 环境变量覆盖。您不能将会话令牌指定为命令行选项。

aws_session_token = AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5TthT+FvwqnKwRcOIfrRh3c/LTo6UDdyJwOOvEVPvLXCrrrUtdnniCEXAMPLE/IvU1dYUg2RVAJBanLiHb4IgRmpRV3zrkuWJOgQs8IZZaIv2BXIa2R4Olgk
external_id

第三方用于在其客户账户中代入角色的唯一标识符。这将映射到 AssumeRole 操作中的 ExternalId 参数。此参数是可选的,除非角色的信任策略指定 ExternalId 必须为特定值。

ca_bundle

指定用于验证 SSL 证书的 CA 证书捆绑包(具有 .pem 扩展名的文件)。

可以被 AWS_CA_BUNDLE 环境变量或 --ca-bundle 命令行选项覆盖。

ca_bundle = dev/apps/ca-certs/cabundle-2019mar05.pem
cli_follow_urlparam

指定 CLI 是否尝试跟踪命令行参数中以 http://https:// 开头的 URL 链接。启用后,将检索到的内容而不是 URL 用作参数值。

  • true:这是默认值。配置后,将抓取任何以 http://https:// 开头的字符串参数,并将任何下载的内容用作该命令的参数值。

  • false:CLI 不将以 http://https:// 开头的参数字符串值与其他字符串区别对待。

该条目没有等效的环境变量或命令行选项。

cli_follow_urlparam = false
cli_timestamp_format

指定输出中包含的时间戳值的格式。可以指定以下任一值:

  • none:这是默认值。按原样显示 HTTP 查询响应中收到的时间戳值。

  • iso8601:按 ISO 8601 指定的格式重新格式化时间戳。

该条目没有等效的环境变量或命令行选项。

cli_timestamp_format = iso8601
credential_process

指定 CLI 运行的外部命令,以生成或检索用于该命令的身份验证凭证。命令必须以特定格式返回凭证。有关如何使用该设置的更多信息,请参阅使用外部进程获取凭证

该条目没有等效的环境变量或命令行选项。

credential_process = /opt/bin/awscreds-retriever --username susan
web_identity_token_file

指定一个文件的路径,该文件包含由身份提供商提供的 OAuth 2.0 访问令牌或 OpenID Connect ID 令牌。AWS CLI 加载此文件的内容,并将其作为 WebIdentityToken 参数传递给 AssumeRoleWithWebIdentity 操作。

output

指定使用该配置文件请求的命令的默认输出格式。您可以指定以下任意值:

  • json:这是默认值。输出采用 JSON 字符串的格式。

  • text:输出采用多行制表符分隔的字符串值的格式,如果要将输出传递给文本处理器(如 grepsedawk),则该格式非常有用。

  • table:输出采用表格形式,使用字符 +|- 以形成单元格边框。它通常以“人性化”格式呈现信息,这种格式比其他格式更容易阅读,但从编程方面来讲不是那么有用。

可以被 AWS_DEFAULT_OUTPUT 环境变量或 --output 命令行选项覆盖。

output = table
parameter_validation

指定 CLI 客户端在将参数发送到 AWS 服务终端节点之前是否尝试验证参数。

  • true:这是默认值。配置后,CLI 将执行命令行参数的本地验证。

  • false:配置后,CLI 在将命令行参数发送到 AWS 服务终端节点前不对其进行验证。

该条目没有等效的环境变量或命令行选项。

parameter_validation = false
区域

对于使用该配置文件请求的命令,指定要将请求发送到的默认 AWS 区域。您可以指定可用于所选服务的任何区域代码(有关服务和区域代码的列表,请参阅 Amazon Web Services 一般参考 中的 AWS 区域和终端节点)。

可以被 AWS_DEFAULT_REGION 环境变量或 --region 命令行选项覆盖。

region = us-west-2
tcp_keepalive

指定 CLI 客户端是否使用 TCP keep-alive 数据包。

该条目没有等效的环境变量或命令行选项。

tcp_keepalive = false
api_versions

某些 AWS 服务维护多个 API 版本以支持向后兼容性。默认情况下,CLI 命令使用最新的可用 API 版本。您可以通过在 config 文件中包含 api_versions 设置来指定要用于配置文件的 API 版本。

这是一个“嵌套”设置,后跟一个或多个缩进行,每行标识一个 AWS 服务和要使用的 API 版本。请参阅每项服务的文档以了解可用的 API 版本。

以下示例显示如何为两种 AWS 服务指定 API 版本。这些 API 版本仅用于在包含这些设置的配置文件下运行的命令。

api_versions = ec2 = 2015-03-01 cloudfront = 2015-09-017

S3 自定义命令设置

Amazon S3 支持多项配置 CLI 如何执行 S3 操作的设置。一些设置适用于 s3apis3 命名空间中的所有 S3 命令。其他的则专门用于抽象常见操作的 S3“自定义”命令,而不仅仅是对 API 操作的一对一映射。aws s3 传输命令 cpsyncmvrm 具有可用于控制 S3 传输的其他设置。

可以通过在 config 文件中指定 s3 嵌套设置来配置所有这些选项。每个设置在其自己的行上缩进。

注意

这些设置完全是可选的。即使不配置这些设置中的任何一个,您也应该能够成功使用 aws s3 传输命令。提供这些设置是为了让您能够调整性能或匹配运行这些 aws s3 命令的特定环境。

以下设置适用于 s3s3api 命名空间中的任何 S3 命令。

use_accelerate_endpoint

为所有 s3s3api 命令使用 Amazon S3 加速终端节点。默认值为 False。该设置与 use_dualstack_endpoint 设置互斥。

如果设置为 true,CLI 会将所有 Amazon S3 请求定向到 s3-accelerate.amazonaws.com 的 S3 加速终端节点。要使用该终端节点,您必须让您的存储桶使用 S3 加速。使用存储桶寻址的虚拟样式发送所有请求:my-bucket.s3-accelerate.amazonaws.com。不会将任何 ListBucketsCreateBucketDeleteBucket 请求发送到加速终端节点,因为该终端节点不支持这些操作。如果将任何 s3s3api 命令的 --endpoint-url 参数设置为 https://s3-accelerate.amazonaws.comhttp://s3-accelerate.amazonaws.com,也可以设置该行为。

use_dualstack_endpoint

为所有 s3s3api 命令使用 Amazon S3 双 IPv4 / IPv6 终端节点。默认值为 False。该设置与 use_accelerate_endpoint 设置互斥。

如果设置为 true,CLI 会将所有 Amazon S3 请求定向到配置的区域的双 IPv4/IPv6 终端节点。

addressing_style

指定要使用的寻址样式。这将控制存储桶名称位于主机名还是 URL 中。有效值为:pathvirtualauto。默认值为 auto

构造 S3 终端节点的样式有两种。第一种称为 virtual,它将存储桶名称包含为主机名的一部分。例如:https://bucketname.s3.amazonaws.com。另一种为 path 样式 - 将存储桶名称视为 URI 中的路径。例如:https://s3.amazonaws.com/bucketname。CLI 中的默认值是使用 auto,它尝试尽可能使用 virtual 样式,但在需要时回退到 path 样式。例如,如果您的存储桶名称与 DNS 不兼容,则存储桶名称不能是主机名的一部分,而必须位于路径中。使用 auto 时,CLI 将检测这种情况并自动切换到 path 样式。如果将寻址方式设置为 path,您必须确保在 AWS CLI 中配置的 AWS 区域与存储桶的区域匹配。

payload_sigining_enabled

指定是否对 sigv4 负载进行 SHA256 签名。默认情况下,使用 https 时,将对流式上传(UploadPartPutObject)禁用该设置。默认情况下,对于流式上传(UploadPartPutObject),此设置为 false,但仅限存在 ContentMD5(默认生成)并且终端节点使用 HTTPS 时。

如果设置为 true,则 S3 请求接收 SHA256 校验和形式的额外内容验证(替您计算并包含在请求签名中)。如果设置为 false,则不计算校验和。禁用该设置可减少校验和计算产生的性能开销。

以下设置仅适用于 s3 命名空间命令集中的命令:

max_concurrent_requests

指定最大并发请求数。默认值是 10。

aws s3 传输命令是多线程的。在任意给定时间,都可以运行多个 Amazon S3 请求。例如,当您使用命令 aws s3 cp localdir s3://bucket/ --recursive 将文件上传到 S3 存储桶时,AWS CLI 可以并行上传文件 localdir/file1localdir/file2localdir/file3。设置 max_concurrent_requests 指定可同时运行的最大传输操作数。

您可能由于以下原因而需要更改该值:

  • 减小该值 – 在某些环境中,默认的 10 个并发请求可能会占用过多的系统资源。这可能导致连接超时或系统响应速度变慢。减小该值可减少 S3 传输命令消耗的资源。但不利后果是 S3 传输可能需要更长时间才能完成。如果使用了限制带宽的工具,则可能需要减小该值。

  • 增大该值 – 在某些情况下,您可能希望 S3 传输根据需要使用尽可能多的网络带宽,以尽可能快地完成任务。在这种情况下,默认的并发请求数可能不足以利用所有可用的网络带宽。增大该值可缩短完成 S3 传输所需的时间。

max_queue_size

指定任务队列中的最大任务数。默认值是 1000。

AWS CLI 在内部使用这样一种模型:将 S3 任务排队,然后由数量受 max_concurrent_requests 限制的使用者执行。任务通常映射到单个 S3 操作。例如,任务可以是 PutObjectTaskGetObjectTaskUploadPartTask。任务添加到队列的速度可能比使用者完成任务的速度快得多。为避免无限制增长,任务队列大小设置了特定大小的上限。该设置用于更改该最大数量的值。

您通常不需要更改该设置。该设置还对应于 CLI 知道需要运行的任务数。这意味着,默认情况下 CLI 只能查看前 1000 个任务。在 S3 命令得知执行的任务总数之前,进度线显示总计 ...。增大该值意味着 CLI 可更快得知所需任务的总数(假设排队速度快于任务完成速度)。但不利后果是更大的最大队列大小需要更多的内存。

multipart_threshold

指定 CLI 用于单个文件的分段传输的大小阈值。默认值为 8 MB。

上传、下载或复制文件时,如果文件超出该大小,S3 命令将切换到分段操作。您可以通过以下两种方式之一指定该值:

  • 文件大小(以字节为单位)。例如:1048576

  • 文件大小及大小后缀。您可以使用 KBMBGBTB。例如,10MB1GB

    注意

    S3 可能会对可用于分段操作的有效值施加约束。有关更多信息,请参阅 Amazon Simple Storage Service 开发人员指南 中的 S3 分段上传文档

multipart_chunksize

指定 CLI 用于单个文件的分段传输的块大小。默认值为 8 MB,最小值为 5 MB。

当文件传输超出 multipart_threshold 时,CLI 将文件分成该大小的块。可以使用与 multipart_threshold 相同的语法指定该值,即整数形式的字节数,或使用大小和后缀。

max_bandwidth

指定向 Amazon S3 上传数据和从其下载数据可使用的最大带宽。默认为无限制。

这限制了 S3 命令可用于向 S3 传输数据和从 S3 传输数据的最大带宽。该值仅适用于上传和下载;它不适用于复制或删除。值以每秒字节数表示。该值可以指定为:

  • 一个整数。例如,1048576 将最大带宽使用率设置为每秒 1 兆字节。

  • 一个整数,后跟速率后缀。可以使用以下格式指定速率后缀:KB/sMB/sGB/s。例如,300KB/s10MB/s

通常,我们建议您先尝试通过降低 max_concurrent_requests 来降低带宽使用率。如果这样做没有将带宽使用率限制到所需速率,接下来您可以使用 max_bandwidth 设置进一步限制带宽使用率。这是因为 max_concurrent_requests 控制当前运行的线程数。如果您先降低 max_bandwidth 但保持较高的 max_concurrent_requests 设置,则可能导致线程进行不必要等待,从而造成过多的资源消耗和连接超时。

这些设置都在 config 文件中的顶层 s3 关键字下设置,如以下 development 配置文件示例所示:

[profile development] s3 = max_concurrent_requests = 20 max_queue_size = 10000 multipart_threshold = 64MB multipart_chunksize = 16MB max_bandwidth = 50MB/s use_accelerate_endpoint = true addressing_style = path