AWS CloudFormation
User Guide (API Version 2010-05-15)
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。请点击 Amazon AWS 入门,可查看中国地区的具体差异

AWS::S3::Bucket

AWS::S3::Bucket 资源将在您创建 AWS CloudFormation 堆栈的同一 AWS 区域中创建 Amazon Simple Storage Service (Amazon S3) 存储桶。

您可以为您的存储桶设置删除策略,以控制在堆栈删除后 AWS CloudFormation 如何处理实例。对于 Amazon S3 存储桶,您可以选择保留删除 该存储桶。有关更多信息,请参阅 DeletionPolicy 属性

重要

您只能删除空存储桶。如果存储桶中包含内容,则删除操作会失败。

语法

要在 AWS CloudFormation 模板中声明此实体,请使用以下语法:

JSON

Copy
{ "Type" : "AWS::S3::Bucket", "Properties" : { "AccessControl" : String, "AccelerateConfiguration" : AccelerateConfiguration, "BucketName" : String, "CorsConfiguration" : CorsConfiguration, "LifecycleConfiguration" : LifecycleConfiguration, "LoggingConfiguration" : LoggingConfiguration, "MetricsConfigurations" : [ MetricsConfiguration, ... ] "NotificationConfiguration" : NotificationConfiguration, "ReplicationConfiguration" : ReplicationConfiguration, "Tags" : [ Resource Tag, ... ], "VersioningConfiguration" : VersioningConfiguration, "WebsiteConfiguration" : WebsiteConfiguration } }

YAML

Copy
Type: "AWS::S3::Bucket" Properties: AccessControl: String AccelerateConfiguration: AccelerateConfiguration BucketName: String CorsConfiguration: CorsConfiguration LifecycleConfiguration: LifecycleConfiguration LoggingConfiguration: LoggingConfiguration NotificationConfiguration: NotificationConfiguration MetricsConfigurations: - MetricsConfiguration ReplicationConfiguration: ReplicationConfiguration Tags: - Resource Tag VersioningConfiguration: VersioningConfiguration WebsiteConfiguration: WebsiteConfiguration

属性

AccessControl

对存储桶授予预定义权限的预装访问控制列表 (ACL)。有关标准 ACL 的更多信息,请参阅 Amazon Simple Storage Service 开发人员指南Amazon S3 文档中的标准 ACL

Required: No

Type: String

Valid values: AuthenticatedRead | AwsExecRead | BucketOwnerRead | BucketOwnerFullControl | LogDeliveryWrite | Private | PublicRead | PublicReadWrite

更新要求无需中断

AccelerateConfiguration

传输加速状态配置。有关更多信息,请参阅 Amazon Simple Storage Service 开发人员指南 中的 Amazon S3 传输加速

Required: No

类型Amazon S3 存储桶 AccelerateConfiguration

更新要求无需中断

BucketName

存储桶的名称。如果您不指定名称,则 AWS CloudFormation 将生成一个唯一物理 ID 并将该 ID 用作存储桶名称。有关更多信息,请参阅 名称类型。存储桶名称必须仅包含小写字母、数字、句点 (.) 和短划线 (-)。

重要

如果指定一个名称,您将无法执行需要替换此资源的更新。您可以执行不需要或者只需要部分中断的更新。如果必须替换资源,请指定新名称。

Required: No

Type: String

更新要求替换

CorsConfiguration

定义此存储桶中对象的跨源资源共享的规则。有关更多信息,请参阅 Amazon Simple Storage Service 开发人员指南 中的启用跨源资源共享部分。

Required: No

类型Amazon S3 存储桶 CorsConfiguration

更新要求无需中断

LifecycleConfiguration

定义 Amazon S3 如何在对象生命周期内管理对象的规则。有关更多信息,请参阅 Amazon Simple Storage Service 开发人员指南 中的对象生命周期管理

Required: No

类型Amazon S3 存储桶 LifecycleConfiguration

更新要求无需中断

LoggingConfiguration

定义日志存储位置的设置。

Required: No

类型Amazon S3 存储桶 LoggingConfiguration

更新要求无需中断

MetricsConfigurations

为存储桶中的 CloudWatch 请求指标定义指标配置的设置。

必需:否

类型Amazon S3 存储桶 MetricsConfiguration 的列表

更新要求无需中断

不允许重复项。

NotificationConfiguration

