google.cloud.gcp_vertexai_index module – Creates a GCP VertexAI.Index resource

Note

This module is part of the google.cloud collection (version 1.13.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install google.cloud. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: google.cloud.gcp_vertexai_index.

Synopsis
Requirements
Parameters
Notes
Examples
Return Values

Synopsis

A representation of a collection of database items organized in a way that allows for approximate nearest neighbor (a.k.a ANN) algorithms search.

Requirements

The below requirements are needed on the host that executes this module.

python >= 3.8
requests >= 2.18.4
google-auth >= 2.25.1

Parameters

Parameter	Comments
access_token string	The access token used to authenticate.
auth_kind string / required	The type of credential used. Choices: `"accesstoken"` `"application"` `"machineaccount"` `"serviceaccount"`
description string	The description of the Index.
display_name string / required	The display name of the Index. The name can be up to 128 characters long and can consist of any UTF-8 characters.
encryption_spec dictionary	Customer-managed encryption key spec for an Index. If set, this Index and all sub-resources of this Index will be secured by this key.
kms_key_name string / required	The Cloud KMS resource identifier of the customer managed encryption key used to protect a resource. Has the form: `projects/my-project/locations/my-region/keyRings/my-kr/cryptoKeys/my-key`. The key needs to be in the same region as where the compute resource is created.
env_type string	Specifies which Ansible environment you’re running this module within. This should not be set unless you know what you’re doing. This only alters the User Agent string for any API requests.
index_update_method string	The update method to use with this Index. The value must be the followings. If not set, BATCH_UPDATE will be used by default. * BATCH_UPDATE: user can call indexes.patch with files on Cloud Storage of datapoints to update. * STREAM_UPDATE: user can call indexes.upsertDatapoints/DeleteDatapoints to update the Index and the updates will be applied in corresponding DeployedIndexes in nearly real-time. Default: `"BATCH_UPDATE"`
labels dictionary	The labels with user-defined metadata to organize your Indexes.
metadata dictionary / required	Additional information about the Index. Although this field is not marked as required in the API specification, it is currently required when creating an Index and must be provided. Attempts to create an Index without this field will result in an API error.
config dictionary / required	The configuration of the Matching Engine Index.
algorithm_config dictionary	The configuration with regard to the algorithms used for efficient search. This field may be required based on your configuration.
brute_force_config dictionary	Configuration options for using brute force search, which simply implements the standard linear search in the database for each query.
tree_ah_config dictionary	Configuration options for using the tree-AH algorithm (Shallow tree + Asymmetric Hashing). Please refer to this paper for more details: https://arxiv.org/abs/1908.10396.
leaf_node_embedding_count integer	Number of embeddings on each leaf node. The default value is 1000 if not set. Default: `1000`
leaf_nodes_to_search_percent integer	The default percentage of leaf nodes that any query may be searched. Must be in range 1-100, inclusive. The default value is 10 (means 10%) if not set. Default: `10`
approximate_neighbors_count integer	The default number of neighbors to find via approximate search before exact reordering is performed. Exact reordering is a procedure where results returned by an approximate search algorithm are reordered via a more expensive distance computation. Required if tree-AH algorithm is used.
dimensions integer / required	The number of dimensions of the input vectors.
distance_measure_type string	The distance measure used in nearest neighbor search. The value must be one of the followings: * SQUARED_L2_DISTANCE: Euclidean (L_2) Distance * L1_DISTANCE: Manhattan (L_1) Distance * COSINE_DISTANCE: Cosine Distance. Defined as 1 - cosine similarity. * DOT_PRODUCT_DISTANCE: Dot Product Distance. Defined as a negative of the dot product. Default: `"DOT_PRODUCT_DISTANCE"`
feature_norm_type string	Type of normalization to be carried out on each vector. The value must be one of the followings: * UNIT_L2_NORM: Unit L2 normalization type * NONE: No normalization type is specified. Default: `"NONE"`
shard_size string	Index data is split into equal parts to be processed. These are called “shards”. The shard size must be specified when creating an index. The value must be one of the followings: * SHARD_SIZE_SMALL: Small (2GB) * SHARD_SIZE_MEDIUM: Medium (20GB) * SHARD_SIZE_LARGE: Large (50GB).
contents_delta_uri string	Allows inserting, updating or deleting the contents of the Matching Engine Index. The string must be a valid Cloud Storage directory path. If this field is set when calling IndexService.UpdateIndex, then no other Index field can be also updated as part of the same call. The expected structure and format of the files this URI points to is described at https://cloud.google.com/vertex-ai/docs/matching-engine/using-matching-engine#input-data-format.
is_complete_overwrite boolean	If this field is set together with contentsDeltaUri when calling IndexService.UpdateIndex, then existing content of the Index will be replaced by the data from the contentsDeltaUri. Choices: `false` ← (default) `true`
project string	The Google Cloud Platform project to use.
region string	The region of the index. eg us-central1.
scopes list / elements=string	Array of scopes to be used.
service_account_contents jsonarg	The contents of a Service Account JSON file, either in a dictionary or as a JSON string that represents it.
service_account_email string	An optional service account email address if machineaccount is selected and the user does not wish to use the default email.
service_account_file path	The path of a Service Account JSON file if serviceaccount is selected as type.
state string	Whether the resource should exist in GCP. Choices: `"present"` ← (default) `"absent"`

Notes

Note

API Reference: https://cloud.google.com/vertex-ai/docs/reference/rest/v1/projects.locations.indexes/
For authentication, you can set auth_kind using the GCP_AUTH_KIND env variable.
For authentication, you can set service_account_file using the GCP_SERVICE_ACCOUNT_FILE env variable.
For authentication, you can set service_account_contents using the GCP_SERVICE_ACCOUNT_CONTENTS env variable.
For authentication, you can set service_account_email using the GCP_SERVICE_ACCOUNT_EMAIL env variable.
For authentication, you can set access_token using the GCP_ACCESS_TOKEN env variable.
For authentication, you can set scopes using the GCP_SCOPES env variable.
Environment variables values will only be used if the playbook values are not set.
The service_account_email, service_account_file, service_account_file and access_token options are mutually exclusive.

Examples

- name: Create Index
  google.cloud.gcp_vertexai_index:
    state: present
    display_name: "{{ resource_name }}"
    region: us-central1
    metadata:
      contents_delta_uri: "gs://{{ resource_name }}/contents"
      config:
        dimensions: 2
        approximate_neighbors_count: 150
        shard_size: SHARD_SIZE_SMALL
        distance_measure_type: DOT_PRODUCT_DISTANCE
        algorithm_config:
          tree_ah_config:
            leaf_node_embedding_count: 500
            leaf_nodes_to_search_percent: 7
    project: "{{ gcp_project }}"
    auth_kind: "{{ gcp_cred_kind }}"
    service_account_file: "{{ gcp_cred_file }}"

################################################################################

- name: Create Index with streaming updates
  google.cloud.gcp_vertexai_index:
    state: present
    display_name: "{{ resource_name }}"
    region: us-central1
    metadata:
      contents_delta_uri: "gs://{{ resource_name }}/contents"
      config:
        dimensions: 2
        shard_size: SHARD_SIZE_LARGE
        distance_measure_type: COSINE_DISTANCE
        feature_norm_type: UNIT_L2_NORM
        algorithm_config:
          brute_force_config: {}
    index_update_method: STREAM_UPDATE
    project: "{{ gcp_project }}"
    auth_kind: "{{ gcp_cred_kind }}"
    service_account_file: "{{ gcp_cred_file }}"

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
changed boolean	Whether the resource was changed. Returned: always
createTime string	The timestamp of when the Index was created in RFC3339 UTC “Zulu” format, with nanosecond resolution and up to nine fractional digits. Returned: success
deployedIndexes list / elements=dictionary	The pointers to DeployedIndexes created from this Index. An Index can be only deleted if all its DeployedIndexes had been undeployed first. Returned: success
deployedIndexId string	The ID of the DeployedIndex in the above IndexEndpoint. Returned: success
indexEndpoint string	A resource name of the IndexEndpoint. Returned: success
etag string	Used to perform consistent read-modify-write updates. Returned: success
indexStats dictionary	Stats of the index resource. Returned: success
shardsCount integer	The number of shards in the Index. Returned: success
vectorsCount string	The number of vectors in the Index. Returned: success
metadataSchemaUri string	Points to a YAML file stored on Google Cloud Storage describing additional information about the Index, that is specific to it. Unset if the Index does not have any additional information. Returned: success
name string	The resource name of the Index. Returned: success
state string	The current state of the resource. Returned: always
updateTime string	The timestamp of when the Index was last updated in RFC3339 UTC “Zulu” format, with nanosecond resolution and up to nine fractional digits. Returned: success

Authors

Google Inc. (@googlecloudplatform)

Collection links

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/google/cloud/gcp_vertexai_index_module.html