runai-bgu bash Manual

Introduction

runai-bgu bash is a command-line interface (CLI) for connecting to running workspace workloads on the BGU HPC cluster via an interactive bash shell. This command allows you to access your running workspaces directly for debugging, monitoring, or interactive development. The command automatically detects the workspace type and establishes a direct connection to the specified pod and container.

This manual explains how to use runai-bgu bash to connect to your workspace environments.

Quick Start

To connect to a running workspace, use:

$ runai-bgu bash my-workspace

Connects to the specified workspace in your default project.

Basic Usage

Connect to Workspace

Connect to the main container of a workspace:

$ runai-bgu bash research-workspace

Establishes an interactive bash session with the workspace named research-workspace.

Connect in Specific Project

Connect to a workspace in a specific project:

$ runai-bgu bash dev-workspace -p my-research-project

Connects to the workspace dev-workspace in the specified project my-research-project.

Interactive Session with Full Terminal

Get a complete terminal experience with TTY and stdin:

$ runai-bgu bash my-workspace --stdin --tty

Provides full interactive capabilities including terminal input and proper display formatting.

Advanced Options

Container and Pod Selection

Specific Container

Connect to a specific container within the workspace:

$ runai-bgu bash my-workspace --container workspace-container

Useful when your workspace has multiple containers and you need access to a specific one.

Specific Pod

Connect to a specific pod in multi-pod workspaces:

$ runai-bgu bash my-workspace --pod my-workspace-worker-1

Targets a particular pod when your workspace spans multiple pods.

Timeout Configuration

Pod Running Timeout

Set timeout for waiting for pod to be in running state:

$ runai-bgu bash my-workspace --pod-running-timeout=2m

Waits up to 2 minutes for the pod to reach running status.

Wait Timeout

Set overall timeout for connection establishment:

$ runai-bgu bash my-workspace --wait-timeout=5m

Waits up to 5 minutes for the workspace to be ready for connection.

Common Use Cases

Development and Debugging

Access your development environment for interactive work:

$ runai-bgu bash dev-env --stdin --tty

File Management

Connect to manage files within your workspace:

$ runai-bgu bash data-processing-workspace

Process Monitoring

Check running processes and system status:

$ runai-bgu bash monitoring-workspace --tty

Multi-Container Debugging

Debug specific components in complex workspaces:

$ runai-bgu bash complex-workspace --container worker-container

Prerequisites for Connection

Before connecting to a workspace, ensure:

Running Status: The workspace must be in "Running" status. Use runai-bgu list or runai-bgu describe to check status.
Project Access: You must have appropriate permissions in the project containing the workspace.
Network Connectivity: Ensure network connectivity to the cluster from your client machine.
Valid Session: Your authentication session must be active. Use runai-bgu login if needed.

Understanding Connection Behavior

When you connect to a workspace:

Shell Environment: You get a bash shell with the same environment as your workspace container.
File System Access: Full access to the workspace file system including mounted volumes.
Process Visibility: Can see and interact with processes running in the container.
Resource Sharing: Share CPU, memory, and other resources with existing workspace processes.

Troubleshooting Connection Issues

Workspace Not Found

Check if the workspace exists and is running:

$ runai-bgu list
$ runai-bgu describe my-workspace

Connection Timeout

Increase timeout values for slow-starting workspaces:

$ runai-bgu bash my-workspace --wait-timeout=10m --pod-running-timeout=5m

Multiple Containers

Specify the target container when connection fails:

$ runai-bgu bash my-workspace --container main-container

Permission Issues

Verify project access and workspace ownership:

$ runai-bgu projects
$ runai-bgu describe my-workspace

Best Practices

Save Work Regularly: Always save your work as the connection may be terminated if the workspace stops.
Monitor Resources: Be aware of resource usage to avoid impacting workspace performance.
Clean Exit: Use exit command to cleanly terminate the bash session.
Session Management: Keep track of active sessions to avoid resource conflicts.