Skip to main content

alien_core/
compute_planner.rs

1//! Deployment-time compute planner.
2//!
3//! The planner turns portable stack requirements plus a target platform into a
4//! renderable set of recommended deployment choices. It does not mutate the
5//! stack and does not require database access.
6
7use crate::{
8    instance_catalog::{self, Architecture, InstanceFamily, WorkloadRequirements},
9    CapacityGroup, CapacityGroupScalePolicy, ComputeChoiceRange, ComputePoolSelection, Container,
10    Daemon, ErrorData, FailureDomainSelection, GpuSpec, MachineProfile, Platform, ResourceSpec,
11    Stack, StackState,
12};
13use alien_error::{AlienError, Result};
14use serde::{Deserialize, Serialize};
15use std::collections::HashMap;
16
17/// Full compute plan for one stack/platform pair.
18#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
19#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
20#[serde(rename_all = "camelCase")]
21pub struct ComputePlan {
22    /// Planned pools in stable pool-id order.
23    pub pools: Vec<ComputePoolPlan>,
24    /// Containers whose per-replica allocation can be chosen during setup.
25    #[serde(default, skip_serializing_if = "Vec::is_empty")]
26    pub containers: Vec<ContainerResourcePlan>,
27}
28
29/// Deployment-time resource controls and effective allocation for one container.
30#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
31#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
32#[serde(rename_all = "camelCase")]
33pub struct ContainerResourcePlan {
34    /// Stable container resource ID.
35    pub container_id: String,
36    /// Allowed allocations declared in the release.
37    pub choices: crate::ContainerResourceChoices,
38    /// Effective per-replica CPU reservation and limit.
39    pub cpu: ResourceSpec,
40    /// Effective per-replica memory reservation and limit.
41    pub memory: ResourceSpec,
42    /// Effective persistent capacity per replica, in GiB.
43    #[serde(default, skip_serializing_if = "Option::is_none")]
44    pub volume_size_gib: Option<u32>,
45    /// Installed capacity, or the provider minimum for a new volume.
46    #[serde(default, skip_serializing_if = "Option::is_none")]
47    pub minimum_volume_size_gib: Option<u32>,
48    /// Maximum supported capacity for this provider, in GiB.
49    #[serde(default, skip_serializing_if = "Option::is_none")]
50    pub maximum_volume_size_gib: Option<u32>,
51}
52
53/// Planner output for one compute pool.
54#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
55#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
56#[serde(rename_all = "camelCase")]
57pub struct ComputePoolPlan {
58    /// Pool ID from the stack or derived default.
59    pub pool_id: String,
60    /// Workloads assigned to this pool.
61    pub workloads: Vec<String>,
62    /// Aggregated requirements used for machine selection.
63    pub requirements: MachineProfile,
64    /// Allowed scale policy declared by source or derived for generated pools.
65    pub scale: CapacityGroupScalePolicy,
66    /// Recommended or user-selected deployment choice.
67    pub selected: ComputePoolSelection,
68    /// Planner-recommended default.
69    pub recommended: ComputePoolSelection,
70    /// Every catalog machine for the platform, in catalog order (config series order, then vCPU).
71    /// `available` marks the ones that can run this pool. Empty for local and Kubernetes.
72    pub machines: Vec<ComputeMachineOption>,
73    /// Data disk sizes this deployment may choose, when the pool declares a data disk.
74    #[serde(default, skip_serializing_if = "Option::is_none")]
75    pub data_disk: Option<ComputePoolDataDiskPlan>,
76    /// Validation errors for supplied deployment settings.
77    #[serde(default, skip_serializing_if = "Vec::is_empty")]
78    pub errors: Vec<String>,
79}
80
81/// Data disk sizes a deployment may choose for one pool, in whole GiB. A fixed
82/// declaration has `min_gib == max_gib`. A size of 0 runs the pool without a
83/// data disk, which only a range starting at 0 allows.
84#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
85#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
86#[serde(rename_all = "camelCase")]
87pub struct ComputePoolDataDiskPlan {
88    /// Smallest size the deployment may choose.
89    pub min_gib: u32,
90    /// Largest size the deployment may choose.
91    pub max_gib: u32,
92    /// Size used when the deployment does not choose one.
93    pub default_gib: u32,
94    /// Size this deployment runs with: its choice, or the default.
95    pub selected_gib: u32,
96}
97
98/// One concrete provider machine option.
99#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
100#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
101#[serde(rename_all = "camelCase")]
102pub struct ComputeMachineOption {
103    /// Provider machine name.
104    pub machine: String,
105    /// Provider series the machine belongs to, such as `m8i` or `n2-standard`.
106    pub series: String,
107    /// Category the machine's series belongs to.
108    pub category: InstanceFamily,
109    /// How the series is shown to people choosing a machine.
110    pub label: String,
111    /// Machine hardware profile.
112    pub profile: MachineProfile,
113    /// Whether the machine exposes nested virtualization to guest VMs.
114    pub nested_virtualization: bool,
115    /// Local instance disk the provider reports for the machine, in bytes. Absent when the
116    /// machine has none and its storage is a provider disk.
117    #[serde(default, skip_serializing_if = "Option::is_none")]
118    pub local_storage: Option<u64>,
119    /// Whether the machine can run this pool.
120    pub available: bool,
121    /// Why the machine cannot run this pool. Empty when `available` is true.
122    pub unavailable_reasons: Vec<MachineUnavailableReason>,
123    /// Whether this machine is the planner's default recommendation.
124    pub recommended: bool,
125}
126
127/// A pool requirement a machine does not meet.
128#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
129#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
130#[serde(rename_all = "camelCase")]
131pub enum MachineUnavailableReason {
132    /// The machine's CPU architecture differs from the pool's.
133    Architecture,
134    /// The pool needs nested virtualization and the machine does not expose it.
135    NestedVirtualization,
136    /// The machine has fewer vCPUs than one workload replica needs.
137    Cpu,
138    /// The machine has less memory than one workload replica needs.
139    Memory,
140    /// The machine's local storage, or the largest disk the provider allows, is smaller
141    /// than one workload replica needs.
142    EphemeralStorage,
143    /// The machine lacks the GPU type or count the pool needs.
144    Gpu,
145}
146
147/// Failure-domain policy for a pool that hosts persistent stateful workloads when the
148/// deployment does not choose one: one provider-selected domain, so the pool's machines
149/// and their volumes land in the same zone.
150pub fn default_persistent_failure_domains() -> FailureDomainSelection {
151    FailureDomainSelection {
152        spread: 1,
153        selected_failure_domains: Vec::new(),
154    }
155}
156
157/// Compute a deterministic deployment-time plan.
158pub fn plan_compute(
159    stack: &Stack,
160    platform: Platform,
161    selected_settings: Option<&crate::ComputeSettings>,
162) -> Result<ComputePlan, ErrorData> {
163    plan_compute_with_state(stack, platform, selected_settings, None)
164}
165
166/// Plan a configuration update while retaining the installed machine architecture.
167/// Resource changes must not silently require a different workload image target.
168pub fn plan_compute_with_state(
169    stack: &Stack,
170    platform: Platform,
171    selected_settings: Option<&crate::ComputeSettings>,
172    previous_state: Option<&StackState>,
173) -> Result<ComputePlan, ErrorData> {
174    plan_compute_with_room(stack, platform, selected_settings, previous_state, None)
175}
176
177/// What the cloud account can still launch, asked while pools choose their machines. The
178/// planner visits pools in order, so an implementation can hold back what earlier pools
179/// need before it answers for the next one.
180pub trait MachineRoom {
181    /// Whether `machines` of `spec` fit for the pool when it chooses automatically. An
182    /// installed pool answers for the series it already runs and ignores quota.
183    fn has_room(
184        &self,
185        pool_id: &str,
186        spec: &instance_catalog::InstanceTypeSpec,
187        machines: u32,
188    ) -> bool;
189
190    /// The machine a pool ends up with and the machines it launches with, whether it chose
191    /// automatically or its machine was explicit. Called again with the same pool replaces
192    /// the earlier answer.
193    fn commit(&self, pool_id: &str, spec: &instance_catalog::InstanceTypeSpec, machines: u32);
194}
195
196/// [`plan_compute_with_state`] where automatic selection takes the first series that has
197/// room for the pool's machines, per `room`.
198pub fn plan_compute_with_room(
199    stack: &Stack,
200    platform: Platform,
201    selected_settings: Option<&crate::ComputeSettings>,
202    previous_state: Option<&StackState>,
203    room: Option<&dyn MachineRoom>,
204) -> Result<ComputePlan, ErrorData> {
205    let mut resolved_stack = stack.clone();
206    crate::container_resources::resolve_container_resources(
207        &mut resolved_stack,
208        selected_settings,
209    )?;
210    if let Some(previous_state) = previous_state {
211        crate::container_resources::retain_installed_volume_sizes(
212            &mut resolved_stack,
213            selected_settings,
214            previous_state,
215        );
216    }
217    let (minimum, maximum) = match platform {
218        Platform::Gcp => (10, 65536),
219        Platform::Azure => (1, 32767),
220        _ => (1, 65536),
221    };
222    for (id, entry) in &resolved_stack.resources {
223        let Some(storage) = entry
224            .config
225            .downcast_ref::<Container>()
226            .and_then(|container| container.persistent_storage.as_ref())
227        else {
228            continue;
229        };
230        let size = crate::container_resources::parse_volume_size_gib(&storage.size)
231            .map_err(|reason| crate::container_resources::invalid(id, "volumeSizeGib", &reason))?;
232        if size < minimum || size > maximum {
233            return Err(AlienError::new(
234                ErrorData::ContainerResourceSelectionInvalid {
235                    resource_id: id.clone(),
236                    dimension: "volumeSizeGib".into(),
237                    reason: format!(
238                        "capacity for {platform} must be between {minimum} and {maximum} GiB"
239                    ),
240                },
241            ));
242        }
243    }
244    if let Some(previous_state) = previous_state {
245        for (id, entry) in &resolved_stack.resources {
246            let desired = entry
247                .config
248                .downcast_ref::<Container>()
249                .and_then(|container| container.persistent_storage.as_ref());
250            let previous = previous_state
251                .resources
252                .get(id)
253                .and_then(|resource| resource.config.downcast_ref::<Container>())
254                .and_then(|container| container.persistent_storage.as_ref());
255            if previous.is_some() && desired.is_none() {
256                return Err(crate::container_resources::invalid(
257                    id,
258                    "volumeSizeGib",
259                    "removing installed persistent storage is unsupported",
260                ));
261            }
262            if let (Some(desired), Some(previous)) = (desired, previous) {
263                if desired.mount_path != previous.mount_path {
264                    return Err(crate::container_resources::invalid(
265                        id,
266                        "volumeSizeGib",
267                        "changing an installed persistent storage mount path is unsupported",
268                    ));
269                }
270                let target = crate::container_resources::parse_volume_size_gib(&desired.size);
271                let installed = crate::container_resources::parse_volume_size_gib(&previous.size);
272                if let (Ok(target), Ok(installed)) = (target, installed) {
273                    if target < installed {
274                        return Err(AlienError::new(ErrorData::ContainerResourceSelectionInvalid {
275                            resource_id: id.clone(), dimension: "volumeSizeGib".into(),
276                            reason: format!("existing volumes cannot shrink from {installed} to {target} GiB"),
277                        }));
278                    }
279                }
280            }
281        }
282    }
283    let stack = &resolved_stack;
284    let mut groups = collect_workload_groups(stack)?;
285    merge_explicit_compute_groups(stack, &mut groups)?;
286
287    let mut pool_ids: Vec<String> = groups.keys().cloned().collect();
288    pool_ids.sort();
289
290    // Pools whose machine is explicit hold their quota before any pool chooses, whatever
291    // their order.
292    if let Some(room) = room {
293        for pool_id in &pool_ids {
294            let selected = selected_settings.and_then(|settings| settings.pools.get(pool_id));
295            let declared = stack
296                .resources
297                .values()
298                .filter_map(|entry| entry.config.downcast_ref::<crate::ComputeCluster>())
299                .flat_map(|cluster| &cluster.capacity_groups)
300                .find(|group| &group.group_id == pool_id)
301                .and_then(|group| group.instance_type.as_deref());
302            let machine = match selected {
303                Some(selection) => selection.machine(),
304                None => declared,
305            };
306            if let Some(spec) =
307                machine.and_then(|machine| instance_catalog::find_instance_type(platform, machine))
308            {
309                let machines = selected
310                    .map(ComputePoolSelection::min_size)
311                    .unwrap_or_else(|| groups[pool_id].scale.default_min_size());
312                room.commit(pool_id, spec, machines);
313            }
314        }
315    }
316
317    let mut pools = Vec::new();
318    for pool_id in pool_ids {
319        let mut group = groups.remove(&pool_id).expect("pool id came from map keys");
320        let mut requirements = group.requirements;
321        let selected = selected_settings.and_then(|settings| settings.pools.get(&pool_id));
322        let declared_group = stack
323            .resources
324            .values()
325            .filter_map(|entry| entry.config.downcast_ref::<crate::ComputeCluster>())
326            .flat_map(|cluster| &cluster.capacity_groups)
327            .find(|group| group.group_id == pool_id);
328        let declared_machine = declared_group.and_then(|group| group.instance_type.as_deref());
329        let machine_override = match selected {
330            Some(selection) => selection.machine(),
331            None => declared_machine,
332        };
333        if requirements.architecture.is_none() {
334            requirements.architecture = machine_override
335                .and_then(|machine| instance_catalog::find_instance_type(platform, machine))
336                .map(|spec| spec.architecture)
337                .or_else(|| {
338                    previous_state.and_then(|state| {
339                        state
340                            .resources
341                            .values()
342                            .filter_map(|resource| {
343                                resource.config.downcast_ref::<crate::ComputeCluster>()
344                            })
345                            .flat_map(|cluster| &cluster.capacity_groups)
346                            .find(|group| group.group_id == pool_id)
347                            .and_then(|group| group.instance_type.as_deref())
348                            .and_then(|machine| {
349                                instance_catalog::find_instance_type(platform, machine)
350                            })
351                            .map(|spec| spec.architecture)
352                    })
353                });
354        }
355        // The machines the workloads need, within the fleet a generated pool offers. The
356        // rolling-update machine is left out: it sits empty between releases.
357        let workload_machines = if group.generated {
358            group
359                .scale
360                .default_max_size()
361                .min(GENERATED_POOL_MAX_MACHINES)
362        } else {
363            group.scale.default_max_size()
364        };
365        if group.generated {
366            group.scale = generated_pool_scale_policy(
367                group.scale.default_min_size(),
368                workload_machines + group.rolling_update_machines,
369                selected.map(ComputePoolSelection::max_size),
370            );
371        }
372        let machines = selected
373            .map(ComputePoolSelection::max_size)
374            .unwrap_or(workload_machines)
375            .max(1);
376        let mut sizing = requirements.clone();
377        // A bounded fleet must fit total demand as well as its largest replica.
378        sizing.max_cpu_per_container = sizing
379            .max_cpu_per_container
380            .max(sizing.total_cpu_at_desired / f64::from(machines));
381        sizing.max_memory_per_container = sizing.max_memory_per_container.max(
382            sizing
383                .total_memory_bytes_at_desired
384                .div_ceil(u64::from(machines)),
385        );
386        let recommended = recommended_selection(
387            platform,
388            &sizing,
389            &group.scale,
390            group.requires_failure_domain,
391            group.generated,
392            machine_override,
393            // Only a pool that chooses its machine asks for room.
394            room.filter(|_| machine_override.is_none())
395                .map(|room| PoolRoom {
396                    room,
397                    pool_id: &pool_id,
398                    machines: selected.map(ComputePoolSelection::min_size),
399                }),
400        )?;
401        let mut selected_choice = selected.cloned().unwrap_or_else(|| recommended.clone());
402        if selected.is_none() {
403            if let Some(declared_machine) = declared_machine {
404                match &mut selected_choice {
405                    ComputePoolSelection::Fixed { machine, .. }
406                    | ComputePoolSelection::Autoscale { machine, .. } => {
407                        *machine = Some(declared_machine.to_string());
408                    }
409                }
410            }
411        }
412        // An omitted machine is deployment intent: let the planner choose on
413        // every preparation. Only the returned plan contains the concrete type;
414        // never write it back into the caller's settings as an override.
415        match &mut selected_choice {
416            ComputePoolSelection::Fixed { machine, .. }
417            | ComputePoolSelection::Autoscale { machine, .. } => {
418                if machine.is_none() {
419                    *machine = recommended.machine().map(ToString::to_string);
420                }
421            }
422        }
423        if selected_choice.failure_domains().is_none() {
424            if let Some(default_failure_domains) = recommended.failure_domains().cloned() {
425                match &mut selected_choice {
426                    ComputePoolSelection::Fixed {
427                        failure_domains, ..
428                    }
429                    | ComputePoolSelection::Autoscale {
430                        failure_domains, ..
431                    } => *failure_domains = Some(default_failure_domains),
432                }
433            }
434        }
435        if let Some(room) = room {
436            if let Some(spec) = selected_choice
437                .machine()
438                .and_then(|machine| instance_catalog::find_instance_type(platform, machine))
439            {
440                room.commit(&pool_id, spec, selected_choice.min_size());
441            }
442        }
443        let mut errors = validate_compute_pool_selection(
444            platform,
445            &pool_id,
446            &selected_choice,
447            &requirements,
448            &group.scale,
449        );
450        // Only workloads assigned to the pool give it real demand; a declared pool without
451        // them carries just its machine profile.
452        if let Some(workload_requirements) = &group.workload_requirements {
453            if let Err(message) =
454                check_pool_capacity(platform, &pool_id, &selected_choice, workload_requirements)
455            {
456                errors.push(message);
457            }
458        }
459        let selected_data_disk_gib = selected.and_then(ComputePoolSelection::data_disk_gib);
460        let data_disk_choices = declared_group.and_then(crate::CapacityGroup::data_disk_choices);
461        let data_disk_result = match declared_group {
462            Some(group) => group.effective_data_disk_gib(selected_data_disk_gib),
463            None => match selected_data_disk_gib {
464                None | Some(0) => Ok(None),
465                Some(size) => Err(format!(
466                    "pool '{pool_id}' declares no data disk, so dataDiskGib {size} cannot be chosen"
467                )),
468            },
469        };
470        if let Err(message) = &data_disk_result {
471            errors.push(message.clone());
472        }
473        let data_disk = data_disk_choices.map(|choices| ComputePoolDataDiskPlan {
474            min_gib: choices.min,
475            max_gib: choices.max,
476            default_gib: choices.default,
477            selected_gib: match &data_disk_result {
478                Ok(size) => size.unwrap_or(0),
479                Err(_) => selected_data_disk_gib.unwrap_or(choices.default),
480            },
481        });
482        let machines = machine_options(
483            platform,
484            &requirements,
485            group.workload_requirements.as_ref(),
486            selected_choice.machine(),
487            recommended.machine(),
488        )?;
489
490        pools.push(ComputePoolPlan {
491            pool_id,
492            workloads: group.workloads,
493            requirements: requirements_to_profile(&requirements),
494            scale: group.scale,
495            selected: selected_choice,
496            recommended,
497            machines,
498            data_disk,
499            errors,
500        });
501    }
502
503    let mut containers: Vec<_> = stack
504        .resources
505        .values()
506        .filter_map(|entry| entry.config.downcast_ref::<Container>())
507        .filter(|container| {
508            container.resource_choices.is_some() || container.persistent_storage.is_some()
509        })
510        .map(|container| {
511            let capacity = |storage: &crate::PersistentStorage| {
512                crate::container_resources::parse_volume_size_gib(&storage.size).map_err(|reason| {
513                    crate::container_resources::invalid(&container.id, "volumeSizeGib", &reason)
514                })
515            };
516            let volume_size_gib = container
517                .persistent_storage
518                .as_ref()
519                .map(capacity)
520                .transpose()?;
521            let installed = previous_state
522                .and_then(|state| state.resources.get(&container.id))
523                .and_then(|resource| resource.config.downcast_ref::<Container>())
524                .and_then(|container| container.persistent_storage.as_ref())
525                .map(capacity)
526                .transpose()?;
527            Ok(ContainerResourcePlan {
528                container_id: container.id.clone(),
529                choices: container.resource_choices.clone().unwrap_or_default(),
530                cpu: container.cpu.clone(),
531                memory: container.memory.clone(),
532                volume_size_gib,
533                minimum_volume_size_gib: volume_size_gib
534                    .map(|_| installed.unwrap_or(if platform == Platform::Gcp { 10 } else { 1 })),
535                maximum_volume_size_gib: volume_size_gib.map(|_| {
536                    if platform == Platform::Azure {
537                        32767
538                    } else {
539                        65536
540                    }
541                }),
542            })
543        })
544        .collect::<Result<Vec<_>, ErrorData>>()?;
545    containers.sort_by(|a, b| a.container_id.cmp(&b.container_id));
546    Ok(ComputePlan { pools, containers })
547}
548
549#[derive(Debug, Clone)]
550struct PlannedGroup {
551    workloads: Vec<String>,
552    /// Actual allocations, excluding a declaration's minimum machine profile.
553    workload_requirements: Option<WorkloadRequirements>,
554    requirements: WorkloadRequirements,
555    scale: CapacityGroupScalePolicy,
556    requires_failure_domain: bool,
557    /// No capacity group in the source declares this pool. Its scale is the
558    /// planner's recommendation, not a bound the developer chose.
559    generated: bool,
560    /// Machines a generated pool's default max adds on top of its workloads, so a rolling
561    /// update has room to start a new replica before stopping the old one.
562    rolling_update_machines: u32,
563}
564
565/// Machine count up to which a setup offers choices for a pool the source does not declare.
566///
567/// It is not a limit: such a pool has no upper bound, and a saved choice above it widens the
568/// offered range. Recommendations above it are clamped to it.
569pub const GENERATED_POOL_MAX_MACHINES: u32 = 100;
570
571/// Allowed scale for a pool that no capacity group declares.
572///
573/// The planner derives `default_min`/`default_max` from workload replicas, assuming one
574/// container per machine. They are a recommendation, not a bound: the developer did not bound
575/// the pool, a larger machine fits more containers, and replica counts change between releases
576/// while the installer's saved choice stays. The installer may choose any count from the
577/// workload minimum (one machine when any workload runs) upwards, fixed or autoscaling (a fixed
578/// N is accepted as the autoscale range N..N). The range reaches
579/// [`GENERATED_POOL_MAX_MACHINES`], or `selected_max` when the saved choice is larger, so the
580/// saved choice is always inside it. Whether the choice can hold the workloads is
581/// [`check_pool_capacity`]'s question.
582pub fn generated_pool_scale_policy(
583    default_min: u32,
584    default_max: u32,
585    selected_max: Option<u32>,
586) -> CapacityGroupScalePolicy {
587    let offered = GENERATED_POOL_MAX_MACHINES;
588    let ceiling = offered.max(selected_max.unwrap_or(0));
589    let default_min = default_min.min(offered);
590    CapacityGroupScalePolicy::Autoscale {
591        min: ComputeChoiceRange {
592            min: default_min,
593            max: ceiling,
594            default: default_min,
595        },
596        max: ComputeChoiceRange {
597            min: default_min.max(1),
598            max: ceiling,
599            default: default_max.clamp(default_min.max(1), offered),
600        },
601    }
602}
603
604/// Rejects a selection whose largest fleet cannot hold the workloads at their desired replica
605/// counts after reserving host resources. It also checks that one replica fits;
606/// arbitrary multi-replica packing can still require runtime validation.
607pub fn check_pool_capacity(
608    platform: Platform,
609    pool_id: &str,
610    selection: &ComputePoolSelection,
611    requirements: &WorkloadRequirements,
612) -> std::result::Result<(), String> {
613    let Some(spec) = selection
614        .machine()
615        .and_then(|machine| instance_catalog::find_instance_type(platform, machine))
616    else {
617        // Machine presence and catalog membership are reported by the selection checks.
618        return Ok(());
619    };
620    let machines = selection.max_size();
621    let per_machine_cpu = instance_catalog::allocatable_cpu(spec);
622    let per_machine_memory = instance_catalog::allocatable_memory_bytes(spec);
623    if per_machine_cpu + f64::EPSILON < requirements.max_cpu_per_container
624        || per_machine_memory < requirements.max_memory_per_container
625    {
626        return Err(format!(
627            "Pool '{pool_id}' machine '{}' cannot fit one replica after reserving host resources",
628            spec.name,
629        ));
630    }
631    let cpu = f64::from(machines) * per_machine_cpu;
632    let memory = u64::from(machines) * per_machine_memory;
633    if cpu + f64::EPSILON >= requirements.total_cpu_at_desired
634        && memory >= requirements.total_memory_bytes_at_desired
635    {
636        return Ok(());
637    }
638    const GIB: f64 = 1024.0 * 1024.0 * 1024.0;
639    Err(format!(
640        "Pool '{pool_id}' is too small for its workloads: {machines} x {} has {cpu:.2} vCPU and {:.1} GiB, and the workloads request {:.2} vCPU and {:.1} GiB at their desired replica counts",
641        spec.name,
642        memory as f64 / GIB,
643        requirements.total_cpu_at_desired,
644        requirements.total_memory_bytes_at_desired as f64 / GIB,
645    ))
646}
647
648fn collect_workload_groups(stack: &Stack) -> Result<HashMap<String, PlannedGroup>, ErrorData> {
649    let mut groups: HashMap<String, Vec<Workload>> = HashMap::new();
650
651    for entry in stack.resources.values() {
652        if let Some(container) = entry.config.downcast_ref::<Container>() {
653            groups
654                .entry(
655                    container
656                        .pool
657                        .clone()
658                        .unwrap_or_else(|| needed_container_pool(container).to_string()),
659                )
660                .or_default()
661                .push(Workload::from_container(container)?);
662        }
663        if let Some(daemon) = entry.config.downcast_ref::<Daemon>() {
664            if daemon.cluster.is_some() {
665                groups
666                    .entry(daemon.pool.clone().unwrap_or_else(|| "general".to_string()))
667                    .or_default()
668                    .push(Workload::from_daemon(daemon)?);
669            }
670        }
671    }
672
673    let mut planned = HashMap::new();
674    for (pool_id, workloads) in groups {
675        let requirements = aggregate_workloads(&workloads);
676        let requires_failure_domain = workloads
677            .iter()
678            .any(|workload| workload.requires_failure_domain);
679        let min_size = default_min_machines(&requirements);
680        let max_size = default_max_machines(&requirements);
681        // A replicated container's rolling update starts the new replica before it stops the
682        // old one. A stateful container replaces in place (its volume has one owner) and a
683        // daemon runs one replica per machine, so neither needs room for an extra replica.
684        let rolling_update_machines = u32::from(workloads.iter().any(|w| w.starts_before_stop));
685        planned.insert(
686            pool_id,
687            PlannedGroup {
688                workloads: workloads.into_iter().map(|w| w.id).collect(),
689                workload_requirements: Some(requirements.clone()),
690                // Merged with any declared group below; widened in `plan_compute` if none declares it.
691                scale: CapacityGroupScalePolicy::from_selected_bounds(min_size, max_size),
692                requirements,
693                requires_failure_domain,
694                generated: true,
695                rolling_update_machines,
696            },
697        );
698    }
699    Ok(planned)
700}
701
702fn merge_explicit_compute_groups(
703    stack: &Stack,
704    groups: &mut HashMap<String, PlannedGroup>,
705) -> Result<(), ErrorData> {
706    for entry in stack.resources.values() {
707        let Some(cluster) = entry.config.downcast_ref::<crate::ComputeCluster>() else {
708            continue;
709        };
710        for group in &cluster.capacity_groups {
711            let explicit_requirements = profile_to_requirements(
712                group.profile.as_ref(),
713                group.nested_virtualization.unwrap_or(false),
714            );
715            let scale = group.scale_policy.clone().unwrap_or_else(|| {
716                CapacityGroupScalePolicy::from_selected_bounds(group.min_size, group.max_size)
717            });
718            groups
719                .entry(group.group_id.clone())
720                .and_modify(|planned| {
721                    if group.instance_type.is_none() {
722                        merge_requirements(&mut planned.requirements, &explicit_requirements);
723                    } else {
724                        // A materialized capacity group profile describes the
725                        // selected machine, not additional workload demand.
726                        // Merging its full CPU and memory into requirements
727                        // would cause deployment package planning to size an
728                        // already-sized machine a second time. Keep only the
729                        // constraints that affect artifact compatibility.
730                        planned.requirements.architecture = planned
731                            .requirements
732                            .architecture
733                            .or(explicit_requirements.architecture);
734                        planned.requirements.nested_virt |= explicit_requirements.nested_virt;
735                    }
736                    planned.scale = merge_scale_policy(&planned.scale, &scale);
737                    planned.generated = false;
738                })
739                .or_insert_with(|| PlannedGroup {
740                    workloads: Vec::new(),
741                    workload_requirements: None,
742                    scale,
743                    requirements: explicit_requirements,
744                    requires_failure_domain: false,
745                    generated: false,
746                    rolling_update_machines: 0,
747                });
748        }
749    }
750    Ok(())
751}
752
753/// The room a pool that chooses its machine asks, with the machines it launches with when
754/// the installer chose a count.
755struct PoolRoom<'a> {
756    room: &'a dyn MachineRoom,
757    pool_id: &'a str,
758    machines: Option<u32>,
759}
760
761fn recommended_selection(
762    platform: Platform,
763    requirements: &WorkloadRequirements,
764    scale: &CapacityGroupScalePolicy,
765    requires_failure_domain: bool,
766    generated: bool,
767    machine_override: Option<&str>,
768    room: Option<PoolRoom>,
769) -> Result<ComputePoolSelection, ErrorData> {
770    let machine = match platform {
771        Platform::Aws | Platform::Gcp | Platform::Azure => Some(
772            match match room {
773                Some(pool_room) => {
774                    // The machines the pool launches with: the installer's choice when it
775                    // made one, the release's default otherwise.
776                    let launch_machines = pool_room
777                        .machines
778                        .unwrap_or(match scale {
779                            CapacityGroupScalePolicy::Fixed { machines } => machines.default,
780                            CapacityGroupScalePolicy::Autoscale { min, .. } => min.default,
781                        })
782                        .max(1);
783                    instance_catalog::select_instance_type_with_room(
784                        platform,
785                        requirements,
786                        launch_machines,
787                        &|spec, machines| {
788                            pool_room.room.has_room(pool_room.pool_id, spec, machines)
789                        },
790                    )
791                }
792                None => instance_catalog::select_instance_type(platform, requirements),
793            } {
794                Ok(selection) => selection.instance_type.to_string(),
795                Err(message) => {
796                    // Automatic recommendations add headroom. A valid explicit
797                    // machine remains usable even when no catalog entry can
798                    // provide that extra headroom.
799                    let fallback = machine_override
800                        .and_then(|machine| instance_catalog::find_instance_type(platform, machine))
801                        .filter(|spec| {
802                            instance_satisfies(
803                                spec,
804                                requirements,
805                                requirements.architecture.unwrap_or(spec.architecture),
806                            )
807                        });
808                    fallback.map(|spec| spec.name.to_string()).ok_or_else(|| {
809                        AlienError::new(ErrorData::GenericError {
810                            message: format!("Failed to select {platform} machine: {message}"),
811                        })
812                    })?
813                }
814            },
815        ),
816        Platform::Local | Platform::Kubernetes | Platform::Machines | Platform::Test => None,
817    };
818
819    let failure_domains = (requires_failure_domain
820        && matches!(platform, Platform::Aws | Platform::Gcp | Platform::Azure))
821    .then(default_persistent_failure_domains);
822
823    match scale {
824        CapacityGroupScalePolicy::Fixed { machines } => Ok(ComputePoolSelection::Fixed {
825            machines: machines.default.max(1),
826            machine,
827            failure_domains,
828            data_disk_gib: None,
829        }),
830        // Workloads that never scale need no autoscaling fleet, even where any mode is allowed.
831        CapacityGroupScalePolicy::Autoscale { min, max }
832            if generated && min.default == max.default =>
833        {
834            Ok(ComputePoolSelection::Fixed {
835                machines: min.default.max(1),
836                machine,
837                failure_domains,
838                data_disk_gib: None,
839            })
840        }
841        CapacityGroupScalePolicy::Autoscale { min, max } => Ok(ComputePoolSelection::Autoscale {
842            min: min.default,
843            max: max.default.max(min.default),
844            machine,
845            failure_domains,
846            data_disk_gib: None,
847        }),
848    }
849}
850
851/// Validate one selected compute pool against platform machine requirements and
852/// source-declared scale bounds.
853pub fn validate_compute_pool_selection(
854    platform: Platform,
855    pool_id: &str,
856    selection: &ComputePoolSelection,
857    requirements: &WorkloadRequirements,
858    scale: &CapacityGroupScalePolicy,
859) -> Vec<String> {
860    let mut errors = Vec::new();
861    if let Err(message) = selection.validate() {
862        errors.push(message);
863    }
864    if let Err(message) = validate_selection_against_scale(selection, scale) {
865        errors.push(format!("Pool '{pool_id}' {message}"));
866    }
867    if matches!(platform, Platform::Aws | Platform::Gcp | Platform::Azure) {
868        match selection.machine() {
869            Some(machine) => match instance_catalog::find_instance_type(platform, machine) {
870                Some(spec) => {
871                    let architecture = requirements.architecture.unwrap_or(spec.architecture);
872                    if !instance_satisfies(spec, requirements, architecture) {
873                        errors.push(format!(
874                            "{} machine '{}' does not satisfy pool '{}' requirements",
875                            platform, machine, pool_id
876                        ));
877                    }
878                }
879                None => errors.push(format!(
880                    "Unknown {} machine '{}' for pool '{}'",
881                    platform, machine, pool_id
882                )),
883            },
884            None => errors.push(format!(
885                "Pool '{}' requires a provider machine on {}",
886                pool_id, platform
887            )),
888        }
889    }
890    errors
891}
892
893/// Convert a capacity group declaration into planner requirements.
894pub fn capacity_group_requirements(group: &CapacityGroup) -> WorkloadRequirements {
895    profile_to_requirements(
896        group.profile.as_ref(),
897        group.nested_virtualization.unwrap_or(false),
898    )
899}
900
901fn machine_options(
902    platform: Platform,
903    requirements: &WorkloadRequirements,
904    workload_requirements: Option<&WorkloadRequirements>,
905    selected_machine: Option<&str>,
906    recommended_machine: Option<&str>,
907) -> Result<Vec<ComputeMachineOption>, ErrorData> {
908    if !matches!(platform, Platform::Aws | Platform::Gcp | Platform::Azure) {
909        return Ok(Vec::new());
910    }
911    let resolved_architecture = requirements
912        .architecture
913        .or_else(|| {
914            selected_machine.and_then(|machine| {
915                instance_catalog::find_instance_type(platform, machine)
916                    .map(|spec| spec.architecture)
917            })
918        })
919        .or_else(|| {
920            recommended_machine
921                .and_then(|machine| instance_catalog::find_instance_type(platform, machine))
922                .map(|spec| spec.architecture)
923        })
924        .ok_or_else(|| {
925            AlienError::new(ErrorData::GenericError {
926                message: format!("Selected {platform} machine has no CPU architecture"),
927            })
928        })?;
929
930    Ok(instance_catalog::catalog_for_platform(platform)
931        .into_iter()
932        .map(|spec| {
933            let unavailable_reasons = unavailable_reasons(
934                spec,
935                requirements,
936                resolved_architecture,
937                match workload_requirements {
938                    Some(workloads) => Fit::OneReplica(workloads),
939                    None => Fit::Hardware,
940                },
941            );
942            ComputeMachineOption {
943                machine: spec.name.to_string(),
944                series: spec.series.to_string(),
945                category: spec.family,
946                label: spec.label.to_string(),
947                profile: spec
948                    .to_machine_profile_for_storage(requirements.max_ephemeral_storage_bytes),
949                nested_virtualization: spec.is_nested_virt_capable(),
950                local_storage: (spec.local_disk_bytes > 0).then_some(spec.local_disk_bytes),
951                available: unavailable_reasons.is_empty(),
952                unavailable_reasons,
953                recommended: Some(spec.name) == recommended_machine
954                    || Some(spec.name) == selected_machine,
955            }
956        })
957        .collect())
958}
959
960fn instance_satisfies(
961    spec: &instance_catalog::InstanceTypeSpec,
962    requirements: &WorkloadRequirements,
963    resolved_architecture: Architecture,
964) -> bool {
965    unavailable_reasons(spec, requirements, resolved_architecture, Fit::Hardware).is_empty()
966}
967
968/// How `unavailable_reasons` compares a replica's CPU and memory with a machine.
969#[derive(Clone, Copy)]
970enum Fit<'a> {
971    /// Against the machine's hardware totals: what selection validation has always accepted,
972    /// so an explicit choice that validated before still does.
973    Hardware,
974    /// Also against what is left after the host reserve for one replica of the pool's
975    /// workloads, as the pool capacity check does. A pool without workloads carries only its
976    /// machine profile, which describes the machine itself, so it uses `Hardware`.
977    OneReplica(&'a WorkloadRequirements),
978}
979
980/// Every pool requirement `spec` fails, in a fixed order. The fit rule behind both the
981/// machine list and selection validation.
982fn unavailable_reasons(
983    spec: &instance_catalog::InstanceTypeSpec,
984    requirements: &WorkloadRequirements,
985    resolved_architecture: Architecture,
986    fit: Fit<'_>,
987) -> Vec<MachineUnavailableReason> {
988    let mut reasons = Vec::new();
989    if spec.architecture != resolved_architecture {
990        reasons.push(MachineUnavailableReason::Architecture);
991    }
992    if requirements.nested_virt && !spec.is_nested_virt_capable() {
993        reasons.push(MachineUnavailableReason::NestedVirtualization);
994    }
995    let mut cpu_fits = spec.vcpu >= requirements.max_cpu_per_container.ceil() as u32;
996    let mut memory_fits = spec.memory_bytes >= requirements.max_memory_per_container;
997    if let Fit::OneReplica(workloads) = fit {
998        cpu_fits &= instance_catalog::allocatable_cpu(spec) + f64::EPSILON
999            >= workloads.max_cpu_per_container;
1000        memory_fits &=
1001            instance_catalog::allocatable_memory_bytes(spec) >= workloads.max_memory_per_container;
1002    }
1003    if !cpu_fits {
1004        reasons.push(MachineUnavailableReason::Cpu);
1005    }
1006    if !memory_fits {
1007        reasons.push(MachineUnavailableReason::Memory);
1008    }
1009    let storage_fits = if spec.has_configurable_ephemeral_storage() {
1010        crate::instance_catalog::max_configurable_ephemeral_storage_bytes(spec.platform)
1011            .is_some_and(|max| requirements.max_ephemeral_storage_bytes <= max)
1012    } else {
1013        spec.ephemeral_storage_bytes >= requirements.max_ephemeral_storage_bytes
1014    };
1015    if !storage_fits {
1016        reasons.push(MachineUnavailableReason::EphemeralStorage);
1017    }
1018    let gpu_fits = match (&requirements.gpu, spec.gpu) {
1019        (Some(required), Some(actual)) => {
1020            (required.gpu_type == "any" || required.gpu_type == actual.gpu_type)
1021                && actual.count >= required.count
1022        }
1023        (Some(_), None) => false,
1024        (None, _) => true,
1025    };
1026    if !gpu_fits {
1027        reasons.push(MachineUnavailableReason::Gpu);
1028    }
1029    reasons
1030}
1031
1032#[derive(Debug, Clone)]
1033struct Workload {
1034    id: String,
1035    cpu: f64,
1036    memory_bytes: u64,
1037    desired_replicas: f64,
1038    max_replicas: f64,
1039    ephemeral_storage_bytes: u64,
1040    gpu: Option<GpuSpec>,
1041    requires_failure_domain: bool,
1042    /// A rolling update starts a new replica before it stops an old one.
1043    starts_before_stop: bool,
1044}
1045
1046impl Workload {
1047    fn from_container(container: &Container) -> Result<Self, ErrorData> {
1048        let cpu = parse_cpu(&container.id, &container.cpu)?;
1049        let memory_bytes = parse_memory(&container.id, &container.memory)?;
1050        let desired_replicas = container
1051            .autoscaling
1052            .as_ref()
1053            .map(|a| a.desired)
1054            .or(container.replicas)
1055            .unwrap_or(1) as f64;
1056        let max_replicas = container
1057            .autoscaling
1058            .as_ref()
1059            .map(|a| a.max)
1060            .or(container.replicas)
1061            .unwrap_or(1) as f64;
1062        let ephemeral_storage_bytes = container
1063            .ephemeral_storage
1064            .as_deref()
1065            .map(instance_catalog::parse_memory_bytes)
1066            .transpose()
1067            .map_err(|message| {
1068                AlienError::new(ErrorData::GenericError {
1069                    message: format!(
1070                        "Failed to parse ephemeral storage for '{}': {message}",
1071                        container.id
1072                    ),
1073                })
1074            })?
1075            .unwrap_or(0);
1076
1077        Ok(Self {
1078            id: container.id.clone(),
1079            cpu,
1080            memory_bytes,
1081            desired_replicas,
1082            max_replicas,
1083            ephemeral_storage_bytes,
1084            gpu: container.gpu.as_ref().map(|gpu| GpuSpec {
1085                gpu_type: gpu.gpu_type.clone(),
1086                count: gpu.count,
1087            }),
1088            requires_failure_domain: container.stateful && container.persistent_storage.is_some(),
1089            starts_before_stop: !container.stateful,
1090        })
1091    }
1092
1093    fn from_daemon(daemon: &Daemon) -> Result<Self, ErrorData> {
1094        Ok(Self {
1095            id: daemon.id.clone(),
1096            cpu: parse_cpu(&daemon.id, &daemon.cpu)?,
1097            memory_bytes: parse_memory(&daemon.id, &daemon.memory)?,
1098            desired_replicas: 1.0,
1099            max_replicas: 1.0,
1100            ephemeral_storage_bytes: 0,
1101            gpu: None,
1102            requires_failure_domain: false,
1103            starts_before_stop: false,
1104        })
1105    }
1106}
1107
1108fn parse_cpu(resource_id: &str, spec: &ResourceSpec) -> Result<f64, ErrorData> {
1109    instance_catalog::parse_cpu(&spec.desired).map_err(|message| {
1110        AlienError::new(ErrorData::GenericError {
1111            message: format!(
1112                "Failed to parse CPU requirement '{}' for '{}': {message}",
1113                spec.desired, resource_id
1114            ),
1115        })
1116    })
1117}
1118
1119fn parse_memory(resource_id: &str, spec: &ResourceSpec) -> Result<u64, ErrorData> {
1120    instance_catalog::parse_memory_bytes(&spec.desired).map_err(|message| {
1121        AlienError::new(ErrorData::GenericError {
1122            message: format!(
1123                "Failed to parse memory requirement '{}' for '{}': {message}",
1124                spec.desired, resource_id
1125            ),
1126        })
1127    })
1128}
1129
1130fn aggregate_workloads(workloads: &[Workload]) -> WorkloadRequirements {
1131    let mut requirements = default_requirements();
1132    requirements.total_cpu_at_desired = 0.0;
1133    requirements.total_memory_bytes_at_desired = 0;
1134    requirements.total_cpu_at_max = 0.0;
1135    requirements.total_memory_bytes_at_max = 0;
1136    requirements.max_cpu_per_container = 0.0;
1137    requirements.max_memory_per_container = 0;
1138    requirements.max_ephemeral_storage_bytes = 0;
1139    requirements.gpu = None;
1140
1141    for workload in workloads {
1142        requirements.total_cpu_at_desired += workload.cpu * workload.desired_replicas;
1143        requirements.total_cpu_at_max += workload.cpu * workload.max_replicas;
1144        requirements.total_memory_bytes_at_desired +=
1145            (workload.memory_bytes as f64 * workload.desired_replicas) as u64;
1146        requirements.total_memory_bytes_at_max +=
1147            (workload.memory_bytes as f64 * workload.max_replicas) as u64;
1148        requirements.max_cpu_per_container = requirements.max_cpu_per_container.max(workload.cpu);
1149        requirements.max_memory_per_container = requirements
1150            .max_memory_per_container
1151            .max(workload.memory_bytes);
1152        requirements.max_ephemeral_storage_bytes = requirements
1153            .max_ephemeral_storage_bytes
1154            .max(workload.ephemeral_storage_bytes);
1155        if requirements.gpu.is_none() {
1156            requirements.gpu = workload.gpu.clone();
1157        }
1158    }
1159    requirements
1160}
1161
1162fn default_requirements() -> WorkloadRequirements {
1163    WorkloadRequirements {
1164        total_cpu_at_desired: 1.0,
1165        total_memory_bytes_at_desired: 2 * 1024 * 1024 * 1024,
1166        total_cpu_at_max: 1.0,
1167        total_memory_bytes_at_max: 2 * 1024 * 1024 * 1024,
1168        max_cpu_per_container: 1.0,
1169        max_memory_per_container: 2 * 1024 * 1024 * 1024,
1170        max_ephemeral_storage_bytes: 0,
1171        gpu: None,
1172        architecture: None,
1173        nested_virt: false,
1174    }
1175}
1176
1177fn profile_to_requirements(
1178    profile: Option<&MachineProfile>,
1179    nested_virt: bool,
1180) -> WorkloadRequirements {
1181    let Some(profile) = profile else {
1182        return WorkloadRequirements {
1183            nested_virt,
1184            ..default_requirements()
1185        };
1186    };
1187    let cpu = instance_catalog::parse_cpu(&profile.cpu).unwrap_or(1.0);
1188    WorkloadRequirements {
1189        total_cpu_at_desired: cpu,
1190        total_memory_bytes_at_desired: profile.memory_bytes,
1191        total_cpu_at_max: cpu,
1192        total_memory_bytes_at_max: profile.memory_bytes,
1193        max_cpu_per_container: cpu,
1194        max_memory_per_container: profile.memory_bytes,
1195        max_ephemeral_storage_bytes: profile.ephemeral_storage_bytes,
1196        gpu: profile.gpu.clone(),
1197        architecture: profile.architecture,
1198        nested_virt,
1199    }
1200}
1201
1202fn merge_requirements(existing: &mut WorkloadRequirements, declared: &WorkloadRequirements) {
1203    existing.total_cpu_at_desired = existing
1204        .total_cpu_at_desired
1205        .max(declared.total_cpu_at_desired);
1206    existing.total_memory_bytes_at_desired = existing
1207        .total_memory_bytes_at_desired
1208        .max(declared.total_memory_bytes_at_desired);
1209    existing.total_cpu_at_max = existing.total_cpu_at_max.max(declared.total_cpu_at_max);
1210    existing.total_memory_bytes_at_max = existing
1211        .total_memory_bytes_at_max
1212        .max(declared.total_memory_bytes_at_max);
1213    existing.max_cpu_per_container = existing
1214        .max_cpu_per_container
1215        .max(declared.max_cpu_per_container);
1216    existing.max_memory_per_container = existing
1217        .max_memory_per_container
1218        .max(declared.max_memory_per_container);
1219    existing.max_ephemeral_storage_bytes = existing
1220        .max_ephemeral_storage_bytes
1221        .max(declared.max_ephemeral_storage_bytes);
1222    if existing.gpu.is_none() {
1223        existing.gpu = declared.gpu.clone();
1224    }
1225    existing.nested_virt |= declared.nested_virt;
1226    if existing.architecture.is_none() {
1227        existing.architecture = declared.architecture;
1228    }
1229}
1230
1231fn requirements_to_profile(requirements: &WorkloadRequirements) -> MachineProfile {
1232    MachineProfile {
1233        cpu: requirements.max_cpu_per_container.to_string(),
1234        memory_bytes: requirements.max_memory_per_container,
1235        ephemeral_storage_bytes: requirements.max_ephemeral_storage_bytes,
1236        architecture: requirements.architecture,
1237        gpu: requirements.gpu.clone(),
1238        data_disk: None,
1239    }
1240}
1241
1242fn merge_scale_policy(
1243    existing: &CapacityGroupScalePolicy,
1244    declared: &CapacityGroupScalePolicy,
1245) -> CapacityGroupScalePolicy {
1246    match (existing, declared) {
1247        (
1248            CapacityGroupScalePolicy::Fixed {
1249                machines: existing_machines,
1250            },
1251            CapacityGroupScalePolicy::Fixed {
1252                machines: declared_machines,
1253            },
1254        ) => CapacityGroupScalePolicy::Fixed {
1255            machines: merge_choice_range(existing_machines, declared_machines),
1256        },
1257        (_, declared) => declared.clone(),
1258    }
1259}
1260
1261fn merge_choice_range(
1262    existing: &ComputeChoiceRange,
1263    declared: &ComputeChoiceRange,
1264) -> ComputeChoiceRange {
1265    ComputeChoiceRange {
1266        min: existing.min.max(declared.min),
1267        max: existing.max.max(declared.max),
1268        default: declared.default,
1269    }
1270}
1271
1272fn validate_selection_against_scale(
1273    selection: &ComputePoolSelection,
1274    scale: &CapacityGroupScalePolicy,
1275) -> std::result::Result<(), String> {
1276    // A fixed pool of N machines and an autoscaling pool bounded to N..N run the same
1277    // fleet, so either form is accepted wherever the other one is.
1278    match (selection, scale) {
1279        (
1280            ComputePoolSelection::Fixed { machines, .. },
1281            CapacityGroupScalePolicy::Fixed { machines: allowed },
1282        ) => check_machine_count("fixed machine count", *machines, allowed.min, allowed.max),
1283        (
1284            ComputePoolSelection::Autoscale { min, max, .. },
1285            CapacityGroupScalePolicy::Autoscale {
1286                min: allowed_min,
1287                max: allowed_max,
1288            },
1289        ) => {
1290            check_machine_count("autoscale minimum", *min, allowed_min.min, allowed_min.max)?;
1291            check_machine_count("autoscale maximum", *max, allowed_max.min, allowed_max.max)
1292        }
1293        (
1294            ComputePoolSelection::Fixed { machines, .. },
1295            CapacityGroupScalePolicy::Autoscale {
1296                min: allowed_min,
1297                max: allowed_max,
1298            },
1299        ) => {
1300            let lowest = allowed_min.min.max(allowed_max.min);
1301            let highest = allowed_min.max.min(allowed_max.max);
1302            if lowest > highest {
1303                return Err(format!(
1304                    "must use autoscale mode (minimum {}-{}, maximum {}-{})",
1305                    allowed_min.min, allowed_min.max, allowed_max.min, allowed_max.max
1306                ));
1307            }
1308            check_machine_count("fixed machine count", *machines, lowest, highest)
1309        }
1310        (
1311            ComputePoolSelection::Autoscale { min, max, .. },
1312            CapacityGroupScalePolicy::Fixed { machines: allowed },
1313        ) => {
1314            if min != max {
1315                return Err(format!(
1316                    "must use fixed mode with {}-{} machines; autoscale {min}-{max} is not allowed",
1317                    allowed.min, allowed.max
1318                ));
1319            }
1320            check_machine_count("machine count", *min, allowed.min, allowed.max)
1321        }
1322    }
1323}
1324
1325fn check_machine_count(
1326    label: &str,
1327    value: u32,
1328    lowest: u32,
1329    highest: u32,
1330) -> std::result::Result<(), String> {
1331    if (lowest..=highest).contains(&value) {
1332        Ok(())
1333    } else {
1334        Err(format!(
1335            "{label} {value} is outside the allowed range {lowest}-{highest}"
1336        ))
1337    }
1338}
1339
1340fn needed_container_pool(container: &Container) -> &'static str {
1341    if container.stateful && container.persistent_storage.is_some() {
1342        return "stateful";
1343    }
1344    if container.gpu.is_some() {
1345        return "gpu";
1346    }
1347    if let Some(storage) = &container.ephemeral_storage {
1348        if instance_catalog::parse_memory_bytes(storage).unwrap_or(0) > 200 * 1024 * 1024 * 1024 {
1349            return "storage";
1350        }
1351    }
1352    "general"
1353}
1354
1355fn default_min_machines(requirements: &WorkloadRequirements) -> u32 {
1356    if requirements.total_cpu_at_desired > 0.0 || requirements.total_memory_bytes_at_desired > 0 {
1357        1
1358    } else {
1359        0
1360    }
1361}
1362
1363fn default_max_machines(requirements: &WorkloadRequirements) -> u32 {
1364    let min = default_min_machines(requirements);
1365    let by_cpu =
1366        (requirements.total_cpu_at_max / requirements.max_cpu_per_container.max(1.0)).ceil() as u32;
1367    let by_mem = requirements
1368        .total_memory_bytes_at_max
1369        .div_ceil(requirements.max_memory_per_container.max(1)) as u32;
1370    min.max(by_cpu).max(by_mem).max(1)
1371}
1372
1373#[cfg(test)]
1374mod tests {
1375    use super::*;
1376    use crate::{
1377        instance_catalog::Architecture, CapacityGroup, CapacityGroupScalePolicy,
1378        ComputeChoiceRange, ComputeCluster, ComputeSettings, ContainerCode, DaemonCode, Resource,
1379        ResourceEntry, ResourceLifecycle, Stack, Storage, Worker, WorkerCode,
1380    };
1381
1382    #[test]
1383    fn deployment_resources_drive_machine_planning_on_every_cloud() {
1384        let mut stack = stack_with_container();
1385        let container = stack
1386            .resources
1387            .get_mut("api")
1388            .unwrap()
1389            .config
1390            .downcast_mut::<Container>()
1391            .unwrap();
1392        container.resource_choices = Some(crate::ContainerResourceChoices {
1393            cpu: Some(crate::ResourceChoiceRange {
1394                min: "0.5".into(),
1395                max: "8".into(),
1396                default: "2".into(),
1397            }),
1398            memory: Some(crate::ResourceChoiceRange {
1399                min: "512Mi".into(),
1400                max: "16Gi".into(),
1401                default: "4Gi".into(),
1402            }),
1403        });
1404        let settings: ComputeSettings = serde_json::from_value(serde_json::json!({
1405            "pools": { "general": { "mode": "fixed", "machines": 1 } },
1406            "containers": { "api": { "cpu": 8, "memory": "16Gi" } }
1407        }))
1408        .unwrap();
1409        for platform in [Platform::Aws, Platform::Gcp, Platform::Azure] {
1410            let default_plan = plan_compute(&stack, platform, None).unwrap();
1411            let selected_plan = plan_compute(&stack, platform, Some(&settings)).unwrap();
1412            let pool = &selected_plan.pools[0];
1413            assert!(pool.errors.is_empty(), "{platform}: {:?}", pool.errors);
1414            assert_eq!(pool.requirements.cpu, "8");
1415            assert_eq!(pool.requirements.memory_bytes, 16 * 1024 * 1024 * 1024);
1416            assert_ne!(
1417                pool.selected.machine(),
1418                default_plan.pools[0].selected.machine()
1419            );
1420            assert_eq!(selected_plan.containers[0].cpu.min, "8");
1421            assert_eq!(selected_plan.containers[0].memory.desired, "16Gi");
1422            assert_eq!(pool.selected.min_size(), 1);
1423            assert_eq!(pool.selected.max_size(), 1);
1424        }
1425        assert_eq!(
1426            settings.pools["general"].machine(),
1427            None,
1428            "resolving a plan must preserve automatic machine intent"
1429        );
1430        let original = stack.resources["api"]
1431            .config
1432            .downcast_ref::<Container>()
1433            .unwrap();
1434        assert_eq!(
1435            original.cpu.desired, "2",
1436            "planning must not mutate release defaults"
1437        );
1438    }
1439
1440    #[test]
1441    fn explicit_machine_can_fit_a_low_cpu_high_memory_workload() {
1442        let mut stack = stack_with_container();
1443        let container = stack
1444            .resources
1445            .get_mut("api")
1446            .unwrap()
1447            .config
1448            .downcast_mut::<Container>()
1449            .unwrap();
1450        container.cpu = ResourceSpec {
1451            min: "0.5".into(),
1452            desired: "0.5".into(),
1453        };
1454        container.memory = ResourceSpec {
1455            min: "8Gi".into(),
1456            desired: "8Gi".into(),
1457        };
1458        let settings: ComputeSettings = serde_json::from_value(serde_json::json!({
1459            "pools": {"general":{"mode":"fixed","machines":1,"machine":"n2-standard-4"}}
1460        }))
1461        .unwrap();
1462        let plan = plan_compute(&stack, Platform::Gcp, Some(&settings)).unwrap();
1463        assert!(
1464            plan.pools[0].errors.is_empty(),
1465            "{:?}",
1466            plan.pools[0].errors
1467        );
1468        assert_eq!(plan.pools[0].selected.machine(), Some("n2-standard-4"));
1469    }
1470
1471    #[test]
1472    fn pin_must_leave_host_capacity_for_one_replica() {
1473        let mut stack = stack_with_container();
1474        stack
1475            .resources
1476            .get_mut("api")
1477            .unwrap()
1478            .config
1479            .downcast_mut::<Container>()
1480            .unwrap()
1481            .cpu = ResourceSpec {
1482            min: "4".into(),
1483            desired: "4".into(),
1484        };
1485        let settings: ComputeSettings = serde_json::from_value(serde_json::json!({
1486            "pools":{"general":{"mode":"fixed","machines":1,"machine":"t3.xlarge"}}
1487        }))
1488        .unwrap();
1489        let plan = plan_compute(&stack, Platform::Aws, Some(&settings)).unwrap();
1490        assert!(
1491            plan.pools[0]
1492                .errors
1493                .iter()
1494                .any(|error| error.contains("host resources")),
1495            "{:?}",
1496            plan.pools[0].errors
1497        );
1498    }
1499
1500    #[test]
1501    fn valid_pin_does_not_require_automatic_recommendation_headroom() {
1502        let machine = instance_catalog::catalog_for_platform(Platform::Gcp)
1503            .into_iter()
1504            .max_by_key(|machine| machine.memory_bytes)
1505            .unwrap();
1506        let mut stack = stack_with_container();
1507        let container = stack
1508            .resources
1509            .get_mut("api")
1510            .unwrap()
1511            .config
1512            .downcast_mut::<Container>()
1513            .unwrap();
1514        container.cpu = ResourceSpec {
1515            min: "0.5".into(),
1516            desired: "0.5".into(),
1517        };
1518        let memory = instance_catalog::allocatable_memory_bytes(machine).to_string();
1519        container.memory = ResourceSpec {
1520            min: memory.clone(),
1521            desired: memory,
1522        };
1523        assert!(plan_compute(&stack, Platform::Gcp, None).is_err());
1524        let settings: ComputeSettings = serde_json::from_value(serde_json::json!({
1525            "pools":{"general":{"mode":"fixed","machines":1,"machine":machine.name}}
1526        }))
1527        .unwrap();
1528        let plan = plan_compute(&stack, Platform::Gcp, Some(&settings)).unwrap();
1529        assert!(
1530            plan.pools[0].errors.is_empty(),
1531            "{:?}",
1532            plan.pools[0].errors
1533        );
1534        assert_eq!(plan.pools[0].selected.machine(), Some(machine.name));
1535    }
1536
1537    #[test]
1538    fn invalid_deployment_resources_fail_before_capacity_planning() {
1539        let mut stack = stack_with_container();
1540        stack
1541            .resources
1542            .get_mut("api")
1543            .unwrap()
1544            .config
1545            .downcast_mut::<Container>()
1546            .unwrap()
1547            .resource_choices = Some(crate::ContainerResourceChoices {
1548            cpu: Some(crate::ResourceChoiceRange {
1549                min: "0.5".into(),
1550                max: "4".into(),
1551                default: "2".into(),
1552            }),
1553            memory: Some(crate::ResourceChoiceRange {
1554                min: "512Mi".into(),
1555                max: "8Gi".into(),
1556                default: "4Gi".into(),
1557            }),
1558        });
1559        for selection in [
1560            serde_json::json!({"api":{"cpu": 0}}),
1561            serde_json::json!({"api":{"cpu": 5}}),
1562            serde_json::json!({"api":{"memory": "16Gi"}}),
1563            serde_json::json!({"api":{"memory": "NaNGi"}}),
1564            serde_json::json!({"api":{"memory": "-1Gi"}}),
1565            serde_json::json!({"missing":{"cpu": 1}}),
1566        ] {
1567            let settings: ComputeSettings =
1568                serde_json::from_value(serde_json::json!({"containers": selection})).unwrap();
1569            let error = plan_compute(&stack, Platform::Aws, Some(&settings)).unwrap_err();
1570            assert_eq!(error.code, "CONTAINER_RESOURCE_SELECTION_INVALID");
1571        }
1572    }
1573
1574    #[test]
1575    fn deployment_volume_selection_is_applied_without_changing_release_defaults() {
1576        let mut release = stack_with_container();
1577        release
1578            .resources
1579            .get_mut("api")
1580            .unwrap()
1581            .config
1582            .downcast_mut::<Container>()
1583            .unwrap()
1584            .persistent_storage = Some(crate::PersistentStorage {
1585            size: "20Gi".into(),
1586            mount_path: "/data".into(),
1587            backups: crate::VolumeBackups::default(),
1588            encryption_key: None,
1589        });
1590        let settings: ComputeSettings = serde_json::from_value(serde_json::json!({
1591            "containers": {"api": {"volumeSizeGib": 40}}
1592        }))
1593        .unwrap();
1594        let mut deployment = release.clone();
1595        crate::container_resources::resolve_container_resources(&mut deployment, Some(&settings))
1596            .unwrap();
1597        let volume = |stack: &Stack| {
1598            stack.resources["api"]
1599                .config
1600                .downcast_ref::<Container>()
1601                .unwrap()
1602                .persistent_storage
1603                .as_ref()
1604                .unwrap()
1605                .size
1606                .clone()
1607        };
1608        assert_eq!(volume(&deployment), "40Gi");
1609        assert_eq!(volume(&release), "20Gi");
1610        let mut equivalent = release.clone();
1611        equivalent
1612            .resources
1613            .get_mut("api")
1614            .unwrap()
1615            .config
1616            .downcast_mut::<Container>()
1617            .unwrap()
1618            .persistent_storage
1619            .as_mut()
1620            .unwrap()
1621            .size = "1Ti".into();
1622        let same_capacity: ComputeSettings = serde_json::from_value(serde_json::json!({
1623            "containers": {"api": {"volumeSizeGib": 1024}}
1624        }))
1625        .unwrap();
1626        crate::container_resources::resolve_container_resources(
1627            &mut equivalent,
1628            Some(&same_capacity),
1629        )
1630        .unwrap();
1631        assert_eq!(
1632            volume(&equivalent),
1633            "1Ti",
1634            "equivalent selections preserve PVC quantities"
1635        );
1636        crate::container_resources::resolve_container_resources(&mut deployment, Some(&settings))
1637            .unwrap();
1638        assert_eq!(volume(&deployment), "40Gi");
1639        let smaller_initial: ComputeSettings = serde_json::from_value(serde_json::json!({
1640            "containers": {"api": {"volumeSizeGib": 10}}
1641        }))
1642        .unwrap();
1643        crate::container_resources::resolve_container_resources(
1644            &mut release.clone(),
1645            Some(&smaller_initial),
1646        )
1647        .unwrap();
1648        let mut installed = StackState::new(Platform::Aws);
1649        installed.resources.insert(
1650            "api".into(),
1651            crate::StackResourceState::new_pending(
1652                "Container".into(),
1653                deployment.resources["api"].config.clone(),
1654                None,
1655                vec![],
1656            ),
1657        );
1658        let shrinking: ComputeSettings = serde_json::from_value(serde_json::json!({
1659            "containers": {"api": {"volumeSizeGib": 30}}
1660        }))
1661        .unwrap();
1662        let error =
1663            plan_compute_with_state(&release, Platform::Aws, Some(&shrinking), Some(&installed))
1664                .unwrap_err();
1665        assert_eq!(error.code, "CONTAINER_RESOURCE_SELECTION_INVALID");
1666        assert!(error.to_string().contains("cannot shrink from 40 to 30"));
1667        let imported: ComputeSettings = serde_json::from_value(serde_json::json!({
1668            "containers": {"api": {"volumeSizeGib": "40"}}
1669        }))
1670        .unwrap();
1671        assert_eq!(imported.containers["api"].volume_size_gib, Some(40));
1672        for value in [
1673            serde_json::json!(-1),
1674            serde_json::json!(1.5),
1675            serde_json::json!("4294967296"),
1676        ] {
1677            assert!(
1678                serde_json::from_value::<ComputeSettings>(serde_json::json!({
1679                    "containers": {"api": {"volumeSizeGib": value}}
1680                }))
1681                .is_err()
1682            );
1683        }
1684        for (platform, size) in [(Platform::Gcp, 9), (Platform::Azure, 32768)] {
1685            let invalid: ComputeSettings = serde_json::from_value(serde_json::json!({
1686                "containers": {"api": {"volumeSizeGib": size}}
1687            }))
1688            .unwrap();
1689            let error = plan_compute(&release, platform, Some(&invalid)).unwrap_err();
1690            assert_eq!(error.code, "CONTAINER_RESOURCE_SELECTION_INVALID");
1691            assert!(error.to_string().contains("must be between"));
1692        }
1693        for size in [0, 65537] {
1694            let invalid: ComputeSettings = serde_json::from_value(serde_json::json!({
1695                "containers": {"api": {"volumeSizeGib": size}}
1696            }))
1697            .unwrap();
1698            assert_eq!(
1699                crate::container_resources::resolve_container_resources(
1700                    &mut release.clone(),
1701                    Some(&invalid)
1702                )
1703                .unwrap_err()
1704                .code,
1705                "CONTAINER_RESOURCE_SELECTION_INVALID"
1706            );
1707        }
1708        assert_eq!(
1709            crate::container_resources::resolve_container_resources(
1710                &mut stack_with_container(),
1711                Some(&settings)
1712            )
1713            .unwrap_err()
1714            .code,
1715            "CONTAINER_RESOURCE_SELECTION_INVALID"
1716        );
1717    }
1718
1719    fn stack_with_volume(size: &str) -> Stack {
1720        let mut stack = stack_with_container();
1721        stack
1722            .resources
1723            .get_mut("api")
1724            .unwrap()
1725            .config
1726            .downcast_mut::<Container>()
1727            .unwrap()
1728            .persistent_storage = Some(crate::PersistentStorage {
1729            size: size.into(),
1730            mount_path: "/data".into(),
1731            backups: crate::VolumeBackups::default(),
1732            encryption_key: None,
1733        });
1734        stack
1735    }
1736
1737    fn installed_with_volume(platform: Platform, size: &str) -> StackState {
1738        let mut installed = StackState::new(platform);
1739        installed.resources.insert(
1740            "api".into(),
1741            crate::StackResourceState::new_pending(
1742                "Container".into(),
1743                stack_with_volume(size).resources["api"].config.clone(),
1744                None,
1745                vec![],
1746            ),
1747        );
1748        installed
1749    }
1750
1751    fn api_volume(plan: &ComputePlan) -> (Option<u32>, Option<u32>) {
1752        let api = plan
1753            .containers
1754            .iter()
1755            .find(|container| container.container_id == "api")
1756            .expect("api is planned");
1757        (api.volume_size_gib, api.minimum_volume_size_gib)
1758    }
1759
1760    /// A release that lowers its default volume size must not turn into a shrink of every
1761    /// installed deployment that never chose a size: they keep their installed volumes. A
1762    /// larger default still grows them.
1763    #[test]
1764    fn a_lower_release_default_keeps_installed_volumes_without_a_selection() {
1765        for platform in [Platform::Aws, Platform::Gcp, Platform::Azure] {
1766            let installed = installed_with_volume(platform, "30Gi");
1767            let plan = plan_compute_with_state(
1768                &stack_with_volume("20Gi"),
1769                platform,
1770                None,
1771                Some(&installed),
1772            )
1773            .expect("a lower release default keeps the installed volume");
1774            assert_eq!(api_volume(&plan), (Some(30), Some(30)), "{platform}");
1775
1776            let plan = plan_compute_with_state(
1777                &stack_with_volume("40Gi"),
1778                platform,
1779                None,
1780                Some(&installed),
1781            )
1782            .expect("a larger release default grows the volume");
1783            assert_eq!(api_volume(&plan), (Some(40), Some(30)), "{platform}");
1784
1785            // A selection is the deployment's own choice, so it still cannot shrink.
1786            let shrinking: ComputeSettings = serde_json::from_value(serde_json::json!({
1787                "containers": {"api": {"volumeSizeGib": 25}}
1788            }))
1789            .unwrap();
1790            let error = plan_compute_with_state(
1791                &stack_with_volume("20Gi"),
1792                platform,
1793                Some(&shrinking),
1794                Some(&installed),
1795            )
1796            .unwrap_err();
1797            assert!(
1798                error.to_string().contains("cannot shrink from 30 to 25"),
1799                "{error}"
1800            );
1801        }
1802    }
1803
1804    /// Setup sources (CloudFormation parameters, Terraform variables, CLI config files) cannot see
1805    /// growth made through a compute update. Their lower values keep the installed size; equal
1806    /// or larger values, and containers without an installed volume, are left alone.
1807    #[test]
1808    fn setup_source_volume_sizes_below_installed_keep_the_installed_size() {
1809        let mut installed = installed_with_volume(Platform::Aws, "30Gi");
1810        let mut worker = stack_with_volume("10Gi").resources["api"].config.clone();
1811        worker
1812            .downcast_mut::<Container>()
1813            .unwrap()
1814            .persistent_storage = None;
1815        installed.resources.insert(
1816            "worker".into(),
1817            crate::StackResourceState::new_pending("Container".into(), worker, None, vec![]),
1818        );
1819        let mut settings: ComputeSettings = serde_json::from_value(serde_json::json!({
1820            "containers": {
1821                "api": {"volumeSizeGib": 25, "cpu": 2},
1822                "worker": {"volumeSizeGib": 5},
1823                "new": {"volumeSizeGib": 8}
1824            }
1825        }))
1826        .unwrap();
1827
1828        let kept = crate::container_resources::keep_volume_sizes_over_setup_source(
1829            &mut settings,
1830            Some(&installed),
1831            None,
1832        );
1833
1834        assert_eq!(
1835            kept,
1836            vec![crate::container_resources::KeptVolumeSize {
1837                container_id: "api".into(),
1838                requested_gib: 25,
1839                kept_gib: 30,
1840            }]
1841        );
1842        assert_eq!(settings.containers["api"].volume_size_gib, Some(30));
1843        assert_eq!(
1844            settings.containers["api"].cpu,
1845            Some(serde_json::Number::from(2))
1846        );
1847        assert_eq!(settings.containers["worker"].volume_size_gib, Some(5));
1848        assert_eq!(settings.containers["new"].volume_size_gib, Some(8));
1849        let plan = plan_compute_with_state(
1850            &stack_with_volume("20Gi"),
1851            Platform::Aws,
1852            Some(&ComputeSettings {
1853                containers: [("api".to_string(), settings.containers["api"].clone())].into(),
1854                ..Default::default()
1855            }),
1856            Some(&installed_with_volume(Platform::Aws, "30Gi")),
1857        )
1858        .expect("the kept size plans");
1859        assert_eq!(api_volume(&plan), (Some(30), Some(30)));
1860
1861        let mut growing: ComputeSettings = serde_json::from_value(serde_json::json!({
1862            "containers": {"api": {"volumeSizeGib": 35}}
1863        }))
1864        .unwrap();
1865        assert!(
1866            crate::container_resources::keep_volume_sizes_over_setup_source(
1867                &mut growing,
1868                Some(&installed),
1869                None,
1870            )
1871            .is_empty()
1872        );
1873        assert_eq!(growing.containers["api"].volume_size_gib, Some(35));
1874
1875        // A growth the deployment chose but has not applied yet is not undone either.
1876        let chosen: ComputeSettings = serde_json::from_value(serde_json::json!({
1877            "containers": {"api": {"volumeSizeGib": 40}}
1878        }))
1879        .unwrap();
1880        let mut stale: ComputeSettings = serde_json::from_value(serde_json::json!({
1881            "containers": {"api": {"volumeSizeGib": 25}}
1882        }))
1883        .unwrap();
1884        let kept = crate::container_resources::keep_volume_sizes_over_setup_source(
1885            &mut stale,
1886            Some(&installed),
1887            Some(&chosen),
1888        );
1889        assert_eq!(kept[0].kept_gib, 40);
1890        assert_eq!(stale.containers["api"].volume_size_gib, Some(40));
1891
1892        // Before anything is installed (a first install whose preflights failed), a smaller
1893        // value is a correction of the saved choice and is kept as asked.
1894        let mut correction: ComputeSettings = serde_json::from_value(serde_json::json!({
1895            "containers": {"api": {"volumeSizeGib": 20}}
1896        }))
1897        .unwrap();
1898        for nothing_installed in [None, Some(&StackState::new(Platform::Aws))] {
1899            assert!(
1900                crate::container_resources::keep_volume_sizes_over_setup_source(
1901                    &mut correction,
1902                    nothing_installed,
1903                    Some(&chosen),
1904                )
1905                .is_empty()
1906            );
1907            assert_eq!(correction.containers["api"].volume_size_gib, Some(20));
1908        }
1909    }
1910
1911    #[test]
1912    fn installed_storage_cannot_be_removed_or_remounted_on_any_provider() {
1913        for platform in [
1914            Platform::Aws,
1915            Platform::Gcp,
1916            Platform::Azure,
1917            Platform::Kubernetes,
1918        ] {
1919            let mut release = stack_with_container();
1920            release
1921                .resources
1922                .get_mut("api")
1923                .unwrap()
1924                .config
1925                .downcast_mut::<Container>()
1926                .unwrap()
1927                .persistent_storage = Some(crate::PersistentStorage {
1928                size: "20Gi".into(),
1929                mount_path: "/data".into(),
1930                backups: crate::VolumeBackups::default(),
1931                encryption_key: None,
1932            });
1933            let mut installed = StackState::new(platform);
1934            installed.resources.insert(
1935                "api".into(),
1936                crate::StackResourceState::new_pending(
1937                    "Container".into(),
1938                    release.resources["api"].config.clone(),
1939                    None,
1940                    vec![],
1941                ),
1942            );
1943            for remove in [false, true] {
1944                let mut desired = release.clone();
1945                let storage = &mut desired
1946                    .resources
1947                    .get_mut("api")
1948                    .unwrap()
1949                    .config
1950                    .downcast_mut::<Container>()
1951                    .unwrap()
1952                    .persistent_storage;
1953                if remove {
1954                    *storage = None;
1955                } else {
1956                    storage.as_mut().unwrap().mount_path = "/other".into();
1957                }
1958                let error = plan_compute_with_state(&desired, platform, None, Some(&installed))
1959                    .unwrap_err();
1960                assert_eq!(error.code, "CONTAINER_RESOURCE_SELECTION_INVALID");
1961                assert!(
1962                    error.to_string().contains(if remove {
1963                        "removing installed"
1964                    } else {
1965                        "mount path"
1966                    }),
1967                    "{error}"
1968                );
1969            }
1970        }
1971    }
1972
1973    #[test]
1974    fn release_volume_defaults_obey_provider_bounds_without_a_selection() {
1975        for (platform, size) in [(Platform::Gcp, "5Gi"), (Platform::Azure, "40000Gi")] {
1976            let mut stack = stack_with_container();
1977            stack
1978                .resources
1979                .get_mut("api")
1980                .unwrap()
1981                .config
1982                .downcast_mut::<Container>()
1983                .unwrap()
1984                .persistent_storage = Some(crate::PersistentStorage {
1985                size: size.into(),
1986                mount_path: "/data".into(),
1987                backups: crate::VolumeBackups::default(),
1988                encryption_key: None,
1989            });
1990            let error = plan_compute(&stack, platform, None).unwrap_err();
1991            assert_eq!(error.code, "CONTAINER_RESOURCE_SELECTION_INVALID");
1992            assert!(error.to_string().contains("must be between"));
1993        }
1994    }
1995
1996    #[test]
1997    fn volume_capacity_parsing_rejects_overflow_and_preserves_legacy_units() {
1998        use crate::container_resources::parse_volume_size_gib;
1999        for (value, size) in [
2000            ("20Gi", 20),
2001            ("20GiB", 20),
2002            ("20GB", 20),
2003            ("1Ti", 1024),
2004            ("1TB", 1000),
2005            ("1.5Ti", 1536),
2006            ("1536Mi", 2),
2007            ("0.5Gi", 1),
2008            ("1073741824", 1),
2009        ] {
2010            assert_eq!(parse_volume_size_gib(value).unwrap(), size);
2011        }
2012        for value in ["0Gi", "-1Gi", "NaNGi", "4294967295Ti", "65537Gi"] {
2013            assert!(parse_volume_size_gib(value).is_err(), "{value}");
2014        }
2015    }
2016
2017    fn stack_with_container() -> Stack {
2018        let container = Container::new("api".to_string())
2019            .code(ContainerCode::Image {
2020                image: "api:latest".to_string(),
2021            })
2022            .cpu(ResourceSpec {
2023                min: "1".to_string(),
2024                desired: "2".to_string(),
2025            })
2026            .memory(ResourceSpec {
2027                min: "2Gi".to_string(),
2028                desired: "4Gi".to_string(),
2029            })
2030            .permissions("api".to_string())
2031            .build();
2032        Stack {
2033            id: "test".to_string(),
2034            resources: [(
2035                "api".to_string(),
2036                ResourceEntry {
2037                    config: Resource::new(container),
2038                    lifecycle: ResourceLifecycle::Live,
2039                    dependencies: Vec::new(),
2040                    display_name: None,
2041                    description: None,
2042                    remote_access: false,
2043                    enabled_when: None,
2044                },
2045            )]
2046            .into_iter()
2047            .collect(),
2048            permissions: crate::permissions::PermissionsConfig::default(),
2049            supported_platforms: None,
2050            inputs: vec![],
2051            dynamic_container_repositories: Vec::new(),
2052            dynamic_container_image_resources: Vec::new(),
2053            operations: None,
2054            built_architectures: Default::default(),
2055        }
2056    }
2057
2058    #[test]
2059    fn serverless_workers_and_storage_do_not_allocate_machine_pools() {
2060        let mut stack = stack_with_container();
2061        stack.resources.clear();
2062        for (id, resource) in [
2063            (
2064                "api",
2065                Resource::new(
2066                    Worker::new("api".to_string())
2067                        .code(WorkerCode::Image {
2068                            image: "example/worker:v1".to_string(),
2069                        })
2070                        .permissions("execution".to_string())
2071                        .build(),
2072                ),
2073            ),
2074            (
2075                "data",
2076                Resource::new(Storage::new("data".to_string()).build()),
2077            ),
2078        ] {
2079            stack.resources.insert(
2080                id.to_string(),
2081                ResourceEntry {
2082                    config: resource,
2083                    lifecycle: ResourceLifecycle::Frozen,
2084                    dependencies: Vec::new(),
2085                    display_name: None,
2086                    description: None,
2087                    remote_access: false,
2088                    enabled_when: None,
2089                },
2090            );
2091        }
2092
2093        for platform in [Platform::Aws, Platform::Gcp, Platform::Azure] {
2094            let plan = plan_compute(&stack, platform, None).expect("plan should build");
2095            assert!(plan.pools.is_empty(), "serverless plan allocated {plan:?}");
2096        }
2097    }
2098
2099    #[test]
2100    fn empty_stack_does_not_allocate_machine_pools() {
2101        let mut stack = stack_with_container();
2102        stack.resources.clear();
2103        let plan = plan_compute(&stack, Platform::Aws, None).expect("plan should build");
2104        assert!(plan.pools.is_empty());
2105    }
2106
2107    #[test]
2108    fn explicit_cluster_without_workloads_only_plans_declared_pools() {
2109        let mut stack = stack_with_container();
2110        stack.resources.clear();
2111        let cluster = ComputeCluster::new("compute".to_string())
2112            .capacity_group(CapacityGroup {
2113                group_id: "batch".to_string(),
2114                instance_type: Some("t4g.medium".to_string()),
2115                profile: None,
2116                min_size: 1,
2117                max_size: 1,
2118                scale_policy: None,
2119                nested_virtualization: None,
2120                data_disk_gib_range: None,
2121            })
2122            .build();
2123        stack.resources.insert(
2124            "compute".to_string(),
2125            ResourceEntry {
2126                config: Resource::new(cluster),
2127                lifecycle: ResourceLifecycle::Frozen,
2128                dependencies: Vec::new(),
2129                display_name: None,
2130                description: None,
2131                remote_access: false,
2132                enabled_when: None,
2133            },
2134        );
2135
2136        let plan = plan_compute(&stack, Platform::Aws, None).expect("plan should build");
2137        assert_eq!(plan.pools.len(), 1);
2138        assert_eq!(plan.pools[0].pool_id, "batch");
2139        assert!(plan.pools[0].errors.is_empty());
2140    }
2141
2142    #[test]
2143    fn cloud_plan_recommends_provider_machine_without_mutating_selection() {
2144        let stack = stack_with_container();
2145
2146        let plan = plan_compute(&stack, Platform::Aws, None).expect("plan should build");
2147
2148        let pool = plan.pools.first().expect("general pool should exist");
2149        assert_eq!(pool.pool_id, "general");
2150        assert_eq!(pool.workloads, vec!["api"]);
2151        assert!(pool.selected.machine().is_some());
2152        assert!(pool.machines.iter().any(|machine| machine.recommended));
2153    }
2154
2155    #[test]
2156    fn cloud_plan_only_offers_machines_matching_the_default_image_target() {
2157        let stack = stack_with_container();
2158
2159        for platform in [Platform::Aws, Platform::Gcp, Platform::Azure] {
2160            let plan = plan_compute(&stack, platform, None).expect("plan should build");
2161            let pool = plan.pools.first().expect("general pool should exist");
2162            let expected = instance_catalog::default_architecture(platform)
2163                .expect("managed cloud should have a default architecture");
2164
2165            assert!(pool.machines.iter().any(|machine| machine.available));
2166            for machine in &pool.machines {
2167                let spec = instance_catalog::find_instance_type(platform, &machine.machine)
2168                    .expect("every option is a catalog machine");
2169                if machine.available {
2170                    assert_eq!(spec.architecture, expected, "{}", machine.machine);
2171                }
2172                assert_eq!(
2173                    machine
2174                        .unavailable_reasons
2175                        .contains(&MachineUnavailableReason::Architecture),
2176                    spec.architecture != expected,
2177                    "{}",
2178                    machine.machine
2179                );
2180            }
2181        }
2182    }
2183
2184    #[test]
2185    fn selected_machine_is_preserved_as_static_deployment_choice() {
2186        let stack = stack_with_container();
2187        let settings = ComputeSettings {
2188            containers: Default::default(),
2189            pools: [(
2190                "general".to_string(),
2191                ComputePoolSelection::Fixed {
2192                    machines: 1,
2193                    machine: Some("m7g.xlarge".to_string()),
2194                    failure_domains: None,
2195                    data_disk_gib: None,
2196                },
2197            )]
2198            .into_iter()
2199            .collect(),
2200        };
2201
2202        let plan = plan_compute(&stack, Platform::Aws, Some(&settings)).expect("plan should build");
2203
2204        let pool = plan.pools.first().expect("general pool should exist");
2205        assert_eq!(pool.selected.machine(), Some("m7g.xlarge"));
2206        assert!(pool.errors.is_empty());
2207    }
2208
2209    #[test]
2210    fn configurable_cloud_disk_satisfies_storage_above_fixed_local_catalog() {
2211        let mut stack = stack_with_container();
2212        let container = stack
2213            .resources
2214            .get_mut("api")
2215            .and_then(|entry| entry.config.downcast_mut::<Container>())
2216            .expect("test stack should contain a container");
2217        container.ephemeral_storage = Some("8000Gi".to_string());
2218        let settings = ComputeSettings {
2219            containers: Default::default(),
2220            pools: [(
2221                "storage".to_string(),
2222                ComputePoolSelection::Fixed {
2223                    machines: 1,
2224                    machine: Some("m8i.2xlarge".to_string()),
2225                    failure_domains: None,
2226                    data_disk_gib: None,
2227                },
2228            )]
2229            .into_iter()
2230            .collect(),
2231        };
2232
2233        let plan = plan_compute(&stack, Platform::Aws, Some(&settings)).expect("plan should build");
2234        let pool = plan.pools.first().expect("general pool should exist");
2235        assert!(pool.errors.is_empty());
2236        let selected = pool
2237            .machines
2238            .iter()
2239            .find(|option| option.machine == "m8i.2xlarge")
2240            .expect("selected machine should remain an option");
2241        assert_eq!(
2242            selected.profile.ephemeral_storage_bytes,
2243            8_000 * 1024 * 1024 * 1024
2244        );
2245    }
2246
2247    #[test]
2248    fn selected_machine_defines_architecture_when_workloads_do_not() {
2249        let stack = stack_with_container();
2250        let settings = ComputeSettings {
2251            containers: Default::default(),
2252            pools: [(
2253                "general".to_string(),
2254                ComputePoolSelection::Fixed {
2255                    machines: 1,
2256                    machine: Some("m7i.xlarge".to_string()),
2257                    failure_domains: None,
2258                    data_disk_gib: None,
2259                },
2260            )]
2261            .into_iter()
2262            .collect(),
2263        };
2264
2265        let plan = plan_compute(&stack, Platform::Aws, Some(&settings)).expect("plan should build");
2266
2267        let pool = plan.pools.first().expect("general pool should exist");
2268        assert!(pool.errors.is_empty());
2269        assert!(pool.machines.iter().any(|machine| machine.available));
2270        assert!(pool
2271            .machines
2272            .iter()
2273            .filter(|machine| machine.available)
2274            .all(|machine| machine.profile.architecture == Some(Architecture::X86_64)));
2275    }
2276
2277    #[test]
2278    fn graviton4_compute_machine_can_be_selected() {
2279        let stack = stack_with_container();
2280        let settings = ComputeSettings {
2281            containers: Default::default(),
2282            pools: [(
2283                "general".to_string(),
2284                ComputePoolSelection::Fixed {
2285                    machines: 1,
2286                    machine: Some("c8g.2xlarge".to_string()),
2287                    failure_domains: None,
2288                    data_disk_gib: None,
2289                },
2290            )]
2291            .into_iter()
2292            .collect(),
2293        };
2294
2295        let plan = plan_compute(&stack, Platform::Aws, Some(&settings)).expect("plan should build");
2296
2297        let pool = plan.pools.first().expect("general pool should exist");
2298        assert!(pool.errors.is_empty(), "{:?}", pool.errors);
2299        let selected = pool
2300            .machines
2301            .iter()
2302            .find(|option| option.machine == "c8g.2xlarge")
2303            .expect("selected machine should be offered");
2304        assert!(selected.recommended);
2305        assert_eq!(selected.profile.architecture, Some(Architecture::Arm64));
2306    }
2307
2308    #[test]
2309    fn explicit_capacity_group_requirements_are_merged_with_workloads() {
2310        let mut stack = stack_with_container();
2311        let cluster = ComputeCluster::new("compute".to_string())
2312            .capacity_group(CapacityGroup {
2313                group_id: "general".to_string(),
2314                instance_type: None,
2315                profile: Some(MachineProfile {
2316                    cpu: "4".to_string(),
2317                    memory_bytes: 16 * 1024 * 1024 * 1024,
2318                    ephemeral_storage_bytes: 20 * 1024 * 1024 * 1024,
2319                    architecture: Some(Architecture::X86_64),
2320                    gpu: None,
2321                    data_disk: None,
2322                }),
2323                min_size: 2,
2324                max_size: 5,
2325                scale_policy: None,
2326                nested_virtualization: Some(true),
2327                data_disk_gib_range: None,
2328            })
2329            .build();
2330        stack.resources.insert(
2331            "compute".to_string(),
2332            ResourceEntry {
2333                config: Resource::new(cluster),
2334                lifecycle: ResourceLifecycle::Frozen,
2335                dependencies: Vec::new(),
2336                display_name: None,
2337                description: None,
2338                remote_access: false,
2339                enabled_when: None,
2340            },
2341        );
2342
2343        let plan = plan_compute(&stack, Platform::Aws, None).expect("plan should build");
2344
2345        let pool = plan.pools.first().expect("general pool should exist");
2346        let machine = pool
2347            .selected
2348            .machine()
2349            .expect("AWS selection should include a machine");
2350        let spec = instance_catalog::find_instance_type(Platform::Aws, machine)
2351            .expect("selected machine should exist in the catalog");
2352        assert!(spec.is_nested_virt_capable());
2353        assert_eq!(pool.selected.min_size(), 2);
2354        assert_eq!(pool.selected.max_size(), 5);
2355        assert!(pool.errors.is_empty());
2356    }
2357
2358    /// The pool path deployment packages plan: a nested-virtualization pool that
2359    /// leaves the architecture unset must resolve to the x86_64 machines AWS
2360    /// offers for it, the same machine the image build resolves.
2361    /// A machine the plan marks available is one a pin of it accepts: one replica of the
2362    /// pool's workloads fits after the host reserve.
2363    #[test]
2364    fn available_machines_fit_one_replica_after_the_host_reserve() {
2365        let mut stack = stack_with_container();
2366        stack
2367            .resources
2368            .get_mut("api")
2369            .unwrap()
2370            .config
2371            .downcast_mut::<Container>()
2372            .unwrap()
2373            .cpu = ResourceSpec {
2374            min: "4".into(),
2375            desired: "4".into(),
2376        };
2377        let plan = plan_compute(&stack, Platform::Aws, None).expect("plan should build");
2378        let available: Vec<_> = plan.pools[0]
2379            .machines
2380            .iter()
2381            .filter(|option| option.available)
2382            .map(|option| option.machine.clone())
2383            .collect();
2384        assert!(!available.is_empty());
2385        assert!(!available.contains(&"t3.xlarge".to_string()));
2386        for machine in available {
2387            let settings: ComputeSettings = serde_json::from_value(serde_json::json!({
2388                "pools":{"general":{"mode":"fixed","machines":1,"machine":machine}}
2389            }))
2390            .unwrap();
2391            let pinned = plan_compute(&stack, Platform::Aws, Some(&settings)).unwrap();
2392            assert!(
2393                pinned.pools[0].errors.is_empty(),
2394                "{machine} is listed as available: {:?}",
2395                pinned.pools[0].errors
2396            );
2397        }
2398    }
2399
2400    /// A pool without workloads carries only its machine's profile, so that machine stays
2401    /// available: the host reserve applies to workload demand, not to the machine itself.
2402    #[test]
2403    fn a_pool_without_workloads_keeps_its_own_machine_available() {
2404        let spec = instance_catalog::find_instance_type(Platform::Aws, "m7g.large").unwrap();
2405        let mut stack = stack_with_container();
2406        stack.resources.remove("api");
2407        stack.resources.insert(
2408            "compute".to_string(),
2409            ResourceEntry {
2410                config: Resource::new(
2411                    ComputeCluster::new("compute".to_string())
2412                        .capacity_group(CapacityGroup {
2413                            group_id: "general".to_string(),
2414                            instance_type: Some("m7g.large".to_string()),
2415                            profile: Some(spec.to_machine_profile()),
2416                            min_size: 1,
2417                            max_size: 1,
2418                            scale_policy: None,
2419                            nested_virtualization: None,
2420                            data_disk_gib_range: None,
2421                        })
2422                        .build(),
2423                ),
2424                lifecycle: ResourceLifecycle::Frozen,
2425                dependencies: Vec::new(),
2426                display_name: None,
2427                description: None,
2428                remote_access: false,
2429                enabled_when: None,
2430            },
2431        );
2432        let plan = plan_compute(&stack, Platform::Aws, None).expect("plan should build");
2433        let option = plan.pools[0]
2434            .machines
2435            .iter()
2436            .find(|option| option.machine == "m7g.large")
2437            .expect("m7g.large should be listed");
2438        assert!(option.available, "{:?}", option.unavailable_reasons);
2439    }
2440
2441    #[test]
2442    fn nested_pool_without_architecture_plans_an_aws_machine() {
2443        let mut stack = stack_with_container();
2444        let cluster = ComputeCluster::new("compute".to_string())
2445            .capacity_group(CapacityGroup {
2446                group_id: "general".to_string(),
2447                instance_type: None,
2448                profile: Some(MachineProfile {
2449                    cpu: "4".to_string(),
2450                    memory_bytes: 16 * 1024 * 1024 * 1024,
2451                    ephemeral_storage_bytes: 20 * 1024 * 1024 * 1024,
2452                    architecture: None,
2453                    gpu: None,
2454                    data_disk: None,
2455                }),
2456                min_size: 1,
2457                max_size: 1,
2458                scale_policy: None,
2459                nested_virtualization: Some(true),
2460                data_disk_gib_range: None,
2461            })
2462            .build();
2463        stack.resources.insert(
2464            "compute".to_string(),
2465            ResourceEntry {
2466                config: Resource::new(cluster),
2467                lifecycle: ResourceLifecycle::Frozen,
2468                dependencies: Vec::new(),
2469                display_name: None,
2470                description: None,
2471                remote_access: false,
2472                enabled_when: None,
2473            },
2474        );
2475
2476        let plan = plan_compute(&stack, Platform::Aws, None).expect("plan should build");
2477
2478        let pool = plan.pools.first().expect("general pool should exist");
2479        assert!(pool.errors.is_empty(), "{:?}", pool.errors);
2480        let machine = pool
2481            .selected
2482            .machine()
2483            .expect("AWS selection should include a machine");
2484        let spec = instance_catalog::find_instance_type(Platform::Aws, machine)
2485            .expect("selected machine should exist in the catalog");
2486        assert!(
2487            spec.is_nested_virt_capable(),
2488            "{machine} is not nested-capable"
2489        );
2490        assert_eq!(spec.architecture, Architecture::X86_64);
2491
2492        // Every AWS machine is listed, in catalog order: category, series, then vCPU.
2493        let catalog = instance_catalog::catalog_for_platform(Platform::Aws);
2494        assert_eq!(
2495            pool.machines
2496                .iter()
2497                .map(|option| option.machine.as_str())
2498                .collect::<Vec<_>>(),
2499            catalog.iter().map(|spec| spec.name).collect::<Vec<_>>()
2500        );
2501        // The pool needs 4 vCPU and 16 GiB per replica, on a nested-capable x86 machine.
2502        for (option, spec) in pool.machines.iter().zip(&catalog) {
2503            let fits = spec.is_nested_virt_capable()
2504                && spec.architecture == Architecture::X86_64
2505                && spec.vcpu >= 4
2506                && spec.memory_bytes >= 16 * GIB
2507                && (spec.has_configurable_ephemeral_storage()
2508                    || spec.ephemeral_storage_bytes >= 20 * GIB);
2509            assert_eq!(option.available, fits, "{}", option.machine);
2510            assert_eq!(
2511                option.available,
2512                option.unavailable_reasons.is_empty(),
2513                "{}",
2514                option.machine
2515            );
2516        }
2517
2518        let option = |name: &str| {
2519            pool.machines
2520                .iter()
2521                .find(|option| option.machine == name)
2522                .unwrap_or_else(|| panic!("{name} should be listed"))
2523        };
2524        let reasons = |name: &str| option(name).unavailable_reasons.clone();
2525        assert_eq!(reasons("m8i.xlarge"), vec![]);
2526        assert_eq!(
2527            reasons("m8i.large"),
2528            vec![
2529                MachineUnavailableReason::Cpu,
2530                MachineUnavailableReason::Memory
2531            ]
2532        );
2533        assert_eq!(
2534            reasons("c8i.xlarge"),
2535            vec![MachineUnavailableReason::Memory]
2536        );
2537        assert_eq!(
2538            reasons("m7g.xlarge"),
2539            vec![
2540                MachineUnavailableReason::Architecture,
2541                MachineUnavailableReason::NestedVirtualization
2542            ]
2543        );
2544        assert_eq!(
2545            reasons("t3.xlarge"),
2546            vec![MachineUnavailableReason::NestedVirtualization]
2547        );
2548        assert_eq!(
2549            reasons("t4g.micro"),
2550            vec![
2551                MachineUnavailableReason::Architecture,
2552                MachineUnavailableReason::NestedVirtualization,
2553                MachineUnavailableReason::Cpu,
2554                MachineUnavailableReason::Memory
2555            ]
2556        );
2557
2558        let large = option("m8i.24xlarge");
2559        assert!(large.available);
2560        assert_eq!(large.series, "m8i");
2561        assert_eq!(large.category, InstanceFamily::GeneralPurpose);
2562        assert_eq!(large.label, "General purpose · Intel · 8th gen");
2563        assert!(large.nested_virtualization);
2564        assert_eq!(large.local_storage, None);
2565        let local = option("i7i.xlarge");
2566        assert!(local.available);
2567        assert_eq!(local.category, InstanceFamily::StorageOptimized);
2568        // AWS reports 937 decimal GB of local NVMe.
2569        assert_eq!(local.local_storage, Some(893_592 * 1024 * 1024));
2570
2571        let wire = serde_json::to_value(large).expect("option should serialize");
2572        assert_eq!(wire["category"], "generalPurpose");
2573        assert_eq!(wire["nestedVirtualization"], true);
2574        assert_eq!(wire["unavailableReasons"], serde_json::json!([]));
2575        assert!(wire.get("localStorage").is_none());
2576        let wire = serde_json::to_value(option("m7g.xlarge")).expect("option should serialize");
2577        assert_eq!(wire["available"], false);
2578        assert_eq!(
2579            wire["unavailableReasons"],
2580            serde_json::json!(["architecture", "nestedVirtualization"])
2581        );
2582        assert_eq!(
2583            serde_json::to_value(local).expect("option should serialize")["localStorage"],
2584            893_592u64 * 1024 * 1024
2585        );
2586    }
2587
2588    const GIB: u64 = 1024 * 1024 * 1024;
2589
2590    /// A stack with one declared `general` pool. `data_disk_gib` is the
2591    /// declared size (the default for a range) and `range` the sizes offered.
2592    fn stack_with_data_disk_pool(
2593        data_disk_gib: Option<u64>,
2594        range: Option<ComputeChoiceRange>,
2595    ) -> Stack {
2596        let mut stack = stack_with_container();
2597        let cluster = ComputeCluster::new("compute".to_string())
2598            .capacity_group(CapacityGroup {
2599                group_id: "general".to_string(),
2600                instance_type: None,
2601                profile: Some(MachineProfile {
2602                    cpu: "2".to_string(),
2603                    memory_bytes: 8 * GIB,
2604                    ephemeral_storage_bytes: 20 * GIB,
2605                    architecture: None,
2606                    gpu: None,
2607                    data_disk: data_disk_gib.map(|gib| crate::DataDiskRequirement {
2608                        size_bytes: gib * GIB,
2609                    }),
2610                }),
2611                min_size: 1,
2612                max_size: 1,
2613                scale_policy: None,
2614                nested_virtualization: None,
2615                data_disk_gib_range: range,
2616            })
2617            .build();
2618        stack.resources.insert(
2619            "compute".to_string(),
2620            ResourceEntry {
2621                config: Resource::new(cluster),
2622                lifecycle: ResourceLifecycle::Frozen,
2623                dependencies: Vec::new(),
2624                display_name: None,
2625                description: None,
2626                remote_access: false,
2627                enabled_when: None,
2628            },
2629        );
2630        stack
2631    }
2632
2633    fn data_disk_selection(data_disk_gib: Option<u32>) -> ComputeSettings {
2634        ComputeSettings {
2635            pools: [(
2636                "general".to_string(),
2637                ComputePoolSelection::Fixed {
2638                    machines: 1,
2639                    machine: None,
2640                    failure_domains: None,
2641                    data_disk_gib,
2642                },
2643            )]
2644            .into_iter()
2645            .collect(),
2646            containers: HashMap::new(),
2647        }
2648    }
2649
2650    fn general_pool(plan: &ComputePlan) -> &ComputePoolPlan {
2651        plan.pools
2652            .iter()
2653            .find(|pool| pool.pool_id == "general")
2654            .expect("general pool should be planned")
2655    }
2656
2657    #[test]
2658    fn a_deployment_chooses_its_data_disk_within_the_declared_range() {
2659        let range = ComputeChoiceRange {
2660            min: 0,
2661            max: 4096,
2662            default: 200,
2663        };
2664        let stack = stack_with_data_disk_pool(Some(200), Some(range));
2665        for platform in [Platform::Aws, Platform::Machines] {
2666            for (selected, expected_gib) in [(None, 200), (Some(50), 50), (Some(0), 0)] {
2667                let settings = data_disk_selection(selected);
2668                let plan = plan_compute(&stack, platform, Some(&settings)).expect("plan");
2669                let pool = general_pool(&plan);
2670                assert!(
2671                    pool.errors.is_empty(),
2672                    "{platform} {selected:?}: {:?}",
2673                    pool.errors
2674                );
2675                assert_eq!(
2676                    pool.data_disk,
2677                    Some(ComputePoolDataDiskPlan {
2678                        min_gib: 0,
2679                        max_gib: 4096,
2680                        default_gib: 200,
2681                        selected_gib: expected_gib,
2682                    }),
2683                    "{platform} {selected:?}"
2684                );
2685                // An omitted choice stays omitted, so later releases can move the default.
2686                assert_eq!(pool.selected.data_disk_gib(), selected, "{platform}");
2687            }
2688
2689            let settings = data_disk_selection(Some(5000));
2690            let plan = plan_compute(&stack, platform, Some(&settings)).expect("plan");
2691            assert_eq!(
2692                general_pool(&plan).errors,
2693                vec!["pool 'general' data disk must be between 0 and 4096 GiB; dataDiskGib 5000 is outside that range".to_string()],
2694                "{platform}"
2695            );
2696        }
2697    }
2698
2699    #[test]
2700    fn a_fixed_or_absent_data_disk_refuses_another_size() {
2701        let fixed = stack_with_data_disk_pool(Some(100), None);
2702        let plan = plan_compute(&fixed, Platform::Aws, None).expect("plan");
2703        assert_eq!(
2704            general_pool(&plan).data_disk,
2705            Some(ComputePoolDataDiskPlan {
2706                min_gib: 100,
2707                max_gib: 100,
2708                default_gib: 100,
2709                selected_gib: 100,
2710            })
2711        );
2712        let plan = plan_compute(&fixed, Platform::Aws, Some(&data_disk_selection(Some(200))))
2713            .expect("plan");
2714        assert_eq!(
2715            general_pool(&plan).errors,
2716            vec![
2717                "pool 'general' has a fixed 100 GiB data disk; dataDiskGib 200 cannot be chosen"
2718                    .to_string()
2719            ]
2720        );
2721
2722        let absent = stack_with_data_disk_pool(None, None);
2723        let plan = plan_compute(&absent, Platform::Aws, Some(&data_disk_selection(Some(0))))
2724            .expect("plan");
2725        assert!(general_pool(&plan).errors.is_empty());
2726        assert_eq!(general_pool(&plan).data_disk, None);
2727        let plan = plan_compute(&absent, Platform::Aws, Some(&data_disk_selection(Some(50))))
2728            .expect("plan");
2729        assert_eq!(
2730            general_pool(&plan).errors,
2731            vec![
2732                "pool 'general' declares no data disk, so dataDiskGib 50 cannot be chosen"
2733                    .to_string()
2734            ]
2735        );
2736    }
2737
2738    #[test]
2739    fn materialized_machine_profile_is_not_counted_as_workload_demand() {
2740        let mut stack = stack_with_container();
2741        let selected = instance_catalog::find_instance_type(Platform::Aws, "m7g.xlarge")
2742            .expect("machine should exist in catalog");
2743        let cluster = ComputeCluster::new("compute".to_string())
2744            .capacity_group(CapacityGroup {
2745                group_id: "general".to_string(),
2746                instance_type: Some(selected.name.to_string()),
2747                profile: Some(selected.to_machine_profile()),
2748                min_size: 1,
2749                max_size: 1,
2750                scale_policy: None,
2751                nested_virtualization: None,
2752                data_disk_gib_range: None,
2753            })
2754            .build();
2755        stack.resources.insert(
2756            "compute".to_string(),
2757            ResourceEntry {
2758                config: Resource::new(cluster),
2759                lifecycle: ResourceLifecycle::Frozen,
2760                dependencies: Vec::new(),
2761                display_name: None,
2762                description: None,
2763                remote_access: false,
2764                enabled_when: None,
2765            },
2766        );
2767
2768        let plan = plan_compute(&stack, Platform::Aws, None).expect("plan should build");
2769        let pool = plan.pools.first().expect("general pool should exist");
2770
2771        assert_eq!(pool.requirements.cpu, "2");
2772        assert_eq!(pool.requirements.memory_bytes, 4 * 1024 * 1024 * 1024);
2773        assert_eq!(pool.recommended.machine(), Some("m7g.xlarge"));
2774        assert!(pool
2775            .machines
2776            .iter()
2777            .any(|option| option.machine == "m7g.xlarge"));
2778    }
2779
2780    #[test]
2781    fn nested_x86_fixed_range_pool_preserves_bounds_and_rejects_graviton() {
2782        let daemon = Daemon::new("vm-runtime-loader".to_string())
2783            .code(DaemonCode::Image {
2784                image: "example.com/vm-runtime:latest".to_string(),
2785            })
2786            .cluster("vm-runtime".to_string())
2787            .cpu(ResourceSpec {
2788                min: "2".to_string(),
2789                desired: "2".to_string(),
2790            })
2791            .memory(ResourceSpec {
2792                min: "4Gi".to_string(),
2793                desired: "4Gi".to_string(),
2794            })
2795            .permissions("loader".to_string())
2796            .build();
2797        let cluster = ComputeCluster::new("vm-runtime".to_string())
2798            .capacity_group(CapacityGroup {
2799                group_id: "general".to_string(),
2800                instance_type: None,
2801                profile: Some(MachineProfile {
2802                    cpu: "4".to_string(),
2803                    memory_bytes: 16 * 1024 * 1024 * 1024,
2804                    ephemeral_storage_bytes: 20 * 1024 * 1024 * 1024,
2805                    architecture: Some(Architecture::X86_64),
2806                    gpu: None,
2807                    data_disk: None,
2808                }),
2809                min_size: 2,
2810                max_size: 2,
2811                scale_policy: Some(CapacityGroupScalePolicy::Fixed {
2812                    machines: ComputeChoiceRange {
2813                        min: 1,
2814                        max: 5,
2815                        default: 2,
2816                    },
2817                }),
2818                nested_virtualization: Some(true),
2819                data_disk_gib_range: None,
2820            })
2821            .build();
2822        let stack = Stack {
2823            id: "vm-runtime".to_string(),
2824            resources: [
2825                (
2826                    "vm-runtime-loader".to_string(),
2827                    ResourceEntry {
2828                        config: Resource::new(daemon),
2829                        lifecycle: ResourceLifecycle::Live,
2830                        dependencies: Vec::new(),
2831                        display_name: None,
2832                        description: None,
2833                        remote_access: false,
2834                        enabled_when: None,
2835                    },
2836                ),
2837                (
2838                    "vm-runtime".to_string(),
2839                    ResourceEntry {
2840                        config: Resource::new(cluster),
2841                        lifecycle: ResourceLifecycle::Frozen,
2842                        dependencies: Vec::new(),
2843                        display_name: None,
2844                        description: None,
2845                        remote_access: false,
2846                        enabled_when: None,
2847                    },
2848                ),
2849            ]
2850            .into_iter()
2851            .collect(),
2852            permissions: crate::permissions::PermissionsConfig::default(),
2853            supported_platforms: None,
2854            inputs: vec![],
2855            dynamic_container_repositories: Vec::new(),
2856            dynamic_container_image_resources: Vec::new(),
2857            operations: None,
2858            built_architectures: Default::default(),
2859        };
2860
2861        let plan = plan_compute(&stack, Platform::Aws, None).expect("plan should build");
2862        let pool = plan.pools.first().expect("general pool should exist");
2863        assert_eq!(pool.recommended.machine(), Some("m8i.2xlarge"));
2864        assert_eq!(pool.recommended.min_size(), 2);
2865        assert_eq!(pool.recommended.max_size(), 2);
2866        assert_eq!(
2867            pool.scale,
2868            CapacityGroupScalePolicy::Fixed {
2869                machines: ComputeChoiceRange {
2870                    min: 1,
2871                    max: 5,
2872                    default: 2,
2873                },
2874            }
2875        );
2876        let graviton = pool
2877            .machines
2878            .iter()
2879            .find(|option| option.machine == "m7g.2xlarge")
2880            .expect("every AWS machine is listed");
2881        assert!(!graviton.available);
2882        assert_eq!(
2883            graviton.unavailable_reasons,
2884            vec![
2885                MachineUnavailableReason::Architecture,
2886                MachineUnavailableReason::NestedVirtualization
2887            ]
2888        );
2889
2890        let invalid_settings = ComputeSettings {
2891            containers: Default::default(),
2892            pools: [(
2893                "general".to_string(),
2894                ComputePoolSelection::Fixed {
2895                    machines: 2,
2896                    machine: Some("m7g.2xlarge".to_string()),
2897                    failure_domains: None,
2898                    data_disk_gib: None,
2899                },
2900            )]
2901            .into_iter()
2902            .collect(),
2903        };
2904        let invalid_plan = plan_compute(&stack, Platform::Aws, Some(&invalid_settings))
2905            .expect("plan should build");
2906        assert_eq!(
2907            invalid_plan.pools[0].errors,
2908            vec!["aws machine 'm7g.2xlarge' does not satisfy pool 'general' requirements"]
2909        );
2910    }
2911
2912    fn declared_pool_errors(
2913        scale: CapacityGroupScalePolicy,
2914        selection: ComputePoolSelection,
2915    ) -> Vec<String> {
2916        let mut stack = stack_with_container();
2917        let cluster = ComputeCluster::new("compute".to_string())
2918            .capacity_group(CapacityGroup {
2919                group_id: "general".to_string(),
2920                instance_type: None,
2921                profile: None,
2922                min_size: scale.default_min_size(),
2923                max_size: scale.default_max_size(),
2924                scale_policy: Some(scale),
2925                nested_virtualization: None,
2926                data_disk_gib_range: None,
2927            })
2928            .build();
2929        stack.resources.insert(
2930            "compute".to_string(),
2931            ResourceEntry {
2932                config: Resource::new(cluster),
2933                lifecycle: ResourceLifecycle::Frozen,
2934                dependencies: Vec::new(),
2935                display_name: None,
2936                description: None,
2937                remote_access: false,
2938                enabled_when: None,
2939            },
2940        );
2941        let settings = ComputeSettings {
2942            containers: Default::default(),
2943            pools: [("general".to_string(), selection)].into_iter().collect(),
2944        };
2945        plan_compute(&stack, Platform::Aws, Some(&settings))
2946            .expect("plan should build")
2947            .pools
2948            .remove(0)
2949            .errors
2950    }
2951
2952    fn range(min: u32, max: u32, default: u32) -> ComputeChoiceRange {
2953        ComputeChoiceRange { min, max, default }
2954    }
2955
2956    #[test]
2957    fn generated_pool_offers_the_recommendation_as_a_default_not_a_bound() {
2958        let mut stack = stack_with_container();
2959        let api = stack
2960            .resources
2961            .get_mut("api")
2962            .and_then(|entry| entry.config.downcast_mut::<Container>())
2963            .expect("test stack should contain a container");
2964        api.autoscaling = Some(crate::ContainerAutoscaling {
2965            min: 1,
2966            desired: 1,
2967            max: 3,
2968            target_cpu_percent: Some(70.0),
2969            target_memory_percent: None,
2970            target_http_in_flight_per_replica: None,
2971            max_http_p95_latency_ms: None,
2972        });
2973
2974        // Three replicas at most, one machine each, plus one for a rolling update.
2975        let plan = plan_compute(&stack, Platform::Aws, None).expect("plan should build");
2976        let pool = &plan.pools[0];
2977        assert_eq!(
2978            pool.scale,
2979            CapacityGroupScalePolicy::Autoscale {
2980                min: range(1, 100, 1),
2981                max: range(1, 100, 4),
2982            }
2983        );
2984        assert_eq!(
2985            (pool.recommended.min_size(), pool.recommended.max_size()),
2986            (1, 4)
2987        );
2988        assert!(pool.errors.is_empty());
2989    }
2990
2991    /// A one-replica container fills its one machine, so a release has nowhere to start the
2992    /// new replica before stopping the old one. The default pool autoscales 1-2 so it can, on
2993    /// the same machine type: the extra machine is only there during a release.
2994    #[test]
2995    fn generated_pool_has_room_to_start_a_new_replica_before_stopping_the_old_one() {
2996        let plan =
2997            plan_compute(&stack_with_container(), Platform::Aws, None).expect("plan should build");
2998        let pool = &plan.pools[0];
2999        assert_eq!(
3000            pool.scale,
3001            CapacityGroupScalePolicy::Autoscale {
3002                min: range(1, 100, 1),
3003                max: range(1, 100, 2),
3004            }
3005        );
3006        assert_eq!(
3007            (pool.recommended.min_size(), pool.recommended.max_size()),
3008            (1, 2)
3009        );
3010        assert!(matches!(
3011            pool.recommended,
3012            ComputePoolSelection::Autoscale { .. }
3013        ));
3014        assert!(pool.errors.is_empty());
3015
3016        // A stateful container replaces in place, so its pool gets no extra machine.
3017        let mut stateful = stack_with_container();
3018        stateful
3019            .resources
3020            .get_mut("api")
3021            .and_then(|entry| entry.config.downcast_mut::<Container>())
3022            .expect("test stack should contain a container")
3023            .stateful = true;
3024        let stateful_plan =
3025            plan_compute(&stateful, Platform::Aws, None).expect("plan should build");
3026        let stateful_pool = &stateful_plan.pools[0];
3027        assert!(matches!(
3028            stateful_pool.recommended,
3029            ComputePoolSelection::Fixed { machines: 1, .. }
3030        ));
3031
3032        // The extra machine doesn't change the machine type: both pools fit one replica per
3033        // machine on the same type.
3034        assert!(pool.recommended.machine().is_some());
3035        assert_eq!(
3036            pool.recommended.machine(),
3037            stateful_pool.recommended.machine()
3038        );
3039
3040        // A saved choice is the installer's cost bound and stays as chosen.
3041        let saved = ComputeSettings {
3042            containers: Default::default(),
3043            pools: [(
3044                "general".to_string(),
3045                ComputePoolSelection::Fixed {
3046                    machines: 1,
3047                    machine: pool.recommended.machine().map(str::to_string),
3048                    failure_domains: None,
3049                    data_disk_gib: None,
3050                },
3051            )]
3052            .into_iter()
3053            .collect(),
3054        };
3055        let saved_plan = plan_compute(&stack_with_container(), Platform::Aws, Some(&saved))
3056            .expect("plan should build");
3057        assert_eq!(
3058            (
3059                saved_plan.pools[0].selected.min_size(),
3060                saved_plan.pools[0].selected.max_size()
3061            ),
3062            (1, 1)
3063        );
3064    }
3065
3066    /// A pool larger than the offered machine count is sized onto bigger machines, so the
3067    /// offered fleet still holds it. The rolling-update machine doesn't change that.
3068    #[test]
3069    fn generated_pool_beyond_the_offered_fleet_is_sized_to_fit_it() {
3070        let mut stack = stack_with_container();
3071        stack
3072            .resources
3073            .get_mut("api")
3074            .and_then(|entry| entry.config.downcast_mut::<Container>())
3075            .expect("test stack should contain a container")
3076            .replicas = Some(400);
3077
3078        let plan = plan_compute(&stack, Platform::Aws, None).expect("plan should build");
3079        let pool = &plan.pools[0];
3080        assert!(pool.errors.is_empty(), "{:?}", pool.errors);
3081        assert_eq!(pool.recommended.max_size(), GENERATED_POOL_MAX_MACHINES);
3082    }
3083
3084    #[test]
3085    fn generated_pool_rejects_a_fleet_too_small_for_desired_replicas() {
3086        let mut stack = stack_with_container();
3087        let api = stack
3088            .resources
3089            .get_mut("api")
3090            .and_then(|entry| entry.config.downcast_mut::<Container>())
3091            .expect("test stack should contain a container");
3092        // 3 x 2 vCPU / 4 GiB requested at the desired count.
3093        api.replicas = Some(3);
3094        let selection = |machines| ComputeSettings {
3095            containers: Default::default(),
3096            pools: [(
3097                "general".to_string(),
3098                ComputePoolSelection::Fixed {
3099                    machines,
3100                    machine: Some("m7g.xlarge".to_string()),
3101                    failure_domains: None,
3102                    data_disk_gib: None,
3103                },
3104            )]
3105            .into_iter()
3106            .collect(),
3107        };
3108
3109        // m7g.xlarge: 3.5 vCPU available after the host reserve.
3110        let errors = plan_compute(&stack, Platform::Aws, Some(&selection(1)))
3111            .expect("plan should build")
3112            .pools
3113            .remove(0)
3114            .errors;
3115        assert_eq!(errors.len(), 1, "{errors:?}");
3116        assert!(
3117            errors[0].starts_with(
3118                "Pool 'general' is too small for its workloads: 1 x m7g.xlarge has 3.50 vCPU"
3119            ),
3120            "{errors:?}"
3121        );
3122        assert!(errors[0].contains("request 6.00 vCPU"), "{errors:?}");
3123
3124        let errors = plan_compute(&stack, Platform::Aws, Some(&selection(2)))
3125            .expect("plan should build")
3126            .pools
3127            .remove(0)
3128            .errors;
3129        assert!(errors.is_empty(), "{errors:?}");
3130    }
3131
3132    #[test]
3133    fn fixed_and_equal_autoscale_bounds_are_interchangeable_for_declared_pools() {
3134        let fixed = |machines| ComputePoolSelection::Fixed {
3135            machines,
3136            machine: Some("m7g.xlarge".to_string()),
3137            failure_domains: None,
3138            data_disk_gib: None,
3139        };
3140        let autoscale = |min, max| ComputePoolSelection::Autoscale {
3141            min,
3142            max,
3143            machine: Some("m7g.xlarge".to_string()),
3144            failure_domains: None,
3145            data_disk_gib: None,
3146        };
3147        let declared_fixed = CapacityGroupScalePolicy::Fixed {
3148            machines: range(2, 4, 2),
3149        };
3150        let declared_autoscale = CapacityGroupScalePolicy::Autoscale {
3151            min: range(1, 3, 1),
3152            max: range(2, 6, 4),
3153        };
3154
3155        assert!(declared_pool_errors(declared_fixed.clone(), autoscale(3, 3)).is_empty());
3156        assert_eq!(
3157            declared_pool_errors(declared_fixed.clone(), autoscale(2, 4)),
3158            vec!["Pool 'general' must use fixed mode with 2-4 machines; autoscale 2-4 is not allowed"]
3159        );
3160        assert_eq!(
3161            declared_pool_errors(declared_fixed, autoscale(5, 5)),
3162            vec!["Pool 'general' machine count 5 is outside the allowed range 2-4"]
3163        );
3164
3165        // Fixed N must fit both the declared minimum and maximum ranges.
3166        assert!(declared_pool_errors(declared_autoscale.clone(), fixed(3)).is_empty());
3167        assert_eq!(
3168            declared_pool_errors(declared_autoscale.clone(), fixed(1)),
3169            vec!["Pool 'general' fixed machine count 1 is outside the allowed range 2-3"]
3170        );
3171        assert_eq!(
3172            declared_pool_errors(
3173                CapacityGroupScalePolicy::Autoscale {
3174                    min: range(1, 1, 1),
3175                    max: range(3, 5, 3),
3176                },
3177                fixed(1),
3178            ),
3179            vec!["Pool 'general' must use autoscale mode (minimum 1-1, maximum 3-5)"]
3180        );
3181        assert_eq!(
3182            declared_pool_errors(declared_autoscale, autoscale(1, 7)),
3183            vec!["Pool 'general' autoscale maximum 7 is outside the allowed range 2-6"]
3184        );
3185    }
3186
3187    #[test]
3188    fn local_plan_has_no_provider_machine_choices() {
3189        let stack = stack_with_container();
3190
3191        let plan = plan_compute(&stack, Platform::Local, None).expect("plan should build");
3192
3193        let pool = plan.pools.first().expect("general pool should exist");
3194        assert_eq!(pool.selected.machine(), None);
3195        assert!(pool.machines.is_empty());
3196        assert!(pool.errors.is_empty());
3197    }
3198}