Documentation for Kamiwaza 1.0.0

This is documentation for Kamiwaza 1.0.0, which is no longer actively maintained. For the current GA release, see 1.0.1.

Overview

The Cluster Service (ClusterService) provides comprehensive cluster and infrastructure management for the Kamiwaza AI Platform. Located in kamiwaza_sdk/services/cluster.py, this service handles location management, cluster operations, node management, and hardware configuration.

Key Features

• Location Management
• Cluster Operations
• Node Management
• Hardware Configuration
• Runtime Configuration
• Hostname Management

Location Management

Available Methods

• create_location(location: CreateLocation) -> Location: Create new location
• update_location(location_id: UUID, location: UpdateLocation) -> Location: Update location
• get_location(location_id: UUID) -> Location: Get location info
• list_locations() -> List[Location]: List all locations

# Create new location

location = client.cluster.create_location(CreateLocation(

name="us-west",

provider="aws",

region="us-west-2"

))

# Update location

updated = client.cluster.update_location(

location_id=location.id,

location=UpdateLocation(name="us-west-prod")

)

# Get location details

location = client.cluster.get_location(location_id)

# List all locations

locations = client.cluster.list_locations()

Cluster Management

Available Methods

• create_cluster(cluster: CreateCluster) -> Cluster: Create new cluster
• get_cluster(cluster_id: UUID) -> Cluster: Get cluster info
• list_clusters() -> List[Cluster]: List all clusters
• get_hostname() -> str: Get cluster hostname

# Create new cluster

cluster = client.cluster.create_cluster(CreateCluster(

name="training-cluster",

location_id=location_id,

node_count=3

))

# Get cluster info

cluster = client.cluster.get_cluster(cluster_id)

# List clusters

clusters = client.cluster.list_clusters()

# Get hostname

hostname = client.cluster.get_hostname()

Node Management

Available Methods

• get_node_by_id(node_id: UUID) -> Node: Get node info
• get_running_nodes() -> List[Node]: List running nodes
• list_nodes() -> List[Node]: List all nodes

# Get node details

node = client.cluster.get_node_by_id(node_id)

# List running nodes

running_nodes = client.cluster.get_running_nodes()

# List all nodes

all_nodes = client.cluster.list_nodes()

Hardware Management

Available Methods

• create_hardware(hardware: CreateHardware) -> Hardware: Create hardware entry
• get_hardware(hardware_id: UUID) -> Hardware: Get hardware info
• list_hardware() -> List[Hardware]: List hardware entries
• get_runtime_config() -> RuntimeConfig: Get runtime configuration

# Create hardware entry

hardware = client.cluster.create_hardware(CreateHardware(

name="gpu-node",

gpu_count=4,

gpu_type="nvidia-a100"

))

# Get hardware info

hardware = client.cluster.get_hardware(hardware_id)

# List hardware

hardware_list = client.cluster.list_hardware()

# Get runtime config

config = client.cluster.get_runtime_config()

Error Handling

The service includes built-in error handling for common scenarios:

try:

cluster = client.cluster.create_cluster(cluster_config)

except LocationNotFoundError:

print("Location not found")

except ResourceError as e:

print(f"Resource allocation failed: {e}")

except APIError as e:

print(f"Operation failed: {e}")

Best Practices

1. Validate location existence before cluster creation
2. Monitor node health regularly
3. Use appropriate hardware configurations
4. Implement proper error handling
5. Clean up unused resources
6. Consider resource limits
7. Monitor cluster performance
8. Use meaningful naming conventions

Performance Considerations

• Node count affects cluster performance
• Hardware configuration impacts resource availability
• Location selection influences latency
• Runtime configuration affects resource utilization