terraform/website/source/docs/providers/aws/r/s3_bucket.html.markdown

407 lines
13 KiB
Markdown
Raw Normal View History

2014-07-23 22:38:12 +02:00
---
layout: "aws"
page_title: "AWS: aws_s3_bucket"
sidebar_current: "docs-aws-resource-s3-bucket"
2014-10-22 05:21:56 +02:00
description: |-
Provides a S3 bucket resource.
2014-07-23 22:38:12 +02:00
---
# aws\_s3\_bucket
Provides a S3 bucket resource.
## Example Usage
2015-05-01 15:48:08 +02:00
### Private Bucket w/ Tags
```hcl
2014-07-23 22:38:12 +02:00
resource "aws_s3_bucket" "b" {
bucket = "my_tf_test_bucket"
acl = "private"
2015-04-23 14:25:13 +02:00
tags {
Name = "My bucket"
Environment = "Dev"
}
2014-07-23 22:38:12 +02:00
}
```
2015-05-01 15:48:08 +02:00
### Static Website Hosting
```hcl
2015-05-01 15:48:08 +02:00
resource "aws_s3_bucket" "b" {
bucket = "s3-website-test.hashicorp.com"
acl = "public-read"
policy = "${file("policy.json")}"
website {
index_document = "index.html"
error_document = "error.html"
routing_rules = <<EOF
2016-02-25 19:19:23 +01:00
[{
"Condition": {
"KeyPrefixEquals": "docs/"
},
"Redirect": {
"ReplaceKeyPrefixWith": "documents/"
}
}]
EOF
}
2015-05-01 15:48:08 +02:00
}
```
2015-10-01 18:49:32 +02:00
### Using CORS
```hcl
2015-10-01 18:49:32 +02:00
resource "aws_s3_bucket" "b" {
bucket = "s3-website-test.hashicorp.com"
acl = "public-read"
cors_rule {
allowed_headers = ["*"]
allowed_methods = ["PUT", "POST"]
allowed_origins = ["https://s3-website-test.hashicorp.com"]
expose_headers = ["ETag"]
max_age_seconds = 3000
}
2015-10-01 18:49:32 +02:00
}
```
2015-09-06 04:25:24 +02:00
### Using versioning
```hcl
2015-09-06 04:25:24 +02:00
resource "aws_s3_bucket" "b" {
bucket = "my_tf_test_bucket"
acl = "private"
versioning {
enabled = true
}
2015-09-06 04:25:24 +02:00
}
```
2016-01-02 04:45:40 +01:00
### Enable Logging
```hcl
2016-01-02 04:45:40 +01:00
resource "aws_s3_bucket" "log_bucket" {
bucket = "my_tf_log_bucket"
acl = "log-delivery-write"
2016-01-02 04:45:40 +01:00
}
2016-01-02 04:45:40 +01:00
resource "aws_s3_bucket" "b" {
bucket = "my_tf_test_bucket"
acl = "private"
logging {
target_bucket = "${aws_s3_bucket.log_bucket.id}"
target_prefix = "log/"
}
2016-01-02 04:45:40 +01:00
}
```
### Using object lifecycle
```hcl
resource "aws_s3_bucket" "bucket" {
bucket = "my-bucket"
acl = "private"
lifecycle_rule {
id = "log"
prefix = "log/"
enabled = true
transition {
days = 30
storage_class = "STANDARD_IA"
}
transition {
days = 60
storage_class = "GLACIER"
}
expiration {
days = 90
}
}
lifecycle_rule {
id = "tmp"
prefix = "tmp/"
enabled = true
expiration {
date = "2016-01-12"
}
}
}
resource "aws_s3_bucket" "versioning_bucket" {
bucket = "my-versioning-bucket"
acl = "private"
versioning {
enabled = true
}
lifecycle_rule {
prefix = "config/"
enabled = true
noncurrent_version_transition {
days = 30
storage_class = "STANDARD_IA"
}
noncurrent_version_transition {
days = 60
storage_class = "GLACIER"
}
noncurrent_version_expiration {
days = 90
}
}
}
```
### Using replication configuration
```hcl
provider "aws" {
region = "eu-west-1"
}
provider "aws" {
alias = "central"
region = "eu-central-1"
}
resource "aws_iam_role" "replication" {
name = "tf-iam-role-replication-12345"
assume_role_policy = <<POLICY
{
"Version": "2012-10-17",
"Statement": [
{
"Action": "sts:AssumeRole",
"Principal": {
"Service": "s3.amazonaws.com"
},
"Effect": "Allow",
"Sid": ""
}
]
}
POLICY
}
resource "aws_iam_policy" "replication" {
name = "tf-iam-role-policy-replication-12345"
policy = <<POLICY
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"s3:GetReplicationConfiguration",
"s3:ListBucket"
],
"Effect": "Allow",
"Resource": [
"${aws_s3_bucket.bucket.arn}"
]
},
{
"Action": [
"s3:GetObjectVersion",
"s3:GetObjectVersionAcl"
],
"Effect": "Allow",
"Resource": [
"${aws_s3_bucket.bucket.arn}/*"
]
},
{
"Action": [
"s3:ReplicateObject",
"s3:ReplicateDelete"
],
"Effect": "Allow",
"Resource": "${aws_s3_bucket.destination.arn}/*"
}
]
}
POLICY
}
resource "aws_iam_policy_attachment" "replication" {
name = "tf-iam-role-attachment-replication-12345"
roles = ["${aws_iam_role.replication.name}"]
policy_arn = "${aws_iam_policy.replication.arn}"
}
resource "aws_s3_bucket" "destination" {
bucket = "tf-test-bucket-destination-12345"
region = "eu-west-1"
versioning {
enabled = true
}
}
resource "aws_s3_bucket" "bucket" {
provider = "aws.central"
bucket = "tf-test-bucket-12345"
acl = "private"
region = "eu-central-1"
versioning {
enabled = true
}
replication_configuration {
role = "${aws_iam_role.replication.arn}"
rules {
id = "foobar"
prefix = "foo"
status = "Enabled"
destination {
bucket = "${aws_s3_bucket.destination.arn}"
storage_class = "STANDARD"
}
}
}
}
```
2014-07-23 22:38:12 +02:00
## Argument Reference
The following arguments are supported:
* `bucket` - (Optional, Forces new resource) The name of the bucket. If omitted, Terraform will assign a random, unique name.
* `bucket_prefix` - (Optional, Forces new resource) Creates a unique bucket name beginning with the specified prefix. Conflicts with `name`.
2016-01-14 21:55:39 +01:00
* `acl` - (Optional) The [canned ACL](https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl) to apply. Defaults to "private".
* `policy` - (Optional) A valid [bucket policy](https://docs.aws.amazon.com/AmazonS3/latest/dev/example-bucket-policies.html) JSON document. Note that if the policy document is not specific enough (but still valid), Terraform may view the policy as constantly changing in a `terraform plan`. In this case, please make sure you use the verbose/specific version of the policy.
2015-04-23 14:25:13 +02:00
* `tags` - (Optional) A mapping of tags to assign to the bucket.
* `force_destroy` - (Optional, Default:false ) A boolean that indicates all objects should be deleted from the bucket so that the bucket can be destroyed without error. These objects are *not* recoverable.
2015-05-01 15:48:08 +02:00
* `website` - (Optional) A website object (documented below).
2016-01-14 21:55:39 +01:00
* `cors_rule` - (Optional) A rule of [Cross-Origin Resource Sharing](https://docs.aws.amazon.com/AmazonS3/latest/dev/cors.html) (documented below).
* `versioning` - (Optional) A state of [versioning](https://docs.aws.amazon.com/AmazonS3/latest/dev/Versioning.html) (documented below)
* `logging` - (Optional) A settings of [bucket logging](https://docs.aws.amazon.com/AmazonS3/latest/UG/ManagingBucketLogging.html) (documented below).
* `lifecycle_rule` - (Optional) A configuration of [object lifecycle management](http://docs.aws.amazon.com/AmazonS3/latest/dev/object-lifecycle-mgmt.html) (documented below).
* `acceleration_status` - (Optional) Sets the accelerate configuration of an existing bucket. Can be `Enabled` or `Suspended`.
* `region` - (Optional) If specified, the AWS region this bucket should reside in. Otherwise, the region used by the callee.
* `request_payer` - (Optional) Specifies who should bear the cost of Amazon S3 data transfer.
Can be either `BucketOwner` or `Requester`. By default, the owner of the S3 bucket would incur
the costs of any data transfer. See [Requester Pays Buckets](http://docs.aws.amazon.com/AmazonS3/latest/dev/RequesterPaysBuckets.html)
developer guide for more information.
* `replication_configuration` - (Optional) A configuration of [replication configuration](http://docs.aws.amazon.com/AmazonS3/latest/dev/crr.html) (documented below).
2015-05-01 15:48:08 +02:00
~> **NOTE:** You cannot use `acceleration_status` in `cn-north-1` or `us-gov-west-1`
provider/aws: `aws_s3_bucket` acceleration_status not available in china (#7999) or us-gov Fixes #7969 `acceleration_status` is not available in China or US-Gov data centers. Even querying for this will give the following: ``` Error refreshing state: 1 error(s) occurred: 2016/08/04 13:58:52 [DEBUG] plugin: waiting for all plugin processes to complete... * aws_s3_bucket.registry_cn: UnsupportedArgument: The request contained * an unsupported argument. status code: 400, request id: F74BA6AA0985B103 ``` We are going to stop any Read calls for acceleration status from these data centers ``` % make testacc TEST=./builtin/providers/aws % TESTARGS='-run=TestAccAWSS3Bucket_' ✹ ==> Checking that code complies with gofmt requirements... go generate $(go list ./... | grep -v /terraform/vendor/) TF_ACC=1 go test ./builtin/providers/aws -v -run=TestAccAWSS3Bucket_ -timeout 120m === RUN TestAccAWSS3Bucket_Notification --- PASS: TestAccAWSS3Bucket_Notification (409.46s) === RUN TestAccAWSS3Bucket_NotificationWithoutFilter --- PASS: TestAccAWSS3Bucket_NotificationWithoutFilter (166.84s) === RUN TestAccAWSS3Bucket_basic --- PASS: TestAccAWSS3Bucket_basic (133.48s) === RUN TestAccAWSS3Bucket_acceleration --- PASS: TestAccAWSS3Bucket_acceleration (282.06s) === RUN TestAccAWSS3Bucket_Policy --- PASS: TestAccAWSS3Bucket_Policy (332.14s) === RUN TestAccAWSS3Bucket_UpdateAcl --- PASS: TestAccAWSS3Bucket_UpdateAcl (225.96s) === RUN TestAccAWSS3Bucket_Website_Simple --- PASS: TestAccAWSS3Bucket_Website_Simple (358.15s) === RUN TestAccAWSS3Bucket_WebsiteRedirect --- PASS: TestAccAWSS3Bucket_WebsiteRedirect (380.38s) === RUN TestAccAWSS3Bucket_WebsiteRoutingRules --- PASS: TestAccAWSS3Bucket_WebsiteRoutingRules (258.29s) === RUN TestAccAWSS3Bucket_shouldFailNotFound --- PASS: TestAccAWSS3Bucket_shouldFailNotFound (92.24s) === RUN TestAccAWSS3Bucket_Versioning --- PASS: TestAccAWSS3Bucket_Versioning (654.19s) === RUN TestAccAWSS3Bucket_Cors --- PASS: TestAccAWSS3Bucket_Cors (143.58s) === RUN TestAccAWSS3Bucket_Logging --- PASS: TestAccAWSS3Bucket_Logging (249.79s) === RUN TestAccAWSS3Bucket_Lifecycle --- PASS: TestAccAWSS3Bucket_Lifecycle (259.87s) PASS ok github.com/hashicorp/terraform/builtin/providers/aws 3946.464s ``` thanks to @kwilczynski and @radeksimko for the research on how to handle the generic errors here Running these over a 4G tethering connection has been painful :)
2016-08-08 09:05:54 +02:00
The `website` object supports the following:
2015-05-01 15:48:08 +02:00
* `index_document` - (Required, unless using `redirect_all_requests_to`) Amazon S3 returns this index document when requests are made to the root domain or any of the subfolders.
2015-05-01 15:48:08 +02:00
* `error_document` - (Optional) An absolute path to the document to return in case of a 4XX error.
* `redirect_all_requests_to` - (Optional) A hostname to redirect all website requests for this bucket to. Hostname can optionally be prefixed with a protocol (`http://` or `https://`) to use when redirecting requests. The default is the protocol that is used in the original request.
2016-02-25 19:19:23 +01:00
* `routing_rules` - (Optional) A json array containing [routing rules](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-s3-websiteconfiguration-routingrules.html)
describing redirect behavior and when redirects are applied.
2014-07-23 22:38:12 +02:00
The `CORS` object supports the following:
2015-10-01 18:49:32 +02:00
* `allowed_headers` (Optional) Specifies which headers are allowed.
* `allowed_methods` (Required) Specifies which methods are allowed. Can be `GET`, `PUT`, `POST`, `DELETE` or `HEAD`.
* `allowed_origins` (Required) Specifies which origins are allowed.
* `expose_headers` (Optional) Specifies expose header in the response.
* `max_age_seconds` (Optional) Specifies time in seconds that browser can cache the response for a preflight request.
The `versioning` object supports the following:
2015-09-06 04:25:24 +02:00
* `enabled` - (Optional) Enable versioning. Once you version-enable a bucket, it can never return to an unversioned state. You can, however, suspend versioning on that bucket.
provider/aws: Support MFA delete for s3 bucket versioning (#10020) Fixes #7902 ``` % make testacc TEST=./builtin/providers/aws % TESTARGS='-run=TestAccAWSS3Bucket_' % ✹ ==> Checking that code complies with gofmt requirements... go generate $(go list ./... | grep -v /terraform/vendor/) 2016/12/12 12:11:45 Generated command/internal_plugin_list.go TF_ACC=1 go test ./builtin/providers/aws -v -run=TestAccAWSS3Bucket_ -timeout 120m === RUN TestAccAWSS3Bucket_importBasic --- PASS: TestAccAWSS3Bucket_importBasic (55.74s) === RUN TestAccAWSS3Bucket_importWithPolicy --- PASS: TestAccAWSS3Bucket_importWithPolicy (63.34s) === RUN TestAccAWSS3Bucket_Notification --- PASS: TestAccAWSS3Bucket_Notification (165.15s) === RUN TestAccAWSS3Bucket_NotificationWithoutFilter --- PASS: TestAccAWSS3Bucket_NotificationWithoutFilter (63.22s) === RUN TestAccAWSS3Bucket_basic --- PASS: TestAccAWSS3Bucket_basic (47.82s) === RUN TestAccAWSS3Bucket_region --- PASS: TestAccAWSS3Bucket_region (18.88s) === RUN TestAccAWSS3Bucket_acceleration --- PASS: TestAccAWSS3Bucket_acceleration (34.56s) === RUN TestAccAWSS3Bucket_RequestPayer --- PASS: TestAccAWSS3Bucket_RequestPayer (90.26s) === RUN TestAccAWSS3Bucket_Policy --- PASS: TestAccAWSS3Bucket_Policy (120.25s) === RUN TestAccAWSS3Bucket_UpdateAcl --- PASS: TestAccAWSS3Bucket_UpdateAcl (87.51s) === RUN TestAccAWSS3Bucket_Website_Simple --- PASS: TestAccAWSS3Bucket_Website_Simple (138.38s) === RUN TestAccAWSS3Bucket_WebsiteRedirect --- PASS: TestAccAWSS3Bucket_WebsiteRedirect (139.44s) === RUN TestAccAWSS3Bucket_WebsiteRoutingRules --- PASS: TestAccAWSS3Bucket_WebsiteRoutingRules (97.82s) === RUN TestAccAWSS3Bucket_shouldFailNotFound --- PASS: TestAccAWSS3Bucket_shouldFailNotFound (26.84s) === RUN TestAccAWSS3Bucket_Versioning --- PASS: TestAccAWSS3Bucket_Versioning (131.89s) === RUN TestAccAWSS3Bucket_Cors --- PASS: TestAccAWSS3Bucket_Cors (92.71s) === RUN TestAccAWSS3Bucket_Logging --- PASS: TestAccAWSS3Bucket_Logging (86.46s) === RUN TestAccAWSS3Bucket_Lifecycle --- PASS: TestAccAWSS3Bucket_Lifecycle (132.70s) === RUN TestAccAWSS3Bucket_Replication --- PASS: TestAccAWSS3Bucket_Replication (122.70s) === RUN TestAccAWSS3Bucket_ReplicationExpectVersioningValidationError --- PASS: TestAccAWSS3Bucket_ReplicationExpectVersioningValidationError (39.04s) ```
2016-12-12 23:34:03 +01:00
* `mfa_delete` - (Optional) Enable MFA delete for either `Change the versioning state of your bucket` or `Permanently delete an object version`. Default is `false`.
2015-09-06 04:25:24 +02:00
The `logging` object supports the following:
2016-01-02 04:45:40 +01:00
* `target_bucket` - (Required) The name of the bucket that will receive the log objects.
* `target_prefix` - (Optional) To specify a key prefix for log objects.
The `lifecycle_rule` object supports the following:
* `id` - (Optional) Unique identifier for the rule.
* `prefix` - (Required) Object key prefix identifying one or more objects to which the rule applies.
* `enabled` - (Required) Specifies lifecycle rule status.
* `abort_incomplete_multipart_upload_days` (Optional) Specifies the number of days after initiating a multipart upload when the multipart upload must be completed.
* `expiration` - (Optional) Specifies a period in the object's expire (documented below).
* `transition` - (Optional) Specifies a period in the object's transitions (documented below).
* `noncurrent_version_expiration` - (Optional) Specifies when noncurrent object versions expire (documented below).
* `noncurrent_version_transition` - (Optional) Specifies when noncurrent object versions transitions (documented below).
At least one of `expiration`, `transition`, `noncurrent_version_expiration`, `noncurrent_version_transition` must be specified.
The `expiration` object supports the following
* `date` (Optional) Specifies the date after which you want the corresponding action to take effect.
* `days` (Optional) Specifies the number of days after object creation when the specific rule action takes effect.
* `expired_object_delete_marker` (Optional) On a versioned bucket (versioning-enabled or versioning-suspended bucket), you can add this element in the lifecycle configuration to direct Amazon S3 to delete expired object delete markers.
The `transition` object supports the following
* `date` (Optional) Specifies the date after which you want the corresponding action to take effect.
* `days` (Optional) Specifies the number of days after object creation when the specific rule action takes effect.
* `storage_class` (Required) Specifies the Amazon S3 storage class to which you want the object to transition. Can be `STANDARD_IA` or `GLACIER`.
The `noncurrent_version_expiration` object supports the following
* `days` (Required) Specifies the number of days an object is noncurrent object versions expire.
The `noncurrent_version_transition` object supports the following
* `days` (Required) Specifies the number of days an object is noncurrent object versions expire.
* `storage_class` (Required) Specifies the Amazon S3 storage class to which you want the noncurrent versions object to transition. Can be `STANDARD_IA` or `GLACIER`.
The `replication_configuration` object supports the following:
* `role` - (Required) The ARN of the IAM role for Amazon S3 to assume when replicating the objects.
* `rules` - (Required) Specifies the rules managing the replication (documented below).
The `rules` object supports the following:
* `id` - (Optional) Unique identifier for the rule.
* `destination` - (Required) Specifies the destination for the rule (documented below).
* `prefix` - (Required) Object keyname prefix identifying one or more objects to which the rule applies. Set as an empty string to replicate the whole bucket.
* `status` - (Required) The status of the rule. Either `Enabled` or `Disabled`. The rule is ignored if status is not Enabled.
The `destination` object supports the following:
* `bucket` - (Required) The ARN of the S3 bucket where you want Amazon S3 to store replicas of the object identified by the rule.
* `storage_class` - (Optional) The class of storage used to store the object.
2014-07-23 22:38:12 +02:00
## Attributes Reference
The following attributes are exported:
2015-05-01 15:48:08 +02:00
* `id` - The name of the bucket.
* `arn` - The ARN of the bucket. Will be of format `arn:aws:s3:::bucketname`.
* `bucket_domain_name` - The bucket domain name. Will be of format `bucketname.s3.amazonaws.com`.
2016-01-14 21:55:39 +01:00
* `hosted_zone_id` - The [Route 53 Hosted Zone ID](https://docs.aws.amazon.com/general/latest/gr/rande.html#s3_website_region_endpoints) for this bucket's region.
2015-05-07 18:09:19 +02:00
* `region` - The AWS region this bucket resides in.
2015-05-01 15:48:08 +02:00
* `website_endpoint` - The website endpoint, if the bucket is configured with a website. If not, this will be an empty string.
2015-06-03 17:10:17 +02:00
* `website_domain` - The domain of the website endpoint, if the bucket is configured with a website. If not, this will be an empty string. This is used to create Route 53 alias records.
## Import
S3 bucket can be imported using the `bucket`, e.g.
```
$ terraform import aws_s3_bucket.bucket bucket-name
```