Coverage for cli / commands / capacity_cmd.py: 100.00%

1"""Capacity checking commands.""" 

2 

3import sys 

4from typing import Any 

5 

6import click 

7from botocore.exceptions import ClientError 

8 

9from gco.bedrock import BEDROCK_FTU_REMEDIATION, is_bedrock_ftu_form_error 

10 

11from ..capacity import get_capacity_checker 

12from ..capacity.history import METRIC_FIELDS 

13from ..config import GCOConfig 

14from ..output import confirm, format_capacity_table, get_output_formatter 

15 

16pass_config = click.make_pass_decorator(GCOConfig, ensure=True) 

17 

18 

19@click.group() 

20@pass_config 

21def capacity(config: Any) -> None: 

22 """Check EC2 capacity availability.""" 

23 

24 

25@capacity.command("check") 

26@click.option("--instance-type", "-i", required=True, help="EC2 instance type") 

27@click.option("--region", "-r", required=True, help="AWS region") 

28@click.option( 

29 "--type", 

30 "-t", 

31 "capacity_type", 

32 type=click.Choice(["spot", "on-demand", "both"]), 

33 default="both", 

34 help="Capacity type to check", 

35) 

36@click.option( 

37 "--enrich-historical", 

38 is_flag=True, 

39 help="Append historical capacity context (requires historical.enabled)", 

40) 

41@pass_config 

42def check_capacity( 

43 config: Any, 

44 instance_type: Any, 

45 region: Any, 

46 capacity_type: Any, 

47 enrich_historical: Any, 

48) -> None: 

49 """Check capacity availability for an instance type. 

50 

51 Provides estimates based on spot price history and availability patterns. 

52 """ 

53 formatter = get_output_formatter(config) 

54 checker = get_capacity_checker(config) 

55 

56 try: 

57 estimates = checker.estimate_capacity(instance_type, region, capacity_type) 

58 

59 if config.output_format == "table": 

60 print(format_capacity_table(estimates)) 

61 else: 

62 formatter.print(estimates) 

63 

64 if enrich_historical: 

65 _print_historical_enrichment(formatter, instance_type, region) 

66 

67 except Exception as e: 

68 formatter.print_error(f"Failed to check capacity: {e}") 

69 sys.exit(1) 

70 

71 

72@capacity.command("recommend") 

73@click.option("--instance-type", "-i", required=True, help="EC2 instance type") 

74@click.option("--region", "-r", required=True, help="AWS region") 

75@click.option( 

76 "--fault-tolerance", 

77 "-f", 

78 type=click.Choice(["high", "medium", "low"]), 

79 default="medium", 

80 help="Fault tolerance level", 

81) 

82@pass_config 

83def recommend_capacity(config: Any, instance_type: Any, region: Any, fault_tolerance: Any) -> None: 

84 """Get capacity type recommendation for a workload.""" 

85 formatter = get_output_formatter(config) 

86 checker = get_capacity_checker(config) 

87 

88 try: 

89 capacity_type, explanation = checker.recommend_capacity_type( 

90 instance_type, region, fault_tolerance 

91 ) 

92 

93 if config.output_format == "table": 

94 formatter.print_info(f"Recommended: {capacity_type.upper()}") 

95 formatter.print_info(f"Reason: {explanation}") 

96 else: 

97 formatter.print( 

98 { 

99 "capacity_type": capacity_type, 

100 "explanation": explanation, 

101 } 

102 ) 

103 

104 except Exception as e: 

105 formatter.print_error(f"Failed to get recommendation: {e}") 

106 sys.exit(1) 

107 

108 

109@capacity.command("spot-prices") 

110@click.option("--instance-type", "-i", required=True, help="EC2 instance type") 

111@click.option("--region", "-r", required=True, help="AWS region") 

112@click.option("--days", "-d", default=7, help="Days of history") 

113@pass_config 

114def spot_prices(config: Any, instance_type: Any, region: Any, days: Any) -> None: 

115 """Get spot price history for an instance type.""" 

116 formatter = get_output_formatter(config) 

117 checker = get_capacity_checker(config) 

118 

119 try: 

120 prices = checker.get_spot_price_history(instance_type, region, days) 

121 

122 if not prices: 

123 formatter.print_warning(f"No spot price data for {instance_type} in {region}") 

124 return 

125 

