Jump to

• Request
• Response

Update cluster details

put

/20260430/aiDataPlatforms/{aiDataPlatformId}/workspaces/{workspaceKey}/clusters/{clusterKey}

Update the details of a given cluster.

Request

Path Parameters

• aiDataPlatformId(required): string
  Minimum Length: 1

  Maximum Length: 500

  The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the AI Data Platform (Data Lake) instance.
• clusterKey(required): string
  Minimum Length: 1

  Maximum Length: 200

  Cluster key.
• workspaceKey(required): string
  Minimum Length: 1

  Maximum Length: 200

  The key of the Workspace

Header Parameters

• if-match: string
  Maximum Length: 1000

  For optimistic concurrency control. In the PUT or DELETE call for a resource, set the `if-match` parameter to the value of the etag from a previous GET or POST response for that resource. The resource will be updated or deleted only if the etag you provide matches the resource's current etag value.
• opc-request-id: string
  Maximum Length: 255

  Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID. The only valid characters for request IDs are letters, numbers, underscore, and dash.
• should-update-recent: boolean
  A flag to identify if the recent list should be updated.

  Default Value: false

Body ()

The information to be updated.

Root Schema : UpdateClusterDetails

Type: object

Discriminator: type

The data to update a cluster.

Show Source

• description: string
  Minimum Length: 0

  Maximum Length: 1000

  Cluster description.
• displayName: string
  Minimum Length: 1

  Maximum Length: 1000

  Cluster name.
• driverConfig: object DriverConfig
  Driver configuration.
• nodeType: string
  Maximum Length: 255

  Cluster node type encodes the node shape and associated resources.
• type(required): string
  Default Value: USER

  Allowed Values: [ "USER", "AI_COMPUTE" ]

  ClusterType

{
    "description":"The data to update a cluster.",
    "type":"object",
    "required":[
        "type"
    ],
    "discriminator":"type",
    "properties":{
        "type":{
            "type":"string",
            "description":"ClusterType",
            "x-obmcs-top-level-enum":"#/definitions/ClusterType",
            "default":"USER",
            "enum":[
                "USER",
                "AI_COMPUTE"
            ]
        },
        "displayName":{
            "description":"Cluster name.",
            "type":"string",
            "minLength":1,
            "maxLength":1000
        },
        "description":{
            "description":"Cluster description.",
            "type":"string",
            "minLength":0,
            "maxLength":1000
        },
        "driverConfig":{
            "$ref":"#/definitions/DriverConfig"
        },
        "nodeType":{
            "description":"Cluster node type encodes the node shape and associated resources.",
            "type":"string",
            "maxLength":255
        }
    }
}

Nested Schema : DriverConfig

Type: object

Driver configuration.

Show Source

• driverNodeType: string
  Maximum Length: 255

  Node type of optional driver node that encodes the driver node shape and associated resources.
• driverShape: string
  Maximum Length: 255

  Shape of compute cluster driver instance. Example - VM.Standard2.x, VM.Standard.E3.Flex
• driverShapeConfig: object ShapeConfig
  Shape of the driver or executor if a flexible shape is used.

{
    "description":"Driver configuration.",
    "type":"object",
    "properties":{
        "driverNodeType":{
            "description":"Node type of optional driver node that encodes the driver node shape and associated resources.",
            "type":"string",
            "maxLength":255
        },
        "driverShape":{
            "description":"Shape of compute cluster driver instance. Example - VM.Standard2.x, VM.Standard.E3.Flex",
            "type":"string",
            "maxLength":255
        },
        "driverShapeConfig":{
            "$ref":"#/definitions/ShapeConfig"
        }
    }
}

Nested Schema : ShapeConfig

Type: object

Shape of the driver or executor if a flexible shape is used.

Show Source

• gpus: integer
  Minimum Value: 0

  Maximum Value: 2000

  Total number of GPUs used for the driver or workers.
• memoryInGBs: integer
  Minimum Value: 16

  Maximum Value: 2000

  Amount of memory used for the driver or workers.
• ocpus: integer
  Minimum Value: 1

  Maximum Value: 2000

  Total number of OCPUs used for the driver or workers.

{
    "description":"Shape of the driver or executor if a flexible shape is used.",
    "properties":{
        "ocpus":{
            "description":"Total number of OCPUs used for the driver or workers.",
            "type":"integer",
            "minimum":1,
            "maximum":2000
        },
        "gpus":{
            "description":"Total number of GPUs used for the driver or workers.",
            "type":"integer",
            "minimum":0,
            "maximum":2000
        },
        "memoryInGBs":{
            "description":"Amount of memory used for the driver or workers.",
            "type":"integer",
            "minimum":16,
            "maximum":2000
        }
    }
}

