GitHub Repository: ibm/watson-machine-learning-samples
Path: blob/master/cpd5.2/notebooks/python_sdk/instance-management/Space management.ipynb
⁶⁴⁰² views

Kernel: watsonx-ai-samples-py-312

Space management

This notebook contains steps and code to demonstrate how to manage spaces in context of Watson Machine Learning service. It facilitates ibm-watsonx-ai library available in PyPI repository. It introduces commands for creating, updating & deleting spaces, getting list and detailed information about them.

Some familiarity with Python is helpful. This notebook uses Python 3.12.

Learning goals

The learning goals of this notebook are:

Create new space
List existing spaces
Get spaces details
Set default space
Update exisitng space
Delete space

This notebook contains the following parts:

1. Set up the environment

Before you use the sample code in this notebook, you must perform the following setup tasks:

Contact with your Cloud Pak for Data administrator and ask them for your account credentials

Install dependencies

Note: ibm-watsonx-ai documentation can be found here.

In [1]:

%pip install -U ibm-watsonx-ai | tail -n 1

Out[1]:

Successfully installed anyio-4.9.0 certifi-2025.4.26 charset-normalizer-3.4.2 h11-0.16.0 httpcore-1.0.9 httpx-0.28.1 ibm-cos-sdk-2.14.1 ibm-cos-sdk-core-2.14.1 ibm-cos-sdk-s3transfer-2.14.1 ibm-watsonx-ai-1.3.20 idna-3.10 jmespath-1.0.1 lomond-0.3.3 numpy-2.2.6 pandas-2.2.3 pytz-2025.2 requests-2.32.2 sniffio-1.3.1 tabulate-0.9.0 typing_extensions-4.13.2 tzdata-2025.2 urllib3-2.4.0

Define credentials

Authenticate the watsonx.ai Runtime service on IBM Cloud Pak for Data. You need to provide the admin's username and the platform url.

In [2]:

username = "PASTE YOUR USERNAME HERE"
url = "PASTE THE PLATFORM URL HERE"

Use the admin's api_key to authenticate watsonx.ai Runtime services:

In [ ]:

import getpass
from ibm_watsonx_ai import Credentials

credentials = Credentials(
    username=username,
    api_key=getpass.getpass("Enter your watsonx.ai API key and hit enter: "),
    url=url,
    instance_id="openshift",
    version="5.2",
)

Alternatively you can use the admin's password:

In [3]:

import getpass
from ibm_watsonx_ai import Credentials

if "credentials" not in locals() or not credentials.api_key:
    credentials = Credentials(
        username=username,
        password=getpass.getpass("Enter your watsonx.ai password and hit enter: "),
        url=url,
        instance_id="openshift",
        version="5.2",
    )

Create `APIClient` instance

In [4]:

from ibm_watsonx_ai import APIClient

client = APIClient(credentials)

2. Create new space

Define space metadata

In [5]:

space_metadata = {
    "name": "PASTE YOUR SPACE NAME HERE",
    "description": "PASTE YOUR SPACE DESCRIPTION HERE",
}

Next you can create space by following cell execution

In [6]:

space_details = client.spaces.store(space_metadata)
print(space_details)

Out[6]:

Space has been created. However some background setup activities might still be on-going. Check for 'status' field in the response. It has to show 'active' before space can be used. If it's not 'active', you can monitor the state with a call to spaces.get_details(space_id). Alternatively, use background_mode=False when calling client.spaces.store().
{'entity': {'compute': [{'crn': 'crn:v1:cpd:private:pm-20:private:a/cpduser:99999999-9999-9999-9999-999999999999::', 'guid': '99999999-9999-9999-9999-999999999999', 'name': 'Watson Machine Learning', 'type': 'machine_learning'}], 'description': 'This space has been created to showcase support for space management', 'members': [{'id': '1000331001', 'role': 'admin', 'state': 'active', 'type': 'user'}], 'name': 'Space management sample space', 'scope': {'bss_account_id': 'cpdaccount'}, 'settings': {'folders': {'enabled': False}}, 'stage': {'production': False}, 'status': {'state': 'preparing'}, 'type': 'cpd'}, 'metadata': {'created_at': '2025-05-21T06:29:55.114Z', 'creator_id': '1000331001', 'id': '82e4033b-0f21-460f-855c-ef10f5f7b355', 'url': '/v2/spaces/82e4033b-0f21-460f-855c-ef10f5f7b355'}}

You can get space it by executing following cell

In [7]:

space_id = client.spaces.get_id(space_details)
print(space_id)

