---
# ----------------------------------------------------------------------------
#
#     ***     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: "Cloud Spanner"
description: |-
  An isolated set of Cloud Spanner resources on which databases can be
  hosted.
---

# google\_spanner\_instance

An isolated set of Cloud Spanner resources on which databases can be
hosted.


To get more information about Instance, see:

* [API documentation](https://cloud.google.com/spanner/docs/reference/rest/v1/projects.instances)
* How-to Guides
    * [Official Documentation](https://cloud.google.com/spanner/)

<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=spanner_instance_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 - Spanner Instance Basic


```hcl
resource "google_spanner_instance" "example" {
  config       = "regional-us-central1"
  display_name = "Test Spanner Instance"
  num_nodes    = 2
  labels = {
    "foo" = "bar"
  }
}
```
<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=spanner_instance_processing_units&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 - Spanner Instance Processing Units


```hcl
resource "google_spanner_instance" "example" {
  config       = "regional-us-central1"
  display_name = "Test Spanner Instance"
  processing_units    = 200
  labels = {
    "foo" = "bar"
  }
}
```
<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=spanner_instance_with_autoscaling&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 - Spanner Instance With Autoscaling


```hcl
resource "google_spanner_instance" "example" {
  config       = "regional-us-central1"
  display_name = "Test Spanner Instance"
  autoscaling_config {
    autoscaling_limits {
      // Define the minimum and maximum compute capacity allocated to the instance
      // Either use nodes or processing units to specify the limits,
      // but should use the same unit to set both the min_limit and max_limit.
      max_processing_units            = 3000 // OR max_nodes  = 3
      min_processing_units            = 2000 // OR min_nodes = 2
    }
    autoscaling_targets {
      high_priority_cpu_utilization_percent = 75
      storage_utilization_percent           = 90
    }
  }
  labels = {
    "foo" = "bar"
  }
}
```
<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=spanner_instance_multi_regional&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 - Spanner Instance Multi Regional


```hcl
resource "google_spanner_instance" "example" {
  config       = "nam-eur-asia1"
  display_name = "Multi Regional Instance"
  num_nodes    = 2
  labels = {
    "foo" = "bar"
  }
}
```

## Argument Reference

The following arguments are supported:


* `name` -
  (Required)
  A unique identifier for the instance, which cannot be changed after
  the instance is created. The name must be between 6 and 30 characters
  in length.

  If not provided, a random string starting with `tf-` will be selected.

* `config` -
  (Required)
  The name of the instance's configuration (similar but not
  quite the same as a region) which defines the geographic placement and
  replication of your databases in this instance. It determines where your data
  is stored. Values are typically of the form `regional-europe-west1` , `us-central` etc.
  In order to obtain a valid list please consult the
  [Configuration section of the docs](https://cloud.google.com/spanner/docs/instances).

* `display_name` -
  (Required)
  The descriptive name for this instance as it appears in UIs. Must be
  unique per project and between 4 and 30 characters in length.


- - -


* `num_nodes` -
  (Optional)
  The number of nodes allocated to this instance. Exactly one of either node_count or processing_units
  must be present in terraform.

* `processing_units` -
  (Optional)
  The number of processing units allocated to this instance. Exactly one of processing_units
  or node_count must be present in terraform.

* `labels` -
  (Optional)
  An object containing a list of "key": value pairs.
  Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

  **Note**: This field is non-authoritative, and will only manage the labels present in your configuration.
  Please refer to the field `effective_labels` for all of the labels present on the resource.

* `autoscaling_config` -
  (Optional)
  The autoscaling configuration. Autoscaling is enabled if this field is set.
  When autoscaling is enabled, num_nodes and processing_units are treated as,
  OUTPUT_ONLY fields and reflect the current compute capacity allocated to
  the instance.
  Structure is [documented below](#nested_autoscaling_config).

* `project` - (Optional) The ID of the project in which the resource belongs.
    If it is not provided, the provider project is used.

* `force_destroy` - (Optional) When deleting a spanner instance, this boolean option will delete all backups of this instance.
This must be set to true if you created a backup manually in the console.


<a name="nested_autoscaling_config"></a>The `autoscaling_config` block supports:

* `autoscaling_limits` -
  (Optional)
  Defines scale in controls to reduce the risk of response latency
  and outages due to abrupt scale-in events. Users can define the minimum and
  maximum compute capacity allocated to the instance, and the autoscaler will
  only scale within that range. Users can either use nodes or processing
  units to specify the limits, but should use the same unit to set both the
  min_limit and max_limit.
  Structure is [documented below](#nested_autoscaling_limits).

* `autoscaling_targets` -
  (Optional)
  Defines scale in controls to reduce the risk of response latency
  and outages due to abrupt scale-in events
  Structure is [documented below](#nested_autoscaling_targets).


<a name="nested_autoscaling_limits"></a>The `autoscaling_limits` block supports:

* `min_processing_units` -
  (Optional)
  Specifies minimum number of processing units allocated to the instance.
  If set, this number should be multiples of 1000.

* `max_processing_units` -
  (Optional)
  Specifies maximum number of processing units allocated to the instance.
  If set, this number should be multiples of 1000 and be greater than or equal to
  min_processing_units.

* `min_nodes` -
  (Optional)
  Specifies number of nodes allocated to the instance. If set, this number
  should be greater than or equal to 1.

* `max_nodes` -
  (Optional)
  Specifies maximum number of nodes allocated to the instance. If set, this number
  should be greater than or equal to min_nodes.

<a name="nested_autoscaling_targets"></a>The `autoscaling_targets` block supports:

* `high_priority_cpu_utilization_percent` -
  (Optional)
  Specifies the target high priority cpu utilization percentage that the autoscaler
  should be trying to achieve for the instance.
  This number is on a scale from 0 (no utilization) to 100 (full utilization)..

* `storage_utilization_percent` -
  (Optional)
  Specifies the target storage utilization percentage that the autoscaler
  should be trying to achieve for the instance.
  This number is on a scale from 0 (no utilization) to 100 (full utilization).

## Attributes Reference

In addition to the arguments listed above, the following computed attributes are exported:

* `id` - an identifier for the resource with format `{{project}}/{{name}}`

* `state` -
  Instance status: `CREATING` or `READY`.

* `terraform_labels` -
  The combination of labels configured directly on the resource
   and default labels configured on the provider.

* `effective_labels` -
  All of labels (key/value pairs) present on the resource in GCP, including the labels configured through Terraform, other clients and services.


## 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


Instance can be imported using any of these accepted formats:

* `projects/{{project}}/instances/{{name}}`
* `{{project}}/{{name}}`
* `{{name}}`


In Terraform v1.5.0 and later, use an [`import` block](https://developer.hashicorp.com/terraform/language/import) to import Instance using one of the formats above. For example:

```tf
import {
  id = "projects/{{project}}/instances/{{name}}"
  to = google_spanner_instance.default
}
```

When using the [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import), Instance can be imported using one of the formats above. For example:

```
$ terraform import google_spanner_instance.default projects/{{project}}/instances/{{name}}
$ terraform import google_spanner_instance.default {{project}}/{{name}}
$ terraform import google_spanner_instance.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).