Skip to content

quickstart.md

Latest commit

 

History

History
254 lines (182 loc) · 8.53 KB

quickstart.md

File metadata and controls

254 lines (182 loc) · 8.53 KB
Raw
sidebar_position 2
title Quickstart: Clone to First Training Job
description Deploy infrastructure and submit your first robotics training job in 9 steps
author Microsoft Robotics-AI Team
ms.date 2026-09-11
ms.topic tutorial
keywords
quickstart
deployment
training
tutorial

Quick Start

The default starting path is local, not cloud. On T0 — Dev you close the full capture → train → validate → run loop on one laptop and one robot with zero cloud and no required Kubernetes, using ./setup-dev.sh and the Tier 0 — Dev recipe. A single-laptop Kubernetes cluster is an optional local orchestration profile. Start there; come back here when you graduate.

This guide is the cloud path (T2 — Pilot): deploy the Azure + NVIDIA stack and submit a cloud training job in ~1.5-2 hours, using full-public networking and Access Keys authentication for the simplest path. Adopt it when training scale, team collaboration, or a shared model registry outgrows the laptop.

Note

This guide expands on the Getting Started hub. To pick the right tier and see the graduation triggers, see Choose Your Tier. For the per-tier infrastructure boundaries see the Architecture Overview and the canonical Tier Model.

Prerequisites

Requirement Details
Azure subscription Contributor + User Access Administrator roles
GPU quota Standard_NV36ads_A10_v5 (A10 Spot, default) or Standard_NC40ads_H100_v5 (H100) in target region
NVIDIA NGC account Sign up at https://ngc.nvidia.com/ for API key
Development environment Devcontainer (recommended) or local tools

See Prerequisites for installation commands and version requirements. NVIDIA ARM64 hosts in CSV mode also require the dev container GPU runtime setup.

Step 1: Clone and Set Up Environment

Clone the repository and initialize the development environment.

git clone https://github.com/microsoft/physical-ai-toolchain.git
cd physical-ai-toolchain

Use the devcontainer (recommended) or run local setup:

./setup-dev.sh

Step 2: Configure Azure Subscription

Authenticate with Azure and register required resource providers.

source infrastructure/terraform/prerequisites/az-sub-init.sh
bash infrastructure/terraform/prerequisites/register-azure-providers.sh

Verify your subscription:

az account show --query "{name:name, id:id}" -o table

Step 3: Configure Terraform Variables

Create a Terraform variables file for the full-public deployment path. From the repository root:

cd infrastructure/terraform
cp terraform.tfvars.example terraform.tfvars

Edit terraform.tfvars with your values:

environment     = "dev"
location        = "westus3"
resource_prefix = "yourprefix"
instance        = "001"

// Full-public networking (simplest path for inner developer loop)
should_enable_private_endpoint      = false
should_enable_private_aks_cluster   = false
should_enable_public_network_access = true

// Single GPU pool (Spot A10)
node_pools = {
  gpu = {
    vm_size                    = "Standard_NV36ads_A10_v5"
    subnet_address_prefixes    = ["10.0.7.0/24"]
    node_taints                = ["nvidia.com/gpu:NoSchedule", "kubernetes.azure.com/scalesetpriority=spot:NoSchedule"]
    gpu_driver                 = "Install"
    priority                   = "Spot"
    should_enable_auto_scaling = true
    min_count                  = 1
    max_count                  = 1
    zones                      = []
    eviction_policy            = "Delete"
  }
}

// System node pool — enable autoscaling for OSMO workloads
should_enable_system_node_pool_auto_scaling = true
system_node_pool_min_count                  = 1
system_node_pool_max_count                  = 3

// OSMO Backend Services
should_deploy_postgresql = true
should_deploy_redis      = true

Warning

resource_prefix must be lowercase, alphanumeric, and short (6-8 characters recommended). It feeds into Key Vault (kv{prefix}{env}{instance}) and Storage Account names that have 24-character limits and must be globally unique.

Tip

For private networking, set should_enable_private_endpoint = true and should_enable_private_aks_cluster = true, then deploy the VPN from infrastructure/terraform/vpn/ before running any kubectl commands. See the Infrastructure Guide for details.

Step 4: Deploy Infrastructure

Initialize and apply the Terraform configuration. This step takes ~30-40 minutes.

terraform init
terraform plan -out=tfplan
terraform apply tfplan

Verify deployment:

terraform output

Connect to the AKS cluster:

az aks get-credentials \
  --resource-group "$(terraform output -json resource_group | jq -r '.name')" \
  --name "$(terraform output -json aks_cluster | jq -r '.name')"

Step 5: Set NGC API Key

Export your NVIDIA NGC API key for OSMO backend deployment. Obtain a key from https://ngc.nvidia.com/.

export NGC_API_KEY="<your-ngc-api-key>"

Step 6: Configure AKS Cluster

Deploy GPU Operator, KAI Scheduler, and the AzureML extension. From the repository root:

cd infrastructure/setup
bash 01-deploy-robotics-charts.sh --config-preview
bash 01-deploy-robotics-charts.sh
bash 02-deploy-azureml-extension.sh --config-preview
bash 02-deploy-azureml-extension.sh

Tip

All setup scripts support --config-preview to print configuration and exit without changes. Run it before each real deployment to verify values.

Verify GPU operator pods:

kubectl get pods -n gpu-operator

Step 7: Deploy OSMO Components

Deploy the OSMO control plane and backend.

bash 03-deploy-osmo.sh --config-preview
bash 03-deploy-osmo.sh

Verify OSMO pods:

kubectl get pods -n osmo-control-plane
kubectl get pods -n osmo-operator

Step 8: Connect to OSMO

The OSMO CLI requires an authenticated session before submitting workflows. Start a port-forward and login:

kubectl port-forward svc/osmo-gateway 9000:80 -n osmo-control-plane &

osmo login http://localhost:9000 --method=dev --username=admin
osmo profile set pool default
osmo version

See Accessing OSMO for alternative access options (internal load balancer, ingress).

Step 9: Submit First Training Job

Submit a training job from the repository root:

bash training/rl/scripts/submit-osmo-training.sh

Scripts auto-detect configuration from Terraform outputs. Override values with CLI arguments or environment variables as needed. See Scripts Reference for all submission options.

Step 10: Verify Results

Confirm the training job is running:

kubectl get pods -n osmo-workflows --watch

Check OSMO training status through the OSMO web UI or query pod logs:

kubectl logs -n osmo-workflows -l app=osmo-training --tail=50

Cleanup

Remove OSMO Helm releases before destroying infrastructure to avoid orphaned resources:

cd infrastructure/setup
helm uninstall osmo-operator -n osmo-operator --ignore-not-found
helm uninstall service router ui -n osmo-control-plane --ignore-not-found

Destroy all infrastructure when finished to stop incurring costs. From the repository root:

cd infrastructure/terraform
terraform destroy

See Cost Considerations for detailed pricing.

Next Steps

Resource Description
MLflow Integration Track experiments with MLflow
Infrastructure Guide Full deployment reference and options
Contributing Guide Development workflow and code standards