mmv1/products/compute/Image.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: 'Image'
kind: 'compute#image'
description: |
  Represents an Image resource.

  Google Compute Engine uses operating system images to create the root
  persistent disks for your instances. You specify an image when you create
  an instance. Images contain a boot loader, an operating system, and a
  root file system. Linux operating system images are also capable of
  running containers on Compute Engine.

  Images can be either public or custom.

  Public images are provided and maintained by Google, open-source
  communities, and third-party vendors. By default, all projects have
  access to these images and can use them to create instances.  Custom
  images are available only to your project. You can create a custom image
  from root persistent disks and other images. Then, use the custom image
  to create an instance.
references:
  guides:
    'Official Documentation': 'https://cloud.google.com/compute/docs/images'
  api: 'https://cloud.google.com/compute/docs/reference/v1/images'
docs:
base_url: 'projects/{{project}}/global/images'
has_self_link: true
immutable: true
timeouts:
  insert_minutes: 20
  update_minutes: 20
  delete_minutes: 20
async:
  actions: ['create', 'delete', 'update']
  type: 'OpAsync'
  operation:
    base_url: '{{op_id}}'
  result:
    resource_inside_response: false
collection_url_key: 'items'
iam_policy:
  allowed_iam_role: 'roles/compute.imageUser'
  parent_resource_attribute: 'image'
  iam_conditions_request_type: 'QUERY_PARAM'
  example_config_body: 'templates/terraform/iam/iam_attributes.go.tmpl'
custom_code:
examples:
  - name: 'image_basic'
    primary_resource_id: 'example'
    primary_resource_name: 'fmt.Sprintf("tf-test-example-image%s", context["random_suffix"])'
    vars:
      disk_name: 'example-disk'
      image_name: 'example-image'
  - name: 'image_guest_os'
    primary_resource_id: 'example'
    vars:
      disk_name: 'example-disk'
      image_name: 'example-image'
  - name: 'image_basic_storage_location'
    primary_resource_id: 'example'
    vars:
      disk_name: 'example-disk'
      image_name: 'example-sl-image'
      primary_resource_name: 'fmt.Sprintf("tf-test-sl-example-image%s", context["random_suffix"])'
