openapi: 3.0.0 info: title: Leonardo description: | Workbench notebooks service. # Follow semantic versioning https://semver.org/ version: "1.3.6" license: name: BSD url: http://opensource.org/licenses/BSD-3-Clause termsOfService: https://github.com/broadinstitute/leonardo tags: - name: resources description: Resources API. Overarching support of runtimes and apps. - name: runtimes description: Runtimes API. Support both Google Dataproc and Google Compute Engine. - name: disks description: Persistent Disks API. - name: apps description: Apps API. Support Google Kubernetes Engine and Azure Kubernetes Service. - name: proxy description: Proxy API - name: admin description: Admin API - name: notebooks description: Notebooks API. Deprecated in favor of Proxy API. - name: service_info description: Service Info API security: - oidc: - openid ########################################################################################## ## PATHS ########################################################################################## paths: /liveness: get: summary: Gets system liveness responses: "200": description: System is up, other routes may not be ready yet. See status api for readiness operationId: getLiveness /status: get: summary: Gets system readiness responses: "200": description: System ok content: application/json: schema: $ref: "#/components/schemas/SystemStatus" "500": description: One or more subsystems down content: application/json: schema: $ref: "#/components/schemas/SystemStatus" operationId: getSystemStatus tags: - service_info security: [] /version: get: tags: - service_info operationId: leonardoVersion summary: Returns the currently deployed version of this service. responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/LeonardoVersion" security: [] ## All resources path ## "/api/google/v1/resources/{googleProject}/deleteAll": delete: summary: Deletes ALL runtimes, disks and apps associated with the given google project description: deletes all runtimes and apps in a google project operationId: deleteAllResources tags: - resources parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: query name: deleteDisk description: Whether or not disk should be deleted if the runtime is using persistent disk. Default to false if not specified required: false schema: type: boolean default: false responses: "202": description: Resource(s) deletion request accepted "403": description: User does not have permission to perform action on resource(s) "404": description: Resource(s) not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/api/google/v1/resources/{googleProject}/cleanupAll": delete: summary: Cleanup ALL records of runtimes and apps associated with the given google project in the Leonardo and Sam databases description: Marks all runtimes, disks and apps in a google project as deleted in Leonardo and Sam operationId: cleanupAllResources tags: - resources parameters: - in: path name: googleProject description: googleProject required: true schema: type: string responses: "200": description: Resource(s) records cleanup successful "403": description: User does not have permission to perform action on resource(s) "404": description: Resource(s) not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" ## Runtime paths ## "/api/google/v1/runtimes": get: summary: List all runtimes that the caller has access to description: List all runtimes, optionally filtering on a set of labels operationId: listRuntimes tags: - runtimes parameters: - in: query name: _labels description: > Optional label key-value pairs to filter results by. Example: Querying by key1=val1,key2=val2 returns all runtimes that contain the key1/val1 and key2/val2 labels (possibly among other labels). Note: this string format is a workaround because Swagger doesn't support free-form query string parameters. The recommended way to use this endpoint is to specify the labels as top-level query string parameters. For instance: GET /api/google/v1/runtimes?key1=val1&key2=val2. required: false schema: type: string - in: query name: includeDeleted description: Optional filter that includes any runtimes with a Deleted status. required: false schema: type: boolean default: false responses: "200": description: List of runtimes content: application/json: schema: type: array items: $ref: "#/components/schemas/ListRuntimeResponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/api/google/v1/runtimes/{googleProject}": get: summary: List all runtimes within the given Google project that the caller has access to description: List all runtimes within the given Google project, optionally filtering on a set of labels operationId: listRuntimesByProject tags: - runtimes parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: query name: _labels description: > Optional label key-value pairs to filter results by. Example: Querying by key1=val1,key2=val2 returns all runtimes that contain the key1/val1 and key2/val2 labels (possibly among other labels). Note: this string format is a workaround because Swagger doesn't support free-form query string parameters. The recommended way to use this endpoint is to specify the labels as top-level query string parameters. For instance: GET /api/google/v1/runtimes?key1=val1&key2=val2. required: false schema: type: string - in: query name: includeDeleted description: Optional filter that includes any runtimes with a Deleted status. required: false schema: type: boolean default: false responses: "200": description: List of runtimes content: application/json: schema: type: array items: $ref: "#/components/schemas/ListRuntimeResponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/api/google/v1/runtimes/{googleProject}/{name}": get: summary: Get details of a runtime description: > Returns information about an existing runtime managed by Leo. Poll this to find out when your runtime has finished starting up. operationId: getRuntime tags: - runtimes parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: name description: runtimeName required: true schema: type: string responses: "200": description: Runtime found, here are the details content: application/json: schema: $ref: "#/components/schemas/GetRuntimeResponse" "403": description: User does not have permission to perform action on runtime "404": description: Runtime not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" post: summary: Creates a new Dataproc cluster or Google Compute Engine instance in the given project with the given name. description: > The request is completed without waiting for the runtime to be created in Google. The runtime status can be polled using the getRuntime API. Default labels runtimeName, googleProject, serviceAccount, and notebookExtension cannot be overridden. operationId: createRuntime tags: - runtimes parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: name description: runtimeName. only lowercase alphanumeric characters, numbers and dashes are allowed required: true schema: type: string requestBody: $ref: "#/components/requestBodies/CreateRuntimeRequest" responses: "202": description: Runtime creation request accepted content: application/json: schema: $ref: "#/components/schemas/CreateRuntimeResponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "409": description: Conflict content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" delete: summary: Deletes an existing Dataproc cluster or Google Compute Engine instance in the given project description: deletes a runtime operationId: deleteRuntime tags: - runtimes parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: name description: runtimeName required: true schema: type: string - in: query name: deleteDisk description: Whether or not disk should be deleted if the runtime is using persistent disk. Default to false if not specified required: false schema: type: boolean default: false responses: "202": description: Runtime deletion request accepted "403": description: User does not have permission to perform action on runtime "404": description: Runtime not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" patch: summary: Updates the configuration of a runtime description: In order to update the configuration of a runtime, it must first be running or paused operationId: updateRuntime tags: - runtimes parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: name description: runtimeName required: true schema: type: string requestBody: $ref: "#/components/requestBodies/UpdateRuntimeRequest" responses: "202": description: Runtime update request accepted "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "409": description: Conflict content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Server Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/api/google/v1/runtimes/{googleProject}/{name}/stop": post: summary: Stops a Dataproc cluster or Google Compute Engine instance description: > Stops the running compute, but retains any data persisted on disk. The runtime may be restarted with the /start endpoint. operationId: stopRuntime tags: - runtimes parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: name description: runtime name required: true schema: type: string responses: "202": description: Runtime stop request accepted "403": description: User does not have permission to perform action on runtime "404": description: Runtime not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "409": description: Runtime cannot be stopped content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/api/google/v1/runtimes/{googleProject}/{name}/start": post: summary: Starts a Dataproc cluster or Google Compute Engine instance description: Starts the a stopped runtime operationId: startRuntime tags: - runtimes parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: name description: runtimeName required: true schema: type: string responses: "202": description: Runtime start request accepted "403": description: User does not have permission to perform action on runtime "404": description: Runtime not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "409": description: Runtime cannot be started content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/api/v2/runtimes": get: summary: List all runtimes that the caller has access to description: List all runtimes, optionally filtering on a set of labels operationId: listRuntimesV2 tags: - runtimes parameters: - in: query name: _labels description: > Optional label key-value pairs to filter results by. Example: Querying by key1=val1,key2=val2 returns all azure runtimes that contain the key1/val1 and key2/val2 labels (possibly among other labels). Note: this string format is a workaround because Swagger doesn't support free-form query string parameters. The recommended way to use this endpoint is to specify the labels as top-level query string parameters. For instance: GET /api/v2/runtimes?key1=val1&key2=val2. required: false schema: type: string - in: query name: includeDeleted description: Optional filter that includes any runtimes with a Deleted status. required: false schema: type: boolean default: false - in: query name: includeLabels description: > Optional label keys of the labels returned in response. Example: Querying by key1,key2,key3 returns all labels key1/val1 key2/val2 and key3 and val3 for each runtime response required: false schema: type: string responses: "200": description: List of runtimes content: application/json: schema: type: array items: $ref: "#/components/schemas/ListRuntimeResponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/api/v2/runtimes/{workspaceId}": get: summary: List all runtimes within the given workspace that the caller has access to description: List all runtimes within the given workspace, optionally filtering on a set of labels operationId: listRuntimesByWorkspaceV2 tags: - runtimes parameters: - in: path name: workspaceId description: workspaceId required: true schema: type: string - in: query name: _labels description: > Optional label key-value pairs to filter results by. Example: Querying by key1=val1,key2=val2 returns all azure runtimes that contain the key1/val1 and key2/val2 labels (possibly among other labels). Note: this string format is a workaround because Swagger doesn't support free-form query string parameters. The recommended way to use this endpoint is to specify the labels as top-level query string parameters. For instance: GET /api/v2/runtimes/{workspaceId}?key1=val1&key2=val2. required: false schema: type: string - in: query name: includeDeleted description: Optional filter that includes any runtimes with a Deleted status. required: false schema: type: boolean default: false - in: query name: includeLabels description: > Optional label keys of the labels returned in response. Example: Querying by key1,key2,key3 returns all labels key1/val1 key2/val2 and key3 and val3 for each runtime response required: false schema: type: string responses: "200": description: List of runtimes content: application/json: schema: type: array items: $ref: "#/components/schemas/ListRuntimeResponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/api/v2/runtimes/{workspaceId}/azure": get: summary: List all azure runtimes within the given workspace that the caller has access to description: List all azure runtimes within the given workspace, optionally filtering on a set of labels operationId: listAzureRuntimesV2 tags: - runtimes parameters: - in: path name: workspaceId description: workspaceId required: true schema: type: string - in: query name: _labels description: > Optional label key-value pairs to filter results by. Example: Querying by key1=val1,key2=val2 returns all azure runtimes that contain the key1/val1 and key2/val2 labels (possibly among other labels). Note: this string format is a workaround because Swagger doesn't support free-form query string parameters. The recommended way to use this endpoint is to specify the labels as top-level query string parameters. For instance: GET /api/v2/runtimes/{workspaceId}/azure?key1=val1&key2=val2. required: false schema: type: string - in: query name: includeDeleted description: Optional filter that includes any runtimes with a Deleted status. required: false schema: type: boolean default: false - in: query name: includeLabels description: > Optional label keys of the labels returned in response. Example: Querying by key1,key2,key3 returns all labels key1/val1 key2/val2 and key3 and val3 for each runtime response required: false schema: type: string responses: "200": description: List of runtimes content: application/json: schema: type: array items: $ref: "#/components/schemas/ListRuntimeResponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/api/v2/runtimes/{workspaceId}/{name}/start": post: summary: Start runtime (WIP). description: > Start an existing Leonardo managed runtime operationId: startRuntimeV2 tags: - runtimes parameters: - in: path name: workspaceId description: workspaceId required: true schema: type: string - in: path name: name description: runtimeName required: true schema: type: string responses: "202": description: Runtime start request accepted "403": description: User does not have permission to perform action on runtime "404": description: Runtime not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/api/v2/runtimes/{workspaceId}/{name}/stop": post: summary: Stop runtime (WIP). description: > Stop an existing Leonardo managed runtime operationId: stopRuntimeV2 tags: - runtimes parameters: - in: path name: workspaceId description: workspaceId required: true schema: type: string - in: path name: name description: runtimeName required: true schema: type: string responses: "202": description: Runtime stop request accepted "403": description: User does not have permission to perform action on runtime "404": description: Runtime not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/api/v2/runtimes/{workspaceId}/{name}/updateDateAccessed": patch: summary: Update the date accessed of a runtime. description: > This API is used in conjunction with v2 runtime's autopause functionality. Since Azure runtimes are not proxied to Leonardo, the relay must send a 'keep-alive' message of sorts. If no requests are received after a period of time, the runtime will be stopped. Each request to this API does not result in the runtime's date accessed being updated. An async process is responsible for batching them and executing updates. operationId: updateDateAccessed tags: - runtimes parameters: - in: path name: workspaceId description: workspaceId required: true schema: type: string - in: path name: name description: runtimeName required: true schema: type: string responses: "202": description: Runtime update date accessed request accepted "403": description: User does not have permission to perform action on runtime "404": description: Runtime not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/api/v2/runtimes/{workspaceId}/azure/{name}": get: summary: Get details of an azure runtime description: > Returns information about an existing azure runtime managed by Leo. Poll this to find out when your runtime has finished starting up. operationId: getAzureRuntime tags: - runtimes parameters: - in: path name: workspaceId description: workspaceId required: true schema: type: string - in: path name: name description: runtimeName required: true schema: type: string responses: "200": description: Runtime found, here are the details content: application/json: schema: $ref: "#/components/schemas/GetRuntimeResponse" "403": description: User does not have permission to perform action on runtime "404": description: Runtime not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" post: summary: Creates a Azure runtime instance in the given workspace with the given name. description: > The request is completed without waiting for the runtime to be created in Azure. The runtime status can be polled using the getRuntime API. operationId: createAzureRuntime tags: - runtimes parameters: - in: path name: workspaceId description: workspaceId required: true schema: type: string - in: path name: name description: runtimeName. only lowercase alphanumeric characters, numbers and dashes are allowed required: true schema: type: string - in: query name: useExistingDisk description: Defaults to false. If true ignores disk request and creates runtime with an existing disk associated with the user and workspace. Will error if 0 or multiple disks are found. required: false schema: type: boolean default: false requestBody: $ref: "#/components/requestBodies/CreateAzureRuntimeRequest" responses: "202": description: Runtime creation request accepted content: application/json: schema: $ref: "#/components/schemas/CreateRuntimeResponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "409": description: Conflict content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" delete: summary: Deletes an Azure runtime instance in the given workspace description: deletes a runtime operationId: deleteAzureRuntime tags: - runtimes parameters: - in: path name: workspaceId description: workspaceId required: true schema: type: string - in: path name: name description: runtimeName required: true schema: type: string - in: query name: deleteDisk description: Whether or not disk should be deleted upon runtime deletion. Defaults to true if not specified required: false schema: type: boolean default: true responses: "202": description: Runtime deletion request accepted "403": description: User does not have permission to perform action on runtime "404": description: Runtime not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/api/v2/runtimes/{workspaceId}/deleteAll": post: summary: Deletes ALL runtimes associated with the given workspace Id description: deletes all runtimes in a workspace operationId: deleteAllRuntimesV2 tags: - runtimes parameters: - in: path name: workspaceId description: workspaceId required: true schema: type: string - in: query name: deleteDisk description: Whether or not the disk associated with the apps should be deleted. Default to false if not specified. required: false schema: type: boolean default: false responses: "202": description: Runtime(s) deletion request accepted "403": description: User does not have permission to perform action on runtime(s) "404": description: Runtime(s) not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" ## Persistent Disk paths ## /api/google/v1/disks: get: summary: List all persistent disks that the caller has access to description: List all persistent disks, optionally filtering on a set of labels operationId: listDisks tags: - disks parameters: - in: query name: _labels description: > Optional label key-value pairs to filter results by. Example: Querying by key1=val1,key2=val2 returns all persistent disks that contain the key1/val1 and key2/val2 labels (possibly among other labels). Note: this string format is a workaround because Swagger doesn't support free-form query string parameters. The recommended way to use this endpoint is to specify the labels as top-level query string parameters. For instance: GET /api/google/v1/disks?key1=val1&key2=val2. required: false schema: type: string - in: query name: includeDeleted description: Optional filter that includes any persistent disks with a Deleted status. required: false schema: type: boolean default: false - in: query name: includeLabels description: > Optional label keys of the labels returned in response. Example: Querying by key1,key2,key3 returns all labels key1/val1 key2/val2 and key3 and val3 for each persistent disk in response required: false schema: type: string - in: query name: role description: Optional filter that excludes persistent disks you did not create. Accepts "creator" or nothing. required: false schema: type: string responses: "200": description: List of persistent disks content: application/json: schema: type: array items: $ref: "#/components/schemas/ListPersistentDiskResponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" /api/google/v1/disks/{googleProject}: get: summary: List all persistent disks within the given Google project that the caller has access to description: List all persistent disks within the given Google project, optionally filtering on a set of labels operationId: listDisksByProject tags: - disks parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: query name: _labels description: > Optional label key-value pairs to filter results by. Example: Querying by key1=val1,key2=val2 returns all persistent disks that contain the key1/val1 and key2/val2 labels (possibly among other labels). Note: this string format is a workaround because Swagger doesn't support free-form query string parameters. The recommended way to use this endpoint is to specify the labels as top-level query string parameters. For instance: GET /api/google/v1/disks?key1=val1&key2=val2. required: false schema: type: string - in: query name: includeDeleted description: Optional filter that includes any persistent disks with a Deleted status. required: false schema: type: boolean default: false - in: query name: includeLabels description: > Optional label keys of the labels returned in response. Example: Querying by key1,key2,key3 returns all labels key1/val1 key2/val2 and key3 and val3 for each persistent disk in response required: false schema: type: string - in: query name: role description: Optional filter that excludes persistent disks you did not create. Accepts "creator" or nothing. required: false schema: type: string responses: "200": description: List of persistent disks content: application/json: schema: type: array items: $ref: "#/components/schemas/ListPersistentDiskResponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" /api/google/v1/disks/{googleProject}/{name}: get: summary: Get details of a persistent disk description: > Returns information about an existing persistent disk managed by Leo. Poll this to find out when your disk has finished starting up. operationId: getDisk tags: - disks parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: name description: diskName required: true schema: type: string responses: "200": description: Persistent disk found, here are the details content: application/json: schema: $ref: "#/components/schemas/GetPersistentDiskResponse" "403": description: User does not have permission to perform action on persistent disk "404": description: Persistent disk not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" post: summary: Creates a new persistent disk in the given project with the given name. description: > The request is completed without waiting for the persistent disk to be created in Google. The disk status can be polled using the getDisk API. Default labels diskName, googleProject, and creator cannot be overridden. operationId: createDisk tags: - disks parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: name description: diskName. only lowercase alphanumeric characters, numbers and dashes are allowed required: true schema: type: string requestBody: $ref: "#/components/requestBodies/CreateDiskRequest" responses: "202": description: Persistent disk creation request accepted "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "409": description: Conflict content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" delete: summary: Deletes an existing persistent disk in the given project description: Deletes a persistent disk operationId: deleteDisk tags: - disks parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: name description: diskName required: true schema: type: string responses: "202": description: Persistent disk deletion request accepted "403": description: User does not have permission to perform action on persistent disk "404": description: Persistent disk not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" patch: summary: Updates the configuration of a persistent disk description: In order to update the configuration of a persistent disk, it must first be ready operationId: updateDisk tags: - disks parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: name description: diskName required: true schema: type: string requestBody: $ref: "#/components/requestBodies/UpdateDiskRequest" responses: "202": description: Persistent disk update request accepted "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "409": description: Conflict content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/api/v2/disks/{id}": get: summary: Get details of a persistent disk description: > Returns information about an existing persistent disk managed by Leo. Poll this to find out your disk status. operationId: getDiskV2 tags: - disks parameters: - in: path name: id description: diskId required: true schema: type: integer responses: "200": description: Persistent disk found, here are the details content: application/json: schema: $ref: "#/components/schemas/GetPersistentDiskV2Response" "403": description: User does not have permission to perform action on disk "404": description: Persistent disk not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" delete: summary: Deletes an existing persistent disk instance description: Deletes a persistent disk operationId: deleteDiskV2 tags: - disks parameters: - in: path name: id description: diskId required: true schema: type: integer responses: "202": description: Persistent disk deletion request accepted "403": description: User does not have permission to perform action on persistent disk "404": description: Persistent disk not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" ## Kubernetes App API ## "/api/google/v1/apps": get: tags: - apps summary: List apps description: List kubernetes apps the caller has access to, without specifying a project operationId: listApp parameters: - in: query name: _labels description: > Optional label key-value pairs to filter results by. Example: Querying by key1=val1,key2=val2 returns all apps that contain the key1/val1 and key2/val2 labels (possibly among other labels). Note: this string format is a workaround because Swagger doesn't support free-form query string parameters. The recommended way to use this endpoint is to specify the labels as top-level query string parameters. For instance: GET /api/google/v1/app?key1=val1&key2=val2. required: false schema: type: string - in: query name: includeDeleted description: Optional filter that includes any apps with a Deleted status. required: false schema: type: boolean default: false - in: query name: includeLabels description: > Optional label keys of the labels returned in response. Example: Querying by key1,key2,key3 returns all labels key1/val1 key2/val2 and key3 and val3 for each app in response required: false schema: type: string - in: query name: role description: Optional filter that excludes apps you did not create. Accepts "creator" or nothing. required: false schema: type: string responses: "200": description: List of apps content: application/json: schema: type: array items: $ref: "#/components/schemas/ListAppResponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/api/google/v1/apps/{googleProject}": get: summary: List apps within a project description: List kubernetes apps the caller has access to with a project filter operationId: listAppByProject tags: - apps parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: query name: _labels description: > Optional label key-value pairs to filter results by. Example: Querying by key1=val1,key2=val2 returns all apps that contain the key1/val1 and key2/val2 labels (possibly among other labels). Note: this string format is a workaround because Swagger doesn't support free-form query string parameters. The recommended way to use this endpoint is to specify the labels as top-level query string parameters. For instance: GET /api/google/v1/app?key1=val1&key2=val2. required: false schema: type: string - in: query name: includeDeleted description: Optional filter that includes any apps with a Deleted status. required: false schema: type: boolean default: false - in: query name: includeLabels description: > Optional label keys of the labels returned in response. Example: Querying by key1,key2,key3 returns all labels key1/val1 key2/val2 and key3 and val3 for each app in response required: false schema: type: string - in: query name: role description: Optional filter that excludes apps you did not create. Accepts "creator" or nothing. required: false schema: type: string responses: "200": description: List of apps content: application/json: schema: type: array items: $ref: "#/components/schemas/ListAppResponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/api/google/v1/apps/{googleProject}/{appName}": post: summary: Creates a new app in the given project with the given appName description: > The specified appName is suffixed and the resulting string must adhere to Google's name validation regex ?:[a-z](?:[-a-z0-9]{0,38}[a-z0-9])?. Default labels appName, googleProject, serviceAccount, and creator cannot be overridden. operationId: createApp tags: - apps parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: appName description: appName required: true schema: type: string requestBody: $ref: "#/components/requestBodies/CreateAppRequest" responses: "202": description: App creation request has been received "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "403": description: User does not have permission to perform action on App "409": description: Conflict content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" get: summary: Get details of an app description: > Returns information about an existing App managed by Leo. Poll this to find out when your app has finished starting up. operationId: getApp tags: - apps parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: appName description: appName required: true schema: type: string responses: "200": description: App found, here are the details content: application/json: schema: $ref: "#/components/schemas/GetAppResponse" "403": description: User does not have permission to perform action on App "404": description: App not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" delete: summary: Deletes an existing app in the given project description: deletes an App operationId: deleteApp tags: - apps parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: appName description: appName required: true schema: type: string - in: query name: deleteDisk description: Whether or not the disk associated with the app should be deleted. Default to false if not specified. required: false schema: type: boolean default: false responses: "202": description: App deletion request accepted "403": description: User does not have permission to perform action on App "404": description: App not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/api/google/v1/apps/{googleProject}/{appName}/stop": post: summary: Stops an app with the given project and name description: > Stops the running compute, but retains any data persisted on disk. The app may be restarted with the /start endpoint. operationId: stopApp tags: - apps parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: appName description: appName required: true schema: type: string responses: "202": description: App stop request accepted "403": description: User does not have permission to perform action on app "404": description: App not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "409": description: App cannot be stopped content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/api/google/v1/apps/{googleProject}/{appName}/start": post: summary: Starts an app with the given project and name description: Starts the stopped app operationId: startApp tags: - apps parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: appName description: appName required: true schema: type: string responses: "202": description: App start request accepted "403": description: User does not have permission to perform action on app "404": description: App not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "409": description: App cannot be started content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" ## AppsV2 Paths ## "/api/apps/v2/{workspaceId}/{appName}": post: summary: Creates a new app in the given project with the given appName description: > The specified appName is suffixed and the resulting string must adhere to Google's name validation regex ?:[a-z](?:[-a-z0-9]{0,38}[a-z0-9])?. Default labels appName, googleProject, serviceAccount, and creator cannot be overridden. operationId: createAppV2 tags: - apps parameters: - in: path name: workspaceId description: workspaceId required: true schema: type: string - in: path name: appName description: appName required: true schema: type: string requestBody: $ref: "#/components/requestBodies/CreateAppV2Request" responses: "202": description: App creation request has been received "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "403": description: User does not have permission to perform action on App "409": description: Conflict content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" get: summary: Get details of an app description: > Returns information about an existing App managed by Leo. Poll this to find out when your app has finished starting up. operationId: getAppV2 tags: - apps parameters: - in: path name: workspaceId description: workspaceId required: true schema: type: string - in: path name: appName description: appName required: true schema: type: string responses: "200": description: App found, here are the details content: application/json: schema: $ref: "#/components/schemas/GetAppResponse" "403": description: User does not have permission to perform action on App "404": description: App not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" delete: summary: Deletes an existing app in the given project description: deletes an App operationId: deleteAppV2 tags: - apps parameters: - in: path name: workspaceId description: workspaceId required: true schema: type: string - in: path name: appName description: appName required: true schema: type: string - in: query name: deleteDisk description: Whether or not the disk associated with the app should be deleted. Default to false if not specified. required: false schema: type: boolean default: false responses: "202": description: App deletion request accepted "403": description: User does not have permission to perform action on App "404": description: App not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/api/apps/v2/{workspaceId}": get: summary: List apps V2 description: List all apps for a given workspaceId. operationId: listAppsV2 tags: - apps parameters: - in: path name: workspaceId description: workspaceId required: true schema: type: string - in: query name: _labels description: > Optional label key-value pairs to filter results by. Example: Querying by key1=val1,key2=val2 returns all apps that contain the key1/val1 and key2/val2 labels (possibly among other labels). Note: this string format is a workaround because Swagger doesn't support free-form query string parameters. The recommended way to use this endpoint is to specify the labels as top-level query string parameters. For instance: GET /api/google/v1/app?key1=val1&key2=val2. required: false schema: type: string - in: query name: includeDeleted description: Optional filter that includes any apps with a Deleted status. required: false schema: type: boolean default: false - in: query name: includeLabels description: > Optional label keys of the labels returned in response. Example: Querying by key1,key2,key3 returns all labels key1/val1 key2/val2 and key3 and val3 for each app in response required: false schema: type: string - in: query name: role description: Optional filter that excludes apps you did not create. Accepts "creator" or nothing. required: false schema: type: string responses: "200": description: List of apps content: application/json: schema: type: array items: $ref: "#/components/schemas/ListAppResponse" "/api/apps/v2/{workspaceId}/deleteAll": post: summary: Deletes ALL apps associated with the given workspace Id description: deletes all Apps in a workspace operationId: deleteAllAppsV2 tags: - apps parameters: - in: path name: workspaceId description: workspaceId required: true schema: type: string - in: query name: deleteDisk description: Whether or not the disk associated with the apps should be deleted. Default to false if not specified. required: false schema: type: boolean default: false responses: "202": description: App(s) deletion request accepted "403": description: User does not have permission to perform action on App(s) "404": description: App(s) not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" ## Admin API ## "/api/admin/v2/apps/update": post: summary: Updates Kubernetes apps description: Updates a designated collection of Kubernetes apps (both v1 and v2) operationId: updateApps tags: - admin requestBody: $ref: "#/components/requestBodies/UpdateAppsRequest" responses: "200": description: Dry run results successfully returned content: application/json: schema: $ref: "#/components/schemas/ListUpdateableAppResponse" "202": description: App(s) update request accepted content: application/json: schema: $ref: "#/components/schemas/ListUpdateableAppResponse" "403": description: Forbidden (user is not an admin) content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "412": description: Precondition failed (the app type and cloud provider in the request didn't match any app profiles) content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" ## Deprecated Notebook API ## "/notebooks/{googleProject}/{clusterName}": get: deprecated: true summary: (Deprecated) Access Jupyter notebooks on a Dataproc cluster description: > This URI supports all HTTP methods, not just GET as implied by this Swagger. Proxies all requests through to the Jupyter notebook server running on the given cluster. operationId: proxyCluster tags: - notebooks parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: clusterName description: clusterName required: true schema: type: string responses: "200": description: Proxy connection successful "403": description: Proxy connection unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "404": description: Cluster not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "422": description: Cluster is stopped content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "423": description: Cluster not ready for requests. It could be starting. content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/notebooks/{googleProject}/{clusterName}/api/localize": post: deprecated: true summary: Localize files to/from a Jupyter notebook server description: > Sends a command to a Jupyter notebook server to localize files to/from the server. Supports GCS paths and [Data URIs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs). Output, including any errors, will appear in `localization.log` in the working directory of the Jupyter notebook server. By default this operation will happen synchronously and the response status will reflect any errors encountered in the copy. However, if the `async` parameter is specfied then the localization will happen asynchronously to the request, and the API will always return 200. operationId: proxyLocalize tags: - notebooks parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: clusterName description: clusterName required: true schema: type: string - in: query name: async description: > If true, the copy will happen asynchronously to the request and the API will always return 200. If false (the default), the copy will happen synchronously and the response will reflect any errors encountered during the copy. required: false schema: type: boolean default: false requestBody: content: application/json: schema: type: object description: "" example: ~/file.txt: gs://somebucket/file.txt ~/directory: gs://somebucket/* gs://upload/to/this/bucketdir: ~/file.txt ~/data.txt: data:text/plain;base64,SGVsbG8sIFdvcmxkIQ%3D%3D description: > JSON object. Keys represent destinations, values represent sources. The following rules apply: * If either the source or destination is a GCS path, it will be sent to [gsutil cp](https://cloud.google.com/storage/docs/gsutil/commands/cp). Therefore this can be used to localize a file _from_ a bucket _to_ the notebook server; or delocalize a file _from_ the notebook server _to_ a bucket. * If the source is a Data URI, then the destination file will be created with the decoded data URI contents. This mode can only be used to localize files to the notebook server. In both cases all paths will be quoted & sanitized, and intermediate local directories will be made. Note that duplicate keys will lead to unexpected behaviour, so specify the destination filename explicitly if you want to localize multiple files to the same directory. required: true responses: "200": description: Proxy connection successful "400": description: "Bad request. Your POST body is probably malformed: it should be a string/string JSON object." "403": description: Proxy connection unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "404": description: Cluster not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "420": description: Cluster not ready content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "422": description: Cluster is stopped content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/notebooks/{googleProject}/{clusterName}/setCookie": get: deprecated: true summary: (Deprecated) Sets a browser cookie needed to authorize connections to a Jupyter notebook description: > If using Google token-based authorization to a Jupyter notebook, the Leo proxy accepts a Google token passed as a cookie value. This endpoint facilitates setting that cookie. It accepts a bearer token in an Authorization header and responds with a Set-Cookie header. If no bearer token is present, it unsets the cookie by returning a Set-Cookie header with a null value and expiration date in the past. operationId: setCookieApi tags: - notebooks parameters: - in: path name: googleProject required: true schema: type: string - in: path name: clusterName description: clusterName required: true schema: type: string responses: "204": description: Successfully set a cookie "401": description: Proxy connection unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "404": description: Cluster not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" /notebooks/invalidateToken: get: deprecated: true summary: (Deprecated) Invalidates a token description: > If using Google token-based auth, clients can call this endpoint when a user's Google token should be invalidated (e.g. when logging out of the application). This endpoint will unset the Leo token cookie and invalidate caches to ensure the user's proxied notebook connections stop working. operationId: invalidateTokenApi tags: - notebooks responses: "204": description: Successfully invalidated a token "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" ## Proxy API ## "/proxy/{googleProject}/{runtimeName}/jupyter": get: summary: Access Jupyter (if installed) on a Leonardo runtime description: > This URI supports all HTTP methods, not just GET as implied by this Swagger. Proxies all requests through to the tool server running on the given runtime. operationId: proxyClusterJupyter tags: - proxy parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: runtimeName description: runtimeName required: true schema: type: string responses: "200": description: Proxy connection successful "403": description: Proxy connection unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "404": description: Runtime not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "422": description: Runtime is stopped content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "423": description: Runtime not ready content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/proxy/{googleProject}/{runtimeName}/jupyter/lab": get: summary: Access Jupyter Lab (if installed) on a Leonardo runtime description: > This URI supports all HTTP methods, not just GET as implied by this Swagger. Proxies all requests through to the tool server running on the given runtime. operationId: proxyClusterJupyterLab tags: - proxy parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: runtimeName description: runtimeName required: true schema: type: string responses: "200": description: Proxy connection successful "403": description: Proxy connection unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "404": description: Runtime not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "422": description: Runtime is stopped content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "423": description: Runtime not ready content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/proxy/{googleProject}/{runtimeName}/rstudio": get: summary: Access RStudio (if installed) on a Leonardo runtime description: > This URI supports all HTTP methods, not just GET as implied by this Swagger. Proxies all requests through to the tool server running on the given runtime. operationId: proxyClusterRStudio tags: - proxy parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: runtimeName description: runtimeName required: true schema: type: string responses: "200": description: Proxy connection successful "403": description: Proxy connection unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "404": description: Runtime not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "422": description: Runtime is stopped content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "423": description: Runtime not ready content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/proxy/google/v1/apps/{googleProject}/{appName}/{serviceName}": get: summary: Access an app if the app and service name exists description: > This URI supports all HTTP methods, not just GET as implied by this Swagger. Proxies all requests through to the app via an ingress controller operationId: proxyApp tags: - proxy parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: appName description: appName required: true schema: type: string - in: path name: serviceName description: serviceName required: true schema: type: string responses: "200": description: Proxy connection successful "403": description: Proxy connection unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "404": description: App or service not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "422": description: App is stopped content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "423": description: App not ready content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/proxy/setCookie": get: summary: Sets a browser cookie needed to authorize connections to a Leonardo runtime description: > If using Google token-based authorization to a runtime, the Leo proxy accepts a Google token passed as a cookie value. This endpoint facilitates setting that cookie. It accepts a bearer token in an Authorization header and responds with a Set-Cookie header. If no bearer token is present, it unsets the cookie by returning a Set-Cookie header with a null value and expiration date in the past. operationId: setCookie tags: - proxy responses: "204": description: Successfully set a cookie "401": description: Proxy connection unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/proxy/invalidateToken": get: summary: Invalidates a token description: > If using Google token-based auth, clients can call this endpoint when a user's Google token should be invalidated (e.g. when logging out of the application). This endpoint will unset the Leo token cookie and invalidate caches to ensure the user's proxied connections stop working. operationId: invalidateToken tags: - proxy responses: "204": description: Successfully invalidated a token "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/proxy/{googleProject}/{runtimeName}/setCookie": get: deprecated: true summary: (Deprecated) Sets a browser cookie needed to authorize connections to a Leonardo runtime description: > If using Google token-based authorization to a runtime, the Leo proxy accepts a Google token passed as a cookie value. This endpoint facilitates setting that cookie. It accepts a bearer token in an Authorization header and responds with a Set-Cookie header. If no bearer token is present, it unsets the cookie by returning a Set-Cookie header with a null value and expiration date in the past. operationId: setCookieDeprecated tags: - proxy parameters: - in: path name: googleProject required: true schema: type: string - in: path name: runtimeName description: runtimeName required: true schema: type: string responses: "204": description: Successfully set a cookie "401": description: Proxy connection unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "404": description: Runtime not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/proxy/{googleProject}/{runtimeName}/yarn": get: summary: YARN Resource Manager description: > Only available for Dataproc runtimes with Component Gateway enabled. See https://cloud.google.com/dataproc/docs/concepts/accessing/dataproc-gateways operationId: yarn tags: - proxy parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: runtimeName description: runtimeName required: true schema: type: string responses: "200": description: Proxy connection successful "403": description: Proxy connection unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "404": description: Runtime not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "422": description: Runtime is stopped content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "423": description: Runtime not ready content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/proxy/{googleProject}/{runtimeName}/jobhistory": get: summary: MapReduce Job History description: > Only available for Dataproc runtimes with Component Gateway enabled. See https://cloud.google.com/dataproc/docs/concepts/accessing/dataproc-gateways operationId: jobhistory tags: - proxy parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: runtimeName description: runtimeName required: true schema: type: string responses: "200": description: Proxy connection successful "403": description: Proxy connection unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "404": description: Runtime not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "422": description: Runtime is stopped content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "423": description: Runtime not ready content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/proxy/{googleProject}/{runtimeName}/apphistory": get: summary: YARN Application Timeline description: > Only available for Dataproc runtimes with Component Gateway enabled. See https://cloud.google.com/dataproc/docs/concepts/accessing/dataproc-gateways operationId: apphistory tags: - proxy parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: runtimeName description: runtimeName required: true schema: type: string responses: "200": description: Proxy connection successful "403": description: Proxy connection unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "404": description: Runtime not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "422": description: Runtime is stopped content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "423": description: Runtime not ready content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/proxy/{googleProject}/{runtimeName}/sparkhistory": get: summary: Spark History Server description: > Only available for Dataproc runtimes with Component Gateway enabled. See https://cloud.google.com/dataproc/docs/concepts/accessing/dataproc-gateways operationId: sparkhistory tags: - proxy parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: runtimeName description: runtimeName required: true schema: type: string responses: "200": description: Proxy connection successful "403": description: Proxy connection unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "404": description: Runtime not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "422": description: Runtime is stopped content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "423": description: Runtime not ready content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "/proxy/{googleProject}/{runtimeName}/hdfs": get: summary: HDFS NameNode description: > Only available for Dataproc runtimes with Component Gateway enabled. See https://cloud.google.com/dataproc/docs/concepts/accessing/dataproc-gateways operationId: hdfs tags: - proxy parameters: - in: path name: googleProject description: googleProject required: true schema: type: string - in: path name: runtimeName description: runtimeName required: true schema: type: string responses: "200": description: Proxy connection successful "403": description: Proxy connection unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "404": description: Runtime not found content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "422": description: Runtime is stopped content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "423": description: Runtime not ready content: application/json: schema: $ref: "#/components/schemas/ErrorReport" "500": description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorReport" ########################################################################################## ## COMPONENTS ########################################################################################## components: requestBodies: CreateRuntimeRequest: content: application/json: schema: $ref: "#/components/schemas/CreateRuntimeRequest" example: runtimeConfig: cloudService: gce machineType: n1-standard-4 diskSize: 100 UpdateRuntimeRequest: content: application/json: schema: $ref: "#/components/schemas/UpdateRuntimeRequest" example: allowStop: true runtimeConfig: cloudService: gce machineType: n1-highmem-16 diskSize: 500 labelsToUpsert: {new_label : value, old_label : new_value} labelsToDelete: [existing_label] CreateDiskRequest: content: application/json: schema: $ref: "#/components/schemas/CreateDiskRequest" example: size: 500 diskType: "pd-standard" blockSize: 4096 UpdateDiskRequest: content: application/json: schema: $ref: "#/components/schemas/UpdateDiskRequest" example: size: 600 CreateAppRequest: content: application/json: schema: $ref: "#/components/schemas/CreateAppRequest" example: diskConfig: name: "disk1" appType: "GALAXY" CreateAppV2Request: content: application/json: schema: $ref: "#/components/schemas/CreateAppRequest" example: appType: "CROMWELL" CreateAzureRuntimeRequest: content: application/json: schema: $ref: "#/components/schemas/CreateAzureRuntimeRequest" example: labels: { saturnRuntimeName: "saturn-ab9134" } machineSize: "Standard_DS1_v2" disk: { labels: {}, name: "disk1", size: 50 } autopauseThreshold: 15 UpdateAppsRequest: content: application/json: schema: $ref: "#/components/schemas/UpdateAppsRequest" example: appType: CROMWELL cloudProvider: AZURE dryRun: true securitySchemes: oidc: type: openIdConnect openIdConnectUrl: OPEN_ID_CONNECT_URL x-tokenName: id_token schemas: AppType: type: string enum: - CROMWELL - CUSTOM - GALAXY - WDS - HAIL_BATCH - ALLOWED - WORKFLOWS_APP - CROMWELL_RUNNER_APP AllowedChartName: type: string enum: - rstudio - sas AppStatus: type: string enum: - DELETED - DELETING - ERROR - PROVISIONING - RUNNING - STARTING - STATUS_UNSPECIFIED - STOPPED - STOPPING AppAccessScope: type: string enum: - USER_PRIVATE - WORKSPACE_SHARED DiskType: type: string enum: - pd-standard - pd-ssd - pd-balanced CloudProvider: type: string enum: - GCP - AZURE ClusterStatus: type: string enum: - Creating - Running - Updating - Error - Stopping - Stopped - Starting - Deleting - Deleted - Unknown InstanceStatus: type: string enum: - Provisioning - Staging - Running - Stopping - Stopped - Suspending - Suspended - Terminated DiskStatus: type: string enum: - Creating - Restoring - Failed - Ready - Deleting - Deleted ErrorReport: description: "" required: - source - message - causes - stackTrace properties: source: type: string description: service causing error message: type: string description: what went wrong exceptionClass: type: string description: class of exception thrown statusCode: type: integer description: HTTP status code causes: type: array description: errors triggering this one items: $ref: "#/components/schemas/ErrorReport" stackTrace: type: array description: stack trace items: $ref: "#/components/schemas/StackTraceElement" StackTraceElement: description: "" required: - className - methodName - fileName - lineNumber properties: className: type: string description: class name methodName: type: string description: method name fileName: type: string description: source file name lineNumber: type: integer description: line number GetRuntimeResponse: description: "" required: - id - runtimeName - googleProject - cloudContext - serviceAccount - auditInfo - runtimeConfig - proxyUrl - status - labels - errors - autopauseThreshold - runtimeImages - scopes - customEnvironmentVariables - patchInProgress properties: id: type: integer description: The leonardo ID of the runtime runtimeName: type: string description: The user-supplied name for the runtime googleProject: type: string description: Deprecated. The Google Project used to create the runtime cloudContext: $ref: '#/components/schemas/CloudContext' serviceAccount: type: string description: The Google Service Account used to create the runtime asyncRuntimeFields: $ref: "#/components/schemas/AsyncRuntimeFields" auditInfo: $ref: "#/components/schemas/AuditInfo" runtimeConfig: $ref: "#/components/schemas/OneOfRuntimeConfigInResponse" proxyUrl: type: string description: The URL to access a tool on the runtime status: $ref: "#/components/schemas/ClusterStatus" labels: type: object description: The labels to be placed on the runtime. Of type Map[String,String] userScriptUri: type: string description: > Optional GCS or HTTP URI to a bash script the user wishes to run inside their Docker container. This script runs exactly once when the runtime is first initialized. Logs from this script can be found in the Leo staging bucket for the runtime. The script is run as root and docker --privileged. jupyterUserScriptUri: type: string description: DEPRECATED on 05/2021. Please use userScriptUri instead. This field may be removed after 6 months of deprecation. deprecated: true startUserScriptUri: type: string description: > Optional GCS or HTTP URI to a bash script the user wishes to run on runtime start inside the Docker container. In contrast to userScriptUri, this always runs before starting the Docker container, both on initial runtime creation and on runtime resume (sserScriptUri runs once on runtime creation). This script may be used to launch background processes which would not otherwise survive a runtime stop/start. The script is pulled once at runtime creation time; subsequent client changes to the user script at this URI do not affect the runtime. Timestamped logs for this script can be found in the Leo staging bucket for the cluster. The script is run as root and docker --privileged. jupyterStartUserScriptUri: type: string description: DEPRECATED on 05/2021. Please use startUserScriptUri instead. This field may be removed after 6 months of deprecation. deprecated: true errors: type: array description: The list of errors that were encountered on runtime create. Each error consists of the error message, code and timestamp items: $ref: "#/components/schemas/ClusterError" userJupyterExtensionConfig: $ref: "#/components/schemas/UserJupyterExtensionConfig" autopauseThreshold: type: integer description: The number of minutes of idle time to elapse before the runtime is autopaused. A value of 0 is equivalent to autopause being turned off. defaultClientId: type: string description: The default Google Client ID. runtimeImages: type: array description: The docker images on the runtime items: $ref: '#/components/schemas/RuntimeImage' scopes: type: array items: type: string description: The scopes for the runtime. customEnvironmentVariables: type: object description: Optional environment variables to be set on the runtime. diskConfig: $ref: "#/components/schemas/DiskConfig" patchInProgress: type: boolean description: Whether there is a patch in progress on the runtime. Is used to indicate updates that require status transitions. ListRuntimeResponse: description: "" required: - id - runtimeName - googleProject - serviceAccount - runtimeConfig - status - labels properties: id: type: integer description: Internal Leonardo ID of the runtime workspaceId: type: string description: Id of the workspace associated with this runtime runtimeName: type: string description: The user-supplied name for the runtime auditInfo: allOf: - $ref: "#/components/schemas/AuditInfo" - type: object googleProject: type: string description: Deprecated. The Google Project used to create the runtime cloudContext: $ref: '#/components/schemas/CloudContext' runtimeConfig: $ref: "#/components/schemas/OneOfRuntimeConfigInResponse" proxyUrl: type: string description: The URL to access a tool on the runtime status: $ref: "#/components/schemas/ClusterStatus" labels: type: object description: The labels to be placed on the runtime. Of type Map[String,String] patchInProgress: type: boolean description: Whether there is a patch in progress on the runtime. Is used to indicate updates that require status transitions. ListPersistentDiskResponse: description: "" required: - id - cloudContext - zone - name - status - auditInfo - size - diskType - blockSize - labels properties: id: type: integer description: Internal Leonardo ID of the persistent disk cloudContext: $ref: '#/components/schemas/CloudContext' zone: type: string description: The google zone in which the persistent disk was created name: type: string description: The user-supplied name of the persistent disk status: $ref: "#/components/schemas/DiskStatus" auditInfo: $ref: "#/components/schemas/AuditInfo" size: type: integer description: Size of persistent disk in GB diskType: $ref: "#/components/schemas/DiskType" blockSize: type: integer description: Block size of persistent disk in bytes labels: type: object description: The labels of each persistent disk in the response whose key is in includeLabels in the request. Of type Map[String,String] GetPersistentDiskResponse: description: "" required: - id - cloudContext - zone - name - serviceAccount - samResourceId - status - auditInfo - size - diskType - blockSize - labels - formattedBy properties: id: type: integer description: The cloud-platform provided unique ID of this persistent disk cloudContext: $ref: '#/components/schemas/CloudContext' zone: type: string description: The zone in which the persistent disk was created name: type: string description: The name of the persistent disk serviceAccount: type: string description: The account used to create the disk samResourceId: type: string description: Internal resource ID of the persistent disk status: $ref: "#/components/schemas/DiskStatus" auditInfo: $ref: "#/components/schemas/AuditInfo" size: type: integer description: Size of persistent disk in GB diskType: $ref: "#/components/schemas/DiskType" blockSize: type: integer description: Block size of persistent disk in bytes labels: type: object description: The labels to be placed on the persistent disk. Of type Map[String,String] formattedBy: type: string enum: - GALAXY - GCE - CROMWELL - CUSTOM - ALLOWED description: App that formatted disk, missing if unformatted GetPersistentDiskV2Response: description: "" required: - id - cloudContext - zone - name - serviceAccount - samResource - status - auditInfo - size - diskType - blockSize - labels properties: id: type: integer description: The cloud-platform provided unique ID of this persistent disk cloudContext: $ref: '#/components/schemas/CloudContext' zone: type: string description: The zone in which the persistent disk was created name: type: string description: The name of the persistent disk serviceAccount: type: string description: The account used to create the disk samResource: type: string description: Internal resource ID of the persistent disk status: $ref: "#/components/schemas/DiskStatus" auditInfo: $ref: "#/components/schemas/AuditInfo" size: type: integer description: Size of persistent disk in GB diskType: $ref: "#/components/schemas/DiskType" blockSize: type: integer description: Block size of persistent disk in bytes labels: type: object description: The labels to be placed on the persistent disk. Of type Map[String,String] workspaceId: type: string description: The id of the disk's workspace formattedBy: type: string enum: - GALAXY - GCE - CROMWELL - CUSTOM - ALLOWED description: App that formatted disk, missing if unformatted InstanceKey: description: "" required: - project - zone - name properties: project: type: string description: The Google Project the instance belongs to zone: type: string description: The Google zone the instance belongs to name: type: string description: The name of the instance Instance: description: "" required: - key - googleId - status properties: key: $ref: "#/components/schemas/InstanceKey" googleId: type: string description: Google's unique id for this instance status: $ref: "#/components/schemas/InstanceStatus" ip: type: string description: The public IP address of the instance, if any dataprocRole: type: string description: The dataproc role (master, worker, preemptible worker) of this instance, if any createdDate: type: string description: The date and time the instance was created, in ISO-8601 format CreateRuntimeRequest: description: "Creates a new runtime" type: object properties: labels: type: object description: The labels to be placed on the runtime. Of type Map[String,String] userJupyterExtensionConfig: $ref: "#/components/schemas/UserJupyterExtensionConfig" userScriptUri: type: string description: > Optional GCS or HTTP URI to a bash script the user wishes to run inside their Docker container. This script runs exactly once when the runtime is first initialized. Logs from this script can be found in the Leo staging bucket for the runtime. The script is run as root and docker --privileged. jupyterUserScriptUri: type: string description: DEPRECATED on 05/2021. Please use userScriptUri instead. This field may be removed after 6 months of deprecation. deprecated: true startUserScriptUri: type: string description: > Optional GCS or HTTP URI to a bash script the user wishes to run on runtime start inside the Docker container. In contrast to userScriptUri, this always runs before starting the Docker container, both on initial runtime creation and on runtime resume (sserScriptUri runs once on runtime creation). This script may be used to launch background processes which would not otherwise survive a runtime stop/start. The script is pulled once at runtime creation time; subsequent client changes to the user script at this URI do not affect the runtime. Timestamped logs for this script can be found in the Leo staging bucket for the cluster. The script is run as root and docker --privileged. jupyterStartUserScriptUri: type: string description: DEPRECATED on 05/2021. Please use startUserScriptUri instead. This field may be removed after 6 months of deprecation. deprecated: true runtimeConfig: $ref: "#/components/schemas/OneOfRuntimeConfig" autopause: type: boolean description: Whether autopause feature is enabled for this specific cluster. If unset, autopause will be enabled and the threshold value will be set to either the autopauseThreshold value or the system default if autopauseThreshold is also unset. autopauseThreshold: type: integer description: The number of minutes of idle time to elapse before the cluster is autopaused. If autopause is set to false, this value is disregarded. A value of 0 is equivalent to autopause being turned off. If autopause is enabled and this is unset, a system default threshold will be used. defaultClientId: type: string description: The default Google Client ID. timeoutInMinutes: type: integer description: Custom image deployment time out in minutes. The value is currently capped at a maximum of 30 minutes. If nothing is provided, a default of 10 minutes will be used. toolDockerImage: type: string description: The tool docker image to install. May be Google Container Repository (GCR), GitHub Container Repository (GHCR), or Dockerhub. If not set, a default Jupyter image will be installed. welderRegistry: type: string enum: [GCR, DockerHub] description: The container registry from which to pull the latest version of welder. welderDockerImage: type: string description: > The Welder docker image to install. Only takes effect if the tool being installed supports welder. May be Dockerhub or GCR. If not set, then a default Welder image will be installed. scopes: type: array items: type: string description: > The scopes for the cluster. Defaults (userinfo.email, userinfo.profile, bigquery, source.read_only) will be used if left blank. Important: If you choose to specify custom scopes, the defaults will be overwritten. Thus, if you need the defaults, you will need to include the default scopes in your custom list of scopes. default: - https://www.googleapis.com/auth/userinfo.email - https://www.googleapis.com/auth/userinfo.profile - https://www.googleapis.com/auth/bigquery - https://www.googleapis.com/auth/source.read_only customEnvironmentVariables: type: object description: Optional environment variables to be set on the cluster. CreateAzureRuntimeRequest: description: Creates a new runtime type: object required: - machineSize - disk properties: labels: type: object description: The labels to be placed on the runtime. Of type Map[String,String] machineSize: type: string description: The azure-specific machine size identifier string. See https://docs.microsoft.com/en-us/azure/virtual-machines/sizes-general imageUri: type: string description: The azure identifier for the vm image uri. Optional, there is an intelligent default. Note this must be in the same region specified in the request Ex, /subscriptions/3efc5bdf-be0e-44e7-b1d7-c08931e3c16c/resourceGroups/mrg-qi-1-preview-20210517084351/providers/Microsoft.Compute/galleries/msdsvm/images/customized_ms_dsvm/versions/0.1.0 customEnvironmentVariables: type: object description: an optional set of key value pairs for environment variables to be injected into the VM disk: $ref: "#/components/schemas/AzureDiskConfig" autopauseThreshold: type: int description: an optional number to determine when a runtime should autopause AzureDiskConfig: description: The config for creating an azure disk type: object required: - name properties: labels: type: object description: The labels to be placed on the runtime. Of type Map[String,String] name: type: string description: The name of the disk in azure size: type: integer description: the size of the disk in GB diskType: type: string description: Not currently supported, but included for future expansion. One of [Standard, SSD]. UpdateGceConfig: description: Configuration for Google Compute Engine instances. allOf: - $ref: '#/components/schemas/UpdateRuntimeConfig' - type: object properties: machineType: type: string description: > Optional, the machine type determines the number of CPUs and memory for the instance. For example "n1-standard-16" or "n1-highmem-64". To decide which is right for you, see https://cloud.google.com/compute/docs/machine-types diskSize: type: integer description: > Optional, disk size in gigabytes UpdateDataprocConfig: description: Configuration for Google Dataproc clusters. allOf: - $ref: '#/components/schemas/UpdateRuntimeConfig' - type: object properties: masterMachineType: type: string description: > Optional, the machine type determines the number of CPUs and memory for the cluster master node. For example "n1-standard-16" or "n1-highmem-64". To decide which is right for you, see https://cloud.google.com/compute/docs/machine-types masterDiskSize: type: integer description: > Optional, disk size of the master node in gigabytes numberOfWorkers: type: integer description: > Optional, number of workers in the cluster numberOfPreemptibleWorkers: type: integer description: > Optional, number of preemptible workers in the cluster UpdateRuntimeConfig: description: Updates a runtime configuration type: object required: - cloudService properties: cloudService: type: string enum: [gce, dataproc] UpdateRuntimeRequest: description: Updates a runtime type: object properties: runtimeConfig: oneOf: - $ref: "#/components/schemas/UpdateGceConfig" - $ref: "#/components/schemas/UpdateDataprocConfig" discriminator: propertyName: cloudService mapping: gce: "#/components/schemas/UpdateGceConfig" dataproc: "#/components/schemas/UpdateDataprocConfig" allowStop: type: boolean description: Whether leo should stop the runtime if it is necessary for the update. If false, an exception will be thrown in cases where a stop was required. Defaults to false. autopause: type: boolean description: Whether autopause feature is enabled for this specific runtime. autopauseThreshold: type: integer description: The number of minutes of idle time to elapse before the runtime is autopaused. If autopause is set to false, this value is disregarded. A value of 0 is equivalent to autopause being turned off. labelsToUpsert: type: object description: Labels to update or add on the runtime. Of type Map[String, String]. You cannot alter default labels or add a label with a null value. labelsToDelete: type: array description: A set of label keys to remove from the runtime labels. Of type Set[String]. You cannot delete a default label. items: type: string CreateDiskRequest: description: "Creates a new persistent disk" type: object properties: labels: type: object description: The labels to be placed on the persistent disk. Of type Map[String,String] size: type: integer description: The size of the persistent disk to be created in GB. diskType: $ref: "#/components/schemas/DiskType" blockSize: type: integer description: The block size of the persistent disk to be created in bytes. sourceDisk: $ref: "#/components/schemas/SourceDisk" SourceDisk: description: opitonal location of a disk to clone type: object properties: googleProject: type: string description: google project containing the source disk to be cloned name: type: string description: name of the source disk to be cloned UpdateDiskRequest: description: "Updates an existing persistent disk" type: object properties: labels: type: object description: The labels to be added or updated on the persistent disk. Of type Map[String,String] size: type: integer description: The size in GB that the persistent disk is to be updated to. diskType: $ref: "#/components/schemas/DiskType" blockSize: type: integer description: The block size in bytes that the persistent disk is to be updated to. ClusterError: description: Errors encountered on cluster create required: - errorMessage - errorCode - timestamp properties: errorMessage: type: string description: Error message errorCode: type: integer description: Error code timestamp: type: string description: timestamp for error in ISO 8601 format traceId: type: string description: trace for error AsyncRuntimeFields: description: Fields populated asynchronously to the runtime's creation type: object required: - googleId - operationName - stagingBucket properties: googleId: type: string description: Google's UUID for the runtime operationName: type: string description: The google operation name for creating this runtime. This is globally unique among operation names in google. stagingBucket: type: string description: The staging bucket associated with this user's runtime. Used for various logs associated with runtime creation. Useful if creation fails. hostIp: type: string description: optional. The hostIP associated with this runtime. AuditInfo: description: Fields associated with the audit trail for this runtime type: object required: - creator - createdDate - dateAccessed properties: creator: type: string description: The email for the user that created this runtime createdDate: type: string description: timestamp for the date this runtime was created in ISO 8601 format destroyedDate: type: string description: timestamp for the date this runtime was deleted in ISO 8601 format. This is null if it has not been deleted yet. dateAccessed: type: string description: timestamp for the date this runtime was last accessed in ISO 8601 format. This is null if it has not been deleted yet. LeonardoVersion: type: object properties: version: type: string RuntimeConfig: type: object required: - cloudService properties: cloudService: type: string enum: [GCE, DATAPROC, AZURE_VM] configType: type: string enum: [Dataproc, GceConfig, GceWithPdConfig, AzureVmConfig] OneOfRuntimeConfig: oneOf: - $ref: "#/components/schemas/GceConfig" - $ref: "#/components/schemas/GceWithPdConfig" - $ref: "#/components/schemas/DataprocConfig" - $ref: "#/components/schemas/AzureConfig" discriminator: propertyName: cloudService mapping: gce: "#/components/schemas/GceWithPdConfig" dataproc: "#/components/schemas/DataprocConfig" azure_vm: "#/components/schemas/AzureConfig" OneOfRuntimeConfigInResponse: oneOf: - $ref: "#/components/schemas/GceWithPdConfigInResponse" - $ref: "#/components/schemas/DataprocConfig" - $ref: "#/components/schemas/AzureConfig" discriminator: propertyName: cloudService mapping: GCE: "#/components/schemas/GceWithPdConfigInResponse" DATAPROC: "#/components/schemas/DataprocConfig" AZURE_VM: "#/components/schemas/AzureConfig" RuntimeImage: type: object required: - imageType - imageUrl - timestamp properties: imageType: description: "The container this image supports. Ex Jupyter, Proxy, VM" type: string imageUrl: description: "The place this image can be pulled from" type: string timestamp: type: string description: timestamp for image addition to the runtime in ISO 8601 format homeDirectory: type: string description: Home directory in the image GceConfig: description: Configuration for Google Compute Engine instances. allOf: - $ref: '#/components/schemas/RuntimeConfig' - type: object properties: diskSize: type: integer description: > Optional, the size in gigabytes of the disk on the GCE VM. Minimum size is 50GB. If unspecified, default size is 100GB. bootDiskSize: type: integer description: UNUSED machineType: type: string description: > Optional, the machine type determines the number of CPUs and memory for the master node. For example "n1-standard-16" or "n1-highmem-64". If unspecified, defaults to creating a "n1-standard-4" machine. To decide which is right for you, see https://cloud.google.com/compute/docs/machine-types zone: type: string description: > Optional, the deployment area of the GCE VM. For example, us-east1-a or europe-west2-c. Defaults to us-central1-a. gpuConfig: $ref: "#/components/schemas/GpuConfig" GceWithPdConfig: description: Configuration for Google Compute Engine instances. allOf: - $ref: '#/components/schemas/RuntimeConfig' - type: object properties: persistentDisk: $ref: "#/components/schemas/PersistentDiskRequest" bootDiskSize: type: integer description: UNUSED machineType: type: string description: > Optional, the machine type determines the number of CPUs and memory for the master node. For example "n1-standard-16" or "n1-highmem-64". If unspecified, defaults to creating a "n1-standard-4" machine. To decide which is right for you, see https://cloud.google.com/compute/docs/machine-types zone: type: string description: > Optional, the deployment area of the GCE VM. For example, us-east1-a or europe-west2-c. Defaults to us-central1-a. gpuConfig: $ref: "#/components/schemas/GpuConfig" GceWithPdConfigInResponse: description: Configuration for Google Compute Engine instances. allOf: - $ref: '#/components/schemas/RuntimeConfig' - type: object required: - machineType - bootDiskSize - zone properties: persistentDiskId: type: integer bootDiskSize: type: integer description: size for boot disk machineType: type: string description: > Optional, the machine type determines the number of CPUs and memory for the master node. For example "n1-standard-16" or "n1-highmem-64". If unspecified, defaults to creating a "n1-standard-4" machine. To decide which is right for you, see https://cloud.google.com/compute/docs/machine-types zone: type: string description: > Optional, the deployment area of the GCE VM. For example, us-east1-a or europe-west2-c. Defaults to us-central1-a. gpuConfig: $ref: "#/components/schemas/GpuConfig" DataprocConfig: description: Configuration for a single Dataproc cluster. allOf: - $ref: '#/components/schemas/RuntimeConfig' - type: object required: - numberOfWorkers - masterMachineType properties: numberOfWorkers: type: integer description: > Optional, number of workers in the cluster. Can be 0 (default), 2 or more. Google Dataproc does not allow 1 worker. masterMachineType: type: string description: > Optional, the machine type determines the number of CPUs and memory for the master node. For example "n1-standard-16" or "n1-highmem-64". If unspecified, defaults to creating a "n1-standard-4" machine. To decide which is right for you, see https://cloud.google.com/compute/docs/machine-types masterDiskSize: type: integer description: > Optional, the size in gigabytes of the disk on the master node. Minimum size is 50GB. If unspecified, default size is 100GB. workerMachineType: type: string description: > Optional, the machine type determines the number of CPUs and memory for the worker nodes. For example "n1-standard-16" or "n1-highmem-64". If unspecified, defaults to creating a "n1-standard-4" machine. To decide which is right for you, see https://cloud.google.com/compute/docs/machine-types. Ignored if numberOfWorkers is 0. workerDiskSize: type: integer description: > Optional, the size in gigabytes of the disk on the worker nodes. Minimum size is 10GB. If unspecified, default size is 100GB. Ignored if numberOfWorkers is 0. numberOfWorkerLocalSSDs: type: integer description: > Optional, the number of local solid state disks for workers. If unspecified, the default number is 0. Ignored if numberOfWorkers is 0. numberOfPreemptibleWorkers: type: integer description: > Optional, the number of preemptible workers. If unspecified, the default number is 0. Ignored if numberOfWorkers is 0. For more information, see https://cloud.google.com/compute/docs/instances/preemptible properties: description: > Example {"spark:spark.executor.memory": "10g"}. See https://cloud.google.com/dataproc/docs/concepts/configuring-clusters/cluster-properties for allowed property settings type: object additionalProperties: type: string region: type: string description: > Optional, the deployment region of the cluster. For example, us-east1 or europe-west2. Defaults to us-central1. componentGatewayEnabled: type: boolean description: > Optional, specifies whether to enable Dataproc Component Gateway on the cluster. This can be used for accessing Spark web UIs. See https://cloud.google.com/dataproc/docs/concepts/accessing/dataproc-gateways for more details. Defaults to false. workerPrivateAccess: type: boolean description: > Optional, specifies whether to prevent public Internet access from the Dataproc worker nodes, if any. Does not affect the master node. Defaults to false. AzureConfig: description: Configuration for an Azure VM allOf: - $ref: '#/components/schemas/RuntimeConfig' - type: object required: - machineType - persistentDiskId properties: machineType: type: string description: > Azure machine type describing number of CPUs/Memory as , ex: Standard_DS1_v2. See https://learn.microsoft.com/en-us/azure/virtual-machines/sizes persistentDiskId: type: number description: > The id of the persistent disk associated with this runtime (this is Leo's internal ID for the disk) region: type: string description: > The azure region this resource resides in UserJupyterExtensionConfig: description: Specification of Jupyter Extensions to be installed on the cluster properties: nbExtensions: type: object description: > Optional, map of extension name and nbExtension. The nbExtension can either be a tar.gz or .js file, either on google storage or at a URL, or a python package. An archive must not include a parent directory, and must have an entry point named 'main'. For more information on notebook extensions, see http://jupyter-notebook.readthedocs.io/en/latest/extending/frontend_extensions.html. Example, {"ext1":"gs://bucket/extension.tar.gz", "ext2":"python-package", "ext3":"http://foo.com/extension.js"} serverExtensions: type: object description: > Optional, map of extension name and server extension. The serverExtensions can either be a tar.gz file on google storage or a python package. Example, {"ext1":"gs://bucket/extension.tar.gz", "ext2":"python-package"} combinedExtensions: type: object description: > Optional, map of extension name and notebook plus server extension. The extension can either be a tar.gz file on google storage or a python package. Example, {"ext1":"gs://bucket/extension.tar.gz", "ext2":"python-package"} labExtensions: type: object description: > Optional, map of extension name and lab extension. The extension should be a verified jupyterlab extension that is uploaded to npm (list of public extensions here: https://github.com/search?utf8=%E2%9C%93&q=topic%3Ajupyterlab-extension&type=Repositories), a gzipped tarball made using 'npm pack', a folder structured by 'jlpm build', a JS file to be inserted into an JL extension template (see https://github.com/jupyterlab/extension-cookiecutter-js), or a URL to one of the last three options. SystemStatus: description: status of each subsystem Leonardo depends on type: object required: - ok - systems properties: ok: type: boolean description: true if everything is ok, false if anything is amiss systems: type: object description: Map[String, SubsystemStatus] DiskConfig: description: The configuration of a persistent disk, returned in runtime responses type: object required: - name - size - diskType - blockSize properties: name: type: string description: Name of the persistent disk size: type: integer description: Size of persistent disk in GB diskType: $ref: "#/components/schemas/DiskType" blockSize: type: integer description: Block size of persistent disk in bytes CreateRuntimeResponse: description: response for create runtime APIs required: - traceId type: object properties: traceId: type: string description: traceId that's useful for debugging. CreateAppRequest: description: the configuration of an app, used to create an app type: object properties: diskConfig: $ref: '#/components/schemas/PersistentDiskRequest' appType: $ref: '#/components/schemas/AppType' allowedChartName: $ref: '#/components/schemas/AllowedChartName' accessScope: $ref: '#/components/schemas/AppAccessScope' kubernetesRuntimeConfig: $ref: '#/components/schemas/KubernetesRuntimeConfig' labels: type: object description: The labels to be placed on the cluster. Of type Map[String,String] customEnvironmentVariables: type: object description: Optional environment variables to be set on the app descriptorPath: type: string description: URL path to an app descriptor file. Only used if appType is CUSTOM. extraArgs: type: array items: type: string description: Extra arguments to pass to the application. Only used if appType is CUSTOM. workspaceId: type: string description: Optional id of workspace. Every app must have a workspaceId, but this is not required for backwards-compatibility. Note, if you're using v2 APIs, this field is not used. sourceWorkspaceId: type: string description: Optional id of source workspace if app is a clone. autodeleteThreshold: type: integer description: The number of minutes of idle time to elapse before the app is deleted. When autodeleteEnabled is true, a positive integer is required autodeleteEnabled: type: boolean description: Whether to turn on autodelete UpdateAppsRequest: description: a request to update a specific set of apps (v1 or v2) required: - appType - cloudProvider type: object properties: appType: $ref: '#/components/schemas/AppType' cloudProvider: $ref: '#/components/schemas/CloudProvider' appVersionsInclude: type: array description: If provided, apps currently running these chart versions will be updated. Applied after a config-level default exclusion list. items: type: string appVersionsExclude: type: array description: If provided, apps currently running these chart versions will NOT be updated. Applied after a config-level default exclusion list. items: type: string googleProject: type: string description: If provided, update apps in this Google project workspaceId: type: string description: If provided, update apps in this workspace appNames: type: array description: If provided, apps with these names will be updated items: type: string dryRun: type: boolean description: If true, report on what apps would be updated but take no action. Defaults to false. GetAppResponse: description: the configuration of an app required: - kubernetesRuntimeConfig - status - auditInfo type: object properties: workspaceId: type: string description: 'The Terra workspace id for the app. This is not present for apps created with V1 endpoints.' appName: type: string description: the name of the app cloudContext: $ref: '#/components/schemas/CloudContext' region: type: string description: region of app kubernetesRuntimeConfig: $ref: '#/components/schemas/KubernetesRuntimeConfig' errors: type: array description: The list of errors that the app has encountered. items: $ref: "#/components/schemas/KubernetesError" status: $ref: "#/components/schemas/AppStatus" proxyUrls: description: map of service name to proxyUrl type: object additionalProperties: type: string diskName: type: string description: the name of the disk associated with this app customEnvironmentVariables: type: object description: Optional environment variables to be set on the app auditInfo: $ref: "#/components/schemas/AuditInfo" appType: $ref: '#/components/schemas/AppType' accessScope: $ref: '#/components/schemas/AppAccessScope' labels: type: object description: The labels of each app in the response whose key is in includeLabels in the request. Of type Map[String,String] autodeleteEnabled: type: boolean description: Whether to turn on autodelete autodeleteThreshold: type: integer description: The number of minutes of idle time to elapse before the app is deleted. When autodeleteEnabled is true, a positive integer is required ListAppResponse: description: the configuration of an app required: - kubernetesRuntimeConfig - status - auditInfo type: object properties: workspaceId: type: string description: workspaceId cloudContext: $ref: '#/components/schemas/CloudContext' region: type: string description: region of app kubernetesRuntimeConfig: $ref: '#/components/schemas/KubernetesRuntimeConfig' errors: type: array description: The list of errors that the app has encountered. items: $ref: "#/components/schemas/KubernetesError" status: $ref: "#/components/schemas/AppStatus" proxyUrls: description: map of service name to proxyUrl type: object additionalProperties: type: string diskName: type: string description: the name of the disk associated with this app appName: type: string description: the name of the app appType: $ref: '#/components/schemas/AppType' auditInfo: $ref: "#/components/schemas/AuditInfo" accessScope: $ref: '#/components/schemas/AppAccessScope' labels: type: object description: The labels of each app in the response whose key is in includeLabels in the request. Of type Map[String,String] autodeleteEnabled: type: boolean description: Whether to turn on autodelete autodeleteThreshold: type: integer description: The number of minutes of idle time to elapse before the app is deleted. When autodeleteEnabled is true, a positive integer is required ListUpdateableAppResponse: description: out-of-date app properties type: object properties: workspaceId: type: string description: workspaceId cloudContext: $ref: '#/components/schemas/CloudContext' status: $ref: "#/components/schemas/AppStatus" appId: type: number description: the id of the app appName: type: string description: the name of the app appType: $ref: '#/components/schemas/AppType' auditInfo: $ref: "#/components/schemas/AuditInfo" chart: type: string description: the currently installed chart version accessScope: $ref: '#/components/schemas/AppAccessScope' labels: type: object description: The labels of each app in the response whose key is in includeLabels in the request. Of type Map[String,String] CloudContext: description: Cloud platform which holds context for a workspace. type: object required: - cloudProvider - cloudResource properties: cloudProvider: $ref: '#/components/schemas/CloudProvider' cloudResource: type: string description: Cloud resource name. Google project if cloud provider is GCP OR Azure's tenantId/subscriptionId/managedResourceGroupId if in Azure KubernetesRuntimeConfig: description: configuration for a kubernetes app runtime type: object required: - numNodes - machineType - autoscalingEnabled properties: numNodes: type: integer description: number of nodes for the kubernetes app machineType: type: string description: the machine type for the nodes the kubernetes app will run on example: n1-standard-1 autoscalingEnabled: type: boolean description: whether or not the nodes autoscale up and down for this app. This is always `true` for ALLOWED apps. PersistentDiskRequest: description: configuration to create a disk type: object required: - name properties: name: type: string description: The name of the disk. This can reference an existing disk. size: type: integer description: the size of the disk, if this is a creation request. Has an intelligent default otherwise diskType: $ref: "#/components/schemas/DiskType" labels: type: object description: The labels to be placed on the cluster. Of type Map[String,String] KubernetesError: description: a kubernetes app error type: object properties: errorMessage: type: string description: a helpful error message timestamp: type: string description: timestamp for error in ISO 8601 format action: type: string description: the api-level action associated with the error, e.g. createApp source: type: string description: the internal source associated with the error googleErrorCode: type: integer description: if the error is associated with an external API call, the error code will be propagated here GpuConfig: description: A config that describes the gpus associated with a runtime type: object required: - gpuType - numOfGpus properties: gpuType: type: string description: The google identifier for the gpu specs associated with this runtime, ex `nvidia-tesla-t4`. See https://cloud.google.com/compute/docs/gpus numOfGpus: type: integer description: The number of gpus associated with this runtime