Back to Top

Response

Supported Media Types

• application/json

202 Response

Request accepted. Cluster is updated.

Headers

• aidp-async-operation-key: string
  The key of the asynchronous operations associated with an AI Data Platform instance. Use GetAsyncOperation with this key to track the status of the request.
• etag: string
  For optimistic concurrency control. See `if-match`.
• opc-request-id: string
  Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Cluster

Type: object

Discriminator: sourceApi

A Cluster is a compute subresource within AI Data Platform Workbench. Compute/Runtime Clusters are Spark execution environments. Spark clusters are used for Notebook execution and for Spark SQL query execution over JDBC/ODBC. These clusters seamlessly process the data in the AI Data Platform Workbench. Users can also use JDBC/ODBC endpoints for highly performant SQL execution for integration with analytics tools such as Oracle Analytic Cloud and Excel. A DEFAULT cluster is a subresource within AI Data Platform Workbench associated with master catalog and it can not be attached to a notebook. A USER cluster is a subresource within workspace and can be attached to a notebook.

Show Source

• activeClusterResources: object ActiveClusterResources
  Active resources of a cluster.
• createdBy: string
  OCID of the user who created this record.
• createdByName: string
  Name of the user who created this record.
• description: string
  Minimum Length: 0

  Maximum Length: 1000

  Cluster description.
• displayName(required): string
  Minimum Length: 1

  Maximum Length: 1000

  Cluster name.
• driverConfig: object DriverConfig
  Driver configuration.
• key(required): string
  Cluster key.
• nodeType: string
  Maximum Length: 255

  Cluster node type encodes the node shape and associated resources.
• sourceApi: string
  Default Value: CLUSTER_API

  Allowed Values: [ "CLUSTER_API", "DEFAULT_CLUSTER_API", "AI_COMPUTE" ]

  User created clusters are associated with a particular workspace. AI compute is used to execute Agents.
• state(required): string
  Allowed Values: [ "ACCEPTED", "CREATING", "ACTIVE", "DELETING", "DELETED", "FAILED", "STOPPING", "STOPPED", "UPDATING", "RESTARTING", "STARTING", "NETWORK_CONFIGURATION_ATTACH_IN_PROGRESS", "NETWORK_CONFIGURATION_ATTACH_SUCCESSFUL", "NETWORK_CONFIGURATION_ATTACH_FAILED", "NETWORK_CONFIGURATION_DETACH_IN_PROGRESS", "NETWORK_CONFIGURATION_DETACH_SUCCESSFUL", "NETWORK_CONFIGURATION_DETACH_FAILED" ]

  Common lifecycle states for resources in a compute cluster. ACCEPTED - The resource create request has been accepted. CREATING - The resource is being created and might not be usable until the entire metadata is defined. ACTIVE - The resource is valid and available for access. DELETING - The resource is being deleted, and might require a deep clean of any children. DELETED - The resource has been deleted, and isn't available. FAILED - The resource is in a failed state due to validation or other errors. STOPPING - The resource is being stopped. STOPPED - The resource has been stopped. UPDATING - The resource is being updated and might not be usable until all changes are commited. STARTING - The resource is being started. RESTARTING - The resource is being restarted.
• stateDetails: string
  A message that describes the current state of the workspace cluster in more detail. For example, can be used to provide actionable information for a resource in the Failed state.
• stoppedBy: string
  OCID of the user who stopped the cluster. Value will be 'SYSTEM' if it was auto stopped.
• stoppedByName: string
  Name of the user who stopped the cluster. Value will be 'SYSTEM' if it was auto stopped.
• timeCreated(required): string(date-time)
  Date and time the cluster was created.
• timeUpdated: string(date-time)
  Date and time the cluster was updated.
• type: string
  Allowed Values: [ "USER", "AI_COMPUTE" ]

  ClusterType
• updatedBy: string
  OCID of the user who updated this record.
• updatedByName: string
  Name of the user who updated this record.