126 formatter.print( 

127 prices, 

128 columns=[ 

129 "availability_zone", 

130 "current_price", 

131 "avg_price_7d", 

132 "min_price_7d", 

133 "max_price_7d", 

134 "price_stability", 

135 ], 

136 ) 

137 

138 except Exception as e: 

139 formatter.print_error(f"Failed to get spot prices: {e}") 

140 sys.exit(1) 

141 

142 

143@capacity.command("instance-info") 

144@click.argument("instance_type") 

145@click.option( 

146 "--region", 

147 "-r", 

148 help="Region to describe the type in (default: the configured default region)", 

149) 

150@pass_config 

151def instance_info(config: Any, instance_type: Any, region: Any) -> None: 

152 """Describe an instance type's compute characteristics. 

153 

154 Resolved live from EC2 DescribeInstanceTypes every time — there is no 

155 checked-in specification table, so a newly launched accelerator family is 

156 reported the day it ships. 

157 

158 Reports vCPUs/cores/threads, memory, every accelerator class (NVIDIA GPU, 

159 AWS Neuron, Inferentia, media, FPGA) with per-model breakdowns, EFA and 

160 network limits, local NVMe and EBS characteristics, placement-group support, 

161 purchase options (spot / capacity-block), and platform capabilities. 

162 

163 DescribeInstanceTypes is region-scoped: a type is only described where it is 

164 offered. If it is missing, try another region or `gco capacity 

165 recommend-region`. 

166 

167 Examples: 

168 gco capacity instance-info p5.48xlarge 

169 gco capacity instance-info trn2.48xlarge -r us-east-1 

170 gco -o json capacity instance-info p5.48xlarge 

171 gco -o json capacity instance-info g5.2xlarge | jq '.gpu_devices' 

172 """ 

173 formatter = get_output_formatter(config) 

174 checker = get_capacity_checker(config) 

175 

176 try: 

177 info = checker.get_instance_info(instance_type, region=region) 

178 if not info: 

179 target = region or config.default_region 

180 formatter.print_error( 

181 f"Could not describe instance type '{instance_type}' in {target}. " 

182 "It may not exist, or may not be offered in that region — try " 

183 "--region, or 'gco capacity recommend-region'." 

184 ) 

185 sys.exit(1) 

186 

187 if config.output_format != "table": 

188 formatter.print(info) 

189 return 

190 

191 print(f"\n {info.instance_type} ({info.region})") 

192 print(" " + "-" * 58) 

193 print(f" vCPUs: {info.vcpus}", end="") 

194 if info.cores is not None: 

195 print(f" ({info.cores} cores x {info.threads_per_core} threads)", end="") 

196 print() 

197 print(f" Memory: {info.memory_gib} GiB") 

198 print(f" Architecture: {', '.join(info.architectures) or info.architecture}") 

199 if info.processor_manufacturer: 

200 clock = ( 

201 f" @ {info.sustained_clock_speed_ghz} GHz" if info.sustained_clock_speed_ghz else "" 

202 ) 

203 print(f" Processor: {info.processor_manufacturer}{clock}") 

204 

205 if info.gpu_devices: 

206 print(f"\n GPUs: {info.gpu_count} total, {info.gpu_memory_gib} GiB total") 

207 for device in info.gpu_devices: 

208 print( 

209 f" {device.get('count')}x {device.get('manufacturer')} " 

210 f"{device.get('name')} @ {device.get('memory_gib')} GiB each" 

211 ) 

212 if info.neuron_devices: 

213 print( 

214 f"\n Neuron: {info.neuron_count} devices, " 

215 f"{info.neuron_memory_gib} GiB total" 

216 ) 

217 for device in info.neuron_devices: 

218 print( 

219 f" {device.get('count')}x {device.get('name')} " 

220 f"({device.get('core_count')} cores v{device.get('core_version')})" 

221 ) 

222 if info.inference_accelerators: 

223 print(f"\n Inferentia: {info.inference_accelerator_count} accelerators") 

224 

225 print("\n NETWORK") 

226 print(f" EFA: {'yes' if info.efa_supported else 'no'}", end="") 

227 if info.efa_max_interfaces: 

228 print(f" (max {info.efa_max_interfaces} interfaces)", end="") 

229 print() 

230 print(f" Performance: {info.network_performance}") 

231 print(f" Max ENIs: {info.maximum_network_interfaces}") 

232 if info.maximum_network_cards: 

233 print(f" Network cards: {info.maximum_network_cards}") 

234 

235 print("\n STORAGE") 