定义 Amazon S3 如何处理存储桶通知的配置。

Required: No

类型Amazon S3 存储桶 NotificationConfiguration

更新要求无需中断

ReplicationConfiguration

用于复制 S3 存储桶中对象的配置。要启用复制,您还必须通过 VersioningConfiguration 属性启用版本控制。

Amazon S3 只能在一个目标(S3 存储桶)中存储复制对象。目标存储桶必须已存在,并且与来源存储桶位于不同的 AWS 区域。

Required: No

Type: Amazon S3 存储桶 ReplicationConfiguration

更新要求无需中断

Tags

此 S3 存储桶的任意标记组 (键/值对)。

重要

我们建议将标签数量限制为七个。应用七个以上的标签会导致 AWS CLI 和 AWS CloudFormation 控制台及 API 操作无法列出 S3 存储桶的标签。

Required: No

Type: AWS CloudFormation 资源标签

更新要求无需中断

VersioningConfiguration

支持所有对象在此存储桶中存在多个变体。您可以启用版本控制来防止对象被错误删除或覆盖,或者是将对象存档以便检索对象的早期版本。

Required: No

Type: Amazon S3 存储桶 VersioningConfiguration

更新要求无需中断

WebsiteConfiguration

用于将存储段配置为静态网站的信息。更多有关信息,请参阅 Hosting Websites on Amazon S3

Required: No

Type: 网站配置类型

更新要求无需中断

返回值

Ref

当该资源的逻辑 ID 提供给 Ref内部函数时,Ref 将返回资源名称。

示例: mystack-mybucket-kdwwxmddtr2g.

有关使用 Ref 功能的更多信息,请参阅参考

Fn::GetAtt

Fn::GetAtt 返回一个此类型指定属性的值。以下为可用属性和示例返回值。

Arn

返回指定存储桶的 Amazon 资源名称 (ARN)。

示例:arn:aws:s3:::mybucket

DomainName

返回指定存储桶的 IPv4 DNS 名称。

示例:mystack-mybucket-kdwwxmddtr2g.s3.amazonaws.com

DualStackDomainName

返回指定存储桶的 IPv6 DNS 名称。

示例: mystack-mybucket-kdwwxmddtr2g.s3.dualstack.us-east-2.amazonaws.com/

有关双堆栈终端节点的更多信息,请参阅使用 Amazon S3 双堆栈终端节点

WebsiteURL

返回指定存储桶的 Amazon S3 网站终端节点。

示例 (IPv4):http://mystack-mybucket-kdwwxmddtr2g.s3-website-us-east-2.amazonaws.com/

示例 (IPv6):http://mystack-mybucket-kdwwxmddtr2g.s3.dualstack.us-east-2.amazonaws.com/

有关使用 Fn::GetAtt 的更多信息,请参见 Fn::GetAtt

示例

将复制配置 IAM 角色与 S3 存储桶关联

下面的示例创建一个 S3 存储桶,并使用 AWS Identity and Access Management (IAM) 角色向该存储桶授予对复制存储桶进行写入的权限。为避免循环依赖,角色的策略声明为单独的资源。存储桶依赖于 WorkItemBucketBackupRole 角色。如果策略已包含在角色中,则角色也依赖于存储桶。

JSON

Copy
"RecordServiceS3Bucket": { "Type": "AWS::S3::Bucket", "DeletionPolicy": "Retain", "Properties": { "ReplicationConfiguration": { "Role": { "Fn::GetAtt": [ "WorkItemBucketBackupRole", "Arn" ] }, "Rules": [{ "Destination": { "Bucket": { "Fn::Join": [ "", [ "arn:aws:s3:::", { "Fn::Join": [ "-", [ { "Ref": "AWS::Region" }, { "Ref": "AWS::StackName" }, "replicationbucket" ]] } ]] }, "StorageClass": "STANDARD" }, "Id": "Backup", "Prefix": "", "Status": "Enabled" }] }, "VersioningConfiguration": { "Status": "Enabled" } } }, "WorkItemBucketBackupRole": { "Type": "AWS::IAM::Role", "Properties": { "AssumeRolePolicyDocument": { "Statement": [{ "Action": [ "sts:AssumeRole" ], "Effect": "Allow", "Principal": { "Service": [ "s3.amazonaws.com" ] } }] } } }, "BucketBackupPolicy": { "Type": "AWS::IAM::Policy", "Properties": { "PolicyDocument": { "Statement": [{ "Action": [ "s3:GetReplicationConfiguration", "s3:ListBucket" ], "Effect": "Allow", "Resource": [{ "Fn::Join": [ "", [ "arn:aws:s3:::", { "Ref": "RecordServiceS3Bucket" } ] ] }] },{ "Action": [ "s3:GetObjectVersion", "s3:GetObjectVersionAcl" ], "Effect": "Allow", "Resource": [{ "Fn::Join": [ "", [ "arn:aws:s3:::", { "Ref": "RecordServiceS3Bucket" }, "/*" ] ] }] }, { "Action": [ "s3:ReplicateObject", "s3:ReplicateDelete" ], "Effect": "Allow", "Resource": [{ "Fn::Join": [ "", [ "arn:aws:s3:::", { "Fn::Join": [ "-", [ { "Ref": "AWS::Region" }, { "Ref": "AWS::StackName" }, "replicationbucket" ]] }, "/*" ]] }] }] }, "PolicyName": "BucketBackupPolicy", "Roles": [{ "Ref": "WorkItemBucketBackupRole" }] } }

