blob: d3d16606cc28378649b2d4f7ba9b21a6833d207d [file] [log] [blame]
---
# ----------------------------------------------------------------------------
#
# *** AUTO GENERATED CODE *** Type: MMv1 ***
#
# ----------------------------------------------------------------------------
#
# This file is automatically generated by Magic Modules and manual
# changes will be clobbered when the file is regenerated.
#
# Please read more about how to change this file in
# .github/CONTRIBUTING.md.
#
# ----------------------------------------------------------------------------
subcategory: "Compute Engine"
description: |-
Backend buckets allow you to use Google Cloud Storage buckets with HTTP(S)
load balancing.
---
# google\_compute\_backend\_bucket
Backend buckets allow you to use Google Cloud Storage buckets with HTTP(S)
load balancing.
An HTTP(S) load balancer can direct traffic to specified URLs to a
backend bucket rather than a backend service. It can send requests for
static content to a Cloud Storage bucket and requests for dynamic content
to a virtual machine instance.
To get more information about BackendBucket, see:
* [API documentation](https://cloud.google.com/compute/docs/reference/v1/backendBuckets)
* How-to Guides
* [Using a Cloud Storage bucket as a load balancer backend](https://cloud.google.com/compute/docs/load-balancing/http/backend-bucket)
<div class = "oics-button" style="float: right; margin: 0 0 -15px">
<a href="https://console.cloud.google.com/cloudshell/open?cloudshell_git_repo=https%3A%2F%2Fgithub.com%2Fterraform-google-modules%2Fdocs-examples.git&cloudshell_working_dir=backend_bucket_basic&cloudshell_image=gcr.io%2Fcloudshell-images%2Fcloudshell%3Alatest&open_in_editor=main.tf&cloudshell_print=.%2Fmotd&cloudshell_tutorial=.%2Ftutorial.md" target="_blank">
<img alt="Open in Cloud Shell" src="//gstatic.com/cloudssh/images/open-btn.svg" style="max-height: 44px; margin: 32px auto; max-width: 100%;">
</a>
</div>
## Example Usage - Backend Bucket Basic
```hcl
resource "google_compute_backend_bucket" "image_backend" {
name = "image-backend-bucket"
description = "Contains beautiful images"
bucket_name = google_storage_bucket.image_bucket.name
enable_cdn = true
}
resource "google_storage_bucket" "image_bucket" {
name = "image-store-bucket"
location = "EU"
}
```
<div class = "oics-button" style="float: right; margin: 0 0 -15px">
<a href="https://console.cloud.google.com/cloudshell/open?cloudshell_git_repo=https%3A%2F%2Fgithub.com%2Fterraform-google-modules%2Fdocs-examples.git&cloudshell_working_dir=backend_bucket_security_policy&cloudshell_image=gcr.io%2Fcloudshell-images%2Fcloudshell%3Alatest&open_in_editor=main.tf&cloudshell_print=.%2Fmotd&cloudshell_tutorial=.%2Ftutorial.md" target="_blank">
<img alt="Open in Cloud Shell" src="//gstatic.com/cloudssh/images/open-btn.svg" style="max-height: 44px; margin: 32px auto; max-width: 100%;">
</a>
</div>
## Example Usage - Backend Bucket Security Policy
```hcl
resource "google_compute_backend_bucket" "image_backend" {
name = "image-backend-bucket"
description = "Contains beautiful images"
bucket_name = google_storage_bucket.image_backend.name
enable_cdn = true
edge_security_policy = google_compute_security_policy.policy.id
}
resource "google_storage_bucket" "image_backend" {
name = "image-store-bucket"
location = "EU"
}
resource "google_compute_security_policy" "policy" {
name = "image-store-bucket"
description = "basic security policy"
type = "CLOUD_ARMOR_EDGE"
}
```
<div class = "oics-button" style="float: right; margin: 0 0 -15px">
<a href="https://console.cloud.google.com/cloudshell/open?cloudshell_git_repo=https%3A%2F%2Fgithub.com%2Fterraform-google-modules%2Fdocs-examples.git&cloudshell_working_dir=backend_bucket_query_string_whitelist&cloudshell_image=gcr.io%2Fcloudshell-images%2Fcloudshell%3Alatest&open_in_editor=main.tf&cloudshell_print=.%2Fmotd&cloudshell_tutorial=.%2Ftutorial.md" target="_blank">
<img alt="Open in Cloud Shell" src="//gstatic.com/cloudssh/images/open-btn.svg" style="max-height: 44px; margin: 32px auto; max-width: 100%;">
</a>
</div>
## Example Usage - Backend Bucket Query String Whitelist
```hcl
resource "google_compute_backend_bucket" "image_backend" {
name = "image-backend-bucket"
description = "Contains beautiful images"
bucket_name = google_storage_bucket.image_bucket.name
enable_cdn = true
cdn_policy {
cache_key_policy {
query_string_whitelist = ["image-version"]
}
}
}
resource "google_storage_bucket" "image_bucket" {
name = "image-backend-bucket"
location = "EU"
}
```
<div class = "oics-button" style="float: right; margin: 0 0 -15px">
<a href="https://console.cloud.google.com/cloudshell/open?cloudshell_git_repo=https%3A%2F%2Fgithub.com%2Fterraform-google-modules%2Fdocs-examples.git&cloudshell_working_dir=backend_bucket_include_http_headers&cloudshell_image=gcr.io%2Fcloudshell-images%2Fcloudshell%3Alatest&open_in_editor=main.tf&cloudshell_print=.%2Fmotd&cloudshell_tutorial=.%2Ftutorial.md" target="_blank">
<img alt="Open in Cloud Shell" src="//gstatic.com/cloudssh/images/open-btn.svg" style="max-height: 44px; margin: 32px auto; max-width: 100%;">
</a>
</div>
## Example Usage - Backend Bucket Include Http Headers
```hcl
resource "google_compute_backend_bucket" "image_backend" {
name = "image-backend-bucket"
description = "Contains beautiful images"
bucket_name = google_storage_bucket.image_bucket.name
enable_cdn = true
cdn_policy {
cache_key_policy {
include_http_headers = ["X-My-Header-Field"]
}
}
}
resource "google_storage_bucket" "image_bucket" {
name = "image-backend-bucket"
location = "EU"
}
```
## Argument Reference
The following arguments are supported:
* `bucket_name` -
(Required)
Cloud Storage bucket name.
* `name` -
(Required)
Name of the resource. Provided by the client when the resource is
created. The name must be 1-63 characters long, and comply with
RFC1035. Specifically, the name must be 1-63 characters long and
match the regular expression `[a-z]([-a-z0-9]*[a-z0-9])?` which means
the first character must be a lowercase letter, and all following
characters must be a dash, lowercase letter, or digit, except the
last character, which cannot be a dash.
- - -
* `cdn_policy` -
(Optional)
Cloud CDN configuration for this Backend Bucket.
Structure is [documented below](#nested_cdn_policy).
* `compression_mode` -
(Optional)
Compress text responses using Brotli or gzip compression, based on the client's Accept-Encoding header.
Possible values are: `AUTOMATIC`, `DISABLED`.
* `edge_security_policy` -
(Optional)
The security policy associated with this backend bucket.
* `custom_response_headers` -
(Optional)
Headers that the HTTP/S load balancer should add to proxied responses.
* `description` -
(Optional)
An optional textual description of the resource; provided by the
client when the resource is created.
* `enable_cdn` -
(Optional)
If true, enable Cloud CDN for this BackendBucket.
* `project` - (Optional) The ID of the project in which the resource belongs.
If it is not provided, the provider project is used.
<a name="nested_cdn_policy"></a>The `cdn_policy` block supports:
* `cache_key_policy` -
(Optional)
The CacheKeyPolicy for this CdnPolicy.
Structure is [documented below](#nested_cache_key_policy).
* `signed_url_cache_max_age_sec` -
(Optional)
Maximum number of seconds the response to a signed URL request will
be considered fresh. After this time period,
the response will be revalidated before being served.
When serving responses to signed URL requests,
Cloud CDN will internally behave as though
all responses from this backend had a "Cache-Control: public,
max-age=[TTL]" header, regardless of any existing Cache-Control
header. The actual headers served in responses will not be altered.
* `default_ttl` -
(Optional)
Specifies the default TTL for cached content served by this origin for responses
that do not have an existing valid TTL (max-age or s-max-age).
* `max_ttl` -
(Optional)
Specifies the maximum allowed TTL for cached content served by this origin.
* `client_ttl` -
(Optional)
Specifies the maximum allowed TTL for cached content served by this origin.
* `negative_caching` -
(Optional)
Negative caching allows per-status code TTLs to be set, in order to apply fine-grained caching for common errors or redirects.
* `negative_caching_policy` -
(Optional)
Sets a cache TTL for the specified HTTP status code. negativeCaching must be enabled to configure negativeCachingPolicy.
Omitting the policy and leaving negativeCaching enabled will use Cloud CDN's default cache TTLs.
Structure is [documented below](#nested_negative_caching_policy).
* `cache_mode` -
(Optional)
Specifies the cache setting for all responses from this backend.
The possible values are: USE_ORIGIN_HEADERS, FORCE_CACHE_ALL and CACHE_ALL_STATIC
Possible values are: `USE_ORIGIN_HEADERS`, `FORCE_CACHE_ALL`, `CACHE_ALL_STATIC`.
* `serve_while_stale` -
(Optional)
Serve existing content from the cache (if available) when revalidating content with the origin, or when an error is encountered when refreshing the cache.
* `request_coalescing` -
(Optional)
If true then Cloud CDN will combine multiple concurrent cache fill requests into a small number of requests to the origin.
* `bypass_cache_on_request_headers` -
(Optional)
Bypass the cache when the specified request headers are matched - e.g. Pragma or Authorization headers. Up to 5 headers can be specified. The cache is bypassed for all cdnPolicy.cacheMode settings.
Structure is [documented below](#nested_bypass_cache_on_request_headers).
<a name="nested_cache_key_policy"></a>The `cache_key_policy` block supports:
* `query_string_whitelist` -
(Optional)
Names of query string parameters to include in cache keys.
Default parameters are always included. '&' and '=' will
be percent encoded and not treated as delimiters.
* `include_http_headers` -
(Optional)
Allows HTTP request headers (by name) to be used in the
cache key.
<a name="nested_negative_caching_policy"></a>The `negative_caching_policy` block supports:
* `code` -
(Optional)
The HTTP status code to define a TTL against. Only HTTP status codes 300, 301, 308, 404, 405, 410, 421, 451 and 501
can be specified as values, and you cannot specify a status code more than once.
* `ttl` -
(Optional)
The TTL (in seconds) for which to cache responses with the corresponding status code. The maximum allowed value is 1800s
(30 minutes), noting that infrequently accessed objects may be evicted from the cache before the defined TTL.
<a name="nested_bypass_cache_on_request_headers"></a>The `bypass_cache_on_request_headers` block supports:
* `header_name` -
(Optional)
The header field name to match on when bypassing cache. Values are case-insensitive.
## Attributes Reference
In addition to the arguments listed above, the following computed attributes are exported:
* `id` - an identifier for the resource with format `projects/{{project}}/global/backendBuckets/{{name}}`
* `creation_timestamp` -
Creation timestamp in RFC3339 text format.
* `self_link` - The URI of the created resource.
## Timeouts
This resource provides the following
[Timeouts](https://developer.hashicorp.com/terraform/plugin/sdkv2/resources/retries-and-customizable-timeouts) configuration options:
- `create` - Default is 20 minutes.
- `update` - Default is 20 minutes.
- `delete` - Default is 20 minutes.
## Import
BackendBucket can be imported using any of these accepted formats:
* `projects/{{project}}/global/backendBuckets/{{name}}`
* `{{project}}/{{name}}`
* `{{name}}`
In Terraform v1.5.0 and later, use an [`import` block](https://developer.hashicorp.com/terraform/language/import) to import BackendBucket using one of the formats above. For example:
```tf
import {
id = "projects/{{project}}/global/backendBuckets/{{name}}"
to = google_compute_backend_bucket.default
}
```
When using the [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import), BackendBucket can be imported using one of the formats above. For example:
```
$ terraform import google_compute_backend_bucket.default projects/{{project}}/global/backendBuckets/{{name}}
$ terraform import google_compute_backend_bucket.default {{project}}/{{name}}
$ terraform import google_compute_backend_bucket.default {{name}}
```
## User Project Overrides
This resource supports [User Project Overrides](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/provider_reference#user_project_override).