{
    "description":"A Cluster is a compute subresource within AI Data Platform Workbench. Compute/Runtime Clusters are Spark execution environments. \nSpark clusters are used for Notebook execution and for Spark SQL query execution over JDBC/ODBC. \nThese clusters seamlessly process the data in the AI Data Platform Workbench.  Users can also use JDBC/ODBC endpoints for highly \nperformant SQL execution for integration with analytics tools such as Oracle Analytic Cloud and Excel.\nA DEFAULT cluster is a subresource within AI Data Platform Workbench associated with master catalog and it can not be\nattached to a notebook. A USER cluster is a subresource within workspace and can be attached to a notebook.\n",
    "type":"object",
    "required":[
        "key",
        "state",
        "timeCreated",
        "displayName"
    ],
    "discriminator":"sourceApi",
    "properties":{
        "key":{
            "description":"Cluster key.",
            "type":"string"
        },
        "displayName":{
            "description":"Cluster name.",
            "type":"string",
            "minLength":1,
            "maxLength":1000
        },
        "description":{
            "description":"Cluster description.",
            "type":"string",
            "minLength":0,
            "maxLength":1000
        },
        "sourceApi":{
            "description":"User created clusters are associated with a particular workspace. AI compute is used to execute Agents.\n",
            "type":"string",
            "default":"CLUSTER_API",
            "enum":[
                "CLUSTER_API",
                "DEFAULT_CLUSTER_API",
                "AI_COMPUTE"
            ]
        },
        "type":{
            "type":"string",
            "description":"ClusterType",
            "x-obmcs-top-level-enum":"#/definitions/ClusterType",
            "enum":[
                "USER",
                "AI_COMPUTE"
            ]
        },
        "timeCreated":{
            "description":"Date and time the cluster was created.",
            "type":"string",
            "format":"date-time"
        },
        "timeUpdated":{
            "description":"Date and time the cluster was updated.",
            "type":"string",
            "format":"date-time"
        },
        "state":{
            "description":"Common lifecycle states for resources in a compute cluster.\nACCEPTED        - The resource create request has been accepted.\nCREATING        - The resource is being created and might not be usable until the entire metadata is defined.\nACTIVE          - The resource is valid and available for access.\nDELETING        - The resource is being deleted, and might require a deep clean of any children.\nDELETED         - The resource has been deleted, and isn't available.\nFAILED          - The resource is in a failed state due to validation or other errors.\nSTOPPING        - The resource is being stopped.\nSTOPPED         - The resource has been stopped.\nUPDATING        - The resource is being updated and might not be usable until all changes are commited.\nSTARTING        - The resource is being started.\nRESTARTING      - The resource is being restarted.\n",
            "type":"string",
            "enum":[
                "ACCEPTED",
                "CREATING",
                "ACTIVE",
                "DELETING",
                "DELETED",
                "FAILED",
                "STOPPING",
                "STOPPED",
                "UPDATING",
                "RESTARTING",
                "STARTING",
                "NETWORK_CONFIGURATION_ATTACH_IN_PROGRESS",
                "NETWORK_CONFIGURATION_ATTACH_SUCCESSFUL",
                "NETWORK_CONFIGURATION_ATTACH_FAILED",
                "NETWORK_CONFIGURATION_DETACH_IN_PROGRESS",
                "NETWORK_CONFIGURATION_DETACH_SUCCESSFUL",
                "NETWORK_CONFIGURATION_DETACH_FAILED"
            ]
        },
        "stateDetails":{
            "description":"A message that describes the current state of the workspace cluster in more detail. For example, can be used to provide actionable information for a resource in the Failed state.",
            "type":"string"
        },
        "nodeType":{
            "description":"Cluster node type encodes the node shape and associated resources.",
            "type":"string",
            "maxLength":255
        },
        "driverConfig":{
            "$ref":"#/definitions/DriverConfig"
        },
        "activeClusterResources":{
            "$ref":"#/definitions/ActiveClusterResources"
        },
        "createdBy":{
            "description":"OCID of the user who created this record.",
            "type":"string"
        },
        "createdByName":{
            "description":"Name of the user who created this record.",
            "type":"string"
        },
        "updatedBy":{
            "description":"OCID of the user who updated this record.",
            "type":"string"
        },
        "updatedByName":{
            "description":"Name of the user who updated this record.",
            "type":"string"
        },
        "stoppedBy":{
            "description":"OCID of the user who stopped the cluster. Value will be 'SYSTEM' if it was auto stopped.",
            "type":"string"
        },
        "stoppedByName":{
            "description":"Name of the user who stopped the cluster. Value will be 'SYSTEM' if it was auto stopped.",
            "type":"string"
        }
    }
}

Nested Schema : ActiveClusterResources

Type: object

Active resources of a cluster.

Show Source

• activeCores: number(double)
  Count of active cores.
• activeExecutorCount: number(double)
  Count of active executors.
• activeGpuCores: number(double)
  Count of active GPU cores.
• activeGpuMemoryInGBs: number(double)
  Active GPU memory in GB.
• activeMemoryInGBs: number(double)
  Active memory in GB.