236 if info.instance_storage_total_gb: 

237 disks = ", ".join( 

238 f"{d.get('count')}x {d.get('size_gb')} GB {d.get('type')}" 

239 for d in info.instance_storage_disks 

240 ) 

241 print(f" Local: {info.instance_storage_total_gb} GB ({disks})") 

242 else: 

243 print(" Local: none (EBS only)") 

244 print(f" EBS optimized: {info.ebs_optimized_support}") 

245 if info.ebs_maximum_iops: 

246 print( 

247 f" EBS max: {info.ebs_maximum_iops} IOPS, " 

248 f"{info.ebs_maximum_throughput_mbps} MB/s" 

249 ) 

250 

251 print("\n PURCHASING") 

252 print(f" Usage classes: {', '.join(info.supported_usage_classes)}") 

253 print(f" Capacity blocks: {'yes' if info.capacity_block_supported else 'no'}") 

254 if info.supported_placement_strategies: 

255 print(f" Placement: {', '.join(info.supported_placement_strategies)}") 

256 print(f" Current gen: {'yes' if info.current_generation else 'no'}") 

257 print() 

258 

259 except Exception as e: 

260 formatter.print_error(f"Failed to get instance info: {e}") 

261 sys.exit(1) 

262 

263 

264@capacity.command("status") 

265@click.option("--region", "-r", help="Specific region to check") 

266@click.option("--all-regions", "-a", is_flag=True, default=True, help="Check all regions (default)") 

267@pass_config 

268def capacity_status(config: Any, region: Any, all_regions: Any) -> None: 

269 """Show comprehensive resource utilization across regions. 

270 

271 Displays pending/running workloads, GPU/CPU utilization, queue depth, 

272 and active job counts for one or all GCO clusters. 

273 

274 Examples: 

275 gco capacity status 

276 gco capacity status --region us-east-1 

277 gco capacity status --all-regions 

278 """ 

279 from ..capacity import get_multi_region_capacity_checker 

280 

281 formatter = get_output_formatter(config) 

282 

283 try: 

284 checker = get_multi_region_capacity_checker(config) 

285 

286 if region: 

287 capacity = checker.get_region_capacity(region) 

288 formatter.print(capacity) 

289 else: 

290 capacities = checker.get_all_regions_capacity() 

291 

292 if not capacities: 

293 formatter.print_warning("No GCO stacks found") 

294 if config.output_format != "table": 

295 formatter.print(capacities) 

296 return 

297 

298 if config.output_format == "table": 

299 print("\n REGION QUEUE RUNNING GPU% CPU% SCORE") 

300 print(" " + "-" * 55) 

301 for c in sorted(capacities, key=lambda x: x.recommendation_score): 

302 print( 

303 f" {c.region:<15} {c.queue_depth:>5} {c.running_jobs:>7} " 

304 f"{c.gpu_utilization:>4.0f}% {c.cpu_utilization:>4.0f}% " 

305 f"{c.recommendation_score:>5.0f}" 

306 ) 

307 

308 print() 

309 best = min(capacities, key=lambda x: x.recommendation_score) 

310 formatter.print_info(f"Recommended region: {best.region} (lowest score = best)") 

311 else: 

312 formatter.print(capacities) 

313 

314 except Exception as e: 

315 formatter.print_error(f"Failed to get capacity status: {e}") 

316 sys.exit(1) 

317 

318 

319@capacity.command("recommend-region") 

320@click.option("--gpu", is_flag=True, help="Job requires GPUs") 

321@click.option("--min-gpus", default=0, help="Minimum GPUs required") 

322@click.option( 

323 "--instance-type", "-i", default=None, help="Specific instance type for workload-aware scoring" 

324) 

325@click.option("--gpu-count", default=0, help="Number of GPUs required") 

326@pass_config 

327def recommend_region( 

328 config: Any, gpu: Any, min_gpus: Any, instance_type: Any, gpu_count: Any 

329) -> None: 

330 """Recommend optimal region for job placement. 

331 

332 Analyzes capacity across all deployed EKS regions and recommends 

333 the best region. When --instance-type is provided, uses weighted 

334 multi-signal scoring that factors in spot placement scores, pricing, 

335 queue depth, GPU utilization, and running job counts. 

336 

337 Without --instance-type, uses a simpler composite score based on 

338 queue depth, GPU utilization, and running jobs. 

339 

340 Examples: 

341 gco capacity recommend-region 

342 gco capacity recommend-region --gpu 

343 gco capacity recommend-region -i g5.xlarge 

344 gco capacity recommend-region -i p4d.24xlarge --gpu-count 8 

345 """ 

