Notebook Engine Examples
This guide demonstrates how to use the Notebook Engine client with practical examples covering common operations.
See the module documentation for full client reference.
Starting a Notebook engine
The simplest way to create a Notebook engine is using default configuration:
import h2o_engine_manager
from h2o_engine_manager.clients.notebook_engine.engine import NotebookEngine
# Initialize clients.
aiem = h2o_engine_manager.login()
notebook_engine_client = aiem.notebook_engine_client
notebook_engine_profile_client = aiem.notebook_engine_profile_client
notebook_engine_image_client = aiem.notebook_engine_image_client
# You can list available profiles.
profiles = notebook_engine_profile_client.list_all_assigned_notebook_engine_profiles(parent="workspaces/global")
print("Profiles:")
for profile in profiles:
print("\t", profile.name)
# You can list available images.
images = notebook_engine_image_client.list_all_notebook_engine_images(parent="workspaces/global")
print("Images:")
for image in images:
print("\t", image.name)
# Create Notebook engine with required parameters.
# This call returns immediately, and does not wait for the engine to be ready.
eng = notebook_engine_client.create_notebook_engine(
parent="workspaces/default", # You can use alias 'default' for your personal workspace.
notebook_engine=NotebookEngine(
profile="workspaces/global/notebookEngineProfiles/default", # One of the listed profiles.
notebook_image="workspaces/global/notebookEngineImages/default", # One of the listed images.
display_name="My Basic Notebook engine",
),
notebook_engine_id="my-engine"
)
# Wait until the engine is ready.
# This call blocks until the engine is ready.
# It may take a few minutes.
notebook_engine_client.wait(name=eng.name)
# You can access the running Notebook engine in browser via the access URI.
print("Notebook engine access URI: ", notebook_engine_client.access_notebook_engine(name=eng.name))
Advanced Notebook engine
For more control, you can specify custom configuration parameters including CPU, GPU, memory, storage, and timeouts:
import h2o_engine_manager
from h2o_engine_manager.clients.notebook_engine.engine import NotebookEngine
# Initialize clients.
aiem = h2o_engine_manager.login()
notebook_engine_client = aiem.notebook_engine_client
# Create Notebook engine with customized parameters (cpu, gpu, memory, storage, ...).
# This call returns immediately, and does not wait for the engine to be ready.
eng = notebook_engine_client.create_notebook_engine(
parent="workspaces/default", # You can use alias 'default' for your personal workspace.
notebook_engine=NotebookEngine(
profile="workspaces/global/notebookEngineProfiles/default", # One of the listed profiles.
notebook_image="workspaces/global/notebookEngineImages/default", # One of the listed images.
display_name="My Advanced Notebook engine",
cpu=4,
gpu=1,
memory_bytes="2Gi",
storage_bytes="4Gi",
max_idle_duration="2h",
max_running_duration="2h",
),
notebook_engine_id="my-engine",
)
# This call blocks until the engine is ready.
# It may take a few minutes.
notebook_engine_client.wait(name=eng.name)
Fetching a Notebook engine
Retrieve an existing engine by its resource name:
import h2o_engine_manager
notebook_engine_client = h2o_engine_manager.login().notebook_engine_client
engine = notebook_engine_client.get_notebook_engine(name="workspaces/default/notebookEngines/my-engine")
print(engine)
Listing Notebook engines
The list_notebook_engines method supports pagination. The following examples demonstrate basic usage:
import h2o_engine_manager
notebook_engine_client = h2o_engine_manager.login().notebook_engine_client
# By default, engines are ordered by their time of creation in descending order
# and limited to 50 items per page.
page1 = notebook_engine_client.list_notebook_engines(parent="workspaces/default")
# To list a second page, pass the next_page_token from the previous page.
# This example increases the page size to 100.
page2 = notebook_engine_client.list_notebook_engines(
parent="workspaces/default",
page_size=100,
page_token=page1.next_page_token
)
# You can use a convenience function for listing all notebook engines from a specified workspace.
all_engines = notebook_engine_client.list_all_notebook_engines(parent="workspaces/default")
A convenience function list_all_notebook_engines is provided that pages through all engines and returns a complete list.
Although it is strongly recommended to use pagination, this function is useful for quick prototyping.
Pausing a Notebook engine
You should pause your engines when you are not using them to save costs. Pausing terminates all running jobs but all other state is persisted.
import h2o_engine_manager
notebook_engine_client = h2o_engine_manager.login().notebook_engine_client
# Pause the engine.
# This returns immediately and does not wait for the engine to be paused.
notebook_engine_client.pause_notebook_engine(name="workspaces/default/notebookEngines/my-engine")
# You may wait for the engine to get into PAUSED state.
# This is a blocking call.
notebook_engine_client.wait(name="workspaces/default/notebookEngines/my-engine")
An engine can be automatically paused after exceeding the max_idle_duration or max_running_duration.
Resuming a Notebook engine
A paused engine can be resumed to continue using it:
import h2o_engine_manager
notebook_engine_client = h2o_engine_manager.login().notebook_engine_client
# Resume a paused engine.
# This returns immediately and does not wait for the engine to be ready.
notebook_engine_client.resume_notebook_engine(name="workspaces/default/notebookEngines/my-engine")
# You may wait for the engine to get into RUNNING state.
# This call blocks until the engine is ready.
# It may take a few minutes.
notebook_engine_client.wait(name="workspaces/default/notebookEngines/my-engine")
# You can access the again-running Notebook engine in browser via the access URI.
access_uri = notebook_engine_client.access_notebook_engine(name="workspaces/default/notebookEngines/my-engine")
print("Notebook engine access URI: ", access_uri)
Updating a Notebook engine
You can modify an existing engine with the update_notebook_engine method. The engine must be paused before updating.
import h2o_engine_manager
notebook_engine_client = h2o_engine_manager.login().notebook_engine_client
# Get the engine first.
engine = notebook_engine_client.get_notebook_engine(name="workspaces/default/notebookEngines/my-engine")
# Change selected engine fields to new values.
engine.cpu = 2
engine.memory_bytes = "16Gi"
engine.max_idle_duration = "3600s"
# Perform the update.
notebook_engine_client.update_notebook_engine(notebook_engine=engine)
Resizing engine storage
You can increase the storage size of an engine. The engine must be paused before resizing storage.
import h2o_engine_manager
notebook_engine_client = h2o_engine_manager.login().notebook_engine_client
# Resize storage to 100Gi.
notebook_engine_client.resize_notebook_engine_storage(
name="workspaces/default/notebookEngines/my-engine",
new_storage="100Gi"
)
Deleting a Notebook engine
Engine deletion is a destructive operation that immediately terminates the engine and deletes all data contained within. It cannot be undone.
import h2o_engine_manager
notebook_engine_client = h2o_engine_manager.login().notebook_engine_client
# Delete engine.
# This returns immediately and does not wait for the engine to be deleted.
notebook_engine_client.delete_notebook_engine(name="workspaces/default/notebookEngines/my-engine")
# You may wait for the engine to finish deleting.
notebook_engine_client.wait(name="workspaces/default/notebookEngines/my-engine")
Eventual consistency
The API is eventually consistent, meaning that when reading immediately after a write operation, the read may not reflect the written changes immediately. This client is designed to eliminate the hurdles of eventual consistency if used correctly. Always use the object returned by write operations.
notebook_engine_client.create_notebook_engine(...)
engine = notebook_engine_client.get_notebook_engine(...)
engine = notebook_engine_client.create_notebook_engine(...)
Example notebook
You can find a Jupyter notebook with examples here.
- Submit and view feedback for this page
- Send feedback about AI Engine Manager to cloud-feedback@h2o.ai