Skip to main content
API docs by Redocly

ai/h2o/engine/sandbox/v1/filesystem.proto (version not set)

Download OpenAPI specification:Download

FilesystemService

Lists files and directories in a given directory. Symbolic links in the directory are returned with type FILE_TYPE_SYMLINK and are not followed.

Authorization: Only the creator of the parent SandboxEngine is allowed to call this method.

path Parameters
name
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+

Required. The name of the sandbox engine. Format: workspaces/{workspace}/sandboxEngines/{sandbox_engine}

query Parameters
path
required
string

Required. The absolute path to the directory to list. Must start with a forward slash (e.g., "/workspace"). Lists only direct children of the directory (non-recursive).

Responses

Response samples

Content type
application/json
{
  • "files": [
    ]
}

(-- api-linter: core::0136::http-method=disabled aip.dev/not-precedent: MakeDirectory is a custom method on a singleton resource, not a standard Create method. It uses POST for consistency with other custom methods on the Filesystem singleton. --) (-- api-linter: core::0133::synonyms=disabled aip.dev/not-precedent: MakeDirectory is a custom method on a singleton resource. The "make" verb follows Unix convention (mkdir) and clearly conveys imperative action. --) Creates a directory (similar to Unix mkdir). If the path already exists (including if it's a symbolic link to a directory), returns an error.

Authorization: Only the creator of the parent SandboxEngine is allowed to call this method.

path Parameters
name
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+

Required. The name of the sandbox engine. Format: workspaces/{workspace}/sandboxEngines/{sandbox_engine}

Request Body schema: application/json
path
required
string

Required. The absolute path where the directory should be created. Must start with a forward slash (e.g., "/workspace/data"). The directory will be created with 0755 permissions (rwxr-xr-x).

createParentDirectories
boolean

Optional. If true, creates parent directories if they don't exist. If false or unspecified, the operation will fail if parent directories don't exist.

Responses

Request samples

Content type
application/json
{
  • "path": "string",
  • "createParentDirectories": true
}

Response samples

Content type
application/json
{
  • "fileInfo": {
    }
}

(-- api-linter: core::0136::verb-noun=disabled aip.dev/not-precedent: Move is a custom method on a singleton resource. The "move" verb follows Unix convention (mv) and clearly conveys imperative action for filesystem operations. --) Moves or renames a file, directory, or symbolic link. By default, fails if the destination already exists. If the source is a symbolic link, the link itself is moved, not its target. If the destination exists and is a symbolic link, it will be replaced.

Authorization: Only the creator of the parent SandboxEngine is allowed to call this method.

path Parameters
name
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+

Required. The name of the sandbox engine. Format: workspaces/{workspace}/sandboxEngines/{sandbox_engine}

Request Body schema: application/json
sourcePath
required
string

Required. The absolute path of the source. Must start with a forward slash (e.g., "/workspace/old.js"). If the source is a symbolic link, the link itself is moved, not its target.

destinationPath
required
string

Required. The absolute path of the destination. Must start with a forward slash (e.g., "/workspace/new.js"). If the destination is a symbolic link, it will be replaced.

overwrite
boolean or null

Optional. If true, overwrites the destination if it already exists. If explicitly set to false or unspecified, the operation will fail if the destination exists.

createParentDirectories
boolean

Optional. If true, creates parent directories of the destination path if they don't exist. If false or unspecified, the operation will fail if parent directories don't exist.

Responses

Request samples

Content type
application/json
{
  • "sourcePath": "string",
  • "destinationPath": "string",
  • "overwrite": true,
  • "createParentDirectories": true
}

Response samples

Content type
application/json
{
  • "fileInfo": {
    }
}

(-- api-linter: core::0131::synonyms=disabled aip.dev/not-precedent: ReadFile is a custom method on a singleton resource, not a standard Get method. The "read" verb is appropriate for file I/O operations. --) Reads the contents of a file, following symbolic links.

Authorization: Only the creator of the parent SandboxEngine is allowed to call this method.

path Parameters
name
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+

Required. The name of the sandbox engine. Format: workspaces/{workspace}/sandboxEngines/{sandbox_engine}

query Parameters
path
required
string

Required. The absolute path to the file to read. If the path is a symbolic link, it will be resolved to the target file. Must start with a forward slash (e.g., "/workspace/app.js").

Responses

Response samples

Content type
application/json
{
  • "content": "string",
  • "fileInfo": {
    }
}

(-- api-linter: core::0136::http-method=disabled aip.dev/not-precedent: Remove is a custom method on a singleton resource, not a standard Delete method. It uses POST for consistency with other custom methods on the Filesystem singleton. --) (-- api-linter: core::0136::verb-noun=disabled aip.dev/not-precedent: Remove is a custom method on a singleton resource. The "remove" verb follows Unix convention (rm) and clearly conveys imperative action for filesystem operations. --) (-- api-linter: core::0133::synonyms=disabled aip.dev/not-precedent: Remove is a custom method on a singleton resource. The "remove" verb follows Unix convention (rm) and clearly conveys imperative action. --) Removes (deletes) a file or directory. Automatically detects whether the path is a file or directory. If the path is a symbolic link, the link itself is removed, not its target.

Authorization: Only the creator of the parent SandboxEngine is allowed to call this method.

path Parameters
name
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+

Required. The name of the sandbox engine. Format: workspaces/{workspace}/sandboxEngines/{sandbox_engine}

Request Body schema: application/json
path
required
string

Required. The absolute path to the file or directory to delete. Must start with a forward slash (e.g., "/workspace/app.js" or "/workspace/data"). If the path is a symbolic link, the link itself is removed, not its target.

recursive
boolean (Optional. If true, removes directories and their contents recursively (similar to `rm -rf`). If false or unspecified: - Files are removed normally - Empty directories are removed normally - Non-empty directories will cause the operation to fail)

Responses

Request samples

Content type
application/json
{
  • "path": "string",
  • "recursive": true
}

Response samples

Content type
application/json
{ }

(-- api-linter: core::0131::synonyms=disabled aip.dev/not-precedent: StatFile is a custom method on a singleton resource, not a standard Get method. The "stat" verb follows Unix convention and is appropriate for metadata retrieval. --) Gets metadata about a file or directory (similar to Unix stat). If the path is a symbolic link, returns metadata about the target file (symlink is followed).

Authorization: Only the creator of the parent SandboxEngine is allowed to call this method.

path Parameters
name
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+

Required. The name of the sandbox engine. Format: workspaces/{workspace}/sandboxEngines/{sandbox_engine}

query Parameters
path
required
string

Required. The absolute path to the file or directory. Must start with a forward slash (e.g., "/workspace/app.js"). If the path is a symbolic link, metadata about the target file is returned (symlink is followed).

Responses

Response samples

Content type
application/json
{
  • "fileInfo": {
    }
}

Writes content to a file, creating it if it doesn't exist. If the path is a symbolic link, the target file is written to (symlink is followed).

Authorization: Only the creator of the parent SandboxEngine is allowed to call this method.

path Parameters
name
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+

Required. The name of the sandbox engine. Format: workspaces/{workspace}/sandboxEngines/{sandbox_engine}

Request Body schema: application/json
path
required
string

Required. The absolute path where the file should be written. Must start with a forward slash (e.g., "/workspace/app.js"). If the file exists, it will be overwritten unless overwrite=false. If the file doesn't exist, it will be created with 0644 permissions (rw-r--r--). Parent directories must exist unless create_parent_directories is true.

content
required
string <byte>

Required. The raw content to write to the file as bytes. For text files, provide UTF-8 encoded text. For binary files, provide raw binary data.

createParentDirectories
boolean

Optional. If true, creates parent directories if they don't exist. If false or unspecified, the write will fail if parent directories don't exist.

overwrite
boolean or null

Optional. Controls overwrite behavior for existing files. If true or unspecified, overwrites the file if it already exists. If explicitly set to false, the operation will fail if the file already exists. This allows atomic create-new-only semantics (similar to O_CREAT|O_EXCL).

Responses

Request samples

Content type
application/json
{
  • "path": "string",
  • "content": "string",
  • "createParentDirectories": true,
  • "overwrite": true
}

Response samples

Content type
application/json
{
  • "fileInfo": {
    }
}

H2ODriveService

Downloads a file from H2O Drive to the sandbox filesystem.

Retrieves a file from the remote storage and writes it to the specified path in the sandbox filesystem. The caller must have read permissions for the specified workspace.

Authorization: Only the creator of the parent SandboxEngine is allowed to call this method.

path Parameters
name
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+

Required. The name of the sandbox engine. Format: workspaces/{workspace}/sandboxEngines/{sandbox_engine}

Request Body schema: application/json
workspace
string

Optional. The workspace resource name. Format: workspaces/{workspace} If not specified, the default workspace in which the sandbox engine is running will be used.

remotePath
required
string (Required. The object path within the H2O Drive storage. The path should be relative to the workspace root. Example: "data/input.csv", "models/model.pkl")
localPath
required
string

Required. The absolute path in the sandbox filesystem where the file should be written. Must start with a forward slash (e.g., "/home/sandbox/data/input.csv"). If the file doesn't exist, it will be created with 0644 permissions (rw-r--r--).

createParentDirectories
boolean

Optional. If true, creates parent directories if they don't exist. If false or unspecified, the operation will fail if parent directories don't exist.

overwrite
boolean or null

Optional. Controls overwrite behavior for existing files. If true or unspecified, overwrites the file if it already exists. If explicitly set to false, the operation will fail if the file exists.

Responses

Request samples

Content type
application/json
{
  • "workspace": "string",
  • "remotePath": "string",
  • "localPath": "string",
  • "createParentDirectories": true,
  • "overwrite": true
}

Response samples

Content type
application/json
{
  • "fileInfo": {
    }
}

Uploads a file from the sandbox filesystem to H2O Drive.

Reads a file from the sandbox filesystem and stores it in the remote storage at the specified path. If the file already exists in H2O Drive, it will be overwritten. The caller must have write permissions for the specified workspace.

Authorization: Only the creator of the parent SandboxEngine is allowed to call this method.

path Parameters
name
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+

Required. The name of the sandbox engine. Format: workspaces/{workspace}/sandboxEngines/{sandbox_engine}

Request Body schema: application/json
workspace
string

Optional. The workspace resource name. Format: workspaces/{workspace} If not specified, the default workspace in which the sandbox engine is running will be used.

localPath
required
string

Required. The absolute path in the sandbox filesystem to read the file from. Must start with a forward slash (e.g., "/home/sandbox/output/results.json").

remotePath
required
string (Required. The object path where the file should be stored in H2O Drive. The path should be relative to the workspace root. If an object already exists at this path, it will be overwritten. Example: "output/results.json", "logs/execution.log")

Responses

Request samples

Content type
application/json
{
  • "workspace": "string",
  • "localPath": "string",
  • "remotePath": "string"
}

Response samples

Content type
application/json
{
  • "bytesUploaded": "string"
}

H2OSecureStoreService

Reveals a secret value from H2O Secure Store and writes it to a file.

Retrieves a secret version from the secure store and writes its value to the specified path in the sandbox filesystem. The caller must be authorized to reveal the specified secret version.

Files are created with secure 0600 permissions (owner read/write only) to protect sensitive data.

The secret version name can use the "latest" alias to retrieve the most recently created version: "workspaces/{workspace}/secrets/{secret}/versions/latest" (-- api-linter: core::0136::prepositions=disabled aip.dev/not-precedent: The preposition "to" clearly indicates the destination format (file) and is essential for clarity. Alternative names like "RevealSecretAsFile" would be ambiguous. --)

path Parameters
name
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+

Required. The name of the sandbox engine. Format: workspaces/{workspace}/sandboxEngines/{sandbox_engine}

Request Body schema: application/json
secretVersion
required
string (Required. The resource name of the SecretVersion to reveal. Format: "workspaces/{workspace}/secrets/{secret}/versions/{version}")

The version segment can be a specific version ID or "latest" to retrieve the most recently created SecretVersion.

Example: "workspaces/my-workspace/secrets/api-key/versions/latest"

path
required
string

Required. The absolute path in the sandbox filesystem where the secret value should be written. Must start with a forward slash (e.g., "/home/sandbox/.credentials/token"). If the file exists, it will be overwritten. Parent directories will be created automatically if they don't exist for security convenience (unlike other file operations which require explicit opt-in via create_parent_directories parameter). The file will be created with 0600 permissions (owner read/write only).

Responses

Request samples

Content type
application/json
{
  • "secretVersion": "string",
  • "path": "string"
}

Response samples

Content type
application/json
{
  • "secretVersion": "string",
  • "fileInfo": {
    }
}

PortService

Returns a specific Port.

Authorization: Only the creator of the parent SandboxEngine is allowed to call this method.

path Parameters
name
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+/ports/[...

Required. Port resource name.

Responses

Response samples

Content type
application/json
{
  • "port": {
    }
}

Deletes a Port.

Authorization: Only the creator of the parent SandboxEngine is allowed to call this method.

path Parameters
name
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+/ports/[...

Required. Port resource name.

Responses

Response samples

Content type
application/json
{ }

Returns a collection of Ports for a SandboxEngine.

Authorization: Only the creator of the parent SandboxEngine is allowed to call this method.

path Parameters
parent
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+

Required. SandboxEngine resource name.

query Parameters
pageSize
integer <int32>

Maximum number of Ports to return in a response. If unspecified (or set to 0), at most 50 Ports will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

pageToken
string

Leave unset to receive the initial page. To list any subsequent pages use the value of 'next_page_token' returned from the ListPortsResponse.

Responses

Response samples

Content type
application/json
{
  • "ports": [
    ],
  • "nextPageToken": "string"
}

Creates a new Port for a SandboxEngine.

Authorization: Only the creator of the parent SandboxEngine is allowed to call this method.

path Parameters
parent
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+

Required. SandboxEngine resource name.

query Parameters
portId
required
string

Required. The port number to expose (1024-65535). This will become the port ID in the resource name.

Request Body schema: application/json

Required. The Port resource to create.

name
string

Identifier. Resource name of the Port.

displayName
string

Optional. Human-readable display name for this port.

public
boolean

Optional. Whether this port should be publicly accessible. If false, the port is only accessible within the cluster.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "displayName": "string",
  • "public": true
}

Response samples

Content type
application/json
{
  • "port": {
    }
}

Updates a Port.

Authorization: Only the creator of the parent SandboxEngine is allowed to call this method.

path Parameters
port.name
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+/ports/[...

Identifier. Resource name of the Port.

query Parameters
updateMask
required
string

Required. Field mask specifying which fields to update. Updatable fields: display_name, public

Request Body schema: application/json

Required. The Port resource to update.

displayName
string

Optional. Human-readable display name for this port.

public
boolean

Optional. Whether this port should be publicly accessible. If false, the port is only accessible within the cluster.

Responses

Request samples

Content type
application/json
{
  • "displayName": "string",
  • "public": true
}

Response samples

Content type
application/json
{
  • "port": {
    }
}

ProcessService

Gets the details of a specific process.

Authorization: Only the creator of the parent SandboxEngine is allowed to call this method.

path Parameters
name_1
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+/process...

Required. The name of the process to retrieve. Format: workspaces/{workspace}/sandboxEngines/{sandbox_engine}/processes/{process}

Responses

Response samples

Content type
application/json
{
  • "process": {
    }
}

(-- api-linter: core::0131::synonyms=disabled aip.dev/not-precedent: ReadOutput reads stdout/stderr streams, not a resource. This is semantically different from Get operations. --) Reads the entire collected output of a process. This is intended for completed processes with a finite amount of output.

Authorization: Only the creator of the parent SandboxEngine is allowed to call this method.

path Parameters
name
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+/process...

Required. The name of the process whose output to retrieve. Format: workspaces/{workspace}/sandboxEngines/{sandbox_engine}/processes/{process}

query Parameters
outputStream
string
Default: "OUTPUT_STREAM_UNSPECIFIED"
Enum: "OUTPUT_STREAM_UNSPECIFIED" "OUTPUT_STREAM_STDOUT" "OUTPUT_STREAM_STDERR" "OUTPUT_STREAM_COMBINED"

Required. The output stream to read. Must be one of: OUTPUT_STREAM_STDOUT, OUTPUT_STREAM_STDERR, or OUTPUT_STREAM_COMBINED.

  • OUTPUT_STREAM_UNSPECIFIED: Not specified. The server may default to STDOUT.
  • OUTPUT_STREAM_STDOUT: The standard output stream.
  • OUTPUT_STREAM_STDERR: The standard error stream.
  • OUTPUT_STREAM_COMBINED: Both stdout and stderr combined (interleaved in order received).

Responses

Response samples

Content type
application/json
{
  • "data": "string"
}

Sends a signal to a running process.

Authorization: Only the creator of the parent SandboxEngine is allowed to call this method.

path Parameters
name
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+/process...

Required. The name of the process to signal. Format: workspaces/{workspace}/sandboxEngines/{sandbox_engine}/processes/{process}

Request Body schema: application/json
signal
required
integer <int32>

Required. The signal number to send to the process (e.g., 9 for SIGKILL, 15 for SIGTERM).

Responses

Request samples

Content type
application/json
{
  • "signal": 0
}

Response samples

Content type
application/json
{
  • "process": {
    }
}

Starts execution of a previously created process.

Authorization: Only the creator of the parent SandboxEngine is allowed to call this method.

path Parameters
name
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+/process...

Required. The name of the process to start. Format: workspaces/{workspace}/sandboxEngines/{sandbox_engine}/processes/{process}

Request Body schema: application/json
object

Request to start a process.

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "process": {
    }
}

Streams the output of a process in real-time as it happens. This is the gRPC equivalent of a Server-Sent Events (SSE) endpoint.

Authorization: Only the creator of the parent SandboxEngine is allowed to call this method.

path Parameters
name
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+/process...

Required. The name of the process whose output to stream. Format: workspaces/{workspace}/sandboxEngines/{sandbox_engine}/processes/{process}

query Parameters
skipReplay
boolean

Optional. If true, the server will not replay buffered output that was captured before the subscription began. When false or unset, the server replays the captured output prior to streaming live data (default behavior).

Responses

Response samples

Content type
application/json
{
  • "result": {
    },
  • "error": {
    }
}

Waits for a process to complete execution. This is a blocking call that returns when the process reaches a terminal state (STATE_SUCCEEDED or STATE_FAILED).

Authorization: Only the creator of the parent SandboxEngine is allowed to call this method.

path Parameters
name
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+/process...

Required. The name of the process to wait for. Format: workspaces/{workspace}/sandboxEngines/{sandbox_engine}/processes/{process}

Request Body schema: application/json
object

Request to wait for a process to complete.

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "process": {
    }
}

Lists all processes.

Authorization: Only the creator of the parent SandboxEngine is allowed to call this method.

path Parameters
parent
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+

Required. The parent resource to list processes from. Format: workspaces/{workspace}/sandboxEngines/{sandbox_engine}

query Parameters
pageSize
integer <int32>

The maximum number of processes to return.

pageToken
string

A page token from a previous ListProcesses call.

filter
string

Optional. A filter expression to filter processes by state.

Syntax: "state = STATE_VALUE"

Where STATE_VALUE must be one of:

  • STATE_PENDING
  • STATE_RUNNING
  • STATE_SUCCEEDED
  • STATE_FAILED

Examples:

  • "state = STATE_RUNNING" - returns only running processes
  • "state = STATE_SUCCEEDED" - returns only succeeded processes

If empty or unspecified, returns all processes.

Responses

Response samples

Content type
application/json
{
  • "processes": [
    ],
  • "nextPageToken": "string"
}

(-- api-linter: core::0133::method-signature=disabled aip.dev/not-precedent: Method signature includes auto_run field which is a non-standard field for immediate execution workflow. --) Creates a new process.

Authorization: Only the creator of the parent SandboxEngine is allowed to call this method.

path Parameters
parent
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+

Required. The parent resource where the process will be created. Format: workspaces/{workspace}/sandboxEngines/{sandbox_engine}

query Parameters
processId
string

Optional. The ID to use for the process.

It must:

  • contain 1-63 characters
  • contain only lowercase alphanumeric characters or hyphen ('-')
  • start with an alphanumeric character
  • end with an alphanumeric character

If not provided, a random UUID will be generated.

autoRun
boolean

(-- api-linter: core::0133::request-unknown-fields=disabled aip.dev/not-precedent: auto_run enables immediate execution workflow while maintaining support for deferred execution via StartProcess. --) Optional. If true, the process will start execution immediately after creation (transitioning to STATE_RUNNING). If false or unset, the process will be created in STATE_PENDING and require an explicit StartProcess call to begin execution. This allows clients to establish stream connections before execution starts.

Request Body schema: application/json

Required. The process resource to create.

command
required
string

Required. The command that will be executed.

args
Array of strings

Optional. The arguments for the command.

workingDirectory
string

Optional. The working directory for the process.

object

Optional. A map of environment variables to set for the process. If a variable name exists in both environment_variables and secret_environment_variables, the secret value takes precedence.

object

Optional. A map of environment variables populated from H2O Secure Store secrets. The key is the environment variable name, and the value contains the secret configuration including the secret version resource name.

These secret-based environment variables will override any variables with the same name specified in the environment_variables field.

Example: { "API_TOKEN": { "secret_version": "workspaces/my-workspace/secrets/api-key/versions/latest" } }

state
string (v1ProcessState)
Default: "STATE_UNSPECIFIED"
Enum: "STATE_UNSPECIFIED" "STATE_PENDING" "STATE_RUNNING" "STATE_SUCCEEDED" "STATE_FAILED"

The state of the process.

  • STATE_UNSPECIFIED: The state is not specified.
  • STATE_PENDING: The process has been created but has not yet started execution. This is the initial state after a successful CreateProcess call. Use StartProcess method to begin execution.
  • STATE_RUNNING: The process is currently executing.
  • STATE_SUCCEEDED: The process completed successfully, typically with an exit code of 0.
  • STATE_FAILED: The process terminated with an error, typically with a non-zero exit code or due to an external signal.

Responses

Request samples

Content type
application/json
{
  • "command": "string",
  • "args": [
    ],
  • "workingDirectory": "string",
  • "environmentVariables": {
    },
  • "secretEnvironmentVariables": {
    },
  • "state": "STATE_UNSPECIFIED"
}

Response samples

Content type
application/json
{
  • "process": {
    }
}

DAIEngineProfileService

Updates a DAIEngineProfile.

path Parameters
daiEngineProfile.name
required
stringworkspaces/[^/]+/daiEngineProfiles/[^/]+

Output only. Resource name. Format: workspaces//daiEngineProfiles/

query Parameters
updateMask
required
string

Required. The list of paths referencing which fields to update. Update mask must be non-empty.

Allowed field paths are:

  • display_name
  • priority
  • enabled
  • assigned_oidc_roles_enabled
  • assigned_oidc_roles
  • max_running_engines
  • cpu_constraint
  • gpu_constraint
  • memory_bytes_constraint
  • storage_bytes_constraint
  • max_idle_duration_constraint
  • max_running_duration_constraint
  • max_non_interaction_duration
  • max_unused_duration
  • configuration_override
  • base_configuration
  • config_editability
  • yaml_pod_template_spec
  • yaml_gpu_tolerations
  • triton_enabled
  • gpu_resource_name
  • data_directory_storage_class

Paths are case sensitive (must match exactly).

To update all allowed fields, specify exactly one path with value "*".

Request Body schema: application/json

Required. DAIEngineProfile resource.

Authorization may require the following permission on the profile's parent workspace:

  • actions/enginemanager/daiEngineProfiles/UPDATE
displayName
string

Optional. Human-readable name.

priority
integer <int32>

Optional. Priority of the DAIEngineProfile. Lower value means higher priority. Priority is NOT a unique value (any two DAIEngineProfiles can have the same priority value).

enabled
boolean

Optional. When set to true, the DAIEngineProfile is enabled and can be used in DAIEngine. When set to false, the DAIEngineProfile is disabled and cannot be used in any DAIEngine.

assignedOidcRolesEnabled
boolean

Optional. When set to true, the assigned_oidc_roles field is verified when a user uses this profile.

assignedOidcRoles
Array of strings

Optional. List of OIDC roles assigned to this DAIEngineProfile.

When profile has assigned some OIDC roles and verification of this list is enabled (assigned_oidc_roles_enabled=true), then this profile can be used only by users who have assigned at least one role from this list.

Example 1: assigned_oidc_roles = ["role1", "role2"]. This profile can be used only by users who have assigned either role1 or role2.

Example 2 (special case): assigned_oidc_roles = []. Empty list means that the profile has not assigned any OIDC role, therefore this profile cannot be used by any user.

maxRunningEngines
integer or null <int32>

Optional. Maximum number of DAIEngines per user that can be running when using this DAIEngineProfile.

object (v1ProfileConstraintNumeric)

Message representing a constraint on a user-specified numeric value.

object (v1ProfileConstraintNumeric)

Message representing a constraint on a user-specified numeric value.

object (v1ProfileConstraintNumeric)

Message representing a constraint on a user-specified numeric value.

object (v1ProfileConstraintNumeric)

Message representing a constraint on a user-specified numeric value.

object (v1ProfileConstraintDuration)

Message representing a constraint on a user-specified duration value.

object (v1ProfileConstraintDuration)

Message representing a constraint on a user-specified duration value.

maxNonInteractionDuration
string or null

Optional. Max non-interation duration applied on all DAIEngines that use this profile.

maxUnusedDuration
string or null

Optional. Max unused duration applied on all DAIEngines that use this profile.

object

Optional. configuration_override is applied on top of all other configurations when creating the final configuration that is passed to the DAI server.

The whole config setup priority is: final_configuration = configuration_override > core_configuration (hardcoded on AIEM server) > DAIEngine.config > base_configuration where higher priority is always applied on top of the lower priority.

Example:

  • AIEM server has hardcoded core_configuration={"key1": "hardcoded-val1", "key2": "hardcoded-val2"}
  • Admin sets DAIEngineProfile with base_configuration={"key3": "base-val3", "key4": "base-val4"}
  • Admin sets DAIEngineProfile with profile config_editability=CONFIG_EDITABILITY_FULL
  • Admin sets DAIEngineProfile with configuration_override={"key1": "override-val1", "key5": "override-val5"}
  • User creates DAIEngine with this profile. User sets DAIEngine.config={"key3": "user-val3", "key6": "user-val6"}

The final configuration is composed as:

  1. Start with base_configuration: {"key3": "base-val3", "key4": "base-val4"}
  2. Apply DAIEngine.config on top: {"key3": "user-val3", "key4": "base-val4", "key6": "user-val6"}
  3. Apply hardcoded core_configuration on top: {"key1": "hardcoded-val1", "key2": "hardcoded-val2", "key3": "user-val3", "key4": "base-val4", "key6": "user-val6"}
  4. Apply configuration_override on top: {"key1": "override-val1", "key2": "hardcoded-val2", "key3":"user-val3", "key4": "base-val4", "key5": "override-val5", "key6": "user-val6"}.
object

Optional. base configuration forms the basis of the final configuration that is passed to the DAI server. See configuration_override for the overall configuration setup logic.

configEditability
string (DAIEngineProfileConfigEditability)
Default: "CONFIG_EDITABILITY_UNSPECIFIED"
Enum: "CONFIG_EDITABILITY_UNSPECIFIED" "CONFIG_EDITABILITY_DISABLED" "CONFIG_EDITABILITY_BASE_CONFIG_ONLY" "CONFIG_EDITABILITY_FULL"

All possible DAIEngine.config editability options.

  • CONFIG_EDITABILITY_UNSPECIFIED: ConfigEditability is unspecified.
  • CONFIG_EDITABILITY_DISABLED: Specifying DAIEngine.config is not allowed.
  • CONFIG_EDITABILITY_BASE_CONFIG_ONLY: Specifying DAIEngine.config is allowed only when it overrides values from base_configuration.
  • CONFIG_EDITABILITY_FULL: Specifying DAIEngine.config is allowed in full.
yamlPodTemplateSpec
string (Optional. YAML representation of custom PodTemplateSpec. Definition of PodTemplateSpec: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#podtemplatespec-v1-core)

When specified, then it is applied for each DAIEngine that uses this profile. PodTemplateSpec describes what will be applied on top of a regular DriverlessAI pod before it is created. This template is merged into DriverlessAI default pod using StrategicMergePatch method (it overrides the default pod). More info about StrategicMergePatch: https://kubernetes.io/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch/

Example YAML value (custom annotation applied for each DAI pod): metadata: annotations: custom-key: custom-value

yamlGpuTolerations
string (Optional. YAML representation of custom GPU Tolerations. Definition of one Toleration: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#toleration-v1-core)

When specified, then it is applied for each DAIEngine that uses this profile. GPUTolerations sets DriverlessAI's pod.spec.tolerations in case DAIEngine has GPU > 0. This will override any tolerations defined in yaml_pod_template_spec.PodSpec.Tolerations field.

Example YAML value (two GPU tolerations applied for each DAI pod):

  • key: "dedicated" operator: "Equal" value: "gpu" effect: "NoSchedule"
  • key: "key2" operator: "Equal" value: "value2" effect: "NoSchedule"
tritonEnabled
boolean

Optional. True when DAI built-in Triton inference server is enabled, false when it is disabled.

gpuResourceName
string

Non-empty default. K8s GPU resource name. For example: nvidia.com/gpu or amd.com/gpu. When unset, server will choose a default value.

dataDirectoryStorageClass
string

Optional. Name of the storage class used by Driverless AI when using this DAIVersion. When unset, the default storage class of the k8s cluster will be used.

Responses

Request samples

Content type
application/json
{
  • "displayName": "string",
  • "priority": 0,
  • "enabled": true,
  • "assignedOidcRolesEnabled": true,
  • "assignedOidcRoles": [
    ],
  • "maxRunningEngines": 0,
  • "cpuConstraint": {
    },
  • "gpuConstraint": {
    },
  • "memoryBytesConstraint": {
    },
  • "storageBytesConstraint": {
    },
  • "maxIdleDurationConstraint": {
    },
  • "maxRunningDurationConstraint": {
    },
  • "maxNonInteractionDuration": "string",
  • "maxUnusedDuration": "string",
  • "configurationOverride": {
    },
  • "baseConfiguration": {
    },
  • "configEditability": "CONFIG_EDITABILITY_UNSPECIFIED",
  • "yamlPodTemplateSpec": "string",
  • "yamlGpuTolerations": "string",
  • "tritonEnabled": true,
  • "gpuResourceName": "string",
  • "dataDirectoryStorageClass": "string"
}

Response samples

Content type
application/json
{
  • "daiEngineProfile": {
    }
}

Deletes a DAIEngineProfile.

path Parameters
name_1
required
stringworkspaces/[^/]+/daiEngineProfiles/[^/]+

DAIEngineProfile resource name. Format: workspaces/{workspace}/daiEngineProfiles/{dai_engine_profile}

Authorization may require the following permission on the profile's parent workspace:

  • actions/enginemanager/daiEngineProfiles/DELETE

Responses

Response samples

Content type
application/json
{ }

Get DAIEngineProfile.

path Parameters
name_2
required
stringworkspaces/[^/]+/daiEngineProfiles/[^/]+

DAIEngineProfile resource name. Format: workspaces/{workspace}/daiEngineProfiles/{dai_engine_profile}

Authorization may require the following permission on the profile's parent workspace:

  • actions/enginemanager/daiEngineProfiles/GET

Responses

Response samples

Content type
application/json
{
  • "daiEngineProfile": {
    }
}

Copies an existing DAIEngineProfile to a new DAIEngineProfile.

path Parameters
name
required
stringworkspaces/[^/]+/daiEngineProfiles/[^/]+

Required. Source DAIEngineProfile resource name. Format: workspaces/{workspace}/daiEngineProfiles/{dai_engine_profile}

Authorization may require the following permission on the source profile's parent workspace:

  • actions/enginemanager/daiEngineProfiles/GET
Request Body schema: application/json
parent
required
string (Required. The parent workspace where the new DAIEngineProfile will be created. Format: workspaces/{workspace})

Authorization may require the following permission on this workspace:

  • actions/enginemanager/daiEngineProfiles/CREATE
daiEngineProfileId
required
string

Required. Specify the target DAIEngineProfile ID, which will become a part of the new DAIEngineProfile resource name.

Must follow the same format as dai_engine_profile_id when creating a new Profile.

Responses

Request samples

Content type
application/json
{
  • "parent": "string",
  • "daiEngineProfileId": "string"
}

Response samples

Content type
application/json
{
  • "daiEngineProfile": {
    }
}

Returns a collection of DAIEngineProfiles.

path Parameters
parent
required
stringworkspaces/[^/]+

Workspace resource name. Format: workspaces/{workspace}

Authorization may require the following permission on the profile's parent workspace:

  • actions/enginemanager/daiEngineProfiles/LIST
query Parameters
pageSize
integer <int32>

Maximum number of DAIEngineProfiles to return in a response. If unspecified (or set to 0), at most 50 DAIEngineProfiles will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

pageToken
string

Leave unset to receive the initial page. To list any subsequent pages use the value of 'next_page_token' returned from the ListDAIEngineProfilesResponse.

Responses

Response samples

Content type
application/json
{
  • "daiEngineProfiles": [
    ],
  • "nextPageToken": "string"
}

Creates a new DAIEngineProfile.

path Parameters
parent
required
stringworkspaces/[^/]+

Workspace resource name. Format: workspaces/{workspace}

Authorization may require the following permission on the profile's parent workspace:

  • actions/enginemanager/daiEngineProfiles/CREATE
query Parameters
daiEngineProfileId
required
string

Specify the DAIEngineProfile ID, which will become a part of the DAIEngineProfile resource name.

It must:

  • contain 1-63 characters
  • contain only lowercase alphanumeric characters or hyphen ('-')
  • start with an alphabetic character
  • end with an alphanumeric character

This matches a regular expression: ^a-z?$

Request Body schema: application/json

The DAIEngineProfile resource to create.

displayName
string

Optional. Human-readable name.

priority
integer <int32>

Optional. Priority of the DAIEngineProfile. Lower value means higher priority. Priority is NOT a unique value (any two DAIEngineProfiles can have the same priority value).

enabled
boolean

Optional. When set to true, the DAIEngineProfile is enabled and can be used in DAIEngine. When set to false, the DAIEngineProfile is disabled and cannot be used in any DAIEngine.

assignedOidcRolesEnabled
boolean

Optional. When set to true, the assigned_oidc_roles field is verified when a user uses this profile.

assignedOidcRoles
Array of strings

Optional. List of OIDC roles assigned to this DAIEngineProfile.

When profile has assigned some OIDC roles and verification of this list is enabled (assigned_oidc_roles_enabled=true), then this profile can be used only by users who have assigned at least one role from this list.

Example 1: assigned_oidc_roles = ["role1", "role2"]. This profile can be used only by users who have assigned either role1 or role2.

Example 2 (special case): assigned_oidc_roles = []. Empty list means that the profile has not assigned any OIDC role, therefore this profile cannot be used by any user.

maxRunningEngines
integer or null <int32>

Optional. Maximum number of DAIEngines per user that can be running when using this DAIEngineProfile.

object (v1ProfileConstraintNumeric)

Message representing a constraint on a user-specified numeric value.

object (v1ProfileConstraintNumeric)

Message representing a constraint on a user-specified numeric value.

object (v1ProfileConstraintNumeric)

Message representing a constraint on a user-specified numeric value.

object (v1ProfileConstraintNumeric)

Message representing a constraint on a user-specified numeric value.

object (v1ProfileConstraintDuration)

Message representing a constraint on a user-specified duration value.

object (v1ProfileConstraintDuration)

Message representing a constraint on a user-specified duration value.

maxNonInteractionDuration
string or null

Optional. Max non-interation duration applied on all DAIEngines that use this profile.

maxUnusedDuration
string or null

Optional. Max unused duration applied on all DAIEngines that use this profile.

object

Optional. configuration_override is applied on top of all other configurations when creating the final configuration that is passed to the DAI server.

The whole config setup priority is: final_configuration = configuration_override > core_configuration (hardcoded on AIEM server) > DAIEngine.config > base_configuration where higher priority is always applied on top of the lower priority.

Example:

  • AIEM server has hardcoded core_configuration={"key1": "hardcoded-val1", "key2": "hardcoded-val2"}
  • Admin sets DAIEngineProfile with base_configuration={"key3": "base-val3", "key4": "base-val4"}
  • Admin sets DAIEngineProfile with profile config_editability=CONFIG_EDITABILITY_FULL
  • Admin sets DAIEngineProfile with configuration_override={"key1": "override-val1", "key5": "override-val5"}
  • User creates DAIEngine with this profile. User sets DAIEngine.config={"key3": "user-val3", "key6": "user-val6"}

The final configuration is composed as:

  1. Start with base_configuration: {"key3": "base-val3", "key4": "base-val4"}
  2. Apply DAIEngine.config on top: {"key3": "user-val3", "key4": "base-val4", "key6": "user-val6"}
  3. Apply hardcoded core_configuration on top: {"key1": "hardcoded-val1", "key2": "hardcoded-val2", "key3": "user-val3", "key4": "base-val4", "key6": "user-val6"}
  4. Apply configuration_override on top: {"key1": "override-val1", "key2": "hardcoded-val2", "key3":"user-val3", "key4": "base-val4", "key5": "override-val5", "key6": "user-val6"}.
object

Optional. base configuration forms the basis of the final configuration that is passed to the DAI server. See configuration_override for the overall configuration setup logic.

configEditability
string (DAIEngineProfileConfigEditability)
Default: "CONFIG_EDITABILITY_UNSPECIFIED"
Enum: "CONFIG_EDITABILITY_UNSPECIFIED" "CONFIG_EDITABILITY_DISABLED" "CONFIG_EDITABILITY_BASE_CONFIG_ONLY" "CONFIG_EDITABILITY_FULL"

All possible DAIEngine.config editability options.

  • CONFIG_EDITABILITY_UNSPECIFIED: ConfigEditability is unspecified.
  • CONFIG_EDITABILITY_DISABLED: Specifying DAIEngine.config is not allowed.
  • CONFIG_EDITABILITY_BASE_CONFIG_ONLY: Specifying DAIEngine.config is allowed only when it overrides values from base_configuration.
  • CONFIG_EDITABILITY_FULL: Specifying DAIEngine.config is allowed in full.
yamlPodTemplateSpec
string (Optional. YAML representation of custom PodTemplateSpec. Definition of PodTemplateSpec: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#podtemplatespec-v1-core)

When specified, then it is applied for each DAIEngine that uses this profile. PodTemplateSpec describes what will be applied on top of a regular DriverlessAI pod before it is created. This template is merged into DriverlessAI default pod using StrategicMergePatch method (it overrides the default pod). More info about StrategicMergePatch: https://kubernetes.io/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch/

Example YAML value (custom annotation applied for each DAI pod): metadata: annotations: custom-key: custom-value

yamlGpuTolerations
string (Optional. YAML representation of custom GPU Tolerations. Definition of one Toleration: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#toleration-v1-core)

When specified, then it is applied for each DAIEngine that uses this profile. GPUTolerations sets DriverlessAI's pod.spec.tolerations in case DAIEngine has GPU > 0. This will override any tolerations defined in yaml_pod_template_spec.PodSpec.Tolerations field.

Example YAML value (two GPU tolerations applied for each DAI pod):

  • key: "dedicated" operator: "Equal" value: "gpu" effect: "NoSchedule"
  • key: "key2" operator: "Equal" value: "value2" effect: "NoSchedule"
tritonEnabled
boolean

Optional. True when DAI built-in Triton inference server is enabled, false when it is disabled.

gpuResourceName
string

Non-empty default. K8s GPU resource name. For example: nvidia.com/gpu or amd.com/gpu. When unset, server will choose a default value.

dataDirectoryStorageClass
string

Optional. Name of the storage class used by Driverless AI when using this DAIVersion. When unset, the default storage class of the k8s cluster will be used.

Responses

Request samples

Content type
application/json
{
  • "displayName": "string",
  • "priority": 0,
  • "enabled": true,
  • "assignedOidcRolesEnabled": true,
  • "assignedOidcRoles": [
    ],
  • "maxRunningEngines": 0,
  • "cpuConstraint": {
    },
  • "gpuConstraint": {
    },
  • "memoryBytesConstraint": {
    },
  • "storageBytesConstraint": {
    },
  • "maxIdleDurationConstraint": {
    },
  • "maxRunningDurationConstraint": {
    },
  • "maxNonInteractionDuration": "string",
  • "maxUnusedDuration": "string",
  • "configurationOverride": {
    },
  • "baseConfiguration": {
    },
  • "configEditability": "CONFIG_EDITABILITY_UNSPECIFIED",
  • "yamlPodTemplateSpec": "string",
  • "yamlGpuTolerations": "string",
  • "tritonEnabled": true,
  • "gpuResourceName": "string",
  • "dataDirectoryStorageClass": "string"
}

Response samples

Content type
application/json
{
  • "daiEngineProfile": {
    }
}

Returns assigned DAIEngineProfiles that match OIDC roles of the caller. (-- api-linter: core::0136::http-uri-suffix=disabled aip.dev/not-precedent: Not a standard List method. --)

path Parameters
parent
required
stringworkspaces/[^/]+

Workspace resource name. Format: workspaces/{workspace}

Authorization may require the following permission on the profile's parent workspace:

  • actions/enginemanager/daiEngineProfiles/LIST_ASSIGNED
query Parameters
pageSize
integer <int32>

Maximum number of DAIEngineProfiles to return in a response. If unspecified (or set to 0), at most 50 DAIEngineProfiles will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

pageToken
string

Leave unset to receive the initial page. To list any subsequent pages use the value of 'next_page_token' returned from the ListDAIEngineProfilesResponse.

Responses

Response samples

Content type
application/json
{
  • "daiEngineProfiles": [
    ],
  • "nextPageToken": "string"
}

DAIEngineService

Updates a DAIEngine.

path Parameters
daiEngine.name
required
stringworkspaces/[^/]+/daiEngines/[^/]+

DAIEngine resource name.

query Parameters
updateMask
required
string

The list of paths referencing which fields to update. Update mask must be non-empty.

Allowed field paths are: {"profile", "cpu", "gpu", "memory_bytes", "config", "annotations", "display_name", "max_idle_duration", "max_running_duration"}. Paths are case sensitive (must match exactly).

To update all allowed fields, specify exactly one path with value "*".

allowMissing
boolean

When set and the DAIEngine is not found, a new one is created. In this situation, update_mask is ignored, i.e. all fields are applied regardless of any provided update mask; but the update mask must be still present.

validateOnly
boolean

When set, request is validated but no changes are made.

Request Body schema: application/json

DAIEngine resource.

profile
required
string

Required. The resource name of the DAIEngineProfile that is assigned to this DAIEngine. Format is workspaces/*/daiEngineProfiles/*.

object (v1DAIEngineProfileInfo)

The original DAIEngineProfile data used by DAIEngine when using the DAIEngineProfile. For more info about each field see the original DAIEngineProfile resource.

state
string (v1DAIEngineState)
Default: "STATE_UNSPECIFIED"
Enum: "STATE_UNSPECIFIED" "STATE_STARTING" "STATE_RUNNING" "STATE_PAUSING" "STATE_PAUSED" "STATE_FAILED" "STATE_DELETING" "STATE_CONNECTING"

All possible DAIEngine states.

  • STATE_UNSPECIFIED: DAIEngine state is unspecified or unknown.
  • STATE_STARTING: DAIEngine is starting.
  • STATE_RUNNING: DAIEngine is running and can be used.
  • STATE_PAUSING: DAIEngine is pausing.
  • STATE_PAUSED: DAIEngine is paused and can be resumed again.
  • STATE_FAILED: DAIEngine has failed and can be resumed again.
  • STATE_DELETING: DAIEngine is being deleted.
  • STATE_CONNECTING: DAIEngine is establishing a connection with the AI Engine Manager.
object

Additional arbitrary metadata associated with the DAIEngine.

Annotations are key/value pairs. The key must:

  • be 63 characters or less
  • begin and end with an alphanumeric character ([a-z0-9A-Z])
  • with dashes (-), underscores (_), dots (.), and alphanumerics between
  • regex used for validation is: ^A-Za-z0-9?$
displayName
string

Human-readable name of the DAIEngine. Must contain at most 63 characters. Does not have to be unique.

cpu
integer or null <int32>

The amount of CPU units requested by this DAIEngine.

gpu
integer or null <int32>

The amount of GPU units requested by this DAIEngine.

memoryBytes
string or null <int64>

The amount of memory in bytes requested by this DAIEngine.

storageBytes
string or null <int64>

The amount of storage requested by this DAIEngine.

object

Additional Driverless AI configuration.

Temporary: Some config keys are reserved and their value cannot be changed. Attempting to set or override a reserved key will have no effect, no error will be raised. Entries with reserved keys will not be available in this field (they are hidden).

maxIdleDuration
string or null (Maximum time the DAIEngine can be idle. When exceeded, the DAIEngine will pause. The idle time is reset when any of the following occurs: - incoming RPC request from client - user login or logout - system event like sync message from running or finished experiment - initialization of dataset upload - custom recipe upload)
maxRunningDuration
string or null

Maximum time the DAIEngine can be running. When exceeded, the DAIEngine will pause.

daiEngineVersion
required
string (Required. DAIEngineVersion assigned to DAIEngine. Format: workspaces/*/daiEngineVersions/*)
object (v1DAIEngineVersionInfo)

The original DAIEngineVersion data used by DAIEngine when using the DAIEngineVersion. For more info about each field see the original DAIEngineVersion resource.

Responses

Request samples

Content type
application/json
{
  • "profile": "string",
  • "profileInfo": {
    },
  • "state": "STATE_UNSPECIFIED",
  • "annotations": {
    },
  • "displayName": "string",
  • "cpu": 0,
  • "gpu": 0,
  • "memoryBytes": "string",
  • "storageBytes": "string",
  • "config": {
    },
  • "maxIdleDuration": "string",
  • "maxRunningDuration": "string",
  • "daiEngineVersion": "string",
  • "daiEngineVersionInfo": {
    }
}

Response samples

Content type
application/json
{
  • "daiEngine": {
    }
}

Download DAIEngine logs.

path Parameters
daiEngine
required
stringworkspaces/[^/]+/daiEngines/[^/]+

DAIEngine resource name. Format: workspaces/{workspace}/daiEngines/{dai_engine}

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/daiEngines/DOWNLOAD_LOGS
Request Body schema: application/json
object

Request message for downloading DAIEngines log.

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "logs": {
    }
}

Migrate DAIEngine creator. Admin only.

path Parameters
daiEngine
required
stringworkspaces/[^/]+/daiEngines/[^/]+

DAIEngine resource name. Format: workspaces/{workspace}/daiEngines/{dai_engine}

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/daiEngines/MIGRATE_CREATOR
Request Body schema: application/json
newCreator
required
string (New creator value. Name of an entity that becomes the new creator of the DAIEngine. Format: users/397b8c16-f4cb-41dd-a5e9-5e838edb81ab)

Responses

Request samples

Content type
application/json
{
  • "newCreator": "string"
}

Response samples

Content type
application/json
{
  • "daiEngine": {
    }
}

Resize DAIEngine storage.

path Parameters
daiEngine
required
stringworkspaces/[^/]+/daiEngines/[^/]+

DAIEngine resource name. Format: workspaces/{workspace}/daiEngines/{dai_engine}

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/daiEngines/RESIZE_STORAGE
Request Body schema: application/json
newStorageBytes
required
string <int64>

New storage size in bytes.

Responses

Request samples

Content type
application/json
{
  • "newStorageBytes": "string"
}

Response samples

Content type
application/json
{
  • "daiEngine": {
    }
}

Upgrade DAIEngine's dai_engine_version.

(-- api-linter: core::0136::http-uri-suffix=disabled aip.dev/not-precedent: Google linter incorrectly requires URI suffix ":upgradeDaiEngineVersion" --)

path Parameters
daiEngine
required
stringworkspaces/[^/]+/daiEngines/[^/]+

DAIEngine resource name. Format: workspaces/{workspace}/daiEngines/{dai_engine}

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/daiEngines/UPGRADE_DAI_ENGINE_VERSION
Request Body schema: application/json
newDaiEngineVersion
required
string (New dai_engine_version. Format: workspaces/*/daiEngineVersions/*)

Responses

Request samples

Content type
application/json
{
  • "newDaiEngineVersion": "string"
}

Response samples

Content type
application/json
{
  • "daiEngine": {
    }
}

Deletes a DAIEngine.

path Parameters
name_2
required
stringworkspaces/[^/]+/daiEngines/[^/]+

DAIEngine resource name. Format: workspaces/{workspace}/daiEngines/{dai_engine}

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/daiEngines/DELETE
query Parameters
allowMissing
boolean

When set and the DAIEngine is not found, the request will succeed but no changes are made.

validateOnly
boolean

When set, request is validated but no changes are made.

Responses

Response samples

Content type
application/json
{
  • "daiEngine": {
    }
}

Returns a specific DAIEngine.

path Parameters
name_3
required
stringworkspaces/[^/]+/daiEngines/[^/]+

DAIEngine resource name. Format: workspaces/{workspace}/daiEngines/{dai_engine}

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/daiEngines/GET

Responses

Response samples

Content type
application/json
{
  • "daiEngine": {
    }
}

Pauses a DAIEngine.

path Parameters
name
required
stringworkspaces/[^/]+/daiEngines/[^/]+

DAIEngine resource name. Format: workspaces/{workspace}/daiEngines/{dai_engine}

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/daiEngines/PAUSE
Request Body schema: application/json
validateOnly
boolean

When set, request is validated but no changes are made.

Responses

Request samples

Content type
application/json
{
  • "validateOnly": true
}

Response samples

Content type
application/json
{
  • "daiEngine": {
    }
}

Resumes an existing DAIEngine.

path Parameters
name
required
stringworkspaces/[^/]+/daiEngines/[^/]+

DAIEngine resource name. Format: workspaces/{workspace}/daiEngines/{dai_engine}

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/daiEngines/RESUME
Request Body schema: application/json
validateOnly
boolean

When set, request is validated but no changes are made.

Responses

Request samples

Content type
application/json
{
  • "validateOnly": true
}

Response samples

Content type
application/json
{
  • "daiEngine": {
    }
}

Returns a collection of DAIEngines within a workspace.

path Parameters
parent
required
stringworkspaces/[^/]+

Workspace resource name. Format: workspaces/{workspace}

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/daiEngines/LIST
query Parameters
pageSize
integer <int32>

Maximum number of DAIEngines to return in a response. If unspecified (or set to 0), at most 50 DAIEngines will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

pageToken
string

Leave unset to receive the initial page. To list any subsequent pages use the value of 'next_page_token' returned from the ListDAIEnginesResponse.

orderBy
string

Used to specify the sorting order.

When unset, DAIEngines are ordered by their time of creation in descending order. This is equivalent to "create_time desc".

When specified, the value must be a comma separated list of supported fields. The supported fields are:

  • name
  • cpu
  • gpu
  • memory_bytes
  • storage_bytes
  • creator
  • create_time
  • update_time
  • delete_time
  • resume_time
  • display_name
  • max_idle_duration
  • max_running_duration
  • uid

The default sorting order is ascending. For example: "name" and "name asc" are equivalent values.

To specify descending order for a field, append a " desc" suffix. For example: "name desc".

Redundant space characters are insignificant. For example these values are all equal:

  • " name, cpu desc"
  • "name, cpu desc"
  • "name , cpu desc "

Undefined (empty) time is interpreted as a zero time (0s since epoch, i.e. 1970-01-01T00:00:00Z).

Undefined (empty) duration is interpreted as a zero duration (0 seconds).

filter
string

Used to filter DAIEngines. When unset, no filtering is applied.

Filtering implements specification https://google.aip.dev/160.

Supported filter fields:

  • name
  • dai_engine_id
  • state
  • cpu
  • gpu
  • memory_bytes
  • storage_bytes
  • creator
  • creator_display_name
  • create_time
  • update_time
  • delete_time
  • resume_time
  • reconciling
  • uid
  • display_name
  • max_idle_duration
  • max_running_duration
  • current_idle_duration
  • current_running_duration

Examples:

  • cpu > 5
  • gpu < 3
  • cpu >= 5 AND gpu <= 3
  • cpu != 5 OR gpu == 3
  • NOT (cpu > 5 OR gpu < 3)
  • -(cpu > 5 OR gpu < 3)
  • NOT (cpu > 5 OR (gpu < 3))
  • (cpu > 5 OR gpu < 3) AND memory_bytes != 1000
  • (cpu > 5 OR gpu < 3) AND (NOT ((((memory_bytes = 1000)))))
  • state = STATE_RUNNING AND create_time > "2012-04-21T11:30:00-04:00"
  • max_running_duration > "1s" AND max_running_duration != "5s"
  • reconciling = true OR reconciling = false (supporting bool literals)
  • dai_engine_id = "*e*" OR display_name = "*e*" (supporting prefix/suffix wildcard * for string fields equality comparison)

Responses

Response samples

Content type
application/json
{
  • "daiEngines": [
    ],
  • "nextPageToken": "string",
  • "totalSize": 0
}

Creates a new DAIEngine within a specified workspace.

path Parameters
parent
required
stringworkspaces/[^/]+

Workspace resource name. Format: workspaces/{workspace}

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/daiEngines/CREATE
query Parameters
daiEngineId
required
string

Specify the DAIEngine ID, which will become a part of the DAIEngine resource name.

It must:

  • contain 1-63 characters
  • contain only lowercase alphanumeric characters or hyphen ('-')
  • start with an alphabetic character
  • end with an alphanumeric character

This matches a regular expression: ^a-z?$

validateOnly
boolean

When set, request is only validated but no changes are made.

Request Body schema: application/json

The DAIEngine resource to create. NON_EMPTY_DEFAULT fields that are not set in this request will be set to a default value. Default value is determined by the workspace in which the engine is created. Each workspace has a defined constraint set, which contains the default value for each field.

profile
required
string

Required. The resource name of the DAIEngineProfile that is assigned to this DAIEngine. Format is workspaces/*/daiEngineProfiles/*.

object (v1DAIEngineProfileInfo)

The original DAIEngineProfile data used by DAIEngine when using the DAIEngineProfile. For more info about each field see the original DAIEngineProfile resource.

state
string (v1DAIEngineState)
Default: "STATE_UNSPECIFIED"
Enum: "STATE_UNSPECIFIED" "STATE_STARTING" "STATE_RUNNING" "STATE_PAUSING" "STATE_PAUSED" "STATE_FAILED" "STATE_DELETING" "STATE_CONNECTING"

All possible DAIEngine states.

  • STATE_UNSPECIFIED: DAIEngine state is unspecified or unknown.
  • STATE_STARTING: DAIEngine is starting.
  • STATE_RUNNING: DAIEngine is running and can be used.
  • STATE_PAUSING: DAIEngine is pausing.
  • STATE_PAUSED: DAIEngine is paused and can be resumed again.
  • STATE_FAILED: DAIEngine has failed and can be resumed again.
  • STATE_DELETING: DAIEngine is being deleted.
  • STATE_CONNECTING: DAIEngine is establishing a connection with the AI Engine Manager.
object

Additional arbitrary metadata associated with the DAIEngine.

Annotations are key/value pairs. The key must:

  • be 63 characters or less
  • begin and end with an alphanumeric character ([a-z0-9A-Z])
  • with dashes (-), underscores (_), dots (.), and alphanumerics between
  • regex used for validation is: ^A-Za-z0-9?$
displayName
string

Human-readable name of the DAIEngine. Must contain at most 63 characters. Does not have to be unique.

cpu
integer or null <int32>

The amount of CPU units requested by this DAIEngine.

gpu
integer or null <int32>

The amount of GPU units requested by this DAIEngine.

memoryBytes
string or null <int64>

The amount of memory in bytes requested by this DAIEngine.

storageBytes
string or null <int64>

The amount of storage requested by this DAIEngine.

object

Additional Driverless AI configuration.

Temporary: Some config keys are reserved and their value cannot be changed. Attempting to set or override a reserved key will have no effect, no error will be raised. Entries with reserved keys will not be available in this field (they are hidden).

maxIdleDuration
string or null (Maximum time the DAIEngine can be idle. When exceeded, the DAIEngine will pause. The idle time is reset when any of the following occurs: - incoming RPC request from client - user login or logout - system event like sync message from running or finished experiment - initialization of dataset upload - custom recipe upload)
maxRunningDuration
string or null

Maximum time the DAIEngine can be running. When exceeded, the DAIEngine will pause.

daiEngineVersion
required
string (Required. DAIEngineVersion assigned to DAIEngine. Format: workspaces/*/daiEngineVersions/*)
object (v1DAIEngineVersionInfo)

The original DAIEngineVersion data used by DAIEngine when using the DAIEngineVersion. For more info about each field see the original DAIEngineVersion resource.

Responses

Request samples

Content type
application/json
{
  • "profile": "string",
  • "profileInfo": {
    },
  • "state": "STATE_UNSPECIFIED",
  • "annotations": {
    },
  • "displayName": "string",
  • "cpu": 0,
  • "gpu": 0,
  • "memoryBytes": "string",
  • "storageBytes": "string",
  • "config": {
    },
  • "maxIdleDuration": "string",
  • "maxRunningDuration": "string",
  • "daiEngineVersion": "string",
  • "daiEngineVersionInfo": {
    }
}

Response samples

Content type
application/json
{
  • "daiEngine": {
    }
}

DAIEngineVersionService

Updates a DAIEngineVersion.

path Parameters
daiEngineVersion.name
required
stringworkspaces/[^/]+/daiEngineVersions/[^/]+

DAIEngineVersion resource name. For example: workspaces/global/daiEngineVersions/1.10.1.2

query Parameters
updateMask
required
string

Required. The list of paths referencing which fields to update. Update mask must be non-empty.

Allowed field paths are:

  • deprecated
  • image
  • image_pull_policy
  • image_pull_secrets

Paths are case sensitive (must match exactly).

To update all allowed fields, specify exactly one path with value "*".

Request Body schema: application/json

Required. DAIEngineVersion resource.

Authorization may require the following permission on the daiEngineVersion's parent workspace:

  • actions/enginemanager/daiEngineVersions/UPDATE
deprecated
boolean

Indicates whether DAIEngineVersion is deprecated.

aliases
Array of strings

Optional. ResourceID aliases for this DAIEngineVersion. Aliases are unique within the workspace (two versions in the same workspace cannot have the same alias).

Any alias must be in format:

  • contain 1-63 characters
  • contain only lowercase alphanumeric characters or hyphen ('-')
  • start with an alphabetic character
  • end with an alphanumeric character This matches a regular expression: ^a-z?$

For example: when DAIEngineVersion with name "workspaces/global/daiEngineVersions/1.11.1" has aliases={"latest", "prerelease"}, then "workspaces/global/daiEngineVersions/latest" will refer to this DAIEngineVersion.

image
required
string

Name of the Docker image used when using this DAIEngineVersion.

imagePullPolicy
string (v1ImagePullPolicy)
Default: "IMAGE_PULL_POLICY_UNSPECIFIED"
Enum: "IMAGE_PULL_POLICY_UNSPECIFIED" "IMAGE_PULL_POLICY_ALWAYS" "IMAGE_PULL_POLICY_NEVER" "IMAGE_PULL_POLICY_IF_NOT_PRESENT"

Policy for downloading an image in K8s.

  • IMAGE_PULL_POLICY_UNSPECIFIED: Unspecified image pull policy.
  • IMAGE_PULL_POLICY_ALWAYS: Every time the container is launched, the container image registry is queried to resolve the name to an image digest.
  • IMAGE_PULL_POLICY_NEVER: Do not try to fetch the image. If the image is already present locally, the container will start. If the image is not present, container startup will fail.
  • IMAGE_PULL_POLICY_IF_NOT_PRESENT: The image is pulled only if it is not already present locally.
imagePullSecrets
Array of strings

List of references to k8s secrets that can be used for pulling an image of this DAIEngineVersion from a private container image registry or repository.

Responses

Request samples

Content type
application/json
{
  • "deprecated": true,
  • "aliases": [
    ],
  • "image": "string",
  • "imagePullPolicy": "IMAGE_PULL_POLICY_UNSPECIFIED",
  • "imagePullSecrets": [
    ]
}

Response samples

Content type
application/json
{
  • "daiEngineVersion": {
    }
}

Deletes a DAIEngineVersion.

path Parameters
name_3
required
stringworkspaces/[^/]+/daiEngineVersions/[^/]+

DAIEngineVersion resource name. Format: workspaces/{workspace}/daiEngineVersions/{dai_engine_version}

Authorization may require the following permission on the daiEngineVersion's parent workspace:

  • actions/enginemanager/daiEngineVersions/DELETE

Responses

Response samples

Content type
application/json
{ }

Get DAIEngineVersion.

path Parameters
name_4
required
stringworkspaces/[^/]+/daiEngineVersions/[^/]+

DAIEngineVersion resource name. Format: workspaces/{workspace}/daiEngineVersions/{dai_engine_version}

Authorization may require the following permission on the daiEngineVersion's parent workspace:

  • actions/enginemanager/daiEngineVersions/GET

Responses

Response samples

Content type
application/json
{
  • "daiEngineVersion": {
    }
}

Assign new set of resourceID aliases to DAIEngineVersion. This will replace existing DAIEngineVersion resourceID aliases with the new aliases. If there are other DAIEngineVersions with the same alias that we try to assign to this DAIEngineVersion, they will be deleted from the other DAIEngineVersions.

Example 1 - two versions in the same workspace:

  • daiw1v1(name="workspaces/w1/daiEngineVersions/v1", aliases=["latest", "bar"])
  • daiw1v2(name="workspaces/w1/daiEngineVersions/v2", aliases=["baz", "foo"])
  • AssignAliases(daiw1v1, aliases=["latest", "baz"]) => daiw1v1.aliases=["latest", "baz"] (changed) => daiw1v2.aliases=["foo"] (changed)

Example 2 - two versions in different workspaces:

  • daiw1v1(name="workspaces/w1/daiEngineVersions/v1", aliases=["latest", "bar"])
  • daiw2v1(name="workspaces/w2/daiEngineVersions/v1", aliases=["latest", "baz"])
  • AssignAliases(daiw1v1, aliases=["latest", "baz"]) => daiw1v1.aliases=["latest", "baz"] (changed) => daiw2v1.aliases=["latest", "baz"] (unchanged)
path Parameters
name
required
stringworkspaces/[^/]+/daiEngineVersions/[^/]+

DAIEngineVersion resource name. Format: workspaces/{workspace}/daiEngineVersions/{dai_engine_version}

Authorization may require the following permission on the daiEngineVersion's parent workspace:

  • actions/enginemanager/daiEngineVersions/ASSIGN_ALIASES
Request Body schema: application/json
aliases
required
Array of strings

New resourceID aliases of the DAIEngineVersion.

Responses

Request samples

Content type
application/json
{
  • "aliases": [
    ]
}

Response samples

Content type
application/json
{
  • "daiEngineVersions": [
    ]
}

Returns a collection of DAIEngineVersions.

path Parameters
parent
required
stringworkspaces/[^/]+

Workspace resource name. Format: workspaces/{workspace}

Authorization may require the following permission on the daiEngineVersion's parent workspace:

  • actions/enginemanager/daiEngineVersions/LIST
query Parameters
pageSize
integer <int32>

Maximum number of DAIEngineVersions to return in a response. If unspecified (or set to 0), at most 50 DAIEngineVersions will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

pageToken
string

Leave unset to receive the initial page. To list any subsequent pages use the value of 'next_page_token' returned from the ListDAIEngineVersionsResponse.

Responses

Response samples

Content type
application/json
{
  • "daiEngineVersions": [
    ],
  • "nextPageToken": "string"
}

Creates a new DAIEngineVersion.

path Parameters
parent
required
stringworkspaces/[^/]+

Workspace resource name. Format: workspaces/{workspace}

Authorization may require the following permission on the daiEngineVersion's parent workspace:

  • actions/enginemanager/daiEngineVersions/CREATE
query Parameters
daiEngineVersionId
required
string

Specify the DAIEngineVersion ID, which will become a part of the DAIEngineVersion resource name.

It must:

  • be in semver format (more segments than three segments allowed)
  • contain max 63 characters

Examples: "1.10.3", "1.10.3-alpha", "1.10.3.2", "1.10.3.2-alpha"

Request Body schema: application/json

The DAIEngineVersion resource to create.

deprecated
boolean

Indicates whether DAIEngineVersion is deprecated.

aliases
Array of strings

Optional. ResourceID aliases for this DAIEngineVersion. Aliases are unique within the workspace (two versions in the same workspace cannot have the same alias).

Any alias must be in format:

  • contain 1-63 characters
  • contain only lowercase alphanumeric characters or hyphen ('-')
  • start with an alphabetic character
  • end with an alphanumeric character This matches a regular expression: ^a-z?$

For example: when DAIEngineVersion with name "workspaces/global/daiEngineVersions/1.11.1" has aliases={"latest", "prerelease"}, then "workspaces/global/daiEngineVersions/latest" will refer to this DAIEngineVersion.

image
required
string

Name of the Docker image used when using this DAIEngineVersion.

imagePullPolicy
string (v1ImagePullPolicy)
Default: "IMAGE_PULL_POLICY_UNSPECIFIED"
Enum: "IMAGE_PULL_POLICY_UNSPECIFIED" "IMAGE_PULL_POLICY_ALWAYS" "IMAGE_PULL_POLICY_NEVER" "IMAGE_PULL_POLICY_IF_NOT_PRESENT"

Policy for downloading an image in K8s.

  • IMAGE_PULL_POLICY_UNSPECIFIED: Unspecified image pull policy.
  • IMAGE_PULL_POLICY_ALWAYS: Every time the container is launched, the container image registry is queried to resolve the name to an image digest.
  • IMAGE_PULL_POLICY_NEVER: Do not try to fetch the image. If the image is already present locally, the container will start. If the image is not present, container startup will fail.
  • IMAGE_PULL_POLICY_IF_NOT_PRESENT: The image is pulled only if it is not already present locally.
imagePullSecrets
Array of strings

List of references to k8s secrets that can be used for pulling an image of this DAIEngineVersion from a private container image registry or repository.

Responses

Request samples

Content type
application/json
{
  • "deprecated": true,
  • "aliases": [
    ],
  • "image": "string",
  • "imagePullPolicy": "IMAGE_PULL_POLICY_UNSPECIFIED",
  • "imagePullSecrets": [
    ]
}

Response samples

Content type
application/json
{
  • "daiEngineVersion": {
    }
}

EngineService

Returns a collection of Engines within a workspace.

path Parameters
parent
required
stringworkspaces/[^/]+

Workspace resource name. Format: workspaces/{workspace}

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/engines/LIST

The parent workspace can be substituted with a workspaces/- to list engines across all workspaces. Authorization for this requires the following permission on //enginemanager resource:

  • actions/enginemanager/engines/LIST_ALL
query Parameters
pageSize
integer <int32>

Maximum number of Engines to return in a response. If unspecified (or set to 0), at most 50 Engines will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

pageToken
string

Leave unset to receive the initial page. To list any subsequent pages use the value of 'next_page_token' returned from the ListEnginesResponse.

orderBy
string

Used to specify the sorting order.

When unset, Engines are ordered by their time of creation in descending order. This is equivalent to "create_time desc".

When specified, the value must be a comma separated list of supported fields. The supported fields are: {name, version, cpu, gpu, memory_bytes, storage_bytes, creator, create_time, update_time, delete_time, resume_time, display_name, uid}

The default sorting order is ascending. For example: "name" and "name asc" are equivalent values.

To specify descending order for a field, append a " desc" suffix. For example: "name desc".

Redundant space characters are insignificant. For example these values are all equal:

  • " name, cpu desc"
  • "name, cpu desc"
  • "name , cpu desc "
filter
string

Used to filter Engines. When unset, no filtering is applied.

Filtering implements specification https://google.aip.dev/160.

Supported filter fields:

  • name
  • engine_id
  • version (supporting version semantic comparison, does not support aliases)
  • deprecated_version
  • state
  • cpu
  • gpu
  • memory_bytes
  • storage_bytes
  • creator
  • creator_display_name
  • create_time
  • update_time
  • delete_time
  • resume_time
  • reconciling
  • uid
  • display_name
  • max_idle_duration
  • max_running_duration
  • current_idle_duration
  • current_running_duration

Examples:

  • cpu > 5
  • gpu < 3
  • cpu >= 5 AND gpu <= 3
  • cpu != 5 OR gpu == 3
  • NOT (cpu > 5 OR gpu < 3)
  • -(cpu > 5 OR gpu < 3)
  • NOT (cpu > 5 OR (gpu < 3))
  • (cpu > 5 OR gpu < 3) AND memory_bytes != 1000
  • (cpu > 5 OR gpu < 3) AND (NOT ((((memory_bytes = 1000)))))
  • state = STATE_RUNNING AND create_time > "2012-04-21T11:30:00-04:00"
  • version >= "1.10.3"
  • deprecated_version = false
  • reconciling = true OR reconciling = false
  • engine_id = "*e*" OR display_name = "*e*" (supporting prefix/suffix wildcard * for string fields equality comparison)

Responses

Response samples

Content type
application/json
{
  • "engines": [
    ],
  • "nextPageToken": "string",
  • "totalSize": 0
}

H2OEngineProfileService

Updates a H2OEngineProfile.

path Parameters
h2oEngineProfile.name
required
stringworkspaces/[^/]+/h2oEngineProfiles/[^/]+

Output only. Resource name. Format: workspaces//h2oEngineProfiles/

query Parameters
updateMask
required
string

Required. The list of paths referencing which fields to update. Update mask must be non-empty.

Allowed field paths are:

  • display_name
  • priority
  • disabled
  • assigned_oidc_roles
  • max_running_engines
  • node_count_constraint
  • cpu_constraint
  • gpu_constraint
  • memory_bytes_constraint
  • max_idle_duration_constraint
  • max_running_duration_constraint
  • yaml_pod_template_spec
  • yaml_gpu_tolerations
  • gpu_resource_name
  • java_classpath
  • java_options
  • h2o_options

Paths are case sensitive (must match exactly).

To update all allowed fields, specify exactly one path with value "*".

Request Body schema: application/json

Required. H2OEngineProfile resource.

Authorization may require the following permission on the profile's parent workspace:

  • actions/enginemanager/h2oEngineProfiles/UPDATE
displayName
string

Optional. Human-readable name.

priority
integer <int32>

Optional. Priority of the H2OEngineProfile. Lower value means higher priority. Priority is NOT a unique value (any two H2OEngineProfiles can have the same priority value).

enabled
boolean

Optional. When set to true, the H2OEngineProfile is enabled and can be used in an H2OEngine. When set to false, the H2OEngineProfile is disabled and cannot be used in any H2OEngine.

assignedOidcRolesEnabled
boolean

Optional. When set to true, the assigned_oidc_roles field is verified when a user uses this profile.

assignedOidcRoles
Array of strings

Optional. List of OIDC roles assigned to this H2OEngineProfile.

When profile has assigned some OIDC roles and verification of this list is enabled (assigned_oidc_roles_enabled=true), then this profile can be used only by users who have assigned at least one role from this list.

Example 1: assigned_oidc_roles = ["role1", "role2"]. This profile can be used only by users who have assigned either role1 or role2.

Example 2 (special case): assigned_oidc_roles = []. Empty list means that the profile has not assigned any OIDC role, therefore this profile cannot be used by any user.

maxRunningEngines
integer or null <int32>

Optional. Maximum number of H2OEngines per user that can be running when using this H2OEngineProfile.

object (v1ProfileConstraintNumeric)

Message representing a constraint on a user-specified numeric value.

object (v1ProfileConstraintNumeric)

Message representing a constraint on a user-specified numeric value.

object (v1ProfileConstraintNumeric)

Message representing a constraint on a user-specified numeric value.

object (v1ProfileConstraintNumeric)

Message representing a constraint on a user-specified numeric value.

object (v1ProfileConstraintDuration)

Message representing a constraint on a user-specified duration value.

object (v1ProfileConstraintDuration)

Message representing a constraint on a user-specified duration value.

yamlPodTemplateSpec
string (Optional. YAML representation of custom PodTemplateSpec. Definition of PodTemplateSpec: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#podtemplatespec-v1-core)

When specified, then it is applied for each H2OEngine that uses this profile. PodTemplateSpec describes what will be applied on top of a regular H2O pod before it is created. This template is merged into H2O default pod using StrategicMergePatch method (it overrides the default pod). More info about StrategicMergePatch: https://kubernetes.io/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch/

Example YAML value (custom annotation applied for each H2O pod): metadata: annotations: custom-key: custom-value

yamlGpuTolerations
string (Optional. YAML representation of custom GPU Tolerations. Definition of one Toleration: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#toleration-v1-core)

When specified, then it is applied for each H2OEngine that uses this profile. GPUTolerations sets H2O's pod.spec.tolerations in case H2OEngine has GPU > 0. This will override any tolerations defined in yaml_pod_template_spec.PodSpec.Tolerations field.

Example YAML value (two GPU tolerations applied for each H2O pod):

  • key: "dedicated" operator: "Equal" value: "gpu" effect: "NoSchedule"
  • key: "key2" operator: "Equal" value: "value2" effect: "NoSchedule"
gpuResourceName
string

Non-empty default. K8s GPU resource name. For example: nvidia.com/gpu or amd.com/gpu. When unset, server will choose a default value.

javaClasspath
string

Optional. Extra Java classpath for H2OEngine.

javaOptions
string (Optional. Extra command line options passed to Java)
h2oOptions
string (Optional. Extra command line options passed to H2O-3)

Responses

Request samples

Content type
application/json
{
  • "displayName": "string",
  • "priority": 0,
  • "enabled": true,
  • "assignedOidcRolesEnabled": true,
  • "assignedOidcRoles": [
    ],
  • "maxRunningEngines": 0,
  • "nodeCountConstraint": {
    },
  • "cpuConstraint": {
    },
  • "gpuConstraint": {
    },
  • "memoryBytesConstraint": {
    },
  • "maxIdleDurationConstraint": {
    },
  • "maxRunningDurationConstraint": {
    },
  • "yamlPodTemplateSpec": "string",
  • "yamlGpuTolerations": "string",
  • "gpuResourceName": "string",
  • "javaClasspath": "string",
  • "javaOptions": "string",
  • "h2oOptions": "string"
}

Response samples

Content type
application/json
{
  • "h2oEngineProfile": {
    }
}

Copies an existing H2OEngineProfile to a new H2OEngineProfile.

path Parameters
name_1
required
stringworkspaces/[^/]+/h2oEngineProfiles/[^/]+

Required. Source H2OEngineProfile resource name. Format: workspaces/{workspace}/h2oEngineProfiles/{h2o_engine_profile}

Authorization may require the following permission on the profile's parent workspace:

  • actions/enginemanager/h2oEngineProfiles/GET
Request Body schema: application/json
parent
required
string (Required. The parent workspace where the new H2OEngineProfile will be created. Format: workspaces/{workspace})

Authorization may require the following permission on this workspace:

  • actions/enginemanager/h2oEngineProfiles/CREATE
h2oEngineProfileId
required
string

Required. Specify the target H2OEngineProfile ID, which will become a part of the new H2OEngineProfile resource name.

Must follow the same format as h2o_engine_profile_id when creating a new Profile.

Responses

Request samples

Content type
application/json
{
  • "parent": "string",
  • "h2oEngineProfileId": "string"
}

Response samples

Content type
application/json
{
  • "h2oEngineProfile": {
    }
}

Deletes a H2OEngineProfile.

path Parameters
name_4
required
stringworkspaces/[^/]+/h2oEngineProfiles/[^/]+

H2OEngine resource name. Format: workspaces/{workspace}/h2oEngineProfiles/{h2o_engine_profile}

Authorization may require the following permission on the profile's parent workspace:

  • actions/enginemanager/h2oEngineProfiles/DELETE

Responses

Response samples

Content type
application/json
{ }

Get H2OEngineProfile.

path Parameters
name_5
required
stringworkspaces/[^/]+/h2oEngineProfiles/[^/]+

H2OEngineProfile resource name. Format: workspaces/{workspace}/h2oEngineProfiles/{h2o_engine_profile}

Authorization may require the following permission on the profile's parent workspace:

  • actions/enginemanager/h2oEngineProfiles/GET

Responses

Response samples

Content type
application/json
{
  • "h2oEngineProfile": {
    }
}

Returns a collection of H2OEngineProfiles.

path Parameters
parent
required
stringworkspaces/[^/]+

Workspace resource name. Format: workspaces/{workspace}

Authorization may require the following permission on the profile's parent workspace:

  • actions/enginemanager/h2oEngineProfiles/LIST
query Parameters
pageSize
integer <int32>

Maximum number of H2OEngineProfiles to return in a response. If unspecified (or set to 0), at most 50 H2OEngineProfiles will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

pageToken
string

Leave unset to receive the initial page. To list any subsequent pages use the value of 'next_page_token' returned from the ListH2OEngineProfilesResponse.

Responses

Response samples

Content type
application/json
{
  • "h2oEngineProfiles": [
    ],
  • "nextPageToken": "string"
}

Creates a new H2OEngineProfile.

path Parameters
parent
required
stringworkspaces/[^/]+

Workspace resource name. Format: workspaces/{workspace}

Authorization may require the following permission on the profile's parent workspace:

  • actions/enginemanager/h2oEngineProfiles/CREATE
query Parameters
h2oEngineProfileId
required
string

Specify the H2OEngineProfile ID, which will become a part of the H2OEngineProfile resource name.

It must:

  • contain 1-63 characters
  • contain only lowercase alphanumeric characters or hyphen ('-')
  • start with an alphabetic character
  • end with an alphanumeric character

This matches a regular expression: ^a-z?$

Request Body schema: application/json

The H2OEngineProfile resource to create.

displayName
string

Optional. Human-readable name.

priority
integer <int32>

Optional. Priority of the H2OEngineProfile. Lower value means higher priority. Priority is NOT a unique value (any two H2OEngineProfiles can have the same priority value).

enabled
boolean

Optional. When set to true, the H2OEngineProfile is enabled and can be used in an H2OEngine. When set to false, the H2OEngineProfile is disabled and cannot be used in any H2OEngine.

assignedOidcRolesEnabled
boolean

Optional. When set to true, the assigned_oidc_roles field is verified when a user uses this profile.

assignedOidcRoles
Array of strings

Optional. List of OIDC roles assigned to this H2OEngineProfile.

When profile has assigned some OIDC roles and verification of this list is enabled (assigned_oidc_roles_enabled=true), then this profile can be used only by users who have assigned at least one role from this list.

Example 1: assigned_oidc_roles = ["role1", "role2"]. This profile can be used only by users who have assigned either role1 or role2.

Example 2 (special case): assigned_oidc_roles = []. Empty list means that the profile has not assigned any OIDC role, therefore this profile cannot be used by any user.

maxRunningEngines
integer or null <int32>

Optional. Maximum number of H2OEngines per user that can be running when using this H2OEngineProfile.

object (v1ProfileConstraintNumeric)

Message representing a constraint on a user-specified numeric value.

object (v1ProfileConstraintNumeric)

Message representing a constraint on a user-specified numeric value.

object (v1ProfileConstraintNumeric)

Message representing a constraint on a user-specified numeric value.

object (v1ProfileConstraintNumeric)

Message representing a constraint on a user-specified numeric value.

object (v1ProfileConstraintDuration)

Message representing a constraint on a user-specified duration value.

object (v1ProfileConstraintDuration)

Message representing a constraint on a user-specified duration value.

yamlPodTemplateSpec
string (Optional. YAML representation of custom PodTemplateSpec. Definition of PodTemplateSpec: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#podtemplatespec-v1-core)

When specified, then it is applied for each H2OEngine that uses this profile. PodTemplateSpec describes what will be applied on top of a regular H2O pod before it is created. This template is merged into H2O default pod using StrategicMergePatch method (it overrides the default pod). More info about StrategicMergePatch: https://kubernetes.io/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch/

Example YAML value (custom annotation applied for each H2O pod): metadata: annotations: custom-key: custom-value

yamlGpuTolerations
string (Optional. YAML representation of custom GPU Tolerations. Definition of one Toleration: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#toleration-v1-core)

When specified, then it is applied for each H2OEngine that uses this profile. GPUTolerations sets H2O's pod.spec.tolerations in case H2OEngine has GPU > 0. This will override any tolerations defined in yaml_pod_template_spec.PodSpec.Tolerations field.

Example YAML value (two GPU tolerations applied for each H2O pod):

  • key: "dedicated" operator: "Equal" value: "gpu" effect: "NoSchedule"
  • key: "key2" operator: "Equal" value: "value2" effect: "NoSchedule"
gpuResourceName
string

Non-empty default. K8s GPU resource name. For example: nvidia.com/gpu or amd.com/gpu. When unset, server will choose a default value.

javaClasspath
string

Optional. Extra Java classpath for H2OEngine.

javaOptions
string (Optional. Extra command line options passed to Java)
h2oOptions
string (Optional. Extra command line options passed to H2O-3)

Responses

Request samples

Content type
application/json
{
  • "displayName": "string",
  • "priority": 0,
  • "enabled": true,
  • "assignedOidcRolesEnabled": true,
  • "assignedOidcRoles": [
    ],
  • "maxRunningEngines": 0,
  • "nodeCountConstraint": {
    },
  • "cpuConstraint": {
    },
  • "gpuConstraint": {
    },
  • "memoryBytesConstraint": {
    },
  • "maxIdleDurationConstraint": {
    },
  • "maxRunningDurationConstraint": {
    },
  • "yamlPodTemplateSpec": "string",
  • "yamlGpuTolerations": "string",
  • "gpuResourceName": "string",
  • "javaClasspath": "string",
  • "javaOptions": "string",
  • "h2oOptions": "string"
}

Response samples

Content type
application/json
{
  • "h2oEngineProfile": {
    }
}

Returns assigned H2OEngineProfiles that match OIDC roles of the caller. (-- api-linter: core::0136::http-uri-suffix=disabled aip.dev/not-precedent: Not a standard List method. --)

path Parameters
parent
required
stringworkspaces/[^/]+

Workspace resource name. Format: workspaces/{workspace}

Authorization may require the following permission on the profile's parent workspace:

  • actions/enginemanager/h2oEngineProfiles/LIST_ASSIGNED
query Parameters
pageSize
integer <int32>

Maximum number of H2OEngineProfiles to return in a response. If unspecified (or set to 0), at most 50 H2OEngineProfiles will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

pageToken
string

Leave unset to receive the initial page. To list any subsequent pages use the value of 'next_page_token' returned from the ListH2OEngineProfilesResponse.

Responses

Response samples

Content type
application/json
{
  • "h2oEngineProfiles": [
    ],
  • "nextPageToken": "string"
}

H2OEngineService

Return recommended engine size based on the dimensions of the compressed dataset and given engine size limits. (-- api-linter: core::0136::http-uri-suffix=disabled aip.dev/not-precedent: The linter is bugged. It requires incorrect suffix ("H2o" instead of "H2O") --)

Request Body schema: application/json
rowsCount
required
string <int64>

Estimated number of rows in the dataset.

columnsCount
required
string <int64>

Estimated number of columns in the dataset.

object (v1H2OEngineSizeLimits)

Limits required for H2OEngine size calculation.

Responses

Request samples

Content type
application/json
{
  • "rowsCount": "string",
  • "columnsCount": "string",
  • "limits": {
    }
}

Response samples

Content type
application/json
{
  • "h2oEngineSize": {
    }
}

Return recommended engine size based on the raw size of the expected raw dataset size and given engine size limits. (-- api-linter: core::0136::http-uri-suffix=disabled aip.dev/not-precedent: The linter is bugged. It requires incorrect suffix ("H2o" instead of "H2O") --)

Request Body schema: application/json
datasetSizeBytes
required
string <int64>

Estimated size of the dataset in bytes.

object (v1H2OEngineSizeLimits)

Limits required for H2OEngine size calculation.

Responses

Request samples

Content type
application/json
{
  • "datasetSizeBytes": "string",
  • "limits": {
    }
}

Response samples

Content type
application/json
{
  • "h2oEngineSize": {
    }
}

Download H2OEngine logs.

path Parameters
h2oEngine
required
stringworkspaces/[^/]+/h2oEngines/[^/]+

H2OEngine resource name. Format: workspaces/{workspace}/h2oEngines/{h2o_engine}

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/h2oEngines/DOWNLOAD_LOGS
Request Body schema: application/json
object

Request message for downloading H2OEngines logs.

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "logs": {
    }
}

Deletes a H2OEngine.

path Parameters
name_5
required
stringworkspaces/[^/]+/h2oEngines/[^/]+

H2OEngine resource name. Format: workspaces/{workspace}/h2oEngines/{h2o_engine}

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/h2oEngines/DELETE
query Parameters
allowMissing
boolean

When set and the H2OEngine is not found, the request will succeed but no changes are made.

validateOnly
boolean

When set, request is validated but no changes are made.

Responses

Response samples

Content type
application/json
{
  • "h2oEngine": {
    }
}

Returns a specific H2OEngine.

path Parameters
name_6
required
stringworkspaces/[^/]+/h2oEngines/[^/]+

H2OEngine resource name. Format: workspaces/{workspace}/h2oEngines/{h2o_engine}

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/h2oEngines/GET

Responses

Response samples

Content type
application/json
{
  • "h2oEngine": {
    }
}

Terminate H2OEngine.

path Parameters
name
required
stringworkspaces/[^/]+/h2oEngines/[^/]+

H2OEngine resource name.

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/h2oEngines/TERMINATE
Request Body schema: application/json
object

Request message for terminating a running H2OEngine.

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "h2oEngine": {
    }
}

Returns a collection of H2OEngines within a workspace.

path Parameters
parent
required
stringworkspaces/[^/]+

Workspace resource name. Format: workspaces/{workspace}

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/h2oEngines/LIST
query Parameters
pageSize
integer <int32>

Maximum number of H2OEngines to return in a response. If unspecified (or set to 0), at most 50 H2OEngines will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

pageToken
string

Leave unset to receive the initial page. To list any subsequent pages use the value of 'next_page_token' returned from the ListH2OEnginesResponse.

orderBy
string

Used to specify the sorting order.

When unset, H2OEngines are ordered by their time of creation in descending order. This is equivalent to "create_time desc".

When specified, the value must be a comma separated list of supported fields. The supported fields are:

  • name
  • cpu
  • gpu
  • memoryBytes
  • creator
  • create_time
  • update_time
  • delete_time
  • display_name
  • max_idle_duration
  • max_running_duration
  • uid
  • node_count

The default sorting order is ascending. For example: "name" and "name asc" are equivalent values.

To specify descending order for a field, append a " desc" suffix. For example: "name desc".

Redundant space characters are insignificant. For example these values are all equal:

  • " name, cpu desc"
  • "name, cpu desc"
  • "name , cpu desc "

Undefined (empty) time is interpreted as a zero time (0s since epoch, i.e. 1970-01-01T00:00:00Z).

Undefined (empty) duration is interpreted as a zero duration (0 seconds).

filter
string

Used to filter H2OEngines. When unset, no filtering is applied.

Filtering implements specification https://google.aip.dev/160.

Supported filter fields:

  • name
  • h2o_engine_id
  • state
  • cpu
  • gpu
  • memory_bytes
  • creator
  • creator_display_name
  • create_time
  • update_time
  • delete_time
  • reconciling
  • uid
  • display_name
  • max_idle_duration
  • max_running_duration
  • current_idle_duration
  • current_running_duration
  • node_count

Examples:

  • cpu > 5
  • gpu < 3
  • cpu >= 5 AND gpu <= 3
  • cpu != 5 OR gpu == 3
  • NOT (cpu > 5 OR gpu < 3)
  • -(cpu > 5 OR gpu < 3)
  • NOT (cpu > 5 OR (gpu < 3))
  • (cpu > 5 OR gpu < 3) AND memory_bytes != 1000
  • (cpu > 5 OR gpu < 3) AND (NOT ((((memory_bytes = 1000)))))
  • state = STATE_RUNNING AND create_time > "2012-04-21T11:30:00-04:00"
  • max_running_duration > "1s" AND max_running_duration != "5s"
  • reconciling = true OR reconciling = false (supporting bool literals)
  • h2o_engine_id = "*e*" OR display_name = "*e*" (supporting prefix/suffix wildcard * for string fields equality comparison)

Responses

Response samples

Content type
application/json
{
  • "h2oEngines": [
    ],
  • "nextPageToken": "string",
  • "totalSize": 0
}

Creates and starts a new H2OEngine within a specified workspace.

path Parameters
parent
required
stringworkspaces/[^/]+

workspace resource name. Format: workspaces/{workspace}

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/h2oEngines/CREATE
query Parameters
h2oEngineId
required
string

Specify the H2OEngine ID, which will become a part of the H2OEngine resource name.

It must:

  • contain 1-63 characters
  • contain only lowercase alphanumeric characters or hyphen ('-')
  • start with an alphabetic character
  • end with an alphanumeric character

This matches a regular expression: ^a-z?$

validateOnly
boolean

When set, request is only validated but no changes are made.

Request Body schema: application/json

The H2OEngine resource to create. NON_EMPTY_DEFAULT fields that are not set in this request will be set to a default value. Default value is determined by the workspace in which the engine is created. Each workspace has a defined constraint set, which contains the default value for each field.

profile
required
string

Required. The resource name of the H2OEngineProfile that is used by this H2OEngine. Format is workspaces/*/h2oEngineProfiles/*.

object (v1H2OEngineProfileInfo)

The original H2OEngineProfile data used by H2OEngine when using the H2OEngineProfile. For more info about each field see the original H2OEngineProfile resource.

state
string (v1H2OEngineState)
Default: "STATE_UNSPECIFIED"
Enum: "STATE_UNSPECIFIED" "STATE_STARTING" "STATE_RUNNING" "STATE_PAUSING" "STATE_PAUSED" "STATE_FAILED" "STATE_DELETING" "STATE_CONNECTING" "STATE_TERMINATING" "STATE_TERMINATED"

All possible H2OEngine states.

  • STATE_UNSPECIFIED: H2OEngine state is unspecified or unknown.
  • STATE_STARTING: H2OEngine is starting.
  • STATE_RUNNING: H2OEngine is running and can be used.
  • STATE_PAUSING: H2OEngine is pausing. Deprecated, use STATE_TERMINATING.
  • STATE_PAUSED: H2OEngine is paused and CANNOT be resumed again. Deprecated, use STATE_TERMINATED.
  • STATE_FAILED: H2OEngine has failed.
  • STATE_DELETING: H2OEngine is being deleted.
  • STATE_CONNECTING: H2OEngine is establishing a connection with the AI Engine Manager.
  • STATE_TERMINATING: H2OEngine is terminating.
  • STATE_TERMINATED: H2OEngine is terminated. This is a final state.
object

Additional arbitrary metadata associated with the H2OEngine.

Annotations are key/value pairs. The key must:

  • be 63 characters or less
  • begin and end with an alphanumeric character ([a-z0-9A-Z])
  • with dashes (-), underscores (_), dots (.), and alphanumerics between
  • regex used for validation is: ^A-Za-z0-9?$
displayName
string

Human-readable name of the H2OEngine. Must contain at most 63 characters. Does not have to be unique.

cpu
integer or null <int32>

The amount of CPU units per node requested by this H2OEngine.

gpu
integer or null <int32>

The amount of GPU units per node requested by this H2OEngine.

memoryBytes
string or null <int64>

The amount of memory in bytes per node requested by this H2OEngine.

maxIdleDuration
string or null

Maximum time an H2OEngine can be idle. When exceeded, the H2OEngine will terminate.

maxRunningDuration
string or null

Maximum time an H2OEngine can be running. When exceeded, the H2OEngine will terminate.

nodeCount
integer or null <int32>

The number of nodes requested by this H2OEngine.

h2oEngineVersion
required
string (Required. Immutable. H2OEngineVersion assigned to H2OEngine. Format: workspaces/*/h2oEngineVersions/*)
object (v1H2OEngineVersionInfo)

The original H2OEngineVersion data used by H2OEngine when using the H2OEngineVersion. For more info about each field see the original H2OEngineVersion resource.

Responses

Request samples

Content type
application/json
{
  • "profile": "string",
  • "profileInfo": {
    },
  • "state": "STATE_UNSPECIFIED",
  • "annotations": {
    },
  • "displayName": "string",
  • "cpu": 0,
  • "gpu": 0,
  • "memoryBytes": "string",
  • "maxIdleDuration": "string",
  • "maxRunningDuration": "string",
  • "nodeCount": 0,
  • "h2oEngineVersion": "string",
  • "h2oEngineVersionInfo": {
    }
}

Response samples

Content type
application/json
{
  • "h2oEngine": {
    }
}

H2OEngineVersionService

Updates a H2OEngineVersion.

path Parameters
h2oEngineVersion.name
required
stringworkspaces/[^/]+/h2oEngineVersions/[^/]+

H2OEngineVersion resource name. For example: workspaces/global/h2oEngineVersions/3.38.0.1

query Parameters
updateMask
required
string

Required. The list of paths referencing which fields to update. Update mask must be non-empty.

Allowed field paths are:

  • deprecated
  • image
  • image_pull_policy
  • image_pull_secrets

Paths are case sensitive (must match exactly).

To update all allowed fields, specify exactly one path with value "*".

Request Body schema: application/json

Required. H2OEngineVersion resource.

Authorization may require the following permission on the h2oEngineVersion's parent workspace:

  • actions/enginemanager/h2oEngineVersions/UPDATE
deprecated
boolean

Indicates whether H2OEngineVersion is deprecated.

aliases
Array of strings

Optional. ResourceID aliases for this H2OEngineVersion. Aliases are unique within the workspace (two versions in the same workspace cannot have the same alias).

Any alias must be in format:

  • contain 1-63 characters
  • contain only lowercase alphanumeric characters or hyphen ('-')
  • start with an alphabetic character
  • end with an alphanumeric character This matches a regular expression: ^a-z?$

For example: when H2OEngineVersion with name "workspaces/global/h2oEngineVersions/3.38.0.1" has aliases={"latest", "prerelease"}, then "workspaces/global/h2oEngineVersions/latest" will refer to this H2OEngineVersion.

image
required
string

Required. Name of the Docker image used when using this H2OEngineVersion.

imagePullPolicy
string (v1ImagePullPolicy)
Default: "IMAGE_PULL_POLICY_UNSPECIFIED"
Enum: "IMAGE_PULL_POLICY_UNSPECIFIED" "IMAGE_PULL_POLICY_ALWAYS" "IMAGE_PULL_POLICY_NEVER" "IMAGE_PULL_POLICY_IF_NOT_PRESENT"

Policy for downloading an image in K8s.

  • IMAGE_PULL_POLICY_UNSPECIFIED: Unspecified image pull policy.
  • IMAGE_PULL_POLICY_ALWAYS: Every time the container is launched, the container image registry is queried to resolve the name to an image digest.
  • IMAGE_PULL_POLICY_NEVER: Do not try to fetch the image. If the image is already present locally, the container will start. If the image is not present, container startup will fail.
  • IMAGE_PULL_POLICY_IF_NOT_PRESENT: The image is pulled only if it is not already present locally.
imagePullSecrets
Array of strings

List of references to k8s secrets that can be used for pulling an image of this H2OEngineVersion from a private container image registry or repository.

Responses

Request samples

Content type
application/json
{
  • "deprecated": true,
  • "aliases": [
    ],
  • "image": "string",
  • "imagePullPolicy": "IMAGE_PULL_POLICY_UNSPECIFIED",
  • "imagePullSecrets": [
    ]
}

Response samples

Content type
application/json
{
  • "h2oEngineVersion": {
    }
}

Assign new set of resourceID aliases to H2OEngineVersion. This will replace existing H2OEngineVersion resourceID aliases with the new aliases. If there are other H2OEngineVersions with the same alias that we try to assign to this H2OEngineVersion, they will be deleted from the other H2OEngineVersions.

Example 1 - two versions in the same workspace:

  • h2ow1v1(name="workspaces/w1/h2oEngineVersions/v1", aliases=["latest", "bar"])
  • h2ow1v2(name="workspaces/w1/h2oEngineVersions/v2", aliases=["baz", "foo"])
  • AssignAliases(h2ow1v1, aliases=["latest", "baz"]) => h2ow1v1.aliases=["latest", "baz"] (changed) => h2ow1v2.aliases=["foo"] (changed)

Example 2 - two versions in different workspaces:

  • h2ow1v1(name="workspaces/w1/h2oEngineVersions/v1", aliases=["latest", "bar"])
  • h2ow2v1(name="workspaces/w2/h2oEngineVersions/v1", aliases=["latest", "baz"])
  • AssignAliases(h2ow1v1, aliases=["latest", "baz"]) => h2ow1v1.aliases=["latest", "baz"] (changed) => h2ow2v1.aliases=["latest", "baz"] (unchanged)
path Parameters
name_1
required
stringworkspaces/[^/]+/h2oEngineVersions/[^/]+

H2OEngineVersion resource name. Format: workspaces/{workspace}/h2oEngineVersions/{h2o_engine_version}

Authorization may require the following permission on the h2oEngineVersion's parent workspace:

  • actions/enginemanager/h2oEngineVersions/ASSIGN_ALIASES
Request Body schema: application/json
aliases
required
Array of strings

New resourceID aliases of the H2OEngineVersion.

Responses

Request samples

Content type
application/json
{
  • "aliases": [
    ]
}

Response samples

Content type
application/json
{
  • "h2oEngineVersions": [
    ]
}

Deletes a H2OEngineVersion.

path Parameters
name_6
required
stringworkspaces/[^/]+/h2oEngineVersions/[^/]+

H2OEngineVersion resource name. Format: workspaces/{workspace}/h2oEngineVersions/{h2o_engine_version}

Authorization may require the following permission on the h2oEngineVersion's parent workspace:

  • actions/enginemanager/h2oEngineVersions/DELETE

Responses

Response samples

Content type
application/json
{ }

Get H2OEngineVersion.

path Parameters
name_7
required
stringworkspaces/[^/]+/h2oEngineVersions/[^/]+

H2OEngineVersion resource name. Format: workspaces/{workspace}/h2oEngineVersions/{h2o_engine_version}

Authorization may require the following permission on the h2oEngineVersion's parent workspace:

  • actions/enginemanager/h2oEngineVersions/GET

Responses

Response samples

Content type
application/json
{
  • "h2oEngineVersion": {
    }
}

Returns a collection of H2OEngineVersions.

path Parameters
parent
required
stringworkspaces/[^/]+

Workspace resource name. Format: workspaces/{workspace}

Authorization may require the following permission on the h2oEngineVersion's parent workspace:

  • actions/enginemanager/h2oEngineVersions/LIST
query Parameters
pageSize
integer <int32>

Maximum number of H2OEngineVersions to return in a response. If unspecified (or set to 0), at most 50 H2OEngineVersions will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

pageToken
string

Leave unset to receive the initial page. To list any subsequent pages use the value of 'next_page_token' returned from the ListH2OEngineVersionsResponse.

Responses

Response samples

Content type
application/json
{
  • "h2oEngineVersions": [
    ],
  • "nextPageToken": "string"
}

Creates a new H2OEngineVersion.

path Parameters
parent
required
stringworkspaces/[^/]+

Workspace resource name. Format: workspaces/{workspace}

Authorization may require the following permission on the h2oEngineVersion's parent workspace:

  • actions/enginemanager/h2oEngineVersions/CREATE
query Parameters
h2oEngineVersionId
required
string

Specify the H2OEngineVersion ID, which will become a part of the H2OEngineVersion resource name.

It must:

  • be in semver format (more segments than three segments allowed)
  • contain max 63 characters

Examples: "1.10.3", "1.10.3-alpha", "1.10.3.2", "1.10.3.2-alpha"

Request Body schema: application/json

The H2OEngineVersion resource to create.

name
string (H2OEngineVersion resource name. For example: workspaces/global/h2oEngineVersions/3.38.0.1)
deprecated
boolean

Indicates whether H2OEngineVersion is deprecated.

aliases
Array of strings

Optional. ResourceID aliases for this H2OEngineVersion. Aliases are unique within the workspace (two versions in the same workspace cannot have the same alias).

Any alias must be in format:

  • contain 1-63 characters
  • contain only lowercase alphanumeric characters or hyphen ('-')
  • start with an alphabetic character
  • end with an alphanumeric character This matches a regular expression: ^a-z?$

For example: when H2OEngineVersion with name "workspaces/global/h2oEngineVersions/3.38.0.1" has aliases={"latest", "prerelease"}, then "workspaces/global/h2oEngineVersions/latest" will refer to this H2OEngineVersion.

image
required
string

Required. Name of the Docker image used when using this H2OEngineVersion.

imagePullPolicy
string (v1ImagePullPolicy)
Default: "IMAGE_PULL_POLICY_UNSPECIFIED"
Enum: "IMAGE_PULL_POLICY_UNSPECIFIED" "IMAGE_PULL_POLICY_ALWAYS" "IMAGE_PULL_POLICY_NEVER" "IMAGE_PULL_POLICY_IF_NOT_PRESENT"

Policy for downloading an image in K8s.

  • IMAGE_PULL_POLICY_UNSPECIFIED: Unspecified image pull policy.
  • IMAGE_PULL_POLICY_ALWAYS: Every time the container is launched, the container image registry is queried to resolve the name to an image digest.
  • IMAGE_PULL_POLICY_NEVER: Do not try to fetch the image. If the image is already present locally, the container will start. If the image is not present, container startup will fail.
  • IMAGE_PULL_POLICY_IF_NOT_PRESENT: The image is pulled only if it is not already present locally.
imagePullSecrets
Array of strings

List of references to k8s secrets that can be used for pulling an image of this H2OEngineVersion from a private container image registry or repository.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "deprecated": true,
  • "aliases": [
    ],
  • "image": "string",
  • "imagePullPolicy": "IMAGE_PULL_POLICY_UNSPECIFIED",
  • "imagePullSecrets": [
    ]
}

Response samples

Content type
application/json
{
  • "h2oEngineVersion": {
    }
}

NotebookEngineImageService

Deletes a NotebookEngineImage.

path Parameters
name_7
required
stringworkspaces/[^/]+/notebookEngineImages/[^/]+

Required. NotebookEngineImage resource name. Format is workspaces/*/notebookEngineImages/*.

Responses

Response samples

Content type
application/json
{ }

Returns a specific NotebookEngineImage.

path Parameters
name_8
required
stringworkspaces/[^/]+/notebookEngineImages/[^/]+

Required. The name of the NotebookEngineImage to retrieve. Format is workspaces/*/notebookEngineImages/*

Responses

Response samples

Content type
application/json
{
  • "notebookEngineImage": {
    }
}

Updates a NotebookEngineImage.

path Parameters
notebookEngineImage.name
required
stringworkspaces/[^/]+/notebookEngineImages/[^/]+

Output only. Resource name. Format is workspaces/*/notebookEngineImages/*.

query Parameters
updateMask
required
string

Required. The list of paths referencing which fields to update. Update mask must be non-empty.

Allowed field paths are: {"display_name", "image", "enabled", "image_pull_policy", "image_pull_secrets"}. Paths are case sensitive (must match exactly).

To update all allowed fields, specify exactly one path with value "*".

Request Body schema: application/json

Required. NotebookEngineImage resource.

displayName
string

Optional. Human-readable name.

image
required
string (Required. Docker image name. For example: "gcr.io/vorvan/h2oai/h2o-kernel-py:0.3.2")
enabled
boolean

Optional. Whether the NotebookEngineImage is enabled. Disabled NotebookEngineImage cannot be used for creating new NotebookEngine.

imagePullPolicy
string (v1ImagePullPolicy)
Default: "IMAGE_PULL_POLICY_UNSPECIFIED"
Enum: "IMAGE_PULL_POLICY_UNSPECIFIED" "IMAGE_PULL_POLICY_ALWAYS" "IMAGE_PULL_POLICY_NEVER" "IMAGE_PULL_POLICY_IF_NOT_PRESENT"

Policy for downloading an image in K8s.

  • IMAGE_PULL_POLICY_UNSPECIFIED: Unspecified image pull policy.
  • IMAGE_PULL_POLICY_ALWAYS: Every time the container is launched, the container image registry is queried to resolve the name to an image digest.
  • IMAGE_PULL_POLICY_NEVER: Do not try to fetch the image. If the image is already present locally, the container will start. If the image is not present, container startup will fail.
  • IMAGE_PULL_POLICY_IF_NOT_PRESENT: The image is pulled only if it is not already present locally.
imagePullSecrets
Array of strings

Optional. A list of Kubernetes secret references used for authenticating to private container registries or repositories. These secrets provide the necessary credentials to pull Docker images from private repositories. Each entry in this list should be the name of a Kubernetes secret configured in the cluster.

Responses

Request samples

Content type
application/json
{
  • "displayName": "string",
  • "image": "string",
  • "enabled": true,
  • "imagePullPolicy": "IMAGE_PULL_POLICY_UNSPECIFIED",
  • "imagePullSecrets": [
    ]
}

Response samples

Content type
application/json
{
  • "notebookEngineImage": {
    }
}

Returns a collection of NotebookEngineImages.

path Parameters
parent
required
stringworkspaces/[^/]+

Required. The resource name of the workspace to associate with the NotebookEngineImage. Format is workspaces/*.

query Parameters
pageSize
integer <int32>

Optional. Maximum number of NotebookEngineImages to return in a response. If unspecified (or set to 0), at most 50 NotebookEngineImages will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

pageToken
string

Optional. Leave unset to receive the initial page. To list any subsequent pages use the value of 'next_page_token' returned from the ListNotebookEngineImagesResponse.

Responses

Response samples

Content type
application/json
{
  • "notebookEngineImages": [
    ],
  • "nextPageToken": "string"
}

Creates a new NotebookEngineImage.

path Parameters
parent
required
stringworkspaces/[^/]+

Required. The resource name of the workspace to associate with the NotebookEngineImage. Format is workspaces/*.

query Parameters
notebookEngineImageId
string

Optional. Specify the NotebookEngineImage ID, which will become a part of the NotebookEngineImage resource name. If not specified, the server will generate one.

It must:

  • contain 1-63 characters
  • contain only lowercase alphanumeric characters or hyphen ('-')
  • start with an alphabetic character
  • end with an alphanumeric character

This matches a regular expression: ^a-z?$

Request Body schema: application/json

Required. The NotebookEngineImage resource to create.

displayName
string

Optional. Human-readable name.

image
required
string (Required. Docker image name. For example: "gcr.io/vorvan/h2oai/h2o-kernel-py:0.3.2")
enabled
boolean

Optional. Whether the NotebookEngineImage is enabled. Disabled NotebookEngineImage cannot be used for creating new NotebookEngine.

imagePullPolicy
string (v1ImagePullPolicy)
Default: "IMAGE_PULL_POLICY_UNSPECIFIED"
Enum: "IMAGE_PULL_POLICY_UNSPECIFIED" "IMAGE_PULL_POLICY_ALWAYS" "IMAGE_PULL_POLICY_NEVER" "IMAGE_PULL_POLICY_IF_NOT_PRESENT"

Policy for downloading an image in K8s.

  • IMAGE_PULL_POLICY_UNSPECIFIED: Unspecified image pull policy.
  • IMAGE_PULL_POLICY_ALWAYS: Every time the container is launched, the container image registry is queried to resolve the name to an image digest.
  • IMAGE_PULL_POLICY_NEVER: Do not try to fetch the image. If the image is already present locally, the container will start. If the image is not present, container startup will fail.
  • IMAGE_PULL_POLICY_IF_NOT_PRESENT: The image is pulled only if it is not already present locally.
imagePullSecrets
Array of strings

Optional. A list of Kubernetes secret references used for authenticating to private container registries or repositories. These secrets provide the necessary credentials to pull Docker images from private repositories. Each entry in this list should be the name of a Kubernetes secret configured in the cluster.

Responses

Request samples

Content type
application/json
{
  • "displayName": "string",
  • "image": "string",
  • "enabled": true,
  • "imagePullPolicy": "IMAGE_PULL_POLICY_UNSPECIFIED",
  • "imagePullSecrets": [
    ]
}

Response samples

Content type
application/json
{
  • "notebookEngineImage": {
    }
}

NotebookEngineProfileService

Copies an existing NotebookEngineProfile to a new NotebookEngineProfile.

path Parameters
name_2
required
stringworkspaces/[^/]+/notebookEngineProfiles/[^/]+...

Required. Source NotebookEngineProfile resource name. Format: workspaces/{workspace}/notebookEngineProfiles/{notebook_engine_profile}

Authorization may require the following permission on the profile's parent workspace:

  • actions/enginemanager/notebookEngineProfiles/GET
Request Body schema: application/json
parent
required
string (Required. The parent workspace where the new NotebookEngineProfile will be created. Format: workspaces/{workspace})

Authorization may require the following permission on this workspace:

  • actions/enginemanager/notebookEngineProfiles/CREATE
notebookEngineProfileId
required
string

Required. Specify the target NotebookEngineProfile ID, which will become a part of the new NotebookEngineProfile resource name.

Must follow the same format as notebook_engine_profile_id when creating a new Profile.

Responses

Request samples

Content type
application/json
{
  • "parent": "string",
  • "notebookEngineProfileId": "string"
}

Response samples

Content type
application/json
{
  • "notebookEngineProfile": {
    }
}

Deletes a NotebookEngineProfile.

path Parameters
name_8
required
stringworkspaces/[^/]+/notebookEngineProfiles/[^/]+...

NotebookEngine resource name. Format: workspaces/{workspace}/notebookEngineProfiles/{notebook_engine_profile}

Authorization may require the following permission on the profile's parent workspace:

  • actions/enginemanager/notebookEngineProfiles/DELETE

Responses

Response samples

Content type
application/json
{ }

Get NotebookEngineProfile.

path Parameters
name_9
required
stringworkspaces/[^/]+/notebookEngineProfiles/[^/]+...

NotebookEngineProfile resource name. Format: workspaces/{workspace}/notebookEngineProfiles/{notebook_engine_profile}

Authorization may require the following permission on the profile's parent workspace:

  • actions/enginemanager/notebookEngineProfiles/GET

Responses

Response samples

Content type
application/json
{
  • "notebookEngineProfile": {
    }
}

Updates a NotebookEngineProfile.

path Parameters
notebookEngineProfile.name
required
stringworkspaces/[^/]+/notebookEngineProfiles/[^/]+...

Output only. Resource name. Format: workspaces//notebookEngineProfiles/

query Parameters
updateMask
required
string

Required. The list of paths referencing which fields to update. Update mask must be non-empty.

Allowed field paths are:

  • display_name
  • priority
  • enabled
  • assigned_oidc_roles_enabled
  • assigned_oidc_roles
  • max_running_engines
  • cpu_constraint
  • gpu_constraint
  • memory_bytes_constraint
  • storage_bytes_constraint
  • max_idle_duration_constraint
  • max_running_duration_constraint
  • yaml_pod_template_spec
  • yaml_gpu_tolerations
  • storage_class_name
  • gpu_resource_name

Paths are case sensitive (must match exactly).

To update all allowed fields, specify exactly one path with value "*".

Request Body schema: application/json

Required. NotebookEngineProfile resource.

Authorization may require the following permission on the profile's parent workspace:

  • actions/enginemanager/notebookEngineProfiles/UPDATE
displayName
string

Optional. Human-readable name.

priority
integer <int32>

Optional. Priority of the NotebookEngineProfile. Lower value means higher priority. Priority is NOT a unique value (any two NotebookEngineProfiles can have the same priority value).

enabled
boolean

Optional. When set to true, the NotebookEngineProfile is enabled and can be used in NotebookEngine. When set to false, the NotebookEngineProfile is disabled and cannot be used in any NotebookEngine.

assignedOidcRolesEnabled
boolean

Optional. When set to true, the assigned_oidc_roles field is verified when a user uses this profile.

assignedOidcRoles
Array of strings

Optional. List of OIDC roles assigned to this NotebookEngineProfile.

When profile has assigned some OIDC roles and verification of this list is enabled (assigned_oidc_roles_enabled=true), then this profile can be used only by users who have assigned at least one role from this list.

Example 1: assigned_oidc_roles = ["role1", "role2"]. This profile can be used only by users who have assigned either role1 or role2.

Example 2 (special case): assigned_oidc_roles = []. Empty list means that the profile has not assigned any OIDC role, therefore this profile cannot be used by any user.

maxRunningEngines
integer or null <int32>

Optional. Maximum number of NotebookEngines per user that can be running when using this NotebookEngineProfile.

object (v1ProfileConstraintNumeric)

Message representing a constraint on a user-specified numeric value.

object (v1ProfileConstraintNumeric)

Message representing a constraint on a user-specified numeric value.

object (v1ProfileConstraintNumeric)

Message representing a constraint on a user-specified numeric value.

object (v1ProfileConstraintNumeric)

Message representing a constraint on a user-specified numeric value.

object (v1ProfileConstraintDuration)

Message representing a constraint on a user-specified duration value.

object (v1ProfileConstraintDuration)

Message representing a constraint on a user-specified duration value.

yamlPodTemplateSpec
string (Optional. YAML representation of custom PodTemplateSpec. Definition of PodTemplateSpec: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#podtemplatespec-v1-core)

When specified, then it is applied for each NotebookEngine that uses this profile. PodTemplateSpec describes what will be applied on top of a regular Notebook pod before it is created. This template is merged into Notebook default pod using StrategicMergePatch method (it overrides the default pod). More info about StrategicMergePatch: https://kubernetes.io/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch/

Example YAML value (custom annotation applied for each Notebook pod): metadata: annotations: custom-key: custom-value

yamlGpuTolerations
string (Optional. YAML representation of custom GPU Tolerations. Definition of one Toleration: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#toleration-v1-core)

When specified, then it is applied for each NotebookEngine that uses this profile. GPUTolerations sets Notebook's pod.spec.tolerations in case NotebookEngine has GPU > 0. This will override any tolerations defined in yaml_pod_template_spec.PodSpec.Tolerations field.

Example YAML value (two GPU tolerations applied for each Notebook pod):

  • key: "dedicated" operator: "Equal" value: "gpu" effect: "NoSchedule"
  • key: "key2" operator: "Equal" value: "value2" effect: "NoSchedule"
storageClassName
string

Optional. Name of the storage class used by NotebookEngine when using this profile. When unset, the default storage class of the k8s cluster will be used.

gpuResourceName
string

Non-empty default. K8s GPU resource name. For example: nvidia.com/gpu or amd.com/gpu. When unset, server will choose a default value.

syncGitRepositoryEnabled
boolean

Optional. Enables syncing of the git repository when NotebookEngine is created.

gitRepository
string

Optional. The git repository to sync.

gitRef
string

Optional. The git revision (branch, tag, or hash) to check out. If not specified, this defaults to "HEAD" (of the upstream repo's default branch).

gitDirectoryName
string

Optional. The name of the directory in the user's home folder, where the Git repo is synced into. Defaults to "Example".

Responses

Request samples

Content type
application/json
{
  • "displayName": "string",
  • "priority": 0,
  • "enabled": true,
  • "assignedOidcRolesEnabled": true,
  • "assignedOidcRoles": [
    ],
  • "maxRunningEngines": 0,
  • "cpuConstraint": {
    },
  • "gpuConstraint": {
    },
  • "memoryBytesConstraint": {
    },
  • "storageBytesConstraint": {
    },
  • "maxIdleDurationConstraint": {
    },
  • "maxRunningDurationConstraint": {
    },
  • "yamlPodTemplateSpec": "string",
  • "yamlGpuTolerations": "string",
  • "storageClassName": "string",
  • "gpuResourceName": "string",
  • "syncGitRepositoryEnabled": true,
  • "gitRepository": "string",
  • "gitRef": "string",
  • "gitDirectoryName": "string"
}

Response samples

Content type
application/json
{
  • "notebookEngineProfile": {
    }
}

Returns a collection of NotebookEngineProfiles.

path Parameters
parent
required
stringworkspaces/[^/]+

Workspace resource name. Format: workspaces/{workspace}

Authorization may require the following permission on the profile's parent workspace:

  • actions/enginemanager/notebookEngineProfiles/LIST
query Parameters
pageSize
integer <int32>

Maximum number of NotebookEngineProfiles to return in a response. If unspecified (or set to 0), at most 50 NotebookEngineProfiles will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

pageToken
string

Leave unset to receive the initial page. To list any subsequent pages use the value of 'next_page_token' returned from the ListNotebookEngineProfilesResponse.

Responses

Response samples

Content type
application/json
{
  • "notebookEngineProfiles": [
    ],
  • "nextPageToken": "string"
}

Creates a new NotebookEngineProfile.

path Parameters
parent
required
stringworkspaces/[^/]+

Workspace resource name. Format: workspaces/{workspace}

Authorization may require the following permission on the profile's parent workspace:

  • actions/enginemanager/notebookEngineProfiles/CREATE
query Parameters
notebookEngineProfileId
required
string

Specify the NotebookEngineProfile ID, which will become a part of the NotebookEngineProfile resource name.

It must:

  • contain 1-63 characters
  • contain only lowercase alphanumeric characters or hyphen ('-')
  • start with an alphabetic character
  • end with an alphanumeric character

This matches a regular expression: ^a-z?$

Request Body schema: application/json

The NotebookEngineProfile resource to create.

displayName
string

Optional. Human-readable name.

priority
integer <int32>

Optional. Priority of the NotebookEngineProfile. Lower value means higher priority. Priority is NOT a unique value (any two NotebookEngineProfiles can have the same priority value).

enabled
boolean

Optional. When set to true, the NotebookEngineProfile is enabled and can be used in NotebookEngine. When set to false, the NotebookEngineProfile is disabled and cannot be used in any NotebookEngine.

assignedOidcRolesEnabled
boolean

Optional. When set to true, the assigned_oidc_roles field is verified when a user uses this profile.

assignedOidcRoles
Array of strings

Optional. List of OIDC roles assigned to this NotebookEngineProfile.

When profile has assigned some OIDC roles and verification of this list is enabled (assigned_oidc_roles_enabled=true), then this profile can be used only by users who have assigned at least one role from this list.

Example 1: assigned_oidc_roles = ["role1", "role2"]. This profile can be used only by users who have assigned either role1 or role2.

Example 2 (special case): assigned_oidc_roles = []. Empty list means that the profile has not assigned any OIDC role, therefore this profile cannot be used by any user.

maxRunningEngines
integer or null <int32>

Optional. Maximum number of NotebookEngines per user that can be running when using this NotebookEngineProfile.

object (v1ProfileConstraintNumeric)

Message representing a constraint on a user-specified numeric value.

object (v1ProfileConstraintNumeric)

Message representing a constraint on a user-specified numeric value.

object (v1ProfileConstraintNumeric)

Message representing a constraint on a user-specified numeric value.

object (v1ProfileConstraintNumeric)

Message representing a constraint on a user-specified numeric value.

object (v1ProfileConstraintDuration)

Message representing a constraint on a user-specified duration value.

object (v1ProfileConstraintDuration)

Message representing a constraint on a user-specified duration value.

yamlPodTemplateSpec
string (Optional. YAML representation of custom PodTemplateSpec. Definition of PodTemplateSpec: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#podtemplatespec-v1-core)

When specified, then it is applied for each NotebookEngine that uses this profile. PodTemplateSpec describes what will be applied on top of a regular Notebook pod before it is created. This template is merged into Notebook default pod using StrategicMergePatch method (it overrides the default pod). More info about StrategicMergePatch: https://kubernetes.io/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch/

Example YAML value (custom annotation applied for each Notebook pod): metadata: annotations: custom-key: custom-value

yamlGpuTolerations
string (Optional. YAML representation of custom GPU Tolerations. Definition of one Toleration: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#toleration-v1-core)

When specified, then it is applied for each NotebookEngine that uses this profile. GPUTolerations sets Notebook's pod.spec.tolerations in case NotebookEngine has GPU > 0. This will override any tolerations defined in yaml_pod_template_spec.PodSpec.Tolerations field.

Example YAML value (two GPU tolerations applied for each Notebook pod):

  • key: "dedicated" operator: "Equal" value: "gpu" effect: "NoSchedule"
  • key: "key2" operator: "Equal" value: "value2" effect: "NoSchedule"
storageClassName
string

Optional. Name of the storage class used by NotebookEngine when using this profile. When unset, the default storage class of the k8s cluster will be used.

gpuResourceName
string

Non-empty default. K8s GPU resource name. For example: nvidia.com/gpu or amd.com/gpu. When unset, server will choose a default value.

syncGitRepositoryEnabled
boolean

Optional. Enables syncing of the git repository when NotebookEngine is created.

gitRepository
string

Optional. The git repository to sync.

gitRef
string

Optional. The git revision (branch, tag, or hash) to check out. If not specified, this defaults to "HEAD" (of the upstream repo's default branch).

gitDirectoryName
string

Optional. The name of the directory in the user's home folder, where the Git repo is synced into. Defaults to "Example".

Responses

Request samples

Content type
application/json
{
  • "displayName": "string",
  • "priority": 0,
  • "enabled": true,
  • "assignedOidcRolesEnabled": true,
  • "assignedOidcRoles": [
    ],
  • "maxRunningEngines": 0,
  • "cpuConstraint": {
    },
  • "gpuConstraint": {
    },
  • "memoryBytesConstraint": {
    },
  • "storageBytesConstraint": {
    },
  • "maxIdleDurationConstraint": {
    },
  • "maxRunningDurationConstraint": {
    },
  • "yamlPodTemplateSpec": "string",
  • "yamlGpuTolerations": "string",
  • "storageClassName": "string",
  • "gpuResourceName": "string",
  • "syncGitRepositoryEnabled": true,
  • "gitRepository": "string",
  • "gitRef": "string",
  • "gitDirectoryName": "string"
}

Response samples

Content type
application/json
{
  • "notebookEngineProfile": {
    }
}

Returns assigned NotebookEngineProfiles that match OIDC roles of the caller. (-- api-linter: core::0136::http-uri-suffix=disabled aip.dev/not-precedent: Not a standard List method. --)

path Parameters
parent
required
stringworkspaces/[^/]+

Workspace resource name. Format: workspaces/{workspace}

Authorization may require the following permission on the profile's parent workspace:

  • actions/enginemanager/notebookEngineProfiles/LIST_ASSIGNED
query Parameters
pageSize
integer <int32>

Maximum number of NotebookEngineProfiles to return in a response. If unspecified (or set to 0), at most 50 NotebookEngineProfiles will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

pageToken
string

Leave unset to receive the initial page. To list any subsequent pages use the value of 'next_page_token' returned from the ListNotebookEngineProfilesResponse.

Responses

Response samples

Content type
application/json
{
  • "notebookEngineProfiles": [
    ],
  • "nextPageToken": "string"
}

NotebookEngineService

Returns a specific NotebookEngine.

path Parameters
name_10
required
stringworkspaces/[^/]+/notebookEngines/[^/]+

NotebookEngine resource name. Format: workspaces/{workspace}/notebookEngines/{notebook_engine}

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/notebookEngines/GET

Responses

Response samples

Content type
application/json
{
  • "notebookEngine": {
    }
}

Pauses a NotebookEngine.

path Parameters
name_1
required
stringworkspaces/[^/]+/notebookEngines/[^/]+

NotebookEngine resource name. Format: workspaces/{workspace}/notebookEngines/{notebook_engine}

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/notebookEngines/PAUSE
Request Body schema: application/json
object

Request message for pausing a running NotebookEngine.

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "notebookEngine": {
    }
}

Resumes an existing NotebookEngine.

path Parameters
name_1
required
stringworkspaces/[^/]+/notebookEngines/[^/]+

NotebookEngine resource name. Format: workspaces/{workspace}/notebookEngines/{notebook_engine}

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/notebookEngines/RESUME
Request Body schema: application/json
object

Request message for resuming an existing NotebookEngine.

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "notebookEngine": {
    }
}

Deletes a NotebookEngine.

path Parameters
name_9
required
stringworkspaces/[^/]+/notebookEngines/[^/]+

NotebookEngine resource name. Format: workspaces/{workspace}/notebookEngines/{notebook_engine}

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/notebookEngines/DELETE

Responses

Response samples

Content type
application/json
{
  • "notebookEngine": {
    }
}

Resize NotebookEngine storage. (-- api-linter: core::0136::http-uri-suffix=disabled aip.dev/not-precedent: False positive. --)

path Parameters
name
required
stringworkspaces/[^/]+/notebookEngines/[^/]+

NotebookEngine resource name. Format: workspaces/{workspace}/notebookEngines/{notebook_engine}

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/notebookEngines/RESIZE_STORAGE
Request Body schema: application/json
newStorageBytes
required
string <int64>

New storage size in bytes.

Responses

Request samples

Content type
application/json
{
  • "newStorageBytes": "string"
}

Response samples

Content type
application/json
{
  • "notebookEngine": {
    }
}

Updates a NotebookEngine.

path Parameters
notebookEngine.name
required
stringworkspaces/[^/]+/notebookEngines/[^/]+

Output only. The resource name of the NotebookEngine. Format: workspaces/*/notebookEngines/*.

query Parameters
updateMask
required
string

The list of paths referencing which fields to update. Update mask must be non-empty.

Allowed field paths are: {"profile", "notebook_image", "cpu", "gpu", "memory_bytes", "display_name", "max_idle_duration", "max_running_duration"}. Paths are case sensitive (must match exactly).

To update all allowed fields, specify exactly one path with value "*".

Request Body schema: application/json

NotebookEngine resource.

displayName
string

Optional. Human-readable name.

profile
required
string

Required. The resource name of the NotebookEngineProfile that is assigned to this NotebookEngine. Format is workspaces/*/notebookEngineProfiles/*.

notebookImage
required
string

Required. Immutable. The resource name of the NotebookEngineImage that is assigned to this NotebookEngine. Format is workspaces/*/notebookEngineImages/*.

cpu
integer or null <int32>

Non-empty default. The amount of CPU units requested by this NotebookEngine.

gpu
integer or null <int32>

Non-empty default. The amount of GPU units requested by this NotebookEngine.

memoryBytes
string or null <int64>

Non-empty default. The amount of memory in bytes requested by this NotebookEngine.

storageBytes
string or null <int64>

Non-empty default. The amount of storage requested by this NotebookEngine.

maxIdleDuration
string or null

Non-empty default. Maximum time the NotebookEngine can be idle. When exceeded, the NotebookEngine will pause.

maxRunningDuration
string or null

Non-empty default. Maximum time the NotebookEngine can be running. When exceeded, the NotebookEngine will pause.

state
string (v1NotebookEngineState)
Default: "STATE_UNSPECIFIED"
Enum: "STATE_UNSPECIFIED" "STATE_STARTING" "STATE_RUNNING" "STATE_PAUSING" "STATE_PAUSED" "STATE_FAILED" "STATE_DELETING" "STATE_TERMINATED"

The state of the NotebookEngine.

  • STATE_UNSPECIFIED: NotebookEngine state is unspecified or unknown.
  • STATE_STARTING: NotebookEngine is starting.
  • STATE_RUNNING: NotebookEngine is running and can be used.
  • STATE_PAUSING: NotebookEngine is pausing.
  • STATE_PAUSED: NotebookEngine is paused and can be resumed again.
  • STATE_FAILED: NotebookEngine has failed and can be resumed again.
  • STATE_DELETING: NotebookEngine is being deleted.
  • STATE_TERMINATED: NotebookEngine is terminated and cannot be resumed.
object (v1NotebookEngineImageInfo)

The original NotebookEngineImage data used by NotebookEngine when using the NotebookEngineImage. For more info about each field see the original NotebookEngineImage resource.

object (v1NotebookEngineProfileInfo)

The original NotebookEngineProfile data used by NotebookEngine when using the NotebookEngineProfile. For more info about each field see the original NotebookEngineProfile resource.

shared
boolean

Optional. Allows the engine to be shared with all users in the workspace.

failureReason
string (NotebookEngineFailureReason)
Default: "FAILURE_REASON_UNSPECIFIED"
Enum: "FAILURE_REASON_UNSPECIFIED" "FAILURE_REASON_UNKNOWN" "FAILURE_REASON_OOM_KILLED" "FAILURE_REASON_PROCESS_FAILED" "FAILURE_REASON_PVC_ACCESS_FAILURE"

The reason of the failed state for the NotebookEngine.

  • FAILURE_REASON_UNSPECIFIED: NotebookEngine failure reason is not set.
  • FAILURE_REASON_UNKNOWN: NotebookEngine failure reason exists, but is unknown.
  • FAILURE_REASON_OOM_KILLED: NotebookEngine exceeded its memory limit and was killed.
  • FAILURE_REASON_PROCESS_FAILED: NotebookEngine application crashed.
  • FAILURE_REASON_PVC_ACCESS_FAILURE: NotebookEngine cannot access the assigned PVC.

Responses

Request samples

Content type
application/json
{
  • "displayName": "string",
  • "profile": "string",
  • "notebookImage": "string",
  • "cpu": 0,
  • "gpu": 0,
  • "memoryBytes": "string",
  • "storageBytes": "string",
  • "maxIdleDuration": "string",
  • "maxRunningDuration": "string",
  • "state": "STATE_UNSPECIFIED",
  • "notebookImageInfo": {
    },
  • "profileInfo": {
    },
  • "shared": true,
  • "failureReason": "FAILURE_REASON_UNSPECIFIED"
}

Response samples

Content type
application/json
{
  • "notebookEngine": {
    }
}

Access NotebookEngine. (-- api-linter: core::0136::http-uri-suffix=disabled aip.dev/not-precedent: False positive. --)

path Parameters
notebookEngine
required
stringworkspaces/[^/]+/notebookEngines/[^/]+

NotebookEngine resource name. Format: workspaces/{workspace}/notebookEngines/{notebook_engine}

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/notebookEngines/ACCESS

Responses

Response samples

Content type
application/json
{
  • "uri": "string"
}

Returns a collection of NotebookEngines within a workspace.

path Parameters
parent
required
stringworkspaces/[^/]+

Workspace resource name. Format: workspaces/{workspace}

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/notebookEngines/LIST
query Parameters
pageSize
integer <int32>

Maximum number of NotebookEngines to return in a response. If unspecified (or set to 0), at most 50 NotebookEngines will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

pageToken
string

Leave unset to receive the initial page. To list any subsequent pages use the value of 'next_page_token' returned from the ListNotebookEnginesResponse.

Responses

Response samples

Content type
application/json
{
  • "notebookEngines": [
    ],
  • "nextPageToken": "string",
  • "totalSize": 0
}

Creates a new NotebookEngine within a specified workspace.

path Parameters
parent
required
stringworkspaces/[^/]+

Workspace resource name. Format: workspaces/{workspace}

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/notebookEngines/CREATE
query Parameters
notebookEngineId
required
string

Specify the NotebookEngine ID, which will become a part of the NotebookEngine resource name.

It must:

  • contain 1-63 characters
  • contain only lowercase alphanumeric characters or hyphen ('-')
  • start with an alphabetic character
  • end with an alphanumeric character

This matches a regular expression: ^a-z?$

Request Body schema: application/json

The NotebookEngine resource to create. NON_EMPTY_DEFAULT fields that are not set in this request will be set to a value based on the selected profile.

displayName
string

Optional. Human-readable name.

profile
required
string

Required. The resource name of the NotebookEngineProfile that is assigned to this NotebookEngine. Format is workspaces/*/notebookEngineProfiles/*.

notebookImage
required
string

Required. Immutable. The resource name of the NotebookEngineImage that is assigned to this NotebookEngine. Format is workspaces/*/notebookEngineImages/*.

cpu
integer or null <int32>

Non-empty default. The amount of CPU units requested by this NotebookEngine.

gpu
integer or null <int32>

Non-empty default. The amount of GPU units requested by this NotebookEngine.

memoryBytes
string or null <int64>

Non-empty default. The amount of memory in bytes requested by this NotebookEngine.

storageBytes
string or null <int64>

Non-empty default. The amount of storage requested by this NotebookEngine.

maxIdleDuration
string or null

Non-empty default. Maximum time the NotebookEngine can be idle. When exceeded, the NotebookEngine will pause.

maxRunningDuration
string or null

Non-empty default. Maximum time the NotebookEngine can be running. When exceeded, the NotebookEngine will pause.

state
string (v1NotebookEngineState)
Default: "STATE_UNSPECIFIED"
Enum: "STATE_UNSPECIFIED" "STATE_STARTING" "STATE_RUNNING" "STATE_PAUSING" "STATE_PAUSED" "STATE_FAILED" "STATE_DELETING" "STATE_TERMINATED"

The state of the NotebookEngine.

  • STATE_UNSPECIFIED: NotebookEngine state is unspecified or unknown.
  • STATE_STARTING: NotebookEngine is starting.
  • STATE_RUNNING: NotebookEngine is running and can be used.
  • STATE_PAUSING: NotebookEngine is pausing.
  • STATE_PAUSED: NotebookEngine is paused and can be resumed again.
  • STATE_FAILED: NotebookEngine has failed and can be resumed again.
  • STATE_DELETING: NotebookEngine is being deleted.
  • STATE_TERMINATED: NotebookEngine is terminated and cannot be resumed.
object (v1NotebookEngineImageInfo)

The original NotebookEngineImage data used by NotebookEngine when using the NotebookEngineImage. For more info about each field see the original NotebookEngineImage resource.

object (v1NotebookEngineProfileInfo)

The original NotebookEngineProfile data used by NotebookEngine when using the NotebookEngineProfile. For more info about each field see the original NotebookEngineProfile resource.

shared
boolean

Optional. Allows the engine to be shared with all users in the workspace.

failureReason
string (NotebookEngineFailureReason)
Default: "FAILURE_REASON_UNSPECIFIED"
Enum: "FAILURE_REASON_UNSPECIFIED" "FAILURE_REASON_UNKNOWN" "FAILURE_REASON_OOM_KILLED" "FAILURE_REASON_PROCESS_FAILED" "FAILURE_REASON_PVC_ACCESS_FAILURE"

The reason of the failed state for the NotebookEngine.

  • FAILURE_REASON_UNSPECIFIED: NotebookEngine failure reason is not set.
  • FAILURE_REASON_UNKNOWN: NotebookEngine failure reason exists, but is unknown.
  • FAILURE_REASON_OOM_KILLED: NotebookEngine exceeded its memory limit and was killed.
  • FAILURE_REASON_PROCESS_FAILED: NotebookEngine application crashed.
  • FAILURE_REASON_PVC_ACCESS_FAILURE: NotebookEngine cannot access the assigned PVC.

Responses

Request samples

Content type
application/json
{
  • "displayName": "string",
  • "profile": "string",
  • "notebookImage": "string",
  • "cpu": 0,
  • "gpu": 0,
  • "memoryBytes": "string",
  • "storageBytes": "string",
  • "maxIdleDuration": "string",
  • "maxRunningDuration": "string",
  • "state": "STATE_UNSPECIFIED",
  • "notebookImageInfo": {
    },
  • "profileInfo": {
    },
  • "shared": true,
  • "failureReason": "FAILURE_REASON_UNSPECIFIED"
}

Response samples

Content type
application/json
{
  • "notebookEngine": {
    }
}

SandboxEngineImageService

Deletes a SandboxEngineImage.

Authorization may require the following permission on the image's parent workspace:

  • actions/enginemanager/sandboxEngineImages/DELETE
path Parameters
name_10
required
stringworkspaces/[^/]+/sandboxEngineImages/[^/]+

Required. SandboxEngineImage resource name. Format is workspaces/*/sandboxEngineImages/*.

Responses

Response samples

Content type
application/json
{ }

Returns a specific SandboxEngineImage.

Authorization may require the following permission on the image's parent workspace:

  • actions/enginemanager/sandboxEngineImages/GET
path Parameters
name_11
required
stringworkspaces/[^/]+/sandboxEngineImages/[^/]+

Required. The name of the SandboxEngineImage to retrieve. Format is workspaces/*/sandboxEngineImages/*

Responses

Response samples

Content type
application/json
{
  • "sandboxEngineImage": {
    }
}

Returns a collection of SandboxEngineImages.

Authorization may require the following permission on the image's parent workspace:

  • actions/enginemanager/sandboxEngineImages/LIST
path Parameters
parent
required
stringworkspaces/[^/]+

Required. The resource name of the workspace to associate with the SandboxEngineImage. Format is workspaces/*.

query Parameters
pageSize
integer <int32>

Optional. Maximum number of SandboxEngineImages to return in a response. If unspecified (or set to 0), at most 50 SandboxEngineImages will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

pageToken
string

Optional. Leave unset to receive the initial page. To list any subsequent pages use the value of 'next_page_token' returned from the ListSandboxEngineImagesResponse.

Responses

Response samples

Content type
application/json
{
  • "sandboxEngineImages": [
    ],
  • "nextPageToken": "string"
}

Creates a new SandboxEngineImage.

Authorization may require the following permission on the image's parent workspace:

  • actions/enginemanager/sandboxEngineImages/CREATE
path Parameters
parent
required
stringworkspaces/[^/]+

Required. The resource name of the workspace to associate with the SandboxEngineImage. Format is workspaces/*.

query Parameters
sandboxEngineImageId
string

Optional. Specify the SandboxEngineImage ID, which will become a part of the SandboxEngineImage resource name. If not specified, the server will generate one.

It must:

  • contain 1-63 characters
  • contain only lowercase alphanumeric characters or hyphen ('-')
  • start with an alphabetic character
  • end with an alphanumeric character

This matches a regular expression: ^a-z?$

Request Body schema: application/json

Required. The SandboxEngineImage resource to create.

name
string

Identifier. Resource name. Format is workspaces/*/sandboxEngineImages/*.

displayName
string

Optional. Human-readable name.

image
required
string (Required. Docker image name. For example: "353750902984.dkr.ecr.us-east-1.amazonaws.com/h2oai-sandboxengine:latest")
enabled
boolean

Optional. Whether the SandboxEngineImage is enabled. Disabled SandboxEngineImage cannot be used for creating new SandboxEngine.

imagePullPolicy
string (v1ImagePullPolicy)
Default: "IMAGE_PULL_POLICY_UNSPECIFIED"
Enum: "IMAGE_PULL_POLICY_UNSPECIFIED" "IMAGE_PULL_POLICY_ALWAYS" "IMAGE_PULL_POLICY_NEVER" "IMAGE_PULL_POLICY_IF_NOT_PRESENT"

Policy for downloading an image in K8s.

  • IMAGE_PULL_POLICY_UNSPECIFIED: Unspecified image pull policy.
  • IMAGE_PULL_POLICY_ALWAYS: Every time the container is launched, the container image registry is queried to resolve the name to an image digest.
  • IMAGE_PULL_POLICY_NEVER: Do not try to fetch the image. If the image is already present locally, the container will start. If the image is not present, container startup will fail.
  • IMAGE_PULL_POLICY_IF_NOT_PRESENT: The image is pulled only if it is not already present locally.
imagePullSecrets
Array of strings

Optional. A list of Kubernetes secret references used for authenticating to private container registries or repositories. These secrets provide the necessary credentials to pull Docker images from private repositories. Each entry in this list should be the name of a Kubernetes secret configured in the cluster.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "displayName": "string",
  • "image": "string",
  • "enabled": true,
  • "imagePullPolicy": "IMAGE_PULL_POLICY_UNSPECIFIED",
  • "imagePullSecrets": [
    ]
}

Response samples

Content type
application/json
{
  • "sandboxEngineImage": {
    }
}

Updates a SandboxEngineImage.

Authorization may require the following permission on the image's parent workspace:

  • actions/enginemanager/sandboxEngineImages/UPDATE
path Parameters
sandboxEngineImage.name
required
stringworkspaces/[^/]+/sandboxEngineImages/[^/]+

Identifier. Resource name. Format is workspaces/*/sandboxEngineImages/*.

query Parameters
updateMask
required
string

Required. The list of paths referencing which fields to update. Update mask must be non-empty.

Allowed field paths are: {"display_name", "image", "enabled", "image_pull_policy", "image_pull_secrets"}. Paths are case sensitive (must match exactly).

To update all allowed fields, specify exactly one path with value "*".

Request Body schema: application/json

Required. SandboxEngineImage resource.

displayName
string

Optional. Human-readable name.

image
required
string (Required. Docker image name. For example: "353750902984.dkr.ecr.us-east-1.amazonaws.com/h2oai-sandboxengine:latest")
enabled
boolean

Optional. Whether the SandboxEngineImage is enabled. Disabled SandboxEngineImage cannot be used for creating new SandboxEngine.

imagePullPolicy
string (v1ImagePullPolicy)
Default: "IMAGE_PULL_POLICY_UNSPECIFIED"
Enum: "IMAGE_PULL_POLICY_UNSPECIFIED" "IMAGE_PULL_POLICY_ALWAYS" "IMAGE_PULL_POLICY_NEVER" "IMAGE_PULL_POLICY_IF_NOT_PRESENT"

Policy for downloading an image in K8s.

  • IMAGE_PULL_POLICY_UNSPECIFIED: Unspecified image pull policy.
  • IMAGE_PULL_POLICY_ALWAYS: Every time the container is launched, the container image registry is queried to resolve the name to an image digest.
  • IMAGE_PULL_POLICY_NEVER: Do not try to fetch the image. If the image is already present locally, the container will start. If the image is not present, container startup will fail.
  • IMAGE_PULL_POLICY_IF_NOT_PRESENT: The image is pulled only if it is not already present locally.
imagePullSecrets
Array of strings

Optional. A list of Kubernetes secret references used for authenticating to private container registries or repositories. These secrets provide the necessary credentials to pull Docker images from private repositories. Each entry in this list should be the name of a Kubernetes secret configured in the cluster.

Responses

Request samples

Content type
application/json
{
  • "displayName": "string",
  • "image": "string",
  • "enabled": true,
  • "imagePullPolicy": "IMAGE_PULL_POLICY_UNSPECIFIED",
  • "imagePullSecrets": [
    ]
}

Response samples

Content type
application/json
{
  • "sandboxEngineImage": {
    }
}

SandboxEngineService

Deletes a SandboxEngine.

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/sandboxEngines/DELETE
path Parameters
name_11
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+

SandboxEngine resource name. Format: workspaces/{workspace}/sandboxEngines/{sandbox_engine}

Responses

Response samples

Content type
application/json
{ }

Returns a specific SandboxEngine.

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/sandboxEngines/GET
path Parameters
name_12
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+

SandboxEngine resource name. Format: workspaces/{workspace}/sandboxEngines/{sandbox_engine}

Responses

Response samples

Content type
application/json
{
  • "sandboxEngine": {
    }
}

Terminate SandboxEngine.

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/sandboxEngines/TERMINATE
path Parameters
name_1
required
stringworkspaces/[^/]+/sandboxEngines/[^/]+

SandboxEngine resource name.

Request Body schema: application/json
object

Request message for terminating a running SandboxEngine.

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "sandboxEngine": {
    }
}

Returns a collection of SandboxEngines within a workspace.

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/sandboxEngines/LIST
path Parameters
parent
required
stringworkspaces/[^/]+

Workspace resource name. Format: workspaces/{workspace}

query Parameters
pageSize
integer <int32>

Maximum number of SandboxEngines to return in a response. If unspecified (or set to 0), at most 50 SandboxEngines will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

pageToken
string

Leave unset to receive the initial page. To list any subsequent pages use the value of 'next_page_token' returned from the ListSandboxEnginesResponse.

Responses

Response samples

Content type
application/json
{
  • "sandboxEngines": [
    ],
  • "nextPageToken": "string"
}

Creates and starts a new SandboxEngine within a specified workspace.

Authorization may require the following permission on the engine's parent workspace:

  • actions/enginemanager/sandboxEngines/CREATE
path Parameters
parent
required
stringworkspaces/[^/]+

workspace resource name. Format: workspaces/{workspace}

query Parameters
sandboxEngineId
required
string

Specify the SandboxEngine ID, which will become a part of the SandboxEngine resource name.

It must:

  • contain 1-63 characters
  • contain only lowercase alphanumeric characters or hyphen ('-')
  • start with an alphabetic character
  • end with an alphanumeric character

This matches a regular expression: ^a-z?$

Request Body schema: application/json

The SandboxEngine resource to create.

name
string

Identifier. SandboxEngine resource name.

displayName
string

Optional. Human-readable name of the SandboxEngine. Must contain at most 63 characters. Does not have to be unique.

state
string (v1SandboxEngineState)
Default: "STATE_UNSPECIFIED"
Enum: "STATE_UNSPECIFIED" "STATE_STARTING" "STATE_RUNNING" "STATE_TERMINATING" "STATE_TERMINATED" "STATE_FAILED" "STATE_DELETING"

All possible SandboxEngine states.

  • STATE_UNSPECIFIED: SandboxEngine state is unspecified or unknown.
  • STATE_STARTING: SandboxEngine is starting.
  • STATE_RUNNING: SandboxEngine is running.
  • STATE_TERMINATING: SandboxEngine is terminating.
  • STATE_TERMINATED: SandboxEngine is terminated.
  • STATE_FAILED: SandboxEngine has failed.
  • STATE_DELETING: SandboxEngine is being deleted.
sandboxEngineImage
required
string

Required. Immutable. The resource name of the SandboxEngineImage that is assigned to this SandboxEngine. Format is workspaces/*/sandboxEngineImages/*.

object (v1SandboxEngineImageInfo)

The original SandboxEngineImage data used by SandboxEngine when using the SandboxEngineImage. For more info about each field see the original SandboxEngineImage resource.

sandboxEngineTemplate
required
string

Required. Immutable. The resource name of the SandboxEngineTemplate that is assigned to this SandboxEngine. Format is workspaces/*/sandboxEngineTemplates/*.

object (v1SandboxEngineTemplateInfo)

The original SandboxEngineTemplate data used by SandboxEngine when using the SandboxEngineTemplate. For more info about each field see the original SandboxEngineTemplate resource.

object

Optional. Additional arbitrary metadata associated with the SandboxEngine.

Annotations are key/value pairs. The key must:

  • be 63 characters or less
  • begin and end with an alphanumeric character ([a-z0-9A-Z])
  • with dashes (-), underscores (_), dots (.), and alphanumerics between
  • regex used for validation is: ^A-Za-z0-9?$

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "displayName": "string",
  • "state": "STATE_UNSPECIFIED",
  • "sandboxEngineImage": "string",
  • "sandboxEngineImageInfo": {
    },
  • "sandboxEngineTemplate": "string",
  • "sandboxEngineTemplateInfo": { },
  • "annotations": {
    }
}

Response samples

Content type
application/json
{
  • "sandboxEngine": {
    }
}

SandboxEngineTemplateService

Deletes a SandboxEngineTemplate.

Authorization may require the following permission on the template's parent workspace:

  • actions/enginemanager/sandboxEngineTemplates/DELETE
path Parameters
name_12
required
stringworkspaces/[^/]+/sandboxEngineTemplates/[^/]+...

Required. SandboxEngineTemplate resource name. Format is workspaces/*/sandboxEngineTemplates/*.

Responses

Response samples

Content type
application/json
{ }

Returns a specific SandboxEngineTemplate.

Authorization may require the following permission on the template's parent workspace:

  • actions/enginemanager/sandboxEngineTemplates/GET
path Parameters
name_13
required
stringworkspaces/[^/]+/sandboxEngineTemplates/[^/]+...

Required. The name of the SandboxEngineTemplate to retrieve. Format is workspaces/*/sandboxEngineTemplates/*

Responses

Response samples

Content type
application/json
{
  • "sandboxEngineTemplate": {
    }
}

Returns a collection of SandboxEngineTemplates.

Authorization may require the following permission on the template's parent workspace:

  • actions/enginemanager/sandboxEngineTemplates/LIST
path Parameters
parent
required
stringworkspaces/[^/]+

Required. The resource name of the workspace to associate with the SandboxEngineTemplate. Format is workspaces/*.

query Parameters
pageSize
integer <int32>

Optional. Maximum number of SandboxEngineTemplates to return in a response. If unspecified (or set to 0), at most 50 SandboxEngineTemplates will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

pageToken
string

Optional. Leave unset to receive the initial page. To list any subsequent pages use the value of 'next_page_token' returned from the ListSandboxEngineTemplatesResponse.

Responses

Response samples

Content type
application/json
{
  • "sandboxEngineTemplates": [
    ],
  • "nextPageToken": "string"
}

Creates a new SandboxEngineTemplate.

Authorization may require the following permission on the template's parent workspace:

  • actions/enginemanager/sandboxEngineTemplates/CREATE
path Parameters
parent
required
stringworkspaces/[^/]+

Required. The resource name of the workspace to associate with the SandboxEngineTemplate. Format is workspaces/*.

query Parameters
sandboxEngineTemplateId
string

Optional. Specify the SandboxEngineTemplate ID, which will become a part of the SandboxEngineTemplate resource name. If not specified, the server will generate one.

It must:

  • contain 1-63 characters
  • contain only lowercase alphanumeric characters or hyphen ('-')
  • start with an alphabetic character
  • end with an alphanumeric character

This matches a regular expression: ^a-z?$

Request Body schema: application/json

Required. The SandboxEngineTemplate resource to create.

name
string

Identifier. Resource name. Format is workspaces/*/sandboxEngineTemplates/*.

displayName
string

Optional. Human-readable name.

milliCpuRequest
integer <int32>

Optional. MilliCPU units that will be reserved for the SandboxEngine. SandboxEngine may use more CPU resources up to the milli_cpu_limit. It is recommended to set CPU requests to avoid resource contention. 1000 milliCPU = 1 CPU core.

When unset, milli_cpu_request will be set to milli_cpu_limit.

milliCpuLimit
integer <int32>

Optional. Maximum MilliCPU units a SandboxEngine is allowed to use. The SandboxEngine will be throttled to not exceed this limit. It is discouraged to set CPU limits when possible. 1000 milliCPU = 1 CPU core.

gpuResource
string

Optional. Kubernetes GPU resource name. For example: nvidia.com/gpu or amd.com/gpu. When unset, server will choose a default value.

gpu
integer <int32>

Optional. The amount of GPU units requested by this SandboxEngine.

memoryBytesRequest
string <int64>

Optional. Memory in bytes that will be reserved for the SandboxEngine.

When unset, memory_bytes_request will be set to memory_bytes_limit.

memoryBytesLimit
required
string <int64>

Required. Max memory in bytes a SandboxEngine is allowed to use. SandboxEngine may fail or be terminated if it exceeds this limit.

storageBytes
string <int64>

Optional. External ephemeral storage in bytes that will be mounted to the SandboxEngine. When unset, the node disk will be used.

object

Optional. Map of environmental variables that will be set in the SandboxEngine.

yamlPodTemplateSpec
string (Optional. YAML representation of custom PodTemplateSpec serialized into bytes. Definition of PodTemplateSpec: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#podtemplatespec-v1-core)

When specified, then it is applied for SandboxEngine pod. PodTemplateSpec describes what will be applied on top of a regular SandboxEngine pod before it is created. This template is merged using StrategicMergePatch method (it overrides the default SandboxEngine pod). More info about StrategicMergePatch: https://kubernetes.io/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch/

Example YAML value (custom annotation applied on SandboxEngine pod): metadata: annotations: custom-key: custom-value

enabled
boolean

Optional. Whether the SandboxEngineTemplate is enabled. Disabled SandboxEngineTemplates cannot be used for creating new SandboxEngines.

maxIdleDuration
required
string

Required. Maximum time a SandboxEngine can be idle before it is automatically terminated.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "displayName": "string",
  • "milliCpuRequest": 0,
  • "milliCpuLimit": 0,
  • "gpuResource": "string",
  • "gpu": 0,
  • "memoryBytesRequest": "string",
  • "memoryBytesLimit": "string",
  • "storageBytes": "string",
  • "environmentalVariables": {
    },
  • "yamlPodTemplateSpec": "string",
  • "enabled": true,
  • "maxIdleDuration": "string"
}

Response samples

Content type
application/json
{
  • "sandboxEngineTemplate": {
    }
}

Updates a SandboxEngineTemplate.

Authorization may require the following permission on the template's parent workspace:

  • actions/enginemanager/sandboxEngineTemplates/UPDATE
path Parameters
sandboxEngineTemplate.name
required
stringworkspaces/[^/]+/sandboxEngineTemplates/[^/]+...

Identifier. Resource name. Format is workspaces/*/sandboxEngineTemplates/*.

query Parameters
updateMask
required
string

Required. The list of paths referencing which fields to update. Update mask must be non-empty.

Allowed field paths are: {"display_name", "milli_cpu_request", "milli_cpu_limit", "gpu_resource", "gpu", "memory_bytes_request", "memory_bytes_limit", "storage_bytes", "storage_class_name", "environmental_variables", "yaml_pod_template_spec", "enabled", "max_idle_duration"}. Paths are case sensitive (must match exactly).

To update all allowed fields, specify exactly one path with value "*".

Request Body schema: application/json

Required. SandboxEngineTemplate resource.

displayName
string

Optional. Human-readable name.

milliCpuRequest
integer <int32>

Optional. MilliCPU units that will be reserved for the SandboxEngine. SandboxEngine may use more CPU resources up to the milli_cpu_limit. It is recommended to set CPU requests to avoid resource contention. 1000 milliCPU = 1 CPU core.

When unset, milli_cpu_request will be set to milli_cpu_limit.

milliCpuLimit
integer <int32>

Optional. Maximum MilliCPU units a SandboxEngine is allowed to use. The SandboxEngine will be throttled to not exceed this limit. It is discouraged to set CPU limits when possible. 1000 milliCPU = 1 CPU core.

gpuResource
string

Optional. Kubernetes GPU resource name. For example: nvidia.com/gpu or amd.com/gpu. When unset, server will choose a default value.

gpu
integer <int32>

Optional. The amount of GPU units requested by this SandboxEngine.

memoryBytesRequest
string <int64>

Optional. Memory in bytes that will be reserved for the SandboxEngine.

When unset, memory_bytes_request will be set to memory_bytes_limit.

memoryBytesLimit
required
string <int64>

Required. Max memory in bytes a SandboxEngine is allowed to use. SandboxEngine may fail or be terminated if it exceeds this limit.

storageBytes
string <int64>

Optional. External ephemeral storage in bytes that will be mounted to the SandboxEngine. When unset, the node disk will be used.

object

Optional. Map of environmental variables that will be set in the SandboxEngine.

yamlPodTemplateSpec
string (Optional. YAML representation of custom PodTemplateSpec serialized into bytes. Definition of PodTemplateSpec: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#podtemplatespec-v1-core)

When specified, then it is applied for SandboxEngine pod. PodTemplateSpec describes what will be applied on top of a regular SandboxEngine pod before it is created. This template is merged using StrategicMergePatch method (it overrides the default SandboxEngine pod). More info about StrategicMergePatch: https://kubernetes.io/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch/

Example YAML value (custom annotation applied on SandboxEngine pod): metadata: annotations: custom-key: custom-value

enabled
boolean

Optional. Whether the SandboxEngineTemplate is enabled. Disabled SandboxEngineTemplates cannot be used for creating new SandboxEngines.

maxIdleDuration
required
string

Required. Maximum time a SandboxEngine can be idle before it is automatically terminated.

Responses

Request samples

Content type
application/json
{
  • "displayName": "string",
  • "milliCpuRequest": 0,
  • "milliCpuLimit": 0,
  • "gpuResource": "string",
  • "gpu": 0,
  • "memoryBytesRequest": "string",
  • "memoryBytesLimit": "string",
  • "storageBytes": "string",
  • "environmentalVariables": {
    },
  • "yamlPodTemplateSpec": "string",
  • "enabled": true,
  • "maxIdleDuration": "string"
}

Response samples

Content type
application/json
{
  • "sandboxEngineTemplate": {
    }
}