mmv1/products/tpu/Node.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: 'Node'
description: |
  A Cloud TPU instance.
references:
  guides:
    'Official Documentation': 'https://cloud.google.com/tpu/docs/'
  api: 'https://cloud.google.com/tpu/docs/reference/rest/v1/projects.locations.nodes'
deprecation_message: >-
  `google_tpu_node` is deprecated and will be removed in a future major release.
  Use `google_tpu_v2_vm` instead. For moving from TPU Node to TPU VM architecture, see
  https://cloud.google.com/tpu/docs/system-architecture-tpu-vm#from-tpu-node-to-tpu-vm.
base_url: 'projects/{{project}}/locations/{{zone}}/nodes'
self_link: 'projects/{{project}}/locations/{{zone}}/nodes/{{name}}'
create_url: 'projects/{{project}}/locations/{{zone}}/nodes?nodeId={{name}}'
immutable: true
timeouts:
  insert_minutes: 20
  update_minutes: 20
  delete_minutes: 20
autogen_async: true
async:
  actions: ['create', 'delete', 'update']
  type: 'OpAsync'
  operation:
    base_url: '{{op_id}}'
  result:
    resource_inside_response: true
custom_code:
  constants: 'templates/terraform/constants/tpu_node.tmpl'
custom_diff:
  - 'tpuNodeCustomizeDiff'
sweeper:
  url_substitutions:
    - zone: "us-central1-b"
examples:
  - name: 'tpu_node_basic'
    primary_resource_id: 'tpu'
    vars:
      node_name: 'test-tpu'
    # resource is deprecated
    exclude_test: true
  - name: 'tpu_node_full'
    primary_resource_id: 'tpu'
    vars:
      node_name: 'test-tpu'
      global_address_name: 'my-global-address'
      network_name: 'tpu-node-network'
    exclude_test: true
  - name: 'tpu_node_full_test'
    primary_resource_id: 'tpu'
    vars:
      node_name: 'test-tpu'
      network_name: 'tpu-node-network'
    test_vars_overrides:
      'network_name': 'acctest.BootstrapSharedServiceNetworkingConnection(t, "vpc-network-1")'
    # resource is deprecated
    exclude_test: true
    exclude_docs: true
parameters:
  # TODO: resourceref?
  - name: 'zone'
    type: String
    description: |
      The GCP location for the TPU. If it is not provided, the provider zone is used.
    url_param_only: true
    immutable: true
    default_from_api: true
properties:
  - name: 'name'
    type: String
    description: |
      The immutable name of the TPU.
    required: true
    immutable: true
    custom_flatten: 'templates/terraform/custom_flatten/name_from_self_link.tmpl'
  - name: 'description'
    type: String
    description: |
      The user-supplied description of the TPU. Maximum of 512 characters.
    immutable: true
  - name: 'acceleratorType'
    type: String
    description: |
      The type of hardware accelerators associated with this node.
    required: true
    immutable: true
  - name: 'tensorflowVersion'
    type: String
    description: |
      The version of Tensorflow running in the Node.
    required: true
    update_url: 'projects/{{project}}/locations/{{zone}}/nodes/{{name}}:reimage'
    update_verb: 'POST'
  - name: 'network'
    type: String
    description: |
      The name of a network to peer the TPU node to. It must be a
      preexisting Compute Engine network inside of the project on which
      this API has been activated. If none is provided, "default" will be
      used.
    immutable: true
    default_from_api: true
    diff_suppress_func: 'tpgresource.CompareSelfLinkOrResourceName'
  - name: 'cidrBlock'
    type: String
    description: |
      The CIDR block that the TPU node will use when selecting an IP
      address. This CIDR block must be a /29 block; the Compute Engine
      networks API forbids a smaller block, and using a larger block would
      be wasteful (a node can only consume one IP address).

      Errors will occur if the CIDR block has already been used for a
      currently existing TPU node, the CIDR block conflicts with any
      subnetworks in the user's provided network, or the provided network
      is peered with another network that is using that CIDR block.
    immutable: true
    default_from_api: true
    conflicts:
      - use_service_networking
  - name: 'serviceAccount'
    type: String
    description: |
      The service account used to run the tensor flow services within the
      node. To share resources, including Google Cloud Storage data, with
      the Tensorflow job running in the Node, this account must have
      permissions to that data.
    output: true
  - name: 'useServiceNetworking'
    type: Boolean
    description: |
      Whether the VPC peering for the node is set up through Service Networking API.
      The VPC Peering should be set up before provisioning the node. If this field is set,
      cidr_block field should not be specified. If the network that you want to peer the
      TPU Node to is a Shared VPC network, the node must be created with this this field enabled.
    immutable: true
    conflicts:
      - cidr_block
    default_value: false
  - name: 'schedulingConfig'
    type: NestedObject
    description: |
      Sets the scheduling options for this TPU instance.
    immutable: true
    diff_suppress_func: 'compareTpuNodeSchedulingConfig'
    properties:
      - name: 'preemptible'
        type: Boolean
        description: |
          Defines whether the TPU instance is preemptible.
        required: true
        diff_suppress_func: 'compareTpuNodeSchedulingConfig'
  - name: 'networkEndpoints'
    type: Array
    description: |
      The network endpoints where TPU workers can be accessed and sent work.
      It is recommended that Tensorflow clients of the node first reach out
      to the first (index 0) entry.
    output: true
    item_type:
      type: NestedObject
      properties:
        - name: 'ipAddress'
          type: String
          description: |
            The IP address of this network endpoint.
          output: true
        - name: 'port'
          type: Integer
          description: |
            The port of this network endpoint.
          output: true
  - name: 'labels'
    type: KeyValueLabels
    description: Resource labels to represent user provided metadata.
    immutable: true