{
    "description":"Active resources of a cluster.",
    "type":"object",
    "properties":{
        "activeExecutorCount":{
            "description":"Count of active executors.",
            "type":"number",
            "format":"double"
        },
        "activeCores":{
            "description":"Count of active cores.",
            "type":"number",
            "format":"double"
        },
        "activeGpuCores":{
            "description":"Count of active GPU cores.",
            "type":"number",
            "format":"double"
        },
        "activeMemoryInGBs":{
            "description":"Active memory in GB.",
            "type":"number",
            "format":"double"
        },
        "activeGpuMemoryInGBs":{
            "description":"Active GPU memory in GB.",
            "type":"number",
            "format":"double"
        }
    }
}

Nested Schema : DriverConfig

Type: object

Driver configuration.

Show Source

• driverNodeType: string
  Maximum Length: 255

  Node type of optional driver node that encodes the driver node shape and associated resources.
• driverShape: string
  Maximum Length: 255

  Shape of compute cluster driver instance. Example - VM.Standard2.x, VM.Standard.E3.Flex
• driverShapeConfig: object ShapeConfig
  Shape of the driver or executor if a flexible shape is used.

{
    "description":"Driver configuration.",
    "type":"object",
    "properties":{
        "driverNodeType":{
            "description":"Node type of optional driver node that encodes the driver node shape and associated resources.",
            "type":"string",
            "maxLength":255
        },
        "driverShape":{
            "description":"Shape of compute cluster driver instance. Example - VM.Standard2.x, VM.Standard.E3.Flex",
            "type":"string",
            "maxLength":255
        },
        "driverShapeConfig":{
            "$ref":"#/definitions/ShapeConfig"
        }
    }
}

Nested Schema : ShapeConfig

Type: object

Shape of the driver or executor if a flexible shape is used.

Show Source

• gpus: integer
  Minimum Value: 0

  Maximum Value: 2000

  Total number of GPUs used for the driver or workers.
• memoryInGBs: integer
  Minimum Value: 16

  Maximum Value: 2000

  Amount of memory used for the driver or workers.
• ocpus: integer
  Minimum Value: 1

  Maximum Value: 2000

  Total number of OCPUs used for the driver or workers.

{
    "description":"Shape of the driver or executor if a flexible shape is used.",
    "properties":{
        "ocpus":{
            "description":"Total number of OCPUs used for the driver or workers.",
            "type":"integer",
            "minimum":1,
            "maximum":2000
        },
        "gpus":{
            "description":"Total number of GPUs used for the driver or workers.",
            "type":"integer",
            "minimum":0,
            "maximum":2000
        },
        "memoryInGBs":{
            "description":"Amount of memory used for the driver or workers.",
            "type":"integer",
            "minimum":16,
            "maximum":2000
        }
    }
}

400 Response

Bad Request (invalid query parameters, malformed headers, and so on).

Headers

• opc-request-id: string
  Unique Oracle-assigned ID for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error message.

{
    "description":"Error information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error message.",
            "type":"string"
        }
    }
}

401 Response

Unauthorized (missing or expired credentials, and so on).

Headers

• opc-request-id: string
  Unique Oracle-assigned ID for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error message.

{
    "description":"Error information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error message.",
            "type":"string"
        }
    }
}

404 Response

Not Found. The requested resource was not found.

Headers

• opc-request-id: string
  Unique Oracle-assigned ID for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error message.

{
    "description":"Error information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error message.",
            "type":"string"
        }
    }
}

405 Response

Method Not Allowed. Request is recognized but not supported.

Headers

• opc-request-id: string
  Unique Oracle-assigned ID for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error message.

{
    "description":"Error information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error message.",
            "type":"string"
        }
    }
}

409 Response

Conflict. Request conflicts with the current state of the resource.

Headers

• opc-request-id: string
  Unique Oracle-assigned ID for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error message.

{
    "description":"Error information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error message.",
            "type":"string"
        }
    }
}

412 Response

Precondition Failed (One or more conditions in request failed).

Headers

• opc-request-id: string
  Unique Oracle-assigned ID for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error message.

{
    "description":"Error information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error message.",
            "type":"string"
        }
    }
}

429 Response

Too Many Requests. Too many requests sent to the server in a short period.

Headers

• opc-request-id: string
  Unique Oracle-assigned ID for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error message.

{
    "description":"Error information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error message.",
            "type":"string"
        }
    }
}

500 Response

Internal Server Error. The server encountered an unexpected condition preventing fulfilment of the request.

Headers

• opc-request-id: string
  Unique Oracle-assigned ID for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error message.

{
    "description":"Error information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error message.",
            "type":"string"
        }
    }
}

Default Response

Unknown Error. Error is not recognized by the system.

Headers

• opc-request-id: string
  Unique Oracle-assigned ID for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error message.

{
    "description":"Error information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error message.",
            "type":"string"
        }
    }
}

Back to Top