346 from ..capacity import get_multi_region_capacity_checker 

347 

348 formatter = get_output_formatter(config) 

349 

350 try: 

351 checker = get_multi_region_capacity_checker(config) 

352 recommendation = checker.recommend_region_for_job( 

353 gpu_required=gpu, 

354 min_gpus=min_gpus, 

355 instance_type=instance_type, 

356 gpu_count=gpu_count, 

357 ) 

358 

359 if config.output_format == "table": 

360 formatter.print_success(f"Recommended region: {recommendation['region']}") 

361 formatter.print_info(f"Reason: {recommendation['reason']}") 

362 

363 if config.verbose: 

364 print("\nAll regions ranked:") 

365 for r in recommendation.get("all_regions", []): 

366 print( 

367 f" {r['region']}: score={r['score']:.4f}, " 

368 f"queue={r['queue_depth']}, gpu={r['gpu_utilization']:.0f}%" 

369 ) 

370 else: 

371 formatter.print(recommendation) 

372 

373 except Exception as e: 

374 formatter.print_error(f"Failed to get recommendation: {e}") 

375 sys.exit(1) 

376 

377 

378@capacity.command("ai-recommend") 

379@click.option("--workload", "-w", help="Description of your workload") 

380@click.option( 

381 "--instance-type", 

382 "-i", 

383 multiple=True, 

384 help="Instance types to consider (can specify multiple)", 

385) 

386@click.option("--region", "-r", multiple=True, help="Regions to consider (can specify multiple)") 

387@click.option("--gpu", is_flag=True, help="Workload requires GPUs") 

388@click.option("--min-gpus", default=0, help="Minimum GPUs required") 

389@click.option("--min-memory-gb", default=0, help="Minimum memory in GB") 

390@click.option( 

391 "--fault-tolerance", 

392 "-f", 

393 type=click.Choice(["high", "medium", "low"]), 

394 default="medium", 

395 help="Fault tolerance level", 

396) 

397@click.option("--max-cost", type=float, help="Maximum cost per hour in USD") 

398@click.option( 

399 "--model", 

400 "-m", 

401 default=None, 

402 help=( 

403 "Bedrock model ID to use " 

404 "(default: cdk.json context.bedrock.capacity_advisor_default_model_id)." 

405 ), 

406) 

407@click.option("--raw", is_flag=True, help="Show raw AI response") 

408@pass_config 

409def ai_recommend( 

410 config: Any, 

411 workload: Any, 

412 instance_type: Any, 

413 region: Any, 

414 gpu: Any, 

415 min_gpus: Any, 

416 min_memory_gb: Any, 

417 fault_tolerance: Any, 

418 max_cost: Any, 

419 model: Any, 

420 raw: Any, 

421) -> None: 

422 """Get AI-powered capacity recommendation using Amazon Bedrock. 

423 

424 This command gathers comprehensive capacity data including: 

425 - Spot placement scores, pricing, and 7-day per-AZ price trends across regions 

426 - On-demand availability and pricing 

427 - Capacity Reservations (ODCRs), Capacity Block offerings, and 26-week 

428 block-availability trends 

429 - Current cluster utilization (queue depth, GPU/CPU usage) 

430 - Running and pending job counts 

431 - The algorithmic multi-signal region ranking as advisory context 

432 

433 Without --instance-type, one representative type per current GPU 

434 generation is scanned (T4, L4, A10G, L40S, RTX PRO 4500/6000 Blackwell, 

435 A100, H100, H200, B200, B300). 

436 

437 The data is analyzed by an LLM to provide intelligent recommendations 

438 for where to place your workload. 

439 

440 ⚠️ DISCLAIMER: Recommendations are AI-generated and should be validated 

441 before making production decisions. Capacity availability and pricing 

442 can change rapidly. 

443 

444 REQUIREMENTS: 

445 - AWS credentials with bedrock:InvokeModel permission 

446 - The specified Bedrock model must be enabled in your account 

447 - Default model: cdk.json context.bedrock.capacity_advisor_default_model_id 

448 

449 Examples: 

450 gco capacity ai-recommend --workload "Training a large language model" 

451 

452 gco capacity ai-recommend -w "Inference workload" --gpu --min-gpus 4 

453 

454 gco capacity ai-recommend -i g5.xlarge -i g5.2xlarge -r us-east-1 -r us-west-2 

455 

456 gco capacity ai-recommend --fault-tolerance high --max-cost 5.00 

457 """ 

