mmv1/products/spanner/Instance.yaml

# Copyright 2024 Google Inc.
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

---
name: 'Instance'
description: |
  An isolated set of Cloud Spanner resources on which databases can be
  hosted.
references:
  guides:
    'Official Documentation': 'https://cloud.google.com/spanner/'
  api: 'https://cloud.google.com/spanner/docs/reference/rest/v1/projects.instances'
docs:
id_format: '{{project}}/{{name}}'
base_url: 'projects/{{project}}/instances'
update_verb: 'PATCH'
import_format:
  - 'projects/{{project}}/instances/{{name}}'
  - '{{project}}/{{name}}'
  - '{{name}}'
timeouts:
  insert_minutes: 20
  update_minutes: 20
  delete_minutes: 20
autogen_async: true
async:
  actions: ['create', 'update']
  type: 'OpAsync'
  operation:
    base_url: '{{op_id}}'
  result:
    resource_inside_response: true
custom_code:
  constants: 'templates/terraform/constants/spanner_instance.go.tmpl'
  encoder: 'templates/terraform/encoders/spanner_instance.go.tmpl'
  update_encoder: 'templates/terraform/encoders/spanner_instance_update.go.tmpl'
  decoder: 'templates/terraform/decoders/spanner_instance.go.tmpl'
  post_create: 'templates/terraform/post_create/sleep.go.tmpl'
  pre_update: 'templates/terraform/pre_update/spanner_instance.go.tmpl'
  pre_delete: 'templates/terraform/pre_delete/spanner_instance.go.tmpl'
examples:
  - name: 'spanner_instance_basic'
    primary_resource_id: 'example'
      # Randomness
    skip_vcr: true
  - name: 'spanner_instance_processing_units'
    primary_resource_id: 'example'
      # Randomness
    skip_vcr: true
  - name: 'spanner_instance_multi_regional'
    primary_resource_id: 'example'
      # Randomness
    skip_vcr: true
virtual_fields:
  - name: 'force_destroy'
    description: |
      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.
    type: Boolean
    default_value: false
parameters:
properties:
  - name: 'name'
    type: String
    description: |
      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.
    immutable: true
        # This resource supports a sort of odd autogenerate-if-not-set
        # system, which is done in the encoder.  Consequently we have
        # to interpret "not set" as "use the name in state".
    default_from_api: true
    custom_flatten: 'templates/terraform/custom_flatten/name_from_self_link.tmpl'
    validation:
      regex: '^[a-z][-a-z0-9]*[a-z0-9]$'
  - name: 'config'
    type: ResourceRef
    description: |
      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).
    required: true
    immutable: true
    custom_expand: 'templates/terraform/custom_expand/spanner_instance_config.go.tmpl'
    resource: 'InstanceConfig'
    imports: 'name'
  - name: 'displayName'
    type: String
    description: |
      The descriptive name for this instance as it appears in UIs. Must be
      unique per project and between 4 and 30 characters in length.
    required: true
  - name: 'num_nodes'
    type: Integer
    description: |
      The number of nodes allocated to this instance. Exactly one of either node_count or processing_units
      must be present in terraform.
    api_name: nodeCount
    default_from_api: true
    exactly_one_of:
      - 'num_nodes'
      - 'processing_units'
      - 'autoscaling_config'
  - name: 'processingUnits'
    type: Integer
    description: |
      The number of processing units allocated to this instance. Exactly one of processing_units
      or node_count must be present in terraform.
    default_from_api: true
    exactly_one_of:
      - 'num_nodes'
      - 'processing_units'
      - 'autoscaling_config'
  - name: 'labels'
    type: KeyValueLabels
    description: |
      An object containing a list of "key": value pairs.
      Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
  - name: 'state'
    type: Enum
    description: |
      Instance status: `CREATING` or `READY`.
    output: true
    enum_values:
      - 'READY'
      - 'CREATING'
  - name: 'autoscalingConfig'
    type: NestedObject
    description: |
      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.
    exactly_one_of:
      - 'num_nodes'
      - 'processing_units'
      - 'autoscaling_config'
    properties:
      - name: 'autoscalingLimits'
        type: NestedObject
        description: |
          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.
        properties:
          - name: 'minProcessingUnits'
            type: Integer
            description: |
              Specifies minimum number of processing units allocated to the instance.
              If set, this number should be multiples of 1000.
            exactly_one_of:
              - 'min_processing_units'
              - 'min_nodes'
          - name: 'maxProcessingUnits'
            type: Integer
            description: |
              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.
            exactly_one_of:
              - 'max_processing_units'
              - 'max_nodes'
          - name: 'minNodes'
            type: Integer
            description: |
              Specifies number of nodes allocated to the instance. If set, this number
              should be greater than or equal to 1.
            exactly_one_of:
              - 'min_processing_units'
              - 'min_nodes'
            required_with:
              - 'max_nodes'
          - name: 'maxNodes'
            type: Integer
            description: |
              Specifies maximum number of nodes allocated to the instance. If set, this number
              should be greater than or equal to min_nodes.
            exactly_one_of:
              - 'max_processing_units'
              - 'max_nodes'
            required_with:
              - 'min_nodes'
      - name: 'autoscalingTargets'
        type: NestedObject
        description: |
          Defines scale in controls to reduce the risk of response latency
          and outages due to abrupt scale-in events
        properties:
          - name: 'highPriorityCpuUtilizationPercent'
            type: Integer
            description: |
              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)..
          - name: 'storageUtilizationPercent'
            type: Integer
            description: |
              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).

      - name: 'asymmetricAutoscalingOptions'
        type: Array
        description: |
          Asymmetric autoscaling options for specific replicas.
        item_type:
          type: NestedObject
          properties:
            - name: 'replicaSelection'
              type: NestedObject
              required: true
              properties:
                - name: 'location'
                  type: String
                  required: true
                  description: |
                    The location of the replica to apply asymmetric autoscaling options.
            - name: 'overrides'
              type: NestedObject
              required: true
              properties:
                - name: 'autoscalingLimits'
                  type: NestedObject
                  required: true
                  properties:
                    - name: 'minNodes'
                      type: Integer
                      required: true
                      description: |
                        The minimum number of nodes for this specific replica.
                    - name: 'maxNodes'
                      type: Integer
                      required: true
                      description: |
                        The maximum number of nodes for this specific replica.
  - name: 'edition'
    type: Enum
    description: |
      The edition selected for this instance. Different editions provide different capabilities at different price points.
    default_from_api: true
    enum_values:
      - 'EDITION_UNSPECIFIED'
      - 'STANDARD'
      - 'ENTERPRISE'
      - 'ENTERPRISE_PLUS'
  - name: 'defaultBackupScheduleType'
    type: Enum
    description: |
      Controls the default backup behavior for new databases within the instance.
      Note that `AUTOMATIC` is not permitted for free instances, as backups and backup schedules are not allowed for free instances.
      if unset or NONE, no default backup schedule will be created for new databases within the instance.
    default_from_api: true
    enum_values:
      - 'NONE'
      - 'AUTOMATIC'