YAML

Copy
RecordServiceS3Bucket: Type: AWS::S3::Bucket DeletionPolicy: Retain Properties: ReplicationConfiguration: Role: !GetAtt [WorkItemBucketBackupRole, Arn] Rules: - Destination: Bucket: !Join ['', ['arn:aws:s3:::', !Join ['-', [!Ref 'AWS::Region', !Ref 'AWS::StackName', replicationbucket]]]] StorageClass: STANDARD Id: Backup Prefix: '' Status: Enabled VersioningConfiguration: Status: Enabled WorkItemBucketBackupRole: Type: AWS::IAM::Role Properties: AssumeRolePolicyDocument: Statement: - Action: ['sts:AssumeRole'] Effect: Allow Principal: Service: [s3.amazonaws.com] BucketBackupPolicy: Type: AWS::IAM::Policy Properties: PolicyDocument: Statement: - Action: ['s3:GetReplicationConfiguration', 's3:ListBucket'] Effect: Allow Resource: - !Join ['', ['arn:aws:s3:::', !Ref 'RecordServiceS3Bucket']] - Action: ['s3:GetObjectVersion', 's3:GetObjectVersionAcl'] Effect: Allow Resource: - !Join ['', ['arn:aws:s3:::', !Ref 'RecordServiceS3Bucket', /*]] - Action: ['s3:ReplicateObject', 's3:ReplicateDelete'] Effect: Allow Resource: - !Join ['', ['arn:aws:s3:::', !Join ['-', [!Ref 'AWS::Region', !Ref 'AWS::StackName', replicationbucket]], /*]] PolicyName: BucketBackupPolicy Roles: [!Ref 'WorkItemBucketBackupRole']

配置具有路由规则的静态网站

在本示例中,AWS::S3::Bucket's Fn::GetAtt 值用于提供输出。如果发生 HTTP 404 错误,则路由规则将请求重定向到 EC2 实例,并在重定向中插入对象键前缀 report-404/。例如,如果请求名为 ExamplePage.html 的页面,而它导致了 HTTP 404 错误,该请求将路由到指定实例上的名为 report-404/ExamplePage.html 的页面。对于其他所有 HTTP 错误代码,会返回 error.html

JSON

Copy
"Resources" : { "S3Bucket" : { "Type" : "AWS::S3::Bucket", "Properties" : { "AccessControl" : "PublicRead", "BucketName" : "PublicBucket", "WebsiteConfiguration" : { "IndexDocument" : "index.html", "ErrorDocument" : "error.html", "RoutingRules": [ { "RoutingRuleCondition": { "HttpErrorCodeReturnedEquals": "404", "KeyPrefixEquals": "out1/" }, "RedirectRule": { "HostName": "ec2-11-22-333-44.compute-1.amazonaws.com", "ReplaceKeyPrefixWith": "report-404/" } } ] } }, "DeletionPolicy" : "Retain" } }, "Outputs" : { "WebsiteURL" : { "Value" : { "Fn::GetAtt" : [ "S3Bucket", "WebsiteURL" ] }, "Description" : "URL for website hosted on S3" }, "S3BucketSecureURL" : { "Value" : { "Fn::Join" : [ "", [ "https://", { "Fn::GetAtt" : [ "S3Bucket", "DomainName" ] } ] ] }, "Description" : "Name of S3 bucket to hold website content" } }

YAML

Copy
Resources: S3Bucket: Type: AWS::S3::Bucket Properties: AccessControl: PublicRead BucketName: PublicBucket WebsiteConfiguration: IndexDocument: index.html ErrorDocument: error.html RoutingRules: - RoutingRuleCondition: HttpErrorCodeReturnedEquals: '404' KeyPrefixEquals: out1/ RedirectRule: HostName: ec2-11-22-333-44.compute-1.amazonaws.com ReplaceKeyPrefixWith: report-404/ DeletionPolicy: Retain Outputs: WebsiteURL: Value: !GetAtt [S3Bucket, WebsiteURL] Description: URL for website hosted on S3 S3BucketSecureURL: Value: !Join ['', ['https://', !GetAtt [S3Bucket, DomainName]]] Description: Name of S3 bucket to hold website content

启用跨源资源共享

下面的示例模板演示具有两个跨源资源共享规则的 S3 存储桶。

JSON

Copy
{ "AWSTemplateFormatVersion": "2010-09-09", "Resources": { "S3Bucket": { "Type": "AWS::S3::Bucket", "Properties": { "AccessControl": "PublicReadWrite", "CorsConfiguration": { "CorsRules": [ { "AllowedHeaders": [ "*" ], "AllowedMethods": [ "GET" ], "AllowedOrigins": [ "*" ], "ExposedHeaders": [ "Date" ], "Id": "myCORSRuleId1", "MaxAge": "3600" }, { "AllowedHeaders": [ "x-amz-*" ], "AllowedMethods": [ "DELETE" ], "AllowedOrigins": [ "http://www.example1.com", "http://www.example2.com" ], "ExposedHeaders": [ "Connection", "Server", "Date" ], "Id": "myCORSRuleId2", "MaxAge": "1800" } ] } } } }, "Outputs": { "BucketName": { "Value": { "Ref": "S3Bucket" }, "Description": "Name of the sample Amazon S3 bucket with CORS enabled." } } }

YAML

Copy
AWSTemplateFormatVersion: '2010-09-09' Resources: S3Bucket: Type: AWS::S3::Bucket Properties: AccessControl: PublicReadWrite CorsConfiguration: CorsRules: - AllowedHeaders: ['*'] AllowedMethods: [GET] AllowedOrigins: ['*'] ExposedHeaders: [Date] Id: myCORSRuleId1 MaxAge: '3600' - AllowedHeaders: [x-amz-*] AllowedMethods: [DELETE] AllowedOrigins: ['http://www.example1.com', 'http://www.example2.com'] ExposedHeaders: [Connection, Server, Date] Id: myCORSRuleId2 MaxAge: '1800' Outputs: BucketName: Value: !Ref 'S3Bucket' Description: Name of the sample Amazon S3 bucket with CORS enabled.

管理 Amazon S3 对象的生命周期

下面的示例模板演示一个具有生命周期配置规则的 S3 存储桶。该规则应用于键前缀为 glacier 的所有对象。这些对象在一天之后转移到 Amazon Glacier,在一年之后删除。

JSON

Copy
{ "AWSTemplateFormatVersion": "2010-09-09", "Resources": { "S3Bucket": { "Type": "AWS::S3::Bucket", "Properties": { "AccessControl": "PublicReadWrite", "LifecycleConfiguration": { "Rules": [ { "Id": "GlacierRule", "Prefix": "glacier", "Status": "Enabled", "ExpirationInDays": "365", "Transitions": [ { "TransitionInDays": "1", "StorageClass": "Glacier" } ] } ] } } } }, "Outputs": { "BucketName": { "Value": { "Ref": "S3Bucket" }, "Description": "Name of the sample Amazon S3 bucket with a lifecycle configuration." } } }

YAML

Copy
AWSTemplateFormatVersion: '2010-09-09' Resources: S3Bucket: Type: AWS::S3::Bucket Properties: AccessControl: PublicReadWrite LifecycleConfiguration: Rules: - Id: GlacierRule Prefix: glacier Status: Enabled ExpirationInDays: '365' Transitions: - TransitionInDays: '1' StorageClass: Glacier Outputs: BucketName: Value: !Ref 'S3Bucket' Description: Name of the sample Amazon S3 bucket with a lifecycle configuration.

针对特定 S3 存储桶的日志访问请求

下面的示例模板创建两个 S3 存储桶。LoggingBucket 存储桶存储来自 S3Bucket 存储桶的日志。日志记录存储桶需要日志传输写入权限才能接收来自 S3Bucket 存储桶的日志。

JSON

Copy
{ "AWSTemplateFormatVersion": "2010-09-09", "Resources": { "S3Bucket": { "Type": "AWS::S3::Bucket", "Properties": { "AccessControl": "PublicRead", "LoggingConfiguration": { "DestinationBucketName": {"Ref" : "LoggingBucket"}, "LogFilePrefix": "testing-logs" } } }, "LoggingBucket": { "Type": "AWS::S3::Bucket", "Properties": { "AccessControl": "LogDeliveryWrite" } } }, "Outputs": { "BucketName": { "Value": { "Ref": "S3Bucket" }, "Description": "Name of the sample Amazon S3 bucket with a logging configuration." } } }

YAML

Copy
AWSTemplateFormatVersion: '2010-09-09' Resources: S3Bucket: Type: AWS::S3::Bucket Properties: AccessControl: PublicRead LoggingConfiguration: DestinationBucketName: !Ref 'LoggingBucket' LogFilePrefix: testing-logs LoggingBucket: Type: AWS::S3::Bucket Properties: AccessControl: LogDeliveryWrite Outputs: BucketName: Value: !Ref 'S3Bucket' Description: Name of the sample Amazon S3 bucket with a logging configuration.

接收发送到 SNS 主题的 S3 存储桶通知

下面的示例模板演示一个 S3 存储桶,该存储桶具有一个在 Amazon S3 丢失对象的所有副本时向指定 SNS 主题发送事件的通知配置。

JSON

Copy
{ "AWSTemplateFormatVersion": "2010-09-09", "Resources": { "S3Bucket": { "Type": "AWS::S3::Bucket", "Properties": { "AccessControl": "PublicReadWrite", "NotificationConfiguration": { "TopicConfigurations": [ { "Topic": "arn:aws:sns:us-east-1:123456789012:TestTopic", "Event": "s3:ReducedRedundancyLostObject" } ] } } } }, "Outputs": { "BucketName": { "Value": { "Ref": "S3Bucket" }, "Description": "Name of the sample Amazon S3 bucket with a notification configuration." } } }

YAML

Copy
AWSTemplateFormatVersion: '2010-09-09' Resources: S3Bucket: Type: AWS::S3::Bucket Properties: AccessControl: PublicReadWrite NotificationConfiguration: TopicConfigurations: - Topic: arn:aws:sns:us-east-1:123456789012:TestTopic Event: s3:ReducedRedundancyLostObject Outputs: BucketName: Value: !Ref 'S3Bucket' Description: Name of the sample Amazon S3 bucket with a notification configuration.

复制对象并将它们存储在另一个 S3 存储桶中

下面的示例包含两条复制规则。Amazon S3 复制带有 MyPrefixMyOtherPrefix 前缀的对象并将它们存储在 my-replication-bucket 存储桶中,此存储桶必须与 S3Bucket 存储桶位于不同的 AWS 区域。

JSON

Copy
"S3Bucket": { "Type": "AWS::S3::Bucket", "Properties": { "VersioningConfiguration":{ "Status":"Enabled" }, "ReplicationConfiguration": { "Role": "arn:aws:iam::123456789012:role/replication_role", "Rules": [ { "Id": "MyRule1", "Status": "Enabled", "Prefix": "MyPrefix", "Destination": { "Bucket": "arn:aws:s3:::my-replication-bucket", "StorageClass": "STANDARD" } }, { "Status": "Enabled", "Prefix": "MyOtherPrefix", "Destination": { "Bucket": "arn:aws:s3:::my-replication-bucket" } } ] } } }

YAML

Copy
S3Bucket: Type: AWS::S3::Bucket Properties: VersioningConfiguration: Status: Enabled ReplicationConfiguration: Role: arn:aws:iam::123456789012:role/replication_role Rules: - Id: MyRule1 Status: Enabled Prefix: MyPrefix Destination: Bucket: arn:aws:s3:::my-replication-bucket StorageClass: STANDARD - Status: Enabled Prefix: MyOtherPrefix Destination: Bucket: arn:aws:s3:::my-replication-bucket

更多信息