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

248 lines
9.0 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
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
```
resource "aws_s3_bucket" "b" {
bucket = "s3-website-test.hashicorp.com"
acl = "public-read"
2015-06-06 01:20:23 +02:00
policy = "${file("policy.json")}"
2015-05-01 15:48:08 +02:00
website {
index_document = "index.html"
error_document = "error.html"
2016-02-25 19:19:23 +01:00
routing_rules = <<EOF
[{
"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
```
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-09-06 04:25:24 +02:00
### Using versioning
```
resource "aws_s3_bucket" "b" {
bucket = "my_tf_test_bucket"
acl = "private"
versioning {
enabled = true
}
}
```
2016-01-02 04:45:40 +01:00
### Enable Logging
```
resource "aws_s3_bucket" "log_bucket" {
bucket = "my_tf_log_bucket"
acl = "log-delivery-write"
}
resource "aws_s3_bucket" "b" {
bucket = "my_tf_test_bucket"
acl = "private"
logging {
target_bucket = "${aws_s3_bucket.log_bucket.id}"
target_prefix = "log/"
}
}
```
### Using object lifecycle
```
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 = "log"
prefix = "tmp/"
enabled = true
expiration {
date = "2016-01-12"
}
}
}
resource "aws_s3_bucket" "versioning_bucket" {
bucket = "my-versioning-bucket"
acl = "private"
versioning {
enabled = false
}
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
}
}
}
```
2014-07-23 22:38:12 +02:00
## Argument Reference
The following arguments are supported:
* `bucket` - (Required) The name of the bucket.
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`.
2015-05-01 15:48:08 +02:00
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
~> **NOTE:** You cannot use `acceleration_status` in `cn-north-1` or `us-gov-west-1`
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.
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`.
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`
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.