cm-bot | 7018e2f | 2024-02-26 09:54:57 -0800 | [diff] [blame^] | 1 | --- |
| 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 | # ---------------------------------------------------------------------------- |
| 15 | subcategory: "Cloud Pub/Sub" |
| 16 | description: |- |
| 17 | A named resource to which messages are sent by publishers. |
| 18 | --- |
| 19 | |
| 20 | # google\_pubsub\_topic |
| 21 | |
| 22 | A named resource to which messages are sent by publishers. |
| 23 | |
| 24 | |
| 25 | To 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 |
| 32 | by 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 |
| 43 | resource "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 |
| 57 | resource "google_pubsub_topic" "example" { |
| 58 | name = "example-topic" |
| 59 | kms_key_name = google_kms_crypto_key.crypto_key.id |
| 60 | } |
| 61 | |
| 62 | resource "google_kms_crypto_key" "crypto_key" { |
| 63 | name = "example-key" |
| 64 | key_ring = google_kms_key_ring.key_ring.id |
| 65 | } |
| 66 | |
| 67 | resource "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 |
| 81 | resource "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 |
| 95 | resource "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 | |
| 101 | resource "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 | |
| 114 | The 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 | |
| 195 | In 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 | |
| 209 | This 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 | |
| 219 | Topic can be imported using any of these accepted formats: |
| 220 | |
| 221 | * `projects/{{project}}/topics/{{name}}` |
| 222 | * `{{project}}/{{name}}` |
| 223 | * `{{name}}` |
| 224 | |
| 225 | |
| 226 | In 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 |
| 229 | import { |
| 230 | id = "projects/{{project}}/topics/{{name}}" |
| 231 | to = google_pubsub_topic.default |
| 232 | } |
| 233 | ``` |
| 234 | |
| 235 | When 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 | |
| 245 | This resource supports [User Project Overrides](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/provider_reference#user_project_override). |