Out[7]:

82e4033b-0f21-460f-855c-ef10f5f7b355

Tip: In order to check if the space creation is completed succesfully change next cell format to code and execute it. It should return 'active'

In [8]:

client.spaces.get_details(space_id)["entity"]["status"]["state"]

Out[8]:

'active'

Action: If you didn't create new space in this notebook by ibm_watsonx_ai, please assign space ID below.

In [ ]:

if "space_id" not in locals():
    space_id = "PASTE YOUR SPACE ID HERE"

3. List all existing spaces

You can use list method to print all existing spaces.

In [9]:

client.spaces.list()

Out[9]:

4. Get details about space

You can use get_details method to print details about given space. You need to provide space_id of desired space.

In [10]:

client.spaces.get_details(space_id)

Out[10]:

{'entity': {'compute': [{'crn': 'crn:v1:cpd:private:pm-20:private:a/cpduser:99999999-9999-9999-9999-999999999999::',
    'guid': '99999999-9999-9999-9999-999999999999',
    'name': 'Watson Machine Learning',
    'type': 'machine_learning'}],
  'description': 'This space has been created to showcase support for space management',
  'name': 'Space management sample space',
  'scope': {'bss_account_id': 'cpdaccount'},
  'settings': {'folders': {'enabled': False}},
  'stage': {'production': False},
  'status': {'state': 'active'},
  'type': 'cpd'},
 'metadata': {'created_at': '2025-05-21T06:29:55.114Z',
  'creator_id': '1000331001',
  'id': '82e4033b-0f21-460f-855c-ef10f5f7b355',
  'updated_at': '2025-05-21T06:29:55.988Z',
  'url': '/v2/spaces/82e4033b-0f21-460f-855c-ef10f5f7b355'}}

5. Set default space

To be able to interact with all resources available in Watson Machine Learning, you need to set space which you will be using.

In [11]:

client.set.default_space(space_id)

Out[11]:

'SUCCESS'

6. Update space metadata

You can update your space by reassigning space metadata and executing: client.spaces.update(space_id, space_metadata).

In [12]:

updated_space_metadata = {
    client.spaces.ConfigurationMetaNames.NAME: "Updated space name"
}

client.spaces.update(space_id, updated_space_metadata)

Out[12]:

{'entity': {'compute': [{'crn': 'crn:v1:cpd:private:pm-20:private:a/cpduser:99999999-9999-9999-9999-999999999999::',
    'guid': '99999999-9999-9999-9999-999999999999',
    'name': 'Watson Machine Learning',
    'type': 'machine_learning'}],
  'description': 'This space has been created to showcase support for space management',
  'members': [{'id': '1000331001',
    'role': 'admin',
    'state': 'active',
    'type': 'user'}],
  'name': 'Updated space name',
  'scope': {'bss_account_id': 'cpdaccount'},
  'settings': {'folders': {'enabled': False}},
  'stage': {'production': False},
  'status': {'state': 'active'},
  'type': 'cpd'},
 'metadata': {'created_at': '2025-05-21T06:29:55.114Z',
  'creator_id': '1000331001',
  'id': '82e4033b-0f21-460f-855c-ef10f5f7b355',
  'updated_at': '2025-05-21T06:30:37.356Z',
  'url': '/v2/spaces/82e4033b-0f21-460f-855c-ef10f5f7b355'}}

7. Delete existing space

You can use the command below to delete existing space. You need to provide space_id of the space you want to delete.

In [13]:

client.spaces.delete(space_id)

Out[13]:

DELETED

'SUCCESS'

8. Summary and next steps

You successfully completed this notebook! You learned how to use ibm-watsonx-ai client for Watson Machine Learning instance space management and clean up.

Check out our Online Documentation for more samples, tutorials, documentation, how-tos, and blog posts.

Authors

Szymon Kucharczyk, Software Engineer at IBM.

Daniel Ryszka, Software Engineer at IBM.

Space management

Learning goals

Contents

1. Set up the environment

Install dependencies

Define credentials

Create `APIClient` instance

2. Create new space

3. List all existing spaces

4. Get details about space

5. Set default space

6. Update space metadata

7. Delete existing space

8. Summary and next steps

Authors

Product

Resources

Company

Space management

Learning goals

Contents

1. Set up the environment

Install dependencies

Define credentials

Create APIClient instance

2. Create new space

3. List all existing spaces

4. Get details about space

5. Set default space

6. Update space metadata

7. Delete existing space

8. Summary and next steps

Authors

Create `APIClient` instance