Skip to main content

Prerequisites and Build Validation

[!NOTE] This guide expands on the Prerequisites section of the main contributing guide.

Tools, Azure access, and build validation requirements for contributing to the Physical AI Toolchain.

Required Tools​

Install these tools before contributing:

ToolMinimum VersionInstallation
Terraform1.9.8https://developer.hashicorp.com/terraform/install
TFLint0.61.0https://github.com/terraform-linters/tflint
Azure CLI2.65.0https://learn.microsoft.com/cli/azure/install-azure-cli
kubectl1.31https://kubernetes.io/docs/tasks/tools/
Helm3.16https://helm.sh/docs/intro/install/
Node.js/npm20+ LTShttps://nodejs.org/
Python3.11+https://www.python.org/downloads/
shellcheck0.10+https://www.shellcheck.net/
uvlatesthttps://docs.astral.sh/uv/
Go1.24+https://go.dev/dl/
golangci-lint2.11+https://golangci-lint.run/welcome/install/
Dockerlatesthttps://docs.docker.com/get-docker/ (with NVIDIA Container Toolkit)
OSMO CLIlatesthttps://developer.nvidia.com/osmo
terraform-docs0.21.0https://github.com/terraform-docs/terraform-docs/releases
hve-corelatesthttps://github.com/microsoft/hve-core

Azure Access Requirements​

Deploying this architecture requires Azure subscription access with specific permissions and quotas:

Subscription Roles​

  • Contributor role for resource group creation and management
  • User Access Administrator role for managed identity assignment

GPU Quota​

  • Request GPU VM quota in your target region before deployment
  • Architecture uses Standard_NC24ads_A100_v4 (24 vCPU, 220 GB RAM, 1x A100 80GB GPU)
  • Check quota: az vm list-usage --location <region> --query "[?name.value=='standardNCadsA100v4Family']"
  • Request increase through Azure Portal → Quotas → Compute

Regional Availability​

NVIDIA NGC Account​

Training workflows use NVIDIA GPU Operator and Isaac Lab, which require NGC credentials:

  • Create account: https://ngc.nvidia.com/signup
  • Generate API key: NGC Console → Account Settings → Generate API Key
  • Store API key in Azure Key Vault or Kubernetes secret (deployment scripts provide guidance)

Cost Awareness​

Full deployment validation incurs Azure costs. Understand cost structure before deploying:

GPU Virtual Machines​

  • Standard_NC24ads_A100_v4: ~$3.06/hour per VM (pay-as-you-go)
  • 8-hour validation session: ~$25
  • 40-hour work week: ~$125

Managed Services​

  • AKS control plane: $0.10/hour ($73/month)
  • Log Analytics workspace: ~$2.76/GB ingested
  • Storage accounts: ~$0.02/GB (block blob, hot tier)
  • Azure Container Registry: Basic tier ~$5/month

Cost Optimization​

  • Use terraform destroy immediately after validation
  • Automate cleanup with -auto-approve flag
  • Monitor costs: Azure Portal → Cost Management + Billing
  • Set budget alerts to prevent overruns

Estimated Costs​

  • Quick validation (deploy + verify + destroy): ~$25-50
  • Extended development session (8 hours): ~$50-100
  • Monthly development (40 hours): ~$200-300

Build and Validation Requirements​

Tool Version Verification​

Verify tool versions before validating:

# Terraform
terraform version  # >= 1.9.8

# TFLint (Terraform linter)
tflint --version  # >= 0.61.0

# Azure CLI
az version  # >= 2.65.0

# kubectl
kubectl version --client  # >= 1.31

# Helm
helm version  # >= 3.16

# Node.js (for documentation linting)
node --version  # >= 20

# Python (for training scripts)
python --version  # >= 3.11

# shellcheck (for shell script validation)
shellcheck --version  # >= 0.10

# uv (Python package manager)
uv --version

# Go
go version  # >= 1.24

# golangci-lint
golangci-lint version  # >= 2.11

# Docker with NVIDIA Container Toolkit
docker --version
nvidia-ctk --version

# OSMO CLI
osmo --version

# terraform-docs
terraform-docs --version  # >= 0.21.0

# hve-core (VS Code extension — verify via extensions list)
code --list-extensions | grep -i hve-core

Validation Commands​

Run these commands before committing:

Terraform:

# Format check (required)
terraform fmt -check -recursive infrastructure/terraform/

# Initialize and validate (required for infrastructure changes)
cd infrastructure/terraform/
terraform init
terraform validate

# Lint Terraform configurations (required for infrastructure changes)
tflint --recursive infrastructure/terraform/

Shell Scripts:

# Lint all shell scripts (required)
shellcheck deploy/**/*.sh scripts/**/*.sh

Go:

# Lint Go modules (required for Go changes)
npm run lint:go

# Test Go modules (required for Go changes)
npm run test:go

Documentation:

# Install dependencies (first time only)
npm install

# Lint markdown (required for documentation changes)
npm run lint:md

VS Code Configuration​

The workspace is configured with python.analysis.extraPaths pointing to src/, enabling imports like:

from training.utils import AzureMLContext, bootstrap_azure_ml

Select the .venv/bin/python interpreter in VS Code for IntelliSense support.

The workspace .vscode/settings.json also configures Copilot Chat to load instructions, prompts, and chat modes from hve-core:

Settinghve-core Paths
chat.modeFilesLocations../hve-core/.github/chatmodes, ../hve-core/copilot/beads/chatmodes
chat.instructionsFilesLocations../hve-core/.github/instructions, ../hve-core/copilot/beads/instructions
chat.promptFilesLocations../hve-core/.github/prompts, ../hve-core/copilot/beads/prompts

These paths resolve when hve-core is installed as a peer directory or via the VS Code Extension. Without hve-core, Copilot still functions but shared conventions, prompts, and chat modes are unavailable.

For a complete list of available agents, prompts, and skills, see Copilot Artifacts.