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        }
2055    }
2056
2057    #[test]
2058    fn serverless_workers_and_storage_do_not_allocate_machine_pools() {
2059        let mut stack = stack_with_container();
2060        stack.resources.clear();
2061        for (id, resource) in [
2062            (
2063                "api",
2064                Resource::new(
2065                    Worker::new("api".to_string())
2066                        .code(WorkerCode::Image {
2067                            image: "example/worker:v1".to_string(),
2068                        })
2069                        .permissions("execution".to_string())
2070                        .build(),
2071                ),
2072            ),
2073            (
2074                "data",
2075                Resource::new(Storage::new("data".to_string()).build()),
2076            ),
2077        ] {
2078            stack.resources.insert(
2079                id.to_string(),
2080                ResourceEntry {
2081                    config: resource,
2082                    lifecycle: ResourceLifecycle::Frozen,
2083                    dependencies: Vec::new(),
2084                    display_name: None,
2085                    description: None,
2086                    remote_access: false,
2087                    enabled_when: None,
2088                },
2089            );
2090        }
2091
2092        for platform in [Platform::Aws, Platform::Gcp, Platform::Azure] {
2093            let plan = plan_compute(&stack, platform, None).expect("plan should build");
2094            assert!(plan.pools.is_empty(), "serverless plan allocated {plan:?}");
2095        }
2096    }
2097
2098    #[test]
2099    fn empty_stack_does_not_allocate_machine_pools() {
2100        let mut stack = stack_with_container();
2101        stack.resources.clear();
2102        let plan = plan_compute(&stack, Platform::Aws, None).expect("plan should build");
2103        assert!(plan.pools.is_empty());
2104    }
2105
2106    #[test]
2107    fn explicit_cluster_without_workloads_only_plans_declared_pools() {
2108        let mut stack = stack_with_container();
2109        stack.resources.clear();
2110        let cluster = ComputeCluster::new("compute".to_string())
2111            .capacity_group(CapacityGroup {
2112                group_id: "batch".to_string(),
2113                instance_type: Some("t4g.medium".to_string()),
2114                profile: None,
2115                min_size: 1,
2116                max_size: 1,
2117                scale_policy: None,
2118                nested_virtualization: None,
2119                data_disk_gib_range: None,
2120            })
2121            .build();
2122        stack.resources.insert(
2123            "compute".to_string(),
2124            ResourceEntry {
2125                config: Resource::new(cluster),
2126                lifecycle: ResourceLifecycle::Frozen,
2127                dependencies: Vec::new(),
2128                display_name: None,
2129                description: None,
2130                remote_access: false,
2131                enabled_when: None,
2132            },
2133        );
2134
2135        let plan = plan_compute(&stack, Platform::Aws, None).expect("plan should build");
2136        assert_eq!(plan.pools.len(), 1);
2137        assert_eq!(plan.pools[0].pool_id, "batch");
2138        assert!(plan.pools[0].errors.is_empty());
2139    }
2140
2141    #[test]
2142    fn cloud_plan_recommends_provider_machine_without_mutating_selection() {
2143        let stack = stack_with_container();
2144
2145        let plan = plan_compute(&stack, Platform::Aws, None).expect("plan should build");
2146
2147        let pool = plan.pools.first().expect("general pool should exist");
2148        assert_eq!(pool.pool_id, "general");
2149        assert_eq!(pool.workloads, vec!["api"]);
2150        assert!(pool.selected.machine().is_some());
2151        assert!(pool.machines.iter().any(|machine| machine.recommended));
2152    }
2153
2154    #[test]
2155    fn cloud_plan_only_offers_machines_matching_the_default_image_target() {
2156        let stack = stack_with_container();
2157
2158        for platform in [Platform::Aws, Platform::Gcp, Platform::Azure] {
2159            let plan = plan_compute(&stack, platform, None).expect("plan should build");
2160            let pool = plan.pools.first().expect("general pool should exist");
2161            let expected = instance_catalog::default_architecture(platform)
2162                .expect("managed cloud should have a default architecture");
2163
2164            assert!(pool.machines.iter().any(|machine| machine.available));
2165            for machine in &pool.machines {
2166                let spec = instance_catalog::find_instance_type(platform, &machine.machine)
2167                    .expect("every option is a catalog machine");
2168                if machine.available {
2169                    assert_eq!(spec.architecture, expected, "{}", machine.machine);
2170                }
2171                assert_eq!(
2172                    machine
2173                        .unavailable_reasons
2174                        .contains(&MachineUnavailableReason::Architecture),
2175                    spec.architecture != expected,
2176                    "{}",
2177                    machine.machine
2178                );
2179            }
2180        }
2181    }
2182
2183    #[test]
2184    fn selected_machine_is_preserved_as_static_deployment_choice() {
2185        let stack = stack_with_container();
2186        let settings = ComputeSettings {
2187            containers: Default::default(),
2188            pools: [(
2189                "general".to_string(),
2190                ComputePoolSelection::Fixed {
2191                    machines: 1,
2192                    machine: Some("m7g.xlarge".to_string()),
2193                    failure_domains: None,
2194                    data_disk_gib: None,
2195                },
2196            )]
2197            .into_iter()
2198            .collect(),
2199        };
2200
2201        let plan = plan_compute(&stack, Platform::Aws, Some(&settings)).expect("plan should build");
2202
2203        let pool = plan.pools.first().expect("general pool should exist");
2204        assert_eq!(pool.selected.machine(), Some("m7g.xlarge"));
2205        assert!(pool.errors.is_empty());
2206    }
2207
2208    #[test]
2209    fn configurable_cloud_disk_satisfies_storage_above_fixed_local_catalog() {
2210        let mut stack = stack_with_container();
2211        let container = stack
2212            .resources
2213            .get_mut("api")
2214            .and_then(|entry| entry.config.downcast_mut::<Container>())
2215            .expect("test stack should contain a container");
2216        container.ephemeral_storage = Some("8000Gi".to_string());
2217        let settings = ComputeSettings {
2218            containers: Default::default(),
2219            pools: [(
2220                "storage".to_string(),
2221                ComputePoolSelection::Fixed {
2222                    machines: 1,
2223                    machine: Some("m8i.2xlarge".to_string()),
2224                    failure_domains: None,
2225                    data_disk_gib: None,
2226                },
2227            )]
2228            .into_iter()
2229            .collect(),
2230        };
2231
2232        let plan = plan_compute(&stack, Platform::Aws, Some(&settings)).expect("plan should build");
2233        let pool = plan.pools.first().expect("general pool should exist");
2234        assert!(pool.errors.is_empty());
2235        let selected = pool
2236            .machines
2237            .iter()
2238            .find(|option| option.machine == "m8i.2xlarge")
2239            .expect("selected machine should remain an option");
2240        assert_eq!(
2241            selected.profile.ephemeral_storage_bytes,
2242            8_000 * 1024 * 1024 * 1024
2243        );
2244    }
2245
2246    #[test]
2247    fn selected_machine_defines_architecture_when_workloads_do_not() {
2248        let stack = stack_with_container();
2249        let settings = ComputeSettings {
2250            containers: Default::default(),
2251            pools: [(
2252                "general".to_string(),
2253                ComputePoolSelection::Fixed {
2254                    machines: 1,
2255                    machine: Some("m7i.xlarge".to_string()),
2256                    failure_domains: None,
2257                    data_disk_gib: None,
2258                },
2259            )]
2260            .into_iter()
2261            .collect(),
2262        };
2263
2264        let plan = plan_compute(&stack, Platform::Aws, Some(&settings)).expect("plan should build");
2265
2266        let pool = plan.pools.first().expect("general pool should exist");
2267        assert!(pool.errors.is_empty());
2268        assert!(pool.machines.iter().any(|machine| machine.available));
2269        assert!(pool
2270            .machines
2271            .iter()
2272            .filter(|machine| machine.available)
2273            .all(|machine| machine.profile.architecture == Some(Architecture::X86_64)));
2274    }
2275
2276    #[test]
2277    fn graviton4_compute_machine_can_be_selected() {
2278        let stack = stack_with_container();
2279        let settings = ComputeSettings {
2280            containers: Default::default(),
2281            pools: [(
2282                "general".to_string(),
2283                ComputePoolSelection::Fixed {
2284                    machines: 1,
2285                    machine: Some("c8g.2xlarge".to_string()),
2286                    failure_domains: None,
2287                    data_disk_gib: None,
2288                },
2289            )]
2290            .into_iter()
2291            .collect(),
2292        };
2293
2294        let plan = plan_compute(&stack, Platform::Aws, Some(&settings)).expect("plan should build");
2295
2296        let pool = plan.pools.first().expect("general pool should exist");
2297        assert!(pool.errors.is_empty(), "{:?}", pool.errors);
2298        let selected = pool
2299            .machines
2300            .iter()
2301            .find(|option| option.machine == "c8g.2xlarge")
2302            .expect("selected machine should be offered");
2303        assert!(selected.recommended);
2304        assert_eq!(selected.profile.architecture, Some(Architecture::Arm64));
2305    }
2306
2307    #[test]
2308    fn explicit_capacity_group_requirements_are_merged_with_workloads() {
2309        let mut stack = stack_with_container();
2310        let cluster = ComputeCluster::new("compute".to_string())
2311            .capacity_group(CapacityGroup {
2312                group_id: "general".to_string(),
2313                instance_type: None,
2314                profile: Some(MachineProfile {
2315                    cpu: "4".to_string(),
2316                    memory_bytes: 16 * 1024 * 1024 * 1024,
2317                    ephemeral_storage_bytes: 20 * 1024 * 1024 * 1024,
2318                    architecture: Some(Architecture::X86_64),
2319                    gpu: None,
2320                    data_disk: None,
2321                }),
2322                min_size: 2,
2323                max_size: 5,
2324                scale_policy: None,
2325                nested_virtualization: Some(true),
2326                data_disk_gib_range: None,
2327            })
2328            .build();
2329        stack.resources.insert(
2330            "compute".to_string(),
2331            ResourceEntry {
2332                config: Resource::new(cluster),
2333                lifecycle: ResourceLifecycle::Frozen,
2334                dependencies: Vec::new(),
2335                display_name: None,
2336                description: None,
2337                remote_access: false,
2338                enabled_when: None,
2339            },
2340        );
2341
2342        let plan = plan_compute(&stack, Platform::Aws, None).expect("plan should build");
2343
2344        let pool = plan.pools.first().expect("general pool should exist");
2345        let machine = pool
2346            .selected
2347            .machine()
2348            .expect("AWS selection should include a machine");
2349        let spec = instance_catalog::find_instance_type(Platform::Aws, machine)
2350            .expect("selected machine should exist in the catalog");
2351        assert!(spec.is_nested_virt_capable());
2352        assert_eq!(pool.selected.min_size(), 2);
2353        assert_eq!(pool.selected.max_size(), 5);
2354        assert!(pool.errors.is_empty());
2355    }
2356
2357    /// The pool path deployment packages plan: a nested-virtualization pool that
2358    /// leaves the architecture unset must resolve to the x86_64 machines AWS
2359    /// offers for it, the same machine the image build resolves.
2360    /// A machine the plan marks available is one a pin of it accepts: one replica of the
2361    /// pool's workloads fits after the host reserve.
2362    #[test]
2363    fn available_machines_fit_one_replica_after_the_host_reserve() {
2364        let mut stack = stack_with_container();
2365        stack
2366            .resources
2367            .get_mut("api")
2368            .unwrap()
2369            .config
2370            .downcast_mut::<Container>()
2371            .unwrap()
2372            .cpu = ResourceSpec {
2373            min: "4".into(),
2374            desired: "4".into(),
2375        };
2376        let plan = plan_compute(&stack, Platform::Aws, None).expect("plan should build");
2377        let available: Vec<_> = plan.pools[0]
2378            .machines
2379            .iter()
2380            .filter(|option| option.available)
2381            .map(|option| option.machine.clone())
2382            .collect();
2383        assert!(!available.is_empty());
2384        assert!(!available.contains(&"t3.xlarge".to_string()));
2385        for machine in available {
2386            let settings: ComputeSettings = serde_json::from_value(serde_json::json!({
2387                "pools":{"general":{"mode":"fixed","machines":1,"machine":machine}}
2388            }))
2389            .unwrap();
2390            let pinned = plan_compute(&stack, Platform::Aws, Some(&settings)).unwrap();
2391            assert!(
2392                pinned.pools[0].errors.is_empty(),
2393                "{machine} is listed as available: {:?}",
2394                pinned.pools[0].errors
2395            );
2396        }
2397    }
2398
2399    /// A pool without workloads carries only its machine's profile, so that machine stays
2400    /// available: the host reserve applies to workload demand, not to the machine itself.
2401    #[test]
2402    fn a_pool_without_workloads_keeps_its_own_machine_available() {
2403        let spec = instance_catalog::find_instance_type(Platform::Aws, "m7g.large").unwrap();
2404        let mut stack = stack_with_container();
2405        stack.resources.remove("api");
2406        stack.resources.insert(
2407            "compute".to_string(),
2408            ResourceEntry {
2409                config: Resource::new(
2410                    ComputeCluster::new("compute".to_string())
2411                        .capacity_group(CapacityGroup {
2412                            group_id: "general".to_string(),
2413                            instance_type: Some("m7g.large".to_string()),
2414                            profile: Some(spec.to_machine_profile()),
2415                            min_size: 1,
2416                            max_size: 1,
2417                            scale_policy: None,
2418                            nested_virtualization: None,
2419                            data_disk_gib_range: None,
2420                        })
2421                        .build(),
2422                ),
2423                lifecycle: ResourceLifecycle::Frozen,
2424                dependencies: Vec::new(),
2425                display_name: None,
2426                description: None,
2427                remote_access: false,
2428                enabled_when: None,
2429            },
2430        );
2431        let plan = plan_compute(&stack, Platform::Aws, None).expect("plan should build");
2432        let option = plan.pools[0]
2433            .machines
2434            .iter()
2435            .find(|option| option.machine == "m7g.large")
2436            .expect("m7g.large should be listed");
2437        assert!(option.available, "{:?}", option.unavailable_reasons);
2438    }
2439
2440    #[test]
2441    fn nested_pool_without_architecture_plans_an_aws_machine() {
2442        let mut stack = stack_with_container();
2443        let cluster = ComputeCluster::new("compute".to_string())
2444            .capacity_group(CapacityGroup {
2445                group_id: "general".to_string(),
2446                instance_type: None,
2447                profile: Some(MachineProfile {
2448                    cpu: "4".to_string(),
2449                    memory_bytes: 16 * 1024 * 1024 * 1024,
2450                    ephemeral_storage_bytes: 20 * 1024 * 1024 * 1024,
2451                    architecture: None,
2452                    gpu: None,
2453                    data_disk: None,
2454                }),
2455                min_size: 1,
2456                max_size: 1,
2457                scale_policy: None,
2458                nested_virtualization: Some(true),
2459                data_disk_gib_range: None,
2460            })
2461            .build();
2462        stack.resources.insert(
2463            "compute".to_string(),
2464            ResourceEntry {
2465                config: Resource::new(cluster),
2466                lifecycle: ResourceLifecycle::Frozen,
2467                dependencies: Vec::new(),
2468                display_name: None,
2469                description: None,
2470                remote_access: false,
2471                enabled_when: None,
2472            },
2473        );
2474
2475        let plan = plan_compute(&stack, Platform::Aws, None).expect("plan should build");
2476
2477        let pool = plan.pools.first().expect("general pool should exist");
2478        assert!(pool.errors.is_empty(), "{:?}", pool.errors);
2479        let machine = pool
2480            .selected
2481            .machine()
2482            .expect("AWS selection should include a machine");
2483        let spec = instance_catalog::find_instance_type(Platform::Aws, machine)
2484            .expect("selected machine should exist in the catalog");
2485        assert!(
2486            spec.is_nested_virt_capable(),
2487            "{machine} is not nested-capable"
2488        );
2489        assert_eq!(spec.architecture, Architecture::X86_64);
2490
2491        // Every AWS machine is listed, in catalog order: category, series, then vCPU.
2492        let catalog = instance_catalog::catalog_for_platform(Platform::Aws);
2493        assert_eq!(
2494            pool.machines
2495                .iter()
2496                .map(|option| option.machine.as_str())
2497                .collect::<Vec<_>>(),
2498            catalog.iter().map(|spec| spec.name).collect::<Vec<_>>()
2499        );
2500        // The pool needs 4 vCPU and 16 GiB per replica, on a nested-capable x86 machine.
2501        for (option, spec) in pool.machines.iter().zip(&catalog) {
2502            let fits = spec.is_nested_virt_capable()
2503                && spec.architecture == Architecture::X86_64
2504                && spec.vcpu >= 4
2505                && spec.memory_bytes >= 16 * GIB
2506                && (spec.has_configurable_ephemeral_storage()
2507                    || spec.ephemeral_storage_bytes >= 20 * GIB);
2508            assert_eq!(option.available, fits, "{}", option.machine);
2509            assert_eq!(
2510                option.available,
2511                option.unavailable_reasons.is_empty(),
2512                "{}",
2513                option.machine
2514            );
2515        }
2516
2517        let option = |name: &str| {
2518            pool.machines
2519                .iter()
2520                .find(|option| option.machine == name)
2521                .unwrap_or_else(|| panic!("{name} should be listed"))
2522        };
2523        let reasons = |name: &str| option(name).unavailable_reasons.clone();
2524        assert_eq!(reasons("m8i.xlarge"), vec![]);
2525        assert_eq!(
2526            reasons("m8i.large"),
2527            vec![
2528                MachineUnavailableReason::Cpu,
2529                MachineUnavailableReason::Memory
2530            ]
2531        );
2532        assert_eq!(
2533            reasons("c8i.xlarge"),
2534            vec![MachineUnavailableReason::Memory]
2535        );
2536        assert_eq!(
2537            reasons("m7g.xlarge"),
2538            vec![
2539                MachineUnavailableReason::Architecture,
2540                MachineUnavailableReason::NestedVirtualization
2541            ]
2542        );
2543        assert_eq!(
2544            reasons("t3.xlarge"),
2545            vec![MachineUnavailableReason::NestedVirtualization]
2546        );
2547        assert_eq!(
2548            reasons("t4g.micro"),
2549            vec![
2550                MachineUnavailableReason::Architecture,
2551                MachineUnavailableReason::NestedVirtualization,
2552                MachineUnavailableReason::Cpu,
2553                MachineUnavailableReason::Memory
2554            ]
2555        );
2556
2557        let large = option("m8i.24xlarge");
2558        assert!(large.available);
2559        assert_eq!(large.series, "m8i");
2560        assert_eq!(large.category, InstanceFamily::GeneralPurpose);
2561        assert_eq!(large.label, "General purpose · Intel · 8th gen");
2562        assert!(large.nested_virtualization);
2563        assert_eq!(large.local_storage, None);
2564        let local = option("i7i.xlarge");
2565        assert!(local.available);
2566        assert_eq!(local.category, InstanceFamily::StorageOptimized);
2567        // AWS reports 937 decimal GB of local NVMe.
2568        assert_eq!(local.local_storage, Some(893_592 * 1024 * 1024));
2569
2570        let wire = serde_json::to_value(large).expect("option should serialize");
2571        assert_eq!(wire["category"], "generalPurpose");
2572        assert_eq!(wire["nestedVirtualization"], true);
2573        assert_eq!(wire["unavailableReasons"], serde_json::json!([]));
2574        assert!(wire.get("localStorage").is_none());
2575        let wire = serde_json::to_value(option("m7g.xlarge")).expect("option should serialize");
2576        assert_eq!(wire["available"], false);
2577        assert_eq!(
2578            wire["unavailableReasons"],
2579            serde_json::json!(["architecture", "nestedVirtualization"])
2580        );
2581        assert_eq!(
2582            serde_json::to_value(local).expect("option should serialize")["localStorage"],
2583            893_592u64 * 1024 * 1024
2584        );
2585    }
2586
2587    const GIB: u64 = 1024 * 1024 * 1024;
2588
2589    /// A stack with one declared `general` pool. `data_disk_gib` is the
2590    /// declared size (the default for a range) and `range` the sizes offered.
2591    fn stack_with_data_disk_pool(
2592        data_disk_gib: Option<u64>,
2593        range: Option<ComputeChoiceRange>,
2594    ) -> Stack {
2595        let mut stack = stack_with_container();
2596        let cluster = ComputeCluster::new("compute".to_string())
2597            .capacity_group(CapacityGroup {
2598                group_id: "general".to_string(),
2599                instance_type: None,
2600                profile: Some(MachineProfile {
2601                    cpu: "2".to_string(),
2602                    memory_bytes: 8 * GIB,
2603                    ephemeral_storage_bytes: 20 * GIB,
2604                    architecture: None,
2605                    gpu: None,
2606                    data_disk: data_disk_gib.map(|gib| crate::DataDiskRequirement {
2607                        size_bytes: gib * GIB,
2608                    }),
2609                }),
2610                min_size: 1,
2611                max_size: 1,
2612                scale_policy: None,
2613                nested_virtualization: None,
2614                data_disk_gib_range: range,
2615            })
2616            .build();
2617        stack.resources.insert(
2618            "compute".to_string(),
2619            ResourceEntry {
2620                config: Resource::new(cluster),
2621                lifecycle: ResourceLifecycle::Frozen,
2622                dependencies: Vec::new(),
2623                display_name: None,
2624                description: None,
2625                remote_access: false,
2626                enabled_when: None,
2627            },
2628        );
2629        stack
2630    }
2631
2632    fn data_disk_selection(data_disk_gib: Option<u32>) -> ComputeSettings {
2633        ComputeSettings {
2634            pools: [(
2635                "general".to_string(),
2636                ComputePoolSelection::Fixed {
2637                    machines: 1,
2638                    machine: None,
2639                    failure_domains: None,
2640                    data_disk_gib,
2641                },
2642            )]
2643            .into_iter()
2644            .collect(),
2645            containers: HashMap::new(),
2646        }
2647    }
2648
2649    fn general_pool(plan: &ComputePlan) -> &ComputePoolPlan {
2650        plan.pools
2651            .iter()
2652            .find(|pool| pool.pool_id == "general")
2653            .expect("general pool should be planned")
2654    }
2655
2656    #[test]
2657    fn a_deployment_chooses_its_data_disk_within_the_declared_range() {
2658        let range = ComputeChoiceRange {
2659            min: 0,
2660            max: 4096,
2661            default: 200,
2662        };
2663        let stack = stack_with_data_disk_pool(Some(200), Some(range));
2664        for platform in [Platform::Aws, Platform::Machines] {
2665            for (selected, expected_gib) in [(None, 200), (Some(50), 50), (Some(0), 0)] {
2666                let settings = data_disk_selection(selected);
2667                let plan = plan_compute(&stack, platform, Some(&settings)).expect("plan");
2668                let pool = general_pool(&plan);
2669                assert!(
2670                    pool.errors.is_empty(),
2671                    "{platform} {selected:?}: {:?}",
2672                    pool.errors
2673                );
2674                assert_eq!(
2675                    pool.data_disk,
2676                    Some(ComputePoolDataDiskPlan {
2677                        min_gib: 0,
2678                        max_gib: 4096,
2679                        default_gib: 200,
2680                        selected_gib: expected_gib,
2681                    }),
2682                    "{platform} {selected:?}"
2683                );
2684                // An omitted choice stays omitted, so later releases can move the default.
2685                assert_eq!(pool.selected.data_disk_gib(), selected, "{platform}");
2686            }
2687
2688            let settings = data_disk_selection(Some(5000));
2689            let plan = plan_compute(&stack, platform, Some(&settings)).expect("plan");
2690            assert_eq!(
2691                general_pool(&plan).errors,
2692                vec!["pool 'general' data disk must be between 0 and 4096 GiB; dataDiskGib 5000 is outside that range".to_string()],
2693                "{platform}"
2694            );
2695        }
2696    }
2697
2698    #[test]
2699    fn a_fixed_or_absent_data_disk_refuses_another_size() {
2700        let fixed = stack_with_data_disk_pool(Some(100), None);
2701        let plan = plan_compute(&fixed, Platform::Aws, None).expect("plan");
2702        assert_eq!(
2703            general_pool(&plan).data_disk,
2704            Some(ComputePoolDataDiskPlan {
2705                min_gib: 100,
2706                max_gib: 100,
2707                default_gib: 100,
2708                selected_gib: 100,
2709            })
2710        );
2711        let plan = plan_compute(&fixed, Platform::Aws, Some(&data_disk_selection(Some(200))))
2712            .expect("plan");
2713        assert_eq!(
2714            general_pool(&plan).errors,
2715            vec![
2716                "pool 'general' has a fixed 100 GiB data disk; dataDiskGib 200 cannot be chosen"
2717                    .to_string()
2718            ]
2719        );
2720
2721        let absent = stack_with_data_disk_pool(None, None);
2722        let plan = plan_compute(&absent, Platform::Aws, Some(&data_disk_selection(Some(0))))
2723            .expect("plan");
2724        assert!(general_pool(&plan).errors.is_empty());
2725        assert_eq!(general_pool(&plan).data_disk, None);
2726        let plan = plan_compute(&absent, Platform::Aws, Some(&data_disk_selection(Some(50))))
2727            .expect("plan");
2728        assert_eq!(
2729            general_pool(&plan).errors,
2730            vec![
2731                "pool 'general' declares no data disk, so dataDiskGib 50 cannot be chosen"
2732                    .to_string()
2733            ]
2734        );
2735    }
2736
2737    #[test]
2738    fn materialized_machine_profile_is_not_counted_as_workload_demand() {
2739        let mut stack = stack_with_container();
2740        let selected = instance_catalog::find_instance_type(Platform::Aws, "m7g.xlarge")
2741            .expect("machine should exist in catalog");
2742        let cluster = ComputeCluster::new("compute".to_string())
2743            .capacity_group(CapacityGroup {
2744                group_id: "general".to_string(),
2745                instance_type: Some(selected.name.to_string()),
2746                profile: Some(selected.to_machine_profile()),
2747                min_size: 1,
2748                max_size: 1,
2749                scale_policy: None,
2750                nested_virtualization: None,
2751                data_disk_gib_range: None,
2752            })
2753            .build();
2754        stack.resources.insert(
2755            "compute".to_string(),
2756            ResourceEntry {
2757                config: Resource::new(cluster),
2758                lifecycle: ResourceLifecycle::Frozen,
2759                dependencies: Vec::new(),
2760                display_name: None,
2761                description: None,
2762                remote_access: false,
2763                enabled_when: None,
2764            },
2765        );
2766
2767        let plan = plan_compute(&stack, Platform::Aws, None).expect("plan should build");
2768        let pool = plan.pools.first().expect("general pool should exist");
2769
2770        assert_eq!(pool.requirements.cpu, "2");
2771        assert_eq!(pool.requirements.memory_bytes, 4 * 1024 * 1024 * 1024);
2772        assert_eq!(pool.recommended.machine(), Some("m7g.xlarge"));
2773        assert!(pool
2774            .machines
2775            .iter()
2776            .any(|option| option.machine == "m7g.xlarge"));
2777    }
2778
2779    #[test]
2780    fn nested_x86_fixed_range_pool_preserves_bounds_and_rejects_graviton() {
2781        let daemon = Daemon::new("vm-runtime-loader".to_string())
2782            .code(DaemonCode::Image {
2783                image: "example.com/vm-runtime:latest".to_string(),
2784            })
2785            .cluster("vm-runtime".to_string())
2786            .cpu(ResourceSpec {
2787                min: "2".to_string(),
2788                desired: "2".to_string(),
2789            })
2790            .memory(ResourceSpec {
2791                min: "4Gi".to_string(),
2792                desired: "4Gi".to_string(),
2793            })
2794            .permissions("loader".to_string())
2795            .build();
2796        let cluster = ComputeCluster::new("vm-runtime".to_string())
2797            .capacity_group(CapacityGroup {
2798                group_id: "general".to_string(),
2799                instance_type: None,
2800                profile: Some(MachineProfile {
2801                    cpu: "4".to_string(),
2802                    memory_bytes: 16 * 1024 * 1024 * 1024,
2803                    ephemeral_storage_bytes: 20 * 1024 * 1024 * 1024,
2804                    architecture: Some(Architecture::X86_64),
2805                    gpu: None,
2806                    data_disk: None,
2807                }),
2808                min_size: 2,
2809                max_size: 2,
2810                scale_policy: Some(CapacityGroupScalePolicy::Fixed {
2811                    machines: ComputeChoiceRange {
2812                        min: 1,
2813                        max: 5,
2814                        default: 2,
2815                    },
2816                }),
2817                nested_virtualization: Some(true),
2818                data_disk_gib_range: None,
2819            })
2820            .build();
2821        let stack = Stack {
2822            id: "vm-runtime".to_string(),
2823            resources: [
2824                (
2825                    "vm-runtime-loader".to_string(),
2826                    ResourceEntry {
2827                        config: Resource::new(daemon),
2828                        lifecycle: ResourceLifecycle::Live,
2829                        dependencies: Vec::new(),
2830                        display_name: None,
2831                        description: None,
2832                        remote_access: false,
2833                        enabled_when: None,
2834                    },
2835                ),
2836                (
2837                    "vm-runtime".to_string(),
2838                    ResourceEntry {
2839                        config: Resource::new(cluster),
2840                        lifecycle: ResourceLifecycle::Frozen,
2841                        dependencies: Vec::new(),
2842                        display_name: None,
2843                        description: None,
2844                        remote_access: false,
2845                        enabled_when: None,
2846                    },
2847                ),
2848            ]
2849            .into_iter()
2850            .collect(),
2851            permissions: crate::permissions::PermissionsConfig::default(),
2852            supported_platforms: None,
2853            inputs: vec![],
2854            dynamic_container_repositories: Vec::new(),
2855            dynamic_container_image_resources: Vec::new(),
2856            operations: None,
2857        };
2858
2859        let plan = plan_compute(&stack, Platform::Aws, None).expect("plan should build");
2860        let pool = plan.pools.first().expect("general pool should exist");
2861        assert_eq!(pool.recommended.machine(), Some("m8i.2xlarge"));
2862        assert_eq!(pool.recommended.min_size(), 2);
2863        assert_eq!(pool.recommended.max_size(), 2);
2864        assert_eq!(
2865            pool.scale,
2866            CapacityGroupScalePolicy::Fixed {
2867                machines: ComputeChoiceRange {
2868                    min: 1,
2869                    max: 5,
2870                    default: 2,
2871                },
2872            }
2873        );
2874        let graviton = pool
2875            .machines
2876            .iter()
2877            .find(|option| option.machine == "m7g.2xlarge")
2878            .expect("every AWS machine is listed");
2879        assert!(!graviton.available);
2880        assert_eq!(
2881            graviton.unavailable_reasons,
2882            vec![
2883                MachineUnavailableReason::Architecture,
2884                MachineUnavailableReason::NestedVirtualization
2885            ]
2886        );
2887
2888        let invalid_settings = ComputeSettings {
2889            containers: Default::default(),
2890            pools: [(
2891                "general".to_string(),
2892                ComputePoolSelection::Fixed {
2893                    machines: 2,
2894                    machine: Some("m7g.2xlarge".to_string()),
2895                    failure_domains: None,
2896                    data_disk_gib: None,
2897                },
2898            )]
2899            .into_iter()
2900            .collect(),
2901        };
2902        let invalid_plan = plan_compute(&stack, Platform::Aws, Some(&invalid_settings))
2903            .expect("plan should build");
2904        assert_eq!(
2905            invalid_plan.pools[0].errors,
2906            vec!["aws machine 'm7g.2xlarge' does not satisfy pool 'general' requirements"]
2907        );
2908    }
2909
2910    fn declared_pool_errors(
2911        scale: CapacityGroupScalePolicy,
2912        selection: ComputePoolSelection,
2913    ) -> Vec<String> {
2914        let mut stack = stack_with_container();
2915        let cluster = ComputeCluster::new("compute".to_string())
2916            .capacity_group(CapacityGroup {
2917                group_id: "general".to_string(),
2918                instance_type: None,
2919                profile: None,
2920                min_size: scale.default_min_size(),
2921                max_size: scale.default_max_size(),
2922                scale_policy: Some(scale),
2923                nested_virtualization: None,
2924                data_disk_gib_range: None,
2925            })
2926            .build();
2927        stack.resources.insert(
2928            "compute".to_string(),
2929            ResourceEntry {
2930                config: Resource::new(cluster),
2931                lifecycle: ResourceLifecycle::Frozen,
2932                dependencies: Vec::new(),
2933                display_name: None,
2934                description: None,
2935                remote_access: false,
2936                enabled_when: None,
2937            },
2938        );
2939        let settings = ComputeSettings {
2940            containers: Default::default(),
2941            pools: [("general".to_string(), selection)].into_iter().collect(),
2942        };
2943        plan_compute(&stack, Platform::Aws, Some(&settings))
2944            .expect("plan should build")
2945            .pools
2946            .remove(0)
2947            .errors
2948    }
2949
2950    fn range(min: u32, max: u32, default: u32) -> ComputeChoiceRange {
2951        ComputeChoiceRange { min, max, default }
2952    }
2953
2954    #[test]
2955    fn generated_pool_offers_the_recommendation_as_a_default_not_a_bound() {
2956        let mut stack = stack_with_container();
2957        let api = stack
2958            .resources
2959            .get_mut("api")
2960            .and_then(|entry| entry.config.downcast_mut::<Container>())
2961            .expect("test stack should contain a container");
2962        api.autoscaling = Some(crate::ContainerAutoscaling {
2963            min: 1,
2964            desired: 1,
2965            max: 3,
2966            target_cpu_percent: Some(70.0),
2967            target_memory_percent: None,
2968            target_http_in_flight_per_replica: None,
2969            max_http_p95_latency_ms: None,
2970        });
2971
2972        // Three replicas at most, one machine each, plus one for a rolling update.
2973        let plan = plan_compute(&stack, Platform::Aws, None).expect("plan should build");
2974        let pool = &plan.pools[0];
2975        assert_eq!(
2976            pool.scale,
2977            CapacityGroupScalePolicy::Autoscale {
2978                min: range(1, 100, 1),
2979                max: range(1, 100, 4),
2980            }
2981        );
2982        assert_eq!(
2983            (pool.recommended.min_size(), pool.recommended.max_size()),
2984            (1, 4)
2985        );
2986        assert!(pool.errors.is_empty());
2987    }
2988
2989    /// A one-replica container fills its one machine, so a release has nowhere to start the
2990    /// new replica before stopping the old one. The default pool autoscales 1-2 so it can, on
2991    /// the same machine type: the extra machine is only there during a release.
2992    #[test]
2993    fn generated_pool_has_room_to_start_a_new_replica_before_stopping_the_old_one() {
2994        let plan =
2995            plan_compute(&stack_with_container(), Platform::Aws, None).expect("plan should build");
2996        let pool = &plan.pools[0];
2997        assert_eq!(
2998            pool.scale,
2999            CapacityGroupScalePolicy::Autoscale {
3000                min: range(1, 100, 1),
3001                max: range(1, 100, 2),
3002            }
3003        );
3004        assert_eq!(
3005            (pool.recommended.min_size(), pool.recommended.max_size()),
3006            (1, 2)
3007        );
3008        assert!(matches!(
3009            pool.recommended,
3010            ComputePoolSelection::Autoscale { .. }
3011        ));
3012        assert!(pool.errors.is_empty());
3013
3014        // A stateful container replaces in place, so its pool gets no extra machine.
3015        let mut stateful = stack_with_container();
3016        stateful
3017            .resources
3018            .get_mut("api")
3019            .and_then(|entry| entry.config.downcast_mut::<Container>())
3020            .expect("test stack should contain a container")
3021            .stateful = true;
3022        let stateful_plan =
3023            plan_compute(&stateful, Platform::Aws, None).expect("plan should build");
3024        let stateful_pool = &stateful_plan.pools[0];
3025        assert!(matches!(
3026            stateful_pool.recommended,
3027            ComputePoolSelection::Fixed { machines: 1, .. }
3028        ));
3029
3030        // The extra machine doesn't change the machine type: both pools fit one replica per
3031        // machine on the same type.
3032        assert!(pool.recommended.machine().is_some());
3033        assert_eq!(
3034            pool.recommended.machine(),
3035            stateful_pool.recommended.machine()
3036        );
3037
3038        // A saved choice is the installer's cost bound and stays as chosen.
3039        let saved = ComputeSettings {
3040            containers: Default::default(),
3041            pools: [(
3042                "general".to_string(),
3043                ComputePoolSelection::Fixed {
3044                    machines: 1,
3045                    machine: pool.recommended.machine().map(str::to_string),
3046                    failure_domains: None,
3047                    data_disk_gib: None,
3048                },
3049            )]
3050            .into_iter()
3051            .collect(),
3052        };
3053        let saved_plan = plan_compute(&stack_with_container(), Platform::Aws, Some(&saved))
3054            .expect("plan should build");
3055        assert_eq!(
3056            (
3057                saved_plan.pools[0].selected.min_size(),
3058                saved_plan.pools[0].selected.max_size()
3059            ),
3060            (1, 1)
3061        );
3062    }
3063
3064    /// A pool larger than the offered machine count is sized onto bigger machines, so the
3065    /// offered fleet still holds it. The rolling-update machine doesn't change that.
3066    #[test]
3067    fn generated_pool_beyond_the_offered_fleet_is_sized_to_fit_it() {
3068        let mut stack = stack_with_container();
3069        stack
3070            .resources
3071            .get_mut("api")
3072            .and_then(|entry| entry.config.downcast_mut::<Container>())
3073            .expect("test stack should contain a container")
3074            .replicas = Some(400);
3075
3076        let plan = plan_compute(&stack, Platform::Aws, None).expect("plan should build");
3077        let pool = &plan.pools[0];
3078        assert!(pool.errors.is_empty(), "{:?}", pool.errors);
3079        assert_eq!(pool.recommended.max_size(), GENERATED_POOL_MAX_MACHINES);
3080    }
3081
3082    #[test]
3083    fn generated_pool_rejects_a_fleet_too_small_for_desired_replicas() {
3084        let mut stack = stack_with_container();
3085        let api = stack
3086            .resources
3087            .get_mut("api")
3088            .and_then(|entry| entry.config.downcast_mut::<Container>())
3089            .expect("test stack should contain a container");
3090        // 3 x 2 vCPU / 4 GiB requested at the desired count.
3091        api.replicas = Some(3);
3092        let selection = |machines| ComputeSettings {
3093            containers: Default::default(),
3094            pools: [(
3095                "general".to_string(),
3096                ComputePoolSelection::Fixed {
3097                    machines,
3098                    machine: Some("m7g.xlarge".to_string()),
3099                    failure_domains: None,
3100                    data_disk_gib: None,
3101                },
3102            )]
3103            .into_iter()
3104            .collect(),
3105        };
3106
3107        // m7g.xlarge: 3.5 vCPU available after the host reserve.
3108        let errors = plan_compute(&stack, Platform::Aws, Some(&selection(1)))
3109            .expect("plan should build")
3110            .pools
3111            .remove(0)
3112            .errors;
3113        assert_eq!(errors.len(), 1, "{errors:?}");
3114        assert!(
3115            errors[0].starts_with(
3116                "Pool 'general' is too small for its workloads: 1 x m7g.xlarge has 3.50 vCPU"
3117            ),
3118            "{errors:?}"
3119        );
3120        assert!(errors[0].contains("request 6.00 vCPU"), "{errors:?}");
3121
3122        let errors = plan_compute(&stack, Platform::Aws, Some(&selection(2)))
3123            .expect("plan should build")
3124            .pools
3125            .remove(0)
3126            .errors;
3127        assert!(errors.is_empty(), "{errors:?}");
3128    }
3129
3130    #[test]
3131    fn fixed_and_equal_autoscale_bounds_are_interchangeable_for_declared_pools() {
3132        let fixed = |machines| ComputePoolSelection::Fixed {
3133            machines,
3134            machine: Some("m7g.xlarge".to_string()),
3135            failure_domains: None,
3136            data_disk_gib: None,
3137        };
3138        let autoscale = |min, max| ComputePoolSelection::Autoscale {
3139            min,
3140            max,
3141            machine: Some("m7g.xlarge".to_string()),
3142            failure_domains: None,
3143            data_disk_gib: None,
3144        };
3145        let declared_fixed = CapacityGroupScalePolicy::Fixed {
3146            machines: range(2, 4, 2),
3147        };
3148        let declared_autoscale = CapacityGroupScalePolicy::Autoscale {
3149            min: range(1, 3, 1),
3150            max: range(2, 6, 4),
3151        };
3152
3153        assert!(declared_pool_errors(declared_fixed.clone(), autoscale(3, 3)).is_empty());
3154        assert_eq!(
3155            declared_pool_errors(declared_fixed.clone(), autoscale(2, 4)),
3156            vec!["Pool 'general' must use fixed mode with 2-4 machines; autoscale 2-4 is not allowed"]
3157        );
3158        assert_eq!(
3159            declared_pool_errors(declared_fixed, autoscale(5, 5)),
3160            vec!["Pool 'general' machine count 5 is outside the allowed range 2-4"]
3161        );
3162
3163        // Fixed N must fit both the declared minimum and maximum ranges.
3164        assert!(declared_pool_errors(declared_autoscale.clone(), fixed(3)).is_empty());
3165        assert_eq!(
3166            declared_pool_errors(declared_autoscale.clone(), fixed(1)),
3167            vec!["Pool 'general' fixed machine count 1 is outside the allowed range 2-3"]
3168        );
3169        assert_eq!(
3170            declared_pool_errors(
3171                CapacityGroupScalePolicy::Autoscale {
3172                    min: range(1, 1, 1),
3173                    max: range(3, 5, 3),
3174                },
3175                fixed(1),
3176            ),
3177            vec!["Pool 'general' must use autoscale mode (minimum 1-1, maximum 3-5)"]
3178        );
3179        assert_eq!(
3180            declared_pool_errors(declared_autoscale, autoscale(1, 7)),
3181            vec!["Pool 'general' autoscale maximum 7 is outside the allowed range 2-6"]
3182        );
3183    }
3184
3185    #[test]
3186    fn local_plan_has_no_provider_machine_choices() {
3187        let stack = stack_with_container();
3188
3189        let plan = plan_compute(&stack, Platform::Local, None).expect("plan should build");
3190
3191        let pool = plan.pools.first().expect("general pool should exist");
3192        assert_eq!(pool.selected.machine(), None);
3193        assert!(pool.machines.is_empty());
3194        assert!(pool.errors.is_empty());
3195    }
3196}