458 from ..capacity import get_bedrock_capacity_advisor 

459 

460 formatter = get_output_formatter(config) 

461 

462 # Print disclaimer 

463 print() 

464 print(" " + "=" * 70) 

465 print(" ⚠️ AI-POWERED RECOMMENDATION DISCLAIMER") 

466 print(" " + "-" * 70) 

467 print(" This recommendation is generated by an AI model and should be") 

468 print(" validated before making production decisions.") 

469 print(" ") 

470 print(" • Capacity availability can change rapidly") 

471 print(" • Spot instances may be interrupted at any time") 

472 print(" • Pricing data may not reflect real-time prices") 

473 print(" • AI recommendations are not guaranteed to be optimal") 

474 print(" " + "=" * 70) 

475 print() 

476 

477 try: 

478 formatter.print_info("Gathering capacity data across regions...") 

479 

480 advisor = get_bedrock_capacity_advisor(config, model_id=model) 

481 

482 # Build requirements dict 

483 requirements = { 

484 "gpu_required": gpu, 

485 "min_gpus": min_gpus if min_gpus > 0 else None, 

486 "min_memory_gb": min_memory_gb if min_memory_gb > 0 else None, 

487 "fault_tolerance": fault_tolerance, 

488 "max_cost_per_hour": max_cost, 

489 } 

490 # Remove None values 

491 requirements = {k: v for k, v in requirements.items() if v is not None} 

492 

493 formatter.print_info(f"Analyzing with {advisor.model_id}...") 

494 

495 recommendation = advisor.get_recommendation( 

496 workload_description=workload, 

497 instance_types=list(instance_type) if instance_type else None, 

498 regions=list(region) if region else None, 

499 requirements=requirements if requirements else None, 

500 ) 

501 

502 # Display recommendation 

503 print() 

504 print(" " + "=" * 70) 

505 print(" 🤖 AI RECOMMENDATION") 

506 print(" " + "=" * 70) 

507 print() 

508 print(f" Region: {recommendation.recommended_region}") 

509 print(f" Instance Type: {recommendation.recommended_instance_type}") 

510 print(f" Capacity Type: {recommendation.recommended_capacity_type.upper()}") 

511 print(f" Confidence: {recommendation.confidence.upper()}") 

512 if recommendation.cost_estimate: 

513 print(f" Est. Cost: {recommendation.cost_estimate}") 

514 print() 

515 print(" REASONING:") 

516 print(" " + "-" * 68) 

517 # Word wrap the reasoning 

518 reasoning_lines = recommendation.reasoning.split(". ") 

519 for line in reasoning_lines: 

520 if line.strip(): 

521 print(f" {line.strip()}.") 

522 print() 

523 

524 # Show alternatives 

525 if recommendation.alternative_options: 

526 print(" ALTERNATIVE OPTIONS:") 

527 print(" " + "-" * 68) 

528 for i, alt in enumerate(recommendation.alternative_options[:3], 1): 

529 print( 

530 f" {i}. {alt.get('region', 'N/A')} / " 

531 f"{alt.get('instance_type', 'N/A')} / " 

532 f"{alt.get('capacity_type', 'N/A').upper()}" 

533 ) 

534 if alt.get("reason"): 

535 print(f" {alt['reason']}") 

536 print() 

537 

538 # Show warnings 

539 if recommendation.warnings: 

540 print(" ⚠️ WARNINGS:") 

541 print(" " + "-" * 68) 

542 for warning in recommendation.warnings: 

543 print(f" • {warning}") 

544 print() 

545 

546 # Show raw response if requested 

547 if raw: 

548 print(" RAW AI RESPONSE:") 

549 print(" " + "-" * 68) 

550 print(recommendation.raw_response) 

551 print() 

552 

553 print(" " + "=" * 70) 

554 print() 

555 

556 except Exception as e: 

557 if is_bedrock_ftu_form_error(e): 

558 formatter.print_error(BEDROCK_FTU_REMEDIATION) 

559 sys.exit(1) 

560 # Advisor errors are already fully worded (and may carry their own 

561 # remediation); re-prefixing here used to print the same phrase twice. 

562 formatter.print_error(str(e)) 

563 sys.exit(1) 

564 

