Foundry Flow SDK Documentation
Flow programmatic SDK and libraries. Pythonic interface to interact with the Foundry API.
Note: the Flow Task SDK and CLI are currently in preview. Please message us in your dedicated Foundry Slack channel to request access, and we will send right away.
Welcome to the Foundry Flow SDK, a Python library designed to streamline the configuration, orchestration, and management of resources on the Foundry Cloud Platform (FCP). This SDK provides:
• Simple authentication to the Foundry API
• Programmatic management of projects, SSH keys, spot-bids, instances, and storage
• High-level, modular, and extensible abstractions to simplify key workflows, such as setting thresholds for spot-instances and managing persistent storage
With the Foundry Flow SDK, you can build robust Python applications that automate complex resource provisioning and lifecycle operations, while maintaining control over user-defined configurations and budgets.
Overview of Core Components
The Foundry Flow SDK comprises multiple pieces that work together to simplify your interactions with the Foundry Cloud Platform. Below is a brief overview of the foundational components.
FoundryClient
FoundryClient is the core interface to the Foundry platform. It handles:
Authentication
User management (e.g., retrieving user info)
Project management (e.g., listing projects and retrieving project IDs)
Instance operations (e.g., retrieving instance details)
Bid submission and management (e.g., placing or canceling bids)
Disk and storage operations (e.g., creating, listing, and deleting disks)
Example:
BidManager
BidManager offers higher-level functionality on top of FoundryClient for:
Preparing bid payloads with prepare_bid_payload()
Submitting bids with submit_bid()
Listing and canceling existing bids
This abstraction lets you more simply define and execute spot bids in Foundry.
InstanceManager
InstanceManager manages instances created from successful bids. Key features include:
Retrieving a list of instances in a particular project
Filtering instances by name, status, or other criteria
StorageManager
StorageManager simplifies managing ephemeral or persistent storage for your Foundry tasks:
Creating new disks
Retrieving existing disks
Attaching or detaching persistent storage to your instances
AuctionFinder
AuctionFinder helps retrieve auctions that match specific resource requirements (e.g., GPU type).
It can:
Fetch available auctions for a project
Filter them based on user-defined specifications (e.g., number of GPUs, GPU type)
FlowTaskManager
The FlowTaskManager is the centerpiece for orchestrating a higher-level Flow “task.”
It coordinates parsing user configurations, preparing startup scripts (including optional compression when scripts get large), and submitting a spot bid to provision an instance. Specifically, it:
Parses task configurations (e.g., from a ConfigParser) that might include resource specs, ephemeral/persistent storage needs, ports configs, etc.
Builds a combined startup script:
Injects ephemeral storage configuration
Adds persistent storage attachments
Sets up port forwards (optional)
Incorporates user-provided scripts
Authenticates the user and retrieves relevant Foundry project, user, and SSH key IDs.
Finds matching auctions (using AuctionFinder) that meet the user’s resource specs.
Creates a final bid payload (via BidManager) and submits it to Foundry.
Using the FlowTaskManager abstracts away a large portion of the boilerplate. Under the hood, it calls multiple managers (BidManager, StorageManager, etc.) so you don’t have to.
Key Methods in FlowTaskManager
run()
The entry point that encapsulates the entire flow: parse configs, build scripts, find auctions, prepare and submit bids, and handle success notifications.
cancel_bid(name)
Cancels a submitted bid by name. After authenticating and looking up the project ID, it retrieves a list of bids and cancels the matching one.
check_status(task_name=None, show_all=False)
Retrieves the status of bids and instances, optionally filtered by the provided task_name. If show_all is True, it includes incomplete or partial data as well.
Getting Started
Installation
Authentication
All interactions with the Foundry Cloud Platform require authentication. You can authenticate by creating a FoundryClient instance with your credentials:
Usage Examples
4.1 Submitting a Bid with FlowTaskManager
Below is a minimal example of using the FlowTaskManager to parse a configuration, build the startup script, and place a spot bid.
4.2 Managing Disks with StorageManager
Below is an example of how you can create and delete a disk programmatically:
Filtering Instances with InstanceManager
Advanced Topics
Handling Large Ephemeral/Persistent Storage
FlowTaskManager and StorageManager can handle ephemeral storage for short-lived tasks or persistent storage for tasks that require data to persist across restarts. Both ephemeral and persistent storage sections can be injected into your final startup script automatically, making it easy to spin up tasks with pre-formatted storage volumes.
Conclusion
The Foundry Flow SDK is a modular and extensible toolkit for developers looking to automate provisioning, bidding, instance lifecycle management, and storage operations on the Foundry Cloud Platform. By leveraging convenient abstractions like FlowTaskManager, you can drastically reduce boilerplate code and speed up your development.
Feel free to explore and/or extend each undergirding manager (like BidManager, StorageManager, etc.) to fit your application’s unique workflow. As this SDK evolves, we aim to provide even more utility and deeper integrations with FCPs platform offerings.
Happy coding!
Need Help?
For feedback, suggestions, or issues, please open a discussion or file a ticket on our GitHub repository
Appendix of SDK Snippets
FoundryClient
The FoundryClient
is a high-level client that encapsulates interactions with the Foundry Cloud Platform (FCP) compute and storage services. It handles authentication and provides methods to manage users, projects, instances, bids, and storage resources.
Methods
User and Project Management
get_user()
Retrieves authenticated user information.
get_projects()
Retrieves all projects associated with the authenticated user.
get_project_by_name(project_name)
Retrieves a project_id by its name.
Instance Management
get_instances(project_id)
Retrieves instances associated with a project.
Auction and Bid Management
get_auctions(project_id)
Retrieves available auctions for the specified project.
get_bids(project_id)
Retrieves all bids for the specified project.
place_bid(project_id, bid_payload)
Places a bid on an auction.
Parameters:
project_id
: The unique identifier of the project.bid_payload
: Dictionary containing bid details including price, instance specifications, etc.
cancel_bid(project_id, bid_id)
Cancels a bid.
SSH Keys Management
get_ssh_keys(project_id)
Retrieves SSH keys for the specified project.
Storage Management
create_disk(project_id, disk_attachment)
Creates a new disk in the specified project.
Parameters:
disk_attachment
: An instance ofDiskAttachment
containing disk details.
get_disks(project_id)
Retrieves existing disks for the specified project.
delete_disk(project_id, disk_id)
Deletes a disk from the specified project.
get_storage_quota(project_id)
Retrieves storage quota information for the specified project.
get_regions()
Retrieves the list of available regions.
Managers
Managers provide higher-level abstractions over the FoundryClient
methods, offering convenient interfaces for common tasks.
BidManager
The BidManager
handles bid preparation and submission.
prepare_bid_payload(**kwargs)
Prepares and validates the bid payload.
Parameters:
cluster_id
: The ID of the cluster.instance_quantity
: The number of instances.instance_type_id
: The type ID of the instance.limit_price_cents
: The limit price in cents.order_name
: The name of the bid.project_id
: The ID of the project.ssh_key_id
: The SSH key ID.user_id
: The user ID.startup_script
: Optional startup script.disk_attachments
: Optional list ofDiskAttachment
instances.
submit_bid(project_id, bid_payload)
Submits a bid using the
FoundryClient
.get_bids(project_id)
Retrieves all bids for the specified project.
cancel_bid(project_id, bid_id)
Cancels a bid based on the bid ID.
InstanceManager
The InstanceManager
handles retrieval and filtering of instances.
get_instances(project_id)
Retrieves all instances for the specified project.
filter_instances(instances, name=None, status=None)
Filters instances based on name and status.
StorageManager
The StorageManager
manages storage creation and attachment.
handle_persistent_storage(project_id, persistent_storage)
Handles creating or attaching storage as per the configuration.
Parameters:
persistent_storage
: An instance ofPersistentStorage
containing storage configuration.
get_default_region_id()
Retrieves the default region ID.
AuctionFinder
The AuctionFinder
provides methods to find auctions matching specified criteria.
fetch_auctions(project_id)
Fetches auctions for a given project ID.
find_matching_auctions(auctions, criteria)
Finds auctions matching the specified criteria.
Parameters:
auctions
: A list ofAuction
instances to search.criteria
: An instance ofResourcesSpecification
containing matching criteria.
Usage Examples
Managing Disks with StorageManager
Here's how you can create a disk, retrieve it, and then delete it using the StorageManager
and FoundryClient
.
Submitting Bids with BidManager
This example demonstrates how to prepare and submit a bid using the BidManager
.
Last updated