blob: 622210ed41d7ab8c1618f8fac24e50d003b9fcde [file] [log] [blame]
cm-bot7018e2f2024-02-26 09:54:57 -08001---
2# ----------------------------------------------------------------------------
3#
4# *** AUTO GENERATED CODE *** Type: MMv1 ***
5#
6# ----------------------------------------------------------------------------
7#
8# This file is automatically generated by Magic Modules and manual
9# changes will be clobbered when the file is regenerated.
10#
11# Please read more about how to change this file in
12# .github/CONTRIBUTING.md.
13#
14# ----------------------------------------------------------------------------
15subcategory: "Cloud Pub/Sub"
16description: |-
17 A named resource to which messages are sent by publishers.
18---
19
20# google\_pubsub\_topic
21
22A named resource to which messages are sent by publishers.
23
24
25To get more information about Topic, see:
26
27* [API documentation](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics)
28* How-to Guides
29 * [Managing Topics](https://cloud.google.com/pubsub/docs/admin#managing_topics)
30
31~> **Note:** You can retrieve the email of the Google Managed Pub/Sub Service Account used for forwarding
32by using the `google_project_service_identity` resource.
33
34<div class = "oics-button" style="float: right; margin: 0 0 -15px">
35 <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=pubsub_topic_basic&cloudshell_image=gcr.io%2Fcloudshell-images%2Fcloudshell%3Alatest&open_in_editor=main.tf&cloudshell_print=.%2Fmotd&cloudshell_tutorial=.%2Ftutorial.md" target="_blank">
36 <img alt="Open in Cloud Shell" src="//gstatic.com/cloudssh/images/open-btn.svg" style="max-height: 44px; margin: 32px auto; max-width: 100%;">
37 </a>
38</div>
39## Example Usage - Pubsub Topic Basic
40
41
42```hcl
43resource "google_pubsub_topic" "example" {
44 name = "example-topic"
45
46 labels = {
47 foo = "bar"
48 }
49
50 message_retention_duration = "86600s"
51}
52```
53## Example Usage - Pubsub Topic Cmek
54
55
56```hcl
57resource "google_pubsub_topic" "example" {
58 name = "example-topic"
59 kms_key_name = google_kms_crypto_key.crypto_key.id
60}
61
62resource "google_kms_crypto_key" "crypto_key" {
63 name = "example-key"
64 key_ring = google_kms_key_ring.key_ring.id
65}
66
67resource "google_kms_key_ring" "key_ring" {
68 name = "example-keyring"
69 location = "global"
70}
71```
72<div class = "oics-button" style="float: right; margin: 0 0 -15px">
73 <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=pubsub_topic_geo_restricted&cloudshell_image=gcr.io%2Fcloudshell-images%2Fcloudshell%3Alatest&open_in_editor=main.tf&cloudshell_print=.%2Fmotd&cloudshell_tutorial=.%2Ftutorial.md" target="_blank">
74 <img alt="Open in Cloud Shell" src="//gstatic.com/cloudssh/images/open-btn.svg" style="max-height: 44px; margin: 32px auto; max-width: 100%;">
75 </a>
76</div>
77## Example Usage - Pubsub Topic Geo Restricted
78
79
80```hcl
81resource "google_pubsub_topic" "example" {
82 name = "example-topic"
83
84 message_storage_policy {
85 allowed_persistence_regions = [
86 "europe-west3",
87 ]
88 }
89}
90```
91## Example Usage - Pubsub Topic Schema Settings
92
93
94```hcl
95resource "google_pubsub_schema" "example" {
96 name = "example"
97 type = "AVRO"
98 definition = "{\n \"type\" : \"record\",\n \"name\" : \"Avro\",\n \"fields\" : [\n {\n \"name\" : \"StringField\",\n \"type\" : \"string\"\n },\n {\n \"name\" : \"IntField\",\n \"type\" : \"int\"\n }\n ]\n}\n"
99}
100
101resource "google_pubsub_topic" "example" {
102 name = "example-topic"
103
104 depends_on = [google_pubsub_schema.example]
105 schema_settings {
106 schema = "projects/my-project-name/schemas/example"
107 encoding = "JSON"
108 }
109}
110```
111
112## Argument Reference
113
114The following arguments are supported:
115
116
117* `name` -
118 (Required)
119 Name of the topic.
120
121
122- - -
123
124
125* `kms_key_name` -
126 (Optional)
127 The resource name of the Cloud KMS CryptoKey to be used to protect access
128 to messages published on this topic. Your project's PubSub service account
129 (`service-{{PROJECT_NUMBER}}@gcp-sa-pubsub.iam.gserviceaccount.com`) must have
130 `roles/cloudkms.cryptoKeyEncrypterDecrypter` to use this feature.
131 The expected format is `projects/*/locations/*/keyRings/*/cryptoKeys/*`
132
133* `labels` -
134 (Optional)
135 A set of key/value label pairs to assign to this Topic.
136
137 **Note**: This field is non-authoritative, and will only manage the labels present in your configuration.
138 Please refer to the field `effective_labels` for all of the labels present on the resource.
139
140* `message_storage_policy` -
141 (Optional)
142 Policy constraining the set of Google Cloud Platform regions where
143 messages published to the topic may be stored. If not present, then no
144 constraints are in effect.
145 Structure is [documented below](#nested_message_storage_policy).
146
147* `schema_settings` -
148 (Optional)
149 Settings for validating messages published against a schema.
150 Structure is [documented below](#nested_schema_settings).
151
152* `message_retention_duration` -
153 (Optional)
154 Indicates the minimum duration to retain a message after it is published
155 to the topic. If this field is set, messages published to the topic in
156 the last messageRetentionDuration are always available to subscribers.
157 For instance, it allows any attached subscription to seek to a timestamp
158 that is up to messageRetentionDuration in the past. If this field is not
159 set, message retention is controlled by settings on individual subscriptions.
160 The rotation period has the format of a decimal number, followed by the
161 letter `s` (seconds). Cannot be more than 31 days or less than 10 minutes.
162
163* `project` - (Optional) The ID of the project in which the resource belongs.
164 If it is not provided, the provider project is used.
165
166
167<a name="nested_message_storage_policy"></a>The `message_storage_policy` block supports:
168
169* `allowed_persistence_regions` -
170 (Required)
171 A list of IDs of GCP regions where messages that are published to
172 the topic may be persisted in storage. Messages published by
173 publishers running in non-allowed GCP regions (or running outside
174 of GCP altogether) will be routed for storage in one of the
175 allowed regions. An empty list means that no regions are allowed,
176 and is not a valid configuration.
177
178<a name="nested_schema_settings"></a>The `schema_settings` block supports:
179
180* `schema` -
181 (Required)
182 The name of the schema that messages published should be
183 validated against. Format is projects/{project}/schemas/{schema}.
184 The value of this field will be _deleted-schema_
185 if the schema has been deleted.
186
187* `encoding` -
188 (Optional)
189 The encoding of messages validated against schema.
190 Default value is `ENCODING_UNSPECIFIED`.
191 Possible values are: `ENCODING_UNSPECIFIED`, `JSON`, `BINARY`.
192
193## Attributes Reference
194
195In addition to the arguments listed above, the following computed attributes are exported:
196
197* `id` - an identifier for the resource with format `projects/{{project}}/topics/{{name}}`
198
199* `terraform_labels` -
200 The combination of labels configured directly on the resource
201 and default labels configured on the provider.
202
203* `effective_labels` -
204 All of labels (key/value pairs) present on the resource in GCP, including the labels configured through Terraform, other clients and services.
205
206
207## Timeouts
208
209This resource provides the following
210[Timeouts](https://developer.hashicorp.com/terraform/plugin/sdkv2/resources/retries-and-customizable-timeouts) configuration options:
211
212- `create` - Default is 20 minutes.
213- `update` - Default is 20 minutes.
214- `delete` - Default is 20 minutes.
215
216## Import
217
218
219Topic can be imported using any of these accepted formats:
220
221* `projects/{{project}}/topics/{{name}}`
222* `{{project}}/{{name}}`
223* `{{name}}`
224
225
226In Terraform v1.5.0 and later, use an [`import` block](https://developer.hashicorp.com/terraform/language/import) to import Topic using one of the formats above. For example:
227
228```tf
229import {
230 id = "projects/{{project}}/topics/{{name}}"
231 to = google_pubsub_topic.default
232}
233```
234
235When using the [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import), Topic can be imported using one of the formats above. For example:
236
237```
238$ terraform import google_pubsub_topic.default projects/{{project}}/topics/{{name}}
239$ terraform import google_pubsub_topic.default {{project}}/{{name}}
240$ terraform import google_pubsub_topic.default {{name}}
241```
242
243## User Project Overrides
244
245This resource supports [User Project Overrides](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/provider_reference#user_project_override).