565 

566@capacity.command("reservations") 

567@click.option("--instance-type", "-i", help="Filter by instance type") 

568@click.option("--region", "-r", help="Specific region (default: all deployed regions)") 

569@pass_config 

570def list_reservations(config: Any, instance_type: Any, region: Any) -> None: 

571 """List On-Demand Capacity Reservations (ODCRs) across regions. 

572 

573 Shows all active capacity reservations with utilization details. 

574 

575 Examples: 

576 gco capacity reservations 

577 gco capacity reservations -i p5.48xlarge 

578 gco capacity reservations -r us-east-1 

579 """ 

580 formatter = get_output_formatter(config) 

581 checker = get_capacity_checker(config) 

582 

583 try: 

584 if region: 

585 reservations = checker.list_capacity_reservations(region, instance_type=instance_type) 

586 result = { 

587 "regions_checked": [region], 

588 "total_reservations": len(reservations), 

589 "total_reserved_instances": sum(r["total_instances"] for r in reservations), 

590 "total_available_instances": sum(r["available_instances"] for r in reservations), 

591 "reservations": reservations, 

592 } 

593 else: 

594 result = checker.list_all_reservations(instance_type=instance_type) 

595 

596 if config.output_format != "table": 

597 formatter.print(result) 

598 return 

599 

600 reservations = result["reservations"] 

601 if not reservations: 

602 formatter.print_info("No active capacity reservations found") 

603 return 

604 

605 print(f"\n Capacity Reservations ({len(reservations)} found)") 

606 print(" " + "-" * 90) 

607 print( 

608 f" {'INSTANCE TYPE':<18} {'REGION':<15} {'AZ':<18} " 

609 f"{'TOTAL':>5} {'AVAIL':>5} {'USED%':>6} {'MATCH CRITERIA'}" 

610 ) 

611 print(" " + "-" * 90) 

612 for r in reservations: 

613 print( 

614 f" {r['instance_type']:<18} {r['region']:<15} " 

615 f"{r['availability_zone']:<18} {r['total_instances']:>5} " 

616 f"{r['available_instances']:>5} {r['utilization_pct']:>5.1f}% " 

617 f"{r.get('instance_match_criteria', 'open')}" 

618 ) 

619 

620 print() 

621 print( 

622 f" Total: {result['total_reserved_instances']} reserved, " 

623 f"{result['total_available_instances']} available" 

624 ) 

625 print() 

626 

627 except Exception as e: 

628 formatter.print_error(f"Failed to list reservations: {e}") 

629 sys.exit(1) 

630 

631 

632@capacity.command("reservation-check") 

633@click.option("--instance-type", "-i", required=True, help="Instance type to check") 

634@click.option( 

635 "--region", 

636 "-r", 

637 "regions", 

638 multiple=True, 

639 help="Region(s) to check; repeatable (default: all deployed regions)", 

640) 

641@click.option("--count", "-c", default=1, help="Minimum instances needed") 

642@click.option( 

643 "--include-blocks/--no-blocks", 

644 default=True, 

645 help="Include Capacity Block offerings (default: yes)", 

646) 

647@click.option( 

648 "--block-duration", 

649 default=24, 

650 type=int, 

651 help="Capacity Block duration in hours (default: 24)", 

652) 

653@click.option( 

654 "--block-duration-days", 

655 default=None, 

656 type=int, 

657 help="Capacity Block duration in days (overrides --block-duration)", 

658) 

659@click.option( 

660 "--earliest-start", 

661 default=None, 

662 help="Earliest block start date (YYYY-MM-DD or ISO datetime)", 

663) 

664@click.option( 

665 "--latest-start", 

666 default=None, 

667 help="Latest block start date (YYYY-MM-DD or ISO datetime)", 

668) 

669@pass_config 

670def reservation_check( 

671 config: Any, 

672 instance_type: Any, 

673 regions: Any, 

674 count: Any, 

675 include_blocks: Any, 

676 block_duration: Any, 

677 block_duration_days: Any, 

678 earliest_start: Any, 

679 latest_start: Any, 

680) -> None: 