parameters:
properties:
  - name: 'archiveSizeBytes'
    type: Integer
    description: |
      Size of the image tar.gz archive stored in Google Cloud Storage (in
      bytes).
    output: true
  - name: 'creationTimestamp'
    type: Time
    description: 'Creation timestamp in RFC3339 text format.'
    output: true
  - name: 'description'
    type: String
    description: |
      An optional description of this resource. Provide this property when
      you create the resource.
  - name: 'storageLocations'
    type: Array
    description: |
      Cloud Storage bucket storage location of the image
      (regional or multi-regional).
      Reference link: https://cloud.google.com/compute/docs/reference/rest/v1/images
    default_from_api: true
    item_type:
      type: String
  - name: 'diskSizeGb'
    type: Integer
    description: |
      Size of the image when restored onto a persistent disk (in GB).
    # TODO(alexstephen): Build family support.
    # Families use a different API
    default_from_api: true
  - name: 'family'
    type: String
    description: |
      The name of the image family to which this image belongs. You can
      create disks by specifying an image family instead of a specific
      image name. The image family always returns its latest image that is
      not deprecated. The name of the image family must comply with
      RFC1035.
  - name: 'guestOsFeatures'
    type: Array
    description: |
      A list of features to enable on the guest operating system.
      Applicable only for bootable images.
    is_set: true
    default_from_api: true
    item_type:
      type: NestedObject
      properties:
        - name: 'type'
          type: Enum
          description: |
            The type of supported feature. Read [Enabling guest operating system features](https://cloud.google.com/compute/docs/images/create-delete-deprecate-private-images#guest-os-features) to see a list of available options.
          required: true
          enum_values:
            - 'MULTI_IP_SUBNET'
            - 'SECURE_BOOT'
            - 'SEV_CAPABLE'
            - 'UEFI_COMPATIBLE'
            - 'VIRTIO_SCSI_MULTIQUEUE'
            - 'WINDOWS'
            - 'GVNIC'
            - 'IDPF'
            - 'SEV_LIVE_MIGRATABLE'
            - 'SEV_SNP_CAPABLE'
            - 'SUSPEND_RESUME_COMPATIBLE'
            - 'TDX_CAPABLE'
            - 'SEV_LIVE_MIGRATABLE_V2'
  - name: 'imageEncryptionKey'
    type: NestedObject
    description: |
      Encrypts the image using a customer-supplied encryption key.

      After you encrypt an image with a customer-supplied key, you must
      provide the same key if you use the image later (e.g. to create a
      disk from the image)
    properties:
      - name: 'kmsKeySelfLink'
        type: String
        description: |
          The self link of the encryption key that is stored in Google Cloud
          KMS.
        api_name: kmsKeyName
        diff_suppress_func: 'tpgresource.CompareSelfLinkRelativePaths'
        custom_flatten: 'templates/terraform/custom_flatten/image_kms_key_name.go.tmpl'
      - name: 'kmsKeyServiceAccount'
        type: String
        description: |
          The service account being used for the encryption request for the
          given KMS key. If absent, the Compute Engine default service
          account is used.
      - name: 'rawKey'
        type: String
        description: |
          Specifies a 256-bit customer-supplied encryption key, encoded in
          RFC 4648 base64 to either encrypt or decrypt this resource.
        ignore_read: true
        sensitive: true
      - name: 'rsaEncryptedKey'
        type: String
        description: |
          Specifies a 256-bit customer-supplied encryption key, encoded in
          RFC 4648 base64 to either encrypt or decrypt this resource.
        ignore_read: true
        sensitive: true
  - name: 'labels'
    type: KeyValueLabels
    description: Labels to apply to this Image.
    update_url: 'projects/{{project}}/global/images/{{name}}/setLabels'
    update_verb: 'POST'
  - name: 'labelFingerprint'
    type: Fingerprint
    description: |
      The fingerprint used for optimistic locking of this resource. Used
      internally during updates.
    output: true
    update_url: 'projects/{{project}}/global/images/{{name}}/setLabels'
    update_verb: 'POST'
    key_expander: ''
  - name: 'licenses'
    type: Array
    description: Any applicable license URI.
    default_from_api: true
    custom_expand: 'templates/terraform/custom_expand/array_resourceref_with_validation.go.tmpl'
    item_type:
      name: 'license'
      type: ResourceRef
      description: 'An applicable license URI'
      resource: 'License'
      imports: 'selfLink'
  - name: 'name'
    type: String
    description: |
      Name of the resource; provided by the client when the resource is
      created. The name must be 1-63 characters long, and comply with
      RFC1035. Specifically, the name must be 1-63 characters long and
      match the regular expression `[a-z]([-a-z0-9]*[a-z0-9])?` which means
      the first character must be a lowercase letter, and all following
      characters must be a dash, lowercase letter, or digit, except the
      last character, which cannot be a dash.
    required: true
  - name: 'rawDisk'
    type: NestedObject
    description: The parameters of the raw disk image.
    ignore_read: true
    properties:
      - name: 'containerType'
        type: Enum
        description: |
          The format used to encode and transmit the block device, which
          should be TAR. This is just a container and transmission format
          and not a runtime format. Provided by the client when the disk
          image is created.
        default_value: "TAR"
        enum_values:
          - 'TAR'
      - name: 'sha1'
        type: String
        description: |
          An optional SHA1 checksum of the disk image before unpackaging.
          This is provided by the client when the disk image is created.
        api_name: sha1Checksum
        diff_suppress_func: 'tpgresource.Base64DiffSuppress'
      # TODO(alexstephen): Figure out cross-module ResourceRefs
      - name: 'source'
        type: String
        description: |
          The full Google Cloud Storage URL where disk storage is stored
          You must provide either this property or the sourceDisk property
          but not both.
        required: true
  - name: 'sourceDisk'
    type: ResourceRef
    description: |
      The source disk to create this image based on.
      You must provide either this property or the
      rawDisk.source property but not both to create an image.
    custom_expand: 'templates/terraform/custom_expand/resourceref_with_validation.go.tmpl'
    resource: 'Disk'
    imports: 'selfLink'
  - name: 'sourceDiskEncryptionKey'
    type: NestedObject
    ignore_read: true
    description: |
      The customer-supplied encryption key of the source disk. Required if
      the source disk is protected by a customer-supplied encryption key.
    properties:
      - name: 'rawKey'
        type: String
        sensitive: true
        description: |
          Specifies a 256-bit customer-supplied encryption key, encoded in
          RFC 4648 base64 to either encrypt or decrypt this resource.
      - name: 'rsaEncryptedKey'
        type: String
        sensitive: true
        description: |
          Specifies an RFC 4648 base64 encoded, RSA-wrapped 2048-bit
          customer-supplied encryption key to either encrypt or decrypt
          this resource. You can provide either the rawKey or the rsaEncryptedKey.
      - name: 'kmsKeySelfLink'
        type: String
        api_name: kmsKeyName
        diff_suppress_func: 'tpgresource.CompareSelfLinkRelativePaths'
        custom_flatten: 'templates/terraform/custom_flatten/image_kms_key_name.go.tmpl'
        description: |
          The self link of the encryption key used to decrypt this resource. Also called KmsKeyName
          in the cloud console. Your project's Compute Engine System service account
          (`service-{{PROJECT_NUMBER}}@compute-system.iam.gserviceaccount.com`) must have
          `roles/cloudkms.cryptoKeyEncrypterDecrypter` to use this feature.
          See https://cloud.google.com/compute/docs/disks/customer-managed-encryption#encrypt_a_new_persistent_disk_with_your_own_keys
      - name: 'kmsKeyServiceAccount'
        type: String
        description: |
          The service account being used for the encryption request for the
          given KMS key. If absent, the Compute Engine default service
          account is used.
  - name: 'sourceImage'
    type: ResourceRef
    description: |
      URL of the source image used to create this image. In order to create an image, you must provide the full or partial
      URL of one of the following:

      * The selfLink URL
      * This property
      * The rawDisk.source URL
      * The sourceDisk URL
    custom_expand: 'templates/terraform/custom_expand/resourceref_with_validation.go.tmpl'
    resource: 'Image'
    imports: 'selfLink'
  - name: 'sourceImageEncryptionKey'
    type: NestedObject
    ignore_read: true
    description: |
      The customer-supplied encryption key of the source image. Required if
      the source image is protected by a customer-supplied encryption key.
    properties:
      - name: 'rawKey'
        type: String
        sensitive: true
        description: |
          Specifies a 256-bit customer-supplied encryption key, encoded in
          RFC 4648 base64 to either encrypt or decrypt this resource.
      - name: 'rsaEncryptedKey'
        type: String
        sensitive: true
        description: |
          Specifies an RFC 4648 base64 encoded, RSA-wrapped 2048-bit
          customer-supplied encryption key to either encrypt or decrypt
          this resource. You can provide either the rawKey or the rsaEncryptedKey.
      - name: 'kmsKeySelfLink'
        type: String
        api_name: kmsKeyName
        diff_suppress_func: 'tpgresource.CompareSelfLinkRelativePaths'
        custom_flatten: 'templates/terraform/custom_flatten/image_kms_key_name.go.tmpl'
        description: |
          The self link of the encryption key used to decrypt this resource. Also called KmsKeyName
          in the cloud console. Your project's Compute Engine System service account
          (`service-{{PROJECT_NUMBER}}@compute-system.iam.gserviceaccount.com`) must have
          `roles/cloudkms.cryptoKeyEncrypterDecrypter` to use this feature.
          See https://cloud.google.com/compute/docs/disks/customer-managed-encryption#encrypt_a_new_persistent_disk_with_your_own_keys
      - name: 'kmsKeyServiceAccount'
        type: String
        description: |
          The service account being used for the encryption request for the
          given KMS key. If absent, the Compute Engine default service
          account is used.
  - name: 'sourceSnapshot'
    type: ResourceRef
    description: |
      URL of the source snapshot used to create this image.

      In order to create an image, you must provide the full or partial URL of one of the following:

      * The selfLink URL
      * This property
      * The sourceImage URL
      * The rawDisk.source URL
      * The sourceDisk URL
    custom_expand: 'templates/terraform/custom_expand/resourceref_with_validation.go.tmpl'
    resource: 'Snapshot'
    imports: 'selfLink'
  - name: 'shieldedInstanceInitialState'
    type: NestedObject
    description: Set the secure boot keys of shielded instance.
    default_from_api: true
    properties:
      - name: 'pk'
        type: NestedObject
        description: The Platform Key (PK).
        properties:
          - name: 'content'
            type: String
            description: |
              The raw content in the secure keys file.

              A base64-encoded string.
            required: true
            diff_suppress_func: 'tpgresource.Base64DiffSuppress'
          - name: 'fileType'
            type: String
            description: The file type of source file.
      - name: 'keks'
        type: Array
        description: The Key Exchange Key (KEK).
        item_type:
          type: NestedObject
          properties:
            - name: 'content'
              type: String
              description: |
                The raw content in the secure keys file.

                A base64-encoded string.
              required: true
              diff_suppress_func: 'tpgresource.Base64DiffSuppress'
            - name: 'fileType'
              type: String
              description: The file type of source file.
      - name: 'dbs'
        type: Array
        description: The Key Database (db).
        item_type:
          type: NestedObject
          properties:
            - name: 'content'
              type: String
              description: |
                The raw content in the secure keys file.

                A base64-encoded string.
              required: true
              diff_suppress_func: 'tpgresource.Base64DiffSuppress'
            - name: 'fileType'
              type: String
              description: The file type of source file.
      - name: 'dbxs'
        type: Array
        description: The forbidden key database (dbx).
        item_type:
          type: NestedObject
          properties:
            - name: 'content'
              type: String
              description: |
                The raw content in the secure keys file.

                A base64-encoded string.
              required: true
              diff_suppress_func: 'tpgresource.Base64DiffSuppress'
            - name: 'fileType'
              type: String
              description: The file type of source file.
  - name: "sourceSnapshotEncryptionKey"
    type: NestedObject
    ignore_read: true
    description: |
      The customer-supplied encryption key of the source snapshot. Required if
      the source snapshot is protected by a customer-supplied encryption key.
    properties:
      - name: 'rawKey'
        type: String
        sensitive: true
        description: |
          Specifies a 256-bit customer-supplied encryption key, encoded in
          RFC 4648 base64 to either encrypt or decrypt this resource.
      - name: 'rsaEncryptedKey'
        type: String
        sensitive: true
        description: |
          Specifies an RFC 4648 base64 encoded, RSA-wrapped 2048-bit
          customer-supplied encryption key to either encrypt or decrypt
          this resource. You can provide either the rawKey or the rsaEncryptedKey.
      - name: 'kmsKeySelfLink'
        type: String
        api_name: kmsKeyName
        diff_suppress_func: 'tpgresource.CompareSelfLinkRelativePaths'
        custom_flatten: 'templates/terraform/custom_flatten/image_kms_key_name.go.tmpl'
        description: |
          The self link of the encryption key used to decrypt this resource. Also called KmsKeyName
          in the cloud console. Your project's Compute Engine System service account
          (`service-{{PROJECT_NUMBER}}@compute-system.iam.gserviceaccount.com`) must have
          `roles/cloudkms.cryptoKeyEncrypterDecrypter` to use this feature.
          See https://cloud.google.com/compute/docs/disks/customer-managed-encryption#encrypt_a_new_persistent_disk_with_your_own_keys
      - name: 'kmsKeyServiceAccount'
        type: String
        description: |
          The service account being used for the encryption request for the
          given KMS key. If absent, the Compute Engine default service
          account is used.