--- title: "POST /v1/{+parent}/persistentResources" method: POST path: "/v1/{+parent}/persistentResources" tags: ["projects"] --- # POST /v1/{+parent}/persistentResources `POST /v1/{+parent}/persistentResources` Creates a PersistentResource. ## Path parameters - `parent` string, required ## Query parameters - `persistentResourceId` string ## Request body - GoogleCloudAiplatformV1PersistentResource — Represents long-lasting resources that are dedicated to users to runs custom workloads. A PersistentResource can have multiple node pools and each node pool can have its own machine spec. - `resourcePools` GoogleCloudAiplatformV1ResourcePool[] — Required. The spec of the pools of different resources. - `machineSpec` GoogleCloudAiplatformV1MachineSpec — Specification of a single machine. - `reservationAffinity` GoogleCloudAiplatformV1ReservationAffinity — A ReservationAffinity can be used to configure a Vertex AI resource (e.g., a DeployedModel) to draw its Compute Engine resources from a Shared Reservation, or exclusively from on-demand capacity. - `key` string — Optional. Corresponds to the label key of a reservation resource. To target a SPECIFIC_RESERVATION by name, use `compute.googleapis.com/reservation-name` as the key and specify the name of your reservation as its value. - `reservationAffinityType` 'TYPE_UNSPECIFIED' | 'NO_RESERVATION' | 'ANY_RESERVATION' | 'SPECIFIC_RESERVATION' — Required. Specifies the reservation affinity type. - `values` string[] — Optional. Corresponds to the label values of a reservation resource. This must be the full resource name of the reservation or reservation block. - `gpuPartitionSize` string — Optional. Immutable. The Nvidia GPU partition size. When specified, the requested accelerators will be partitioned into smaller GPU partitions. For example, if the request is for 8 units of NVIDIA A100 GPUs, and gpu_partition_size="1g.10gb", the service will create 8 * 7 = 56 partitioned MIG instances. The partition size must be a value supported by the requested accelerator. Refer to [Nvidia GPU Partitioning](https://cloud.google.com/kubernetes-engine/docs/how-to/gpus-multi#multi-instance_gpu_partitions) for the available partition sizes. If set, the accelerator_count should be set to 1. - `tpuTopology` string — Immutable. The topology of the TPUs. Corresponds to the TPU topologies available from GKE. (Example: tpu_topology: "2x2x1"). - `machineType` string — Immutable. The type of the machine. See the [list of machine types supported for prediction](https://cloud.google.com/gemini-enterprise-agent-platform/machine-learning/predictions/configure-compute#machine-types) See the [list of machine types supported for custom training](https://cloud.google.com/gemini-enterprise-agent-platform/machine-learning/training/configure-compute#machine-types). For DeployedModel this field is optional, and the default value is `n1-standard-2`. For BatchPredictionJob or as part of WorkerPoolSpec this field is required. - `acceleratorCount` integer — The number of accelerators to attach to the machine. For [accelerator optimized machine types](https://cloud.google.com/compute/docs/accelerator-optimized-machines), One may set the accelerator_count from 1 to N for machine with N GPUs. If accelerator_count is less than or equal to N / 2, Agent Platform co-schedules the replicas of the model into the same VM to save cost. For example, if the machine type is a3-highgpu-8g, which has 8 H100 GPUs, one can set accelerator_count to 1 to 8. If accelerator_count is 1, 2, 3, or 4, Agent Platform co-schedules 8, 4, 2, or 2 replicas of the model into the same VM to save cost. When co-scheduling, CPU, memory and storage on the VM will be distributed to replicas on the VM. For example, one can expect a co-scheduled replica requesting 2 GPUs out of a 8-GPU VM will receive 25% of the CPU, memory and storage of the VM. Note that the feature is not compatible with multihost_gpu_node_count. When multihost_gpu_node_count is set, the co-scheduling will not be enabled. - `acceleratorType` 'ACCELERATOR_TYPE_UNSPECIFIED' | 'NVIDIA_TESLA_K80' | 'NVIDIA_TESLA_P100' | 'NVIDIA_TESLA_V100' | 'NVIDIA_TESLA_P4' | 'NVIDIA_TESLA_T4' | 'NVIDIA_TESLA_A100' | 'NVIDIA_A100_80GB' | 'NVIDIA_L4' | 'NVIDIA_H100_80GB' | 'NVIDIA_H100_MEGA_80GB' | 'NVIDIA_H200_141GB' | 'NVIDIA_B200' | 'NVIDIA_GB200' | 'NVIDIA_RTX_PRO_6000' | 'TPU_V2' | 'TPU_V3' | 'TPU_V4_POD' | 'TPU_V5_LITEPOD' — Immutable. The type of accelerator(s) that may be attached to the machine as per accelerator_count. - `replicaCount` string, int64 — Optional. The total number of machines to use for this resource pool. - `id` string — Immutable. The unique ID in a PersistentResource for referring to this resource pool. User can specify it if necessary. Otherwise, it's generated automatically. - `autoscalingSpec` GoogleCloudAiplatformV1ResourcePoolAutoscalingSpec — The min/max number of replicas allowed if enabling autoscaling - `maxReplicaCount` string, int64 — Optional. max replicas in the node pool, must be ≥ replica_count and > min_replica_count or will throw error - `minReplicaCount` string, int64 — Optional. min replicas in the node pool, must be ≤ replica_count and < max_replica_count or will throw error. For autoscaling enabled Ray-on-Vertex, we allow min_replica_count of a resource_pool to be 0 to match the OSS Ray behavior(https://docs.ray.io/en/latest/cluster/vms/user-guides/configuring-autoscaling.html#cluster-config-parameters). As for Persistent Resource, the min_replica_count must be > 0, we added a corresponding validation inside CreatePersistentResourceRequestValidator.java. - `diskSpec` GoogleCloudAiplatformV1DiskSpec — Represents the spec of disk options. - `bootDiskType` string — Type of the boot disk. For non-A3U machines, the default value is "pd-ssd", for A3U machines, the default value is "hyperdisk-balanced". Valid values: "pd-ssd" (Persistent Disk Solid State Drive), "pd-standard" (Persistent Disk Hard Disk Drive) or "hyperdisk-balanced". - `bootDiskSizeGb` integer — Size in GB of the boot disk (default is 100GB). - `usedReplicaCount` string, int64 — Output only. The number of machines currently in use by training jobs for this resource pool. Will replace idle_replica_count. - `network` string — Optional. The full name of the Compute Engine [network](/compute/docs/networks-and-firewalls#networks) to peered with Vertex AI to host the persistent resources. For example, `projects/12345/global/networks/myVPC`. [Format](/compute/docs/reference/rest/v1/networks/insert) is of the form `projects/{project}/global/networks/{network}`. Where {project} is a project number, as in `12345`, and {network} is a network name. To specify this field, you must have already [configured VPC Network Peering for Vertex AI](https://cloud.google.com/vertex-ai/docs/general/vpc-peering). If this field is left unspecified, the resources aren't peered with any network. - `displayName` string — Optional. The display name of the PersistentResource. The name can be up to 128 characters long and can consist of any UTF-8 characters. - `satisfiesPzi` boolean — Output only. Reserved for future use. - `name` string — Immutable. Resource name of a PersistentResource. - `error` GoogleRpcStatus — The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors). - `code` integer — The status code, which should be an enum value of google.rpc.Code. - `message` string — A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client. - `details` object[] — A list of messages that carry the error details. There is a common set of message types for APIs to use. - `pscInterfaceConfig` GoogleCloudAiplatformV1PscInterfaceConfig — Configuration for PSC-I. - `networkAttachment` string — Optional. The name of the Compute Engine [network attachment](https://cloud.google.com/vpc/docs/about-network-attachments) to attach to the resource within the region and user project. To specify this field, you must have already [created a network attachment] (https://cloud.google.com/vpc/docs/create-manage-network-attachments#create-network-attachments). This field is only used for resources using PSC-I. - `dnsPeeringConfigs` GoogleCloudAiplatformV1DnsPeeringConfig[] — Optional. DNS peering configurations. When specified, Vertex AI will attempt to configure DNS peering zones in the tenant project VPC to resolve the specified domains using the target network's Cloud DNS. The user must grant the dns.peer role to the Vertex AI Service Agent on the target project. - `domain` string — Required. The DNS name suffix of the zone being peered to, e.g., "my-internal-domain.corp.". Must end with a dot. - `targetProject` string — Required. The project ID hosting the Cloud DNS managed zone that contains the 'domain'. The Vertex AI Service Agent requires the dns.peer role on this project. - `targetNetwork` string — Required. The VPC network name in the target_project where the DNS zone specified by 'domain' is visible. - `resourceRuntimeSpec` GoogleCloudAiplatformV1ResourceRuntimeSpec — Configuration for the runtime on a PersistentResource instance, including but not limited to: * Service accounts used to run the workloads. * Whether to make it a dedicated Ray Cluster. - `raySpec` GoogleCloudAiplatformV1RaySpec — Configuration information for the Ray cluster. For experimental launch, Ray cluster creation and Persistent cluster creation are 1:1 mapping: We will provision all the nodes within the Persistent cluster as Ray nodes. - `rayLogsSpec` GoogleCloudAiplatformV1RayLogsSpec — Configuration for the Ray OSS Logs. - `disabled` boolean — Optional. Flag to disable the export of Ray OSS logs to Cloud Logging. - `resourcePoolImages` object — Optional. Required if image_uri isn't set. A map of resource_pool_id to prebuild Ray image if user need to use different images for different head/worker pools. This map needs to cover all the resource pool ids. Example: { "ray_head_node_pool": "head image" "ray_worker_node_pool1": "worker image" "ray_worker_node_pool2": "another worker image" } - `rayMetricSpec` GoogleCloudAiplatformV1RayMetricSpec — Configuration for the Ray metrics. - `disabled` boolean — Optional. Flag to disable the Ray metrics collection. - `imageUri` string — Optional. Default image for user to choose a preferred ML framework (for example, TensorFlow or Pytorch) by choosing from [Vertex prebuilt images](https://cloud.google.com/vertex-ai/docs/training/pre-built-containers). Either this or the resource_pool_images is required. Use this field if you need all the resource pools to have the same Ray image. Otherwise, use the {@code resource_pool_images} field. - `headNodeResourcePoolId` string — Optional. This will be used to indicate which resource pool will serve as the Ray head node(the first node within that pool). Will use the machine from the first workerpool as the head node by default if this field isn't set. - `serviceAccountSpec` GoogleCloudAiplatformV1ServiceAccountSpec — Configuration for the use of custom service account to run the workloads. - `serviceAccount` string — Optional. Required when all below conditions are met * `enable_custom_service_account` is true; * any runtime is specified via `ResourceRuntimeSpec` on creation time, for example, Ray The users must have `iam.serviceAccounts.actAs` permission on this service account and then the specified runtime containers will run as it. Do not set this field if you want to submit jobs using custom service account to this PersistentResource after creation, but only specify the `service_account` inside the job. - `enableCustomServiceAccount` boolean — Required. If true, custom user-managed service account is enforced to run any workloads (for example, Vertex Jobs) on the resource. Otherwise, uses the [Vertex AI Custom Code Service Agent](https://cloud.google.com/vertex-ai/docs/general/access-control#service-agents). - `satisfiesPzs` boolean — Output only. Reserved for future use. - `startTime` string, google-datetime — Output only. Time when the PersistentResource for the first time entered the `RUNNING` state. - `encryptionSpec` GoogleCloudAiplatformV1EncryptionSpec — Represents a customer-managed encryption key specification that can be applied to a Vertex AI resource. - `kmsKeyName` string — Required. Resource name of the Cloud KMS key used to protect the resource. The Cloud KMS key must be in the same region as the resource. It must have the format `projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}`. - `reservedIpRanges` string[] — Optional. A list of names for the reserved IP ranges under the VPC network that can be used for this persistent resource. If set, we will deploy the persistent resource within the provided IP ranges. Otherwise, the persistent resource is deployed to any IP ranges under the provided VPC network. Example: ['vertex-ai-ip-range']. - `state` 'STATE_UNSPECIFIED' | 'PROVISIONING' | 'RUNNING' | 'STOPPING' | 'ERROR' | 'REBOOTING' | 'UPDATING' — Output only. The detailed state of a Study. - `createTime` string, google-datetime — Output only. Time when the PersistentResource was created. - `resourceRuntime` GoogleCloudAiplatformV1ResourceRuntime — Persistent Cluster runtime information as output - `accessUris` object — Output only. URIs for user to connect to the Cluster. Example: { "RAY_HEAD_NODE_INTERNAL_IP": "head-node-IP:10001" "RAY_DASHBOARD_URI": "ray-dashboard-address:8888" } - `labels` object — Optional. The labels with user-defined metadata to organize PersistentResource. Label keys and values can be no longer than 64 characters (Unicode codepoints), can only contain lowercase letters, numeric characters, underscores and dashes. International characters are allowed. See https://goo.gl/xmQnxf for more information and examples of labels. - `updateTime` string, google-datetime — Output only. Time when the PersistentResource was most recently updated. ## Response `200` Successful response --- [API](https://skmtc.net/google/apis/aiplatform.md) · [All operations](https://skmtc.net/google/apis/aiplatform/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/google/aiplatform/versions/b608d71b91f0/schema)