681 """Check reservation availability and Capacity Block offerings. 

682 

683 Checks both existing ODCRs and purchasable Capacity Blocks for ML 

684 workloads. Capacity Blocks provide guaranteed GPU capacity for a 

685 fixed duration at a known price. Pass --region more than once to check 

686 several regions in parallel, and use --earliest-start/--latest-start to 

687 bound when the block may begin. For a full duration-range sweep across 

688 many regions, use 'gco capacity find-blocks'. 

689 

690 Examples: 

691 gco capacity reservation-check -i p5.48xlarge 

692 gco capacity reservation-check -i p4d.24xlarge -c 2 --block-duration 48 

693 gco capacity reservation-check -i g5.48xlarge -r us-east-1 --no-blocks 

694 gco capacity reservation-check -i p5.48xlarge -r us-east-1 -r us-west-2 \\ 

695 --block-duration-days 14 --earliest-start 2026-07-01 

696 """ 

697 formatter = get_output_formatter(config) 

698 checker = get_capacity_checker(config) 

699 

700 try: 

701 formatter.print_info( 

702 f"Checking reservations for {instance_type} " 

703 f"(min {count} instance{'s' if count > 1 else ''})..." 

704 ) 

705 

706 result = checker.check_reservation_availability( 

707 instance_type=instance_type, 

708 regions=list(regions) or None, 

709 min_count=count, 

710 include_capacity_blocks=include_blocks, 

711 block_duration_hours=block_duration, 

712 block_duration_days=block_duration_days, 

713 earliest_start=earliest_start, 

714 latest_start=latest_start, 

715 ) 

716 

717 if config.output_format != "table": 

718 formatter.print(result) 

719 return 

720 

721 # ODCR section 

722 odcr = result["odcr"] 

723 print(f"\n On-Demand Capacity Reservations for {instance_type}") 

724 print(" " + "-" * 60) 

725 if odcr["reservations"]: 

726 for r in odcr["reservations"]: 

727 print( 

728 f" ✓ {r['availability_zone']}: " 

729 f"{r['available_instances']}/{r['total_instances']} available " 

730 f"({r['reservation_id']})" 

731 ) 

732 print( 

733 f"\n Total: {odcr['total_available_instances']} available " 

734 f"of {odcr['total_reserved_instances']} reserved" 

735 ) 

736 else: 

737 print(" No active ODCRs found for this instance type") 

738 

739 # Capacity Blocks section 

740 if include_blocks: 

741 block_section = result["capacity_blocks"] 

742 duration = block_section.get("duration_hours", block_duration) 

743 print(f"\n Capacity Block Offerings ({duration}h)") 

744 print(" " + "-" * 60) 

745 if block_section["offerings"]: 

746 for b in block_section["offerings"]: 

747 gpu_hr = b.get("price_per_gpu_hour") 

748 gpu_hr_str = f" (${gpu_hr}/GPU-hr)" if gpu_hr is not None else "" 

749 start = (b.get("start_date") or "")[:16] 

750 print( 

751 f" ✓ {b['availability_zone']}: " 

752 f"{b['instance_count']}x {b['duration_hours']}h " 

753 f"starting {start} — ${b['upfront_fee']}{gpu_hr_str}" 

754 ) 

755 else: 

756 print(" No Capacity Block offerings available") 

757 

758 # Recommendation 

759 print() 

760 print(f" 💡 {result['recommendation']}") 

761 print() 

762 

763 except Exception as e: 

764 formatter.print_error(f"Failed to check reservations: {e}") 

765 sys.exit(1) 

766 

767 

768def _print_find_blocks_report(result: dict[str, Any]) -> None: 

769 """Render a consolidated find-blocks report as a readable table block.""" 

770 itype = result["instance_type"] 

771 if result.get("requested_instance_type") and result["requested_instance_type"] != itype: 

772 print(f"\n Capacity Block search for {result['requested_instance_type']} -> {itype}") 

773 else: 

774 print(f"\n Capacity Block search for {itype}") 

775 print(" " + "-" * 72) 

776 

777 window = result.get("date_window", {}) 

778 earliest = (window.get("earliest_start") or "any")[:16] 

779 latest = (window.get("latest_start") or "any")[:16] 

780 days = result.get("durations_probed_days") or [] 

781 if days: 

782 span = f"{min(days):g}-{max(days):g}d" if len(days) > 1 else f"{days[0]:g}d" 

783 else: 

784 span = "n/a" 

785 print(f" Regions: {', '.join(result.get('regions_checked', []))}") 

786 print(f" Durations probed: {span} Start window: {earliest} .. {latest}") 

787 

788 if not result.get("valid_instance_type", True): 

789 print() 

790 print(f" ⚠ {result.get('recommendation', 'Invalid instance type.')}")