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
  The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the AI Data Platform (Data Lake) instance.
• clusterKey(required): string
  Cluster key.
• workspaceKey(required): string
  The key of the Workspace

Header Parameters

• if-match: string
  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
  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: 1

  Maximum Length: 400

  Cluster description.
• displayName: string
  Cluster name.
• driverConfig: object DriverConfig
  Driver configuration.
• nodeType: string
  Minimum Length: 1

  Maximum Length: 255

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

  Allowed Values: [ "USER", "AGENT_FLOW_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",
                "AGENT_FLOW_COMPUTE"
            ]
        },
        "displayName":{
            "description":"Cluster name.",
            "type":"string"
        },
        "description":{
            "description":"Cluster description.",
            "type":"string",
            "minLength":1,
            "maxLength":400
        },
        "driverConfig":{
            "$ref":"#/definitions/DriverConfig"
        },
        "nodeType":{
            "description":"Cluster node type encodes the node shape and associated resources.",
            "type":"string",
            "minLength":1,
            "maxLength":255
        }
    }
}

Nested Schema : DriverConfig

Type: object

Driver configuration.

Show Source

• driverNodeType: string
  Minimum Length: 1

  Maximum Length: 255

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

  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",
            "minLength":1,
            "maxLength":255
        },
        "driverShape":{
            "description":"Shape of compute cluster driver instance. Example - VM.Standard2.x, VM.Standard.E3.Flex",
            "type":"string",
            "minLength":1,
            "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

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

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

  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
        },
        "gpus":{
            "description":"Total number of GPUs used for the driver or workers.",
            "type":"integer",
            "minimum":0
        },
        "memoryInGBs":{
            "description":"Amount of memory used for the driver or workers.",
            "type":"integer",
            "minimum":16
        }
    }
}

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: 1

  Maximum Length: 400

  Cluster description.
• displayName(required): string
  Cluster name.
• driverConfig: object DriverConfig
  Driver configuration.
• key(required): string
  Cluster key.
• nodeType: string
  Minimum Length: 1

  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", "AGENT_FLOW_COMPUTE" ]

  User created clusters are associated with a particular workspace. Default cluster is to be used by all catalogs operations that require compute. Default cluster can be thought of as associated with Master catalog. Agent Flow Compute is used to execute Agent Flows.
• 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", "AGENT_FLOW_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"
        },
        "description":{
            "description":"Cluster description.",
            "type":"string",
            "minLength":1,
            "maxLength":400
        },
        "sourceApi":{
            "description":"User created clusters are associated with a particular workspace. Default cluster is to\nbe used by all catalogs operations that require compute. Default cluster can be thought of as\nassociated with Master catalog. Agent Flow Compute is used to execute Agent Flows.\n",
            "type":"string",
            "default":"CLUSTER_API",
            "enum":[
                "CLUSTER_API",
                "DEFAULT_CLUSTER_API",
                "AGENT_FLOW_COMPUTE"
            ]
        },
        "type":{
            "type":"string",
            "description":"ClusterType",
            "x-obmcs-top-level-enum":"#/definitions/ClusterType",
            "enum":[
                "USER",
                "AGENT_FLOW_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",
            "minLength":1,
            "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
  Minimum Length: 1

  Maximum Length: 255

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

  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",
            "minLength":1,
            "maxLength":255
        },
        "driverShape":{
            "description":"Shape of compute cluster driver instance. Example - VM.Standard2.x, VM.Standard.E3.Flex",
            "type":"string",
            "minLength":1,
            "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

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

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

  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
        },
        "gpus":{
            "description":"Total number of GPUs used for the driver or workers.",
            "type":"integer",
            "minimum":0
        },
        "memoryInGBs":{
            "description":"Amount of memory used for the driver or workers.",
            "type":"integer",
            "minimum":16
        }
    }
}

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