Skip to main content

alien_core/
ownership.rs

1use crate::ResourceLifecycle;
2
3/// When a resource type contributes anything to the setup artifact.
4///
5/// Most types answer with the lifecycle alone. A sandbox does not: a Live one still needs the
6/// setup stack to create its build role, since the runtime controller may only *pass* it —
7/// `sandbox/provision` grants `iam:PassRole` and no `iam:CreateRole`. Only the image moves.
8#[derive(Debug, Clone, Copy, PartialEq, Eq)]
9pub enum SetupEmission {
10    /// Never part of the setup artifact; a runtime controller owns the whole resource.
11    Never,
12    /// Emitted only when the resource is Frozen.
13    WhenFrozen,
14    /// Scaffolding under either lifecycle. Setup still only *owns* the Frozen one — the Live
15    /// resource itself belongs to a runtime controller, which is why the two accessors below
16    /// disagree for exactly these types.
17    Always,
18}
19
20#[derive(Debug, Clone, Copy, PartialEq, Eq)]
21pub struct ResourceOwnershipPolicy {
22    default_lifecycle: ResourceLifecycle,
23    allow_frozen: bool,
24    allow_live: bool,
25    emit_in_setup: SetupEmission,
26    requires_management_permissions: bool,
27    runtime_cleanup_before_teardown: bool,
28}
29
30impl ResourceOwnershipPolicy {
31    pub const fn new(
32        default_lifecycle: ResourceLifecycle,
33        allow_frozen: bool,
34        allow_live: bool,
35        emit_in_setup: SetupEmission,
36        requires_management_permissions: bool,
37        runtime_cleanup_before_teardown: bool,
38    ) -> Self {
39        Self {
40            default_lifecycle,
41            allow_frozen,
42            allow_live,
43            emit_in_setup,
44            requires_management_permissions,
45            runtime_cleanup_before_teardown,
46        }
47    }
48
49    pub const fn default_lifecycle(self) -> ResourceLifecycle {
50        self.default_lifecycle
51    }
52
53    pub const fn allows_frozen(self) -> bool {
54        self.allow_frozen
55    }
56
57    pub const fn allows_live(self) -> bool {
58        self.allow_live
59    }
60
61    pub const fn allows_lifecycle(self, lifecycle: ResourceLifecycle) -> bool {
62        match lifecycle {
63            ResourceLifecycle::Frozen => self.allow_frozen,
64            ResourceLifecycle::Live => self.allow_live,
65        }
66    }
67
68    /// Whether setup *owns* this resource: it creates it, and no runtime controller will.
69    ///
70    /// Gating, lifecycle checks and permission compilation ask this. A Live sandbox answers
71    /// `false` here and `true` from [`Self::emits_setup_scaffolding`]; answering the two with
72    /// one predicate classifies it as setup-created, which keeps its gate out of the runtime
73    /// strip and builds the image for a deployer who declined it.
74    pub const fn should_emit_in_setup(self, lifecycle: ResourceLifecycle) -> bool {
75        !matches!(self.emit_in_setup, SetupEmission::Never)
76            && matches!(lifecycle, ResourceLifecycle::Frozen)
77    }
78
79    /// Whether the setup artifact renders anything for this resource, its own scaffolding
80    /// included — a Live sandbox's build role, which its controller may pass but not create.
81    ///
82    /// The generators and registration's expected set ask this, and must agree: registration
83    /// refuses a payload naming a resource setup does not emit, and one missing a resource it
84    /// does, so a disagreement fails every install after the stack has already completed.
85    pub const fn emits_setup_scaffolding(self, lifecycle: ResourceLifecycle) -> bool {
86        match self.emit_in_setup {
87            SetupEmission::Never => false,
88            SetupEmission::WhenFrozen => matches!(lifecycle, ResourceLifecycle::Frozen),
89            SetupEmission::Always => true,
90        }
91    }
92
93    /// Whether setup renders scaffolding for this type under either lifecycle, whether or not it
94    /// also owns the resource.
95    pub const fn always_emits_setup_scaffolding(self) -> bool {
96        matches!(self.emit_in_setup, SetupEmission::Always)
97    }
98
99    pub const fn requires_management_permissions(self) -> bool {
100        self.requires_management_permissions
101    }
102
103    pub const fn has_runtime_cleanup_before_teardown(self) -> bool {
104        self.runtime_cleanup_before_teardown
105    }
106
107    pub fn allowed_lifecycles(self) -> &'static str {
108        match (self.allow_frozen, self.allow_live) {
109            (true, true) => "Frozen or Live",
110            (true, false) => "Frozen",
111            (false, true) => "Live",
112            (false, false) => "no lifecycle",
113        }
114    }
115}
116
117pub fn ownership_policy_for_resource_type(resource_type: &str) -> ResourceOwnershipPolicy {
118    match resource_type {
119        "function" | "container-cluster" => removed_resource_type(),
120        "worker" | "daemon" | "container" => live_only(),
121        "compute-cluster" => frozen_with_runtime_cleanup(),
122        "sandbox" => sandbox_lifecycle(),
123        "artifact-registry" | "key" => frozen_with_management(),
124        "build"
125        | "network"
126        | "remote-stack-management"
127        | "resource-access"
128        // Only setup changes what the install trusts to change what runs.
129        | "verifier"
130        | "service-account"
131        | "service_activation"
132        | "service-activation"
133        | "azure_resource_group"
134        | "azure-resource-group"
135        | "azure_storage_account"
136        | "azure-storage-account"
137        | "azure_container_apps_environment"
138        | "azure-container-apps-environment"
139        | "azure_service_bus_namespace"
140        | "azure-service-bus-namespace"
141        // Email holds durable routing state (domain identities, DKIM
142        // verification, receipt rules) that setup owns end to end.
143        | "email"
144        // A database is created by setup, which also owns its password, network and size: a
145        // later release changes it by re-running setup.
146        | "postgres" => frozen_only(),
147        // Durable search state, setup-owned only: there is no runtime
148        // controller that could provision or replace the collection.
149        "experimental/aws-opensearch" => frozen_only(),
150        // A setup-created Memorystore instance has no readable auth token in its Terraform
151        // output, so Alien copies it into Secret Manager after setup and needs `redis/management`
152        // even while the resource is Frozen.
153        "redis" => user_choice_with_management(),
154        "storage" | "queue" | "kv" | "vault" | "ai" => user_choice(),
155        _ => user_choice(),
156    }
157}
158
159const fn frozen_only() -> ResourceOwnershipPolicy {
160    ResourceOwnershipPolicy::new(
161        ResourceLifecycle::Frozen,
162        true,
163        false,
164        SetupEmission::WhenFrozen,
165        false,
166        false,
167    )
168}
169
170const fn frozen_with_management() -> ResourceOwnershipPolicy {
171    ResourceOwnershipPolicy::new(
172        ResourceLifecycle::Frozen,
173        true,
174        false,
175        SetupEmission::WhenFrozen,
176        true,
177        false,
178    )
179}
180
181const fn frozen_with_runtime_cleanup() -> ResourceOwnershipPolicy {
182    ResourceOwnershipPolicy::new(
183        ResourceLifecycle::Frozen,
184        true,
185        false,
186        SetupEmission::WhenFrozen,
187        true,
188        true,
189    )
190}
191
192/// A sandbox may be baked by the setup stack or provisioned by a runtime controller.
193///
194/// Live is what lets the base image come from Alien's private registry: the cross-account read is
195/// granted by a repository policy naming the customer's account, which isn't known until the
196/// deployment registers. Frozen stays the default so an already-installed stack keeps its image.
197const fn sandbox_lifecycle() -> ResourceOwnershipPolicy {
198    ResourceOwnershipPolicy::new(
199        ResourceLifecycle::Frozen,
200        true,
201        true,
202        SetupEmission::Always,
203        true,
204        true,
205    )
206}
207
208const fn live_only() -> ResourceOwnershipPolicy {
209    ResourceOwnershipPolicy::new(
210        ResourceLifecycle::Live,
211        false,
212        true,
213        SetupEmission::Never,
214        false,
215        false,
216    )
217}
218
219const fn removed_resource_type() -> ResourceOwnershipPolicy {
220    ResourceOwnershipPolicy::new(
221        ResourceLifecycle::Live,
222        false,
223        false,
224        SetupEmission::Never,
225        false,
226        false,
227    )
228}
229
230const fn user_choice_with_management() -> ResourceOwnershipPolicy {
231    ResourceOwnershipPolicy::new(
232        ResourceLifecycle::Frozen,
233        true,
234        true,
235        SetupEmission::WhenFrozen,
236        true,
237        false,
238    )
239}
240
241const fn user_choice() -> ResourceOwnershipPolicy {
242    ResourceOwnershipPolicy::new(
243        ResourceLifecycle::Frozen,
244        true,
245        true,
246        SetupEmission::WhenFrozen,
247        false,
248        false,
249    )
250}
251
252#[cfg(test)]
253mod tests {
254    use super::*;
255
256    #[test]
257    fn workload_resources_are_live_only() {
258        for resource_type in ["worker", "daemon", "container"] {
259            let policy = ownership_policy_for_resource_type(resource_type);
260            assert_eq!(policy.default_lifecycle(), ResourceLifecycle::Live);
261            assert!(!policy.allows_lifecycle(ResourceLifecycle::Frozen));
262            assert!(policy.allows_lifecycle(ResourceLifecycle::Live));
263            assert!(!policy.should_emit_in_setup(ResourceLifecycle::Live));
264        }
265    }
266
267    #[test]
268    fn compute_cluster_is_frozen_with_runtime_cleanup() {
269        let policy = ownership_policy_for_resource_type("compute-cluster");
270        assert_eq!(policy.default_lifecycle(), ResourceLifecycle::Frozen);
271        assert!(policy.allows_lifecycle(ResourceLifecycle::Frozen));
272        assert!(!policy.allows_lifecycle(ResourceLifecycle::Live));
273        assert!(policy.should_emit_in_setup(ResourceLifecycle::Frozen));
274        assert!(policy.requires_management_permissions());
275        assert!(policy.has_runtime_cleanup_before_teardown());
276    }
277
278    #[test]
279    fn sandbox_defaults_to_frozen_but_may_be_live() {
280        let policy = ownership_policy_for_resource_type("sandbox");
281        assert_eq!(policy.default_lifecycle(), ResourceLifecycle::Frozen);
282        assert!(policy.allows_lifecycle(ResourceLifecycle::Frozen));
283        assert!(policy.allows_lifecycle(ResourceLifecycle::Live));
284        assert!(policy.requires_management_permissions());
285        assert!(policy.has_runtime_cleanup_before_teardown());
286    }
287
288    /// The sandbox is the only type whose two answers differ, and each half is load-bearing:
289    /// setup must still install the build role its controller may only pass, while the image
290    /// belongs to that controller and so must reach the runtime strip a decline runs through.
291    #[test]
292    fn a_live_sandbox_is_scaffolded_by_setup_but_not_owned_by_it() {
293        let policy = ownership_policy_for_resource_type("sandbox");
294
295        assert!(policy.should_emit_in_setup(ResourceLifecycle::Frozen));
296        assert!(policy.emits_setup_scaffolding(ResourceLifecycle::Frozen));
297
298        assert!(!policy.should_emit_in_setup(ResourceLifecycle::Live));
299        assert!(policy.emits_setup_scaffolding(ResourceLifecycle::Live));
300    }
301
302    /// Every type but the sandbox must answer `should_emit_in_setup` and
303    /// `emits_setup_scaffolding` identically; a diverging type has silently changed ownership
304    /// behaviour.
305    #[test]
306    fn only_the_sandbox_separates_ownership_from_scaffolding() {
307        let types = crate::gateability::MANIFEST_TYPES.iter().copied().chain([
308            "function",
309            "container-cluster",
310            "compute-cluster",
311            "artifact-registry",
312            "key",
313            "build",
314            "network",
315            "remote-stack-management",
316            "resource-access",
317            "verifier",
318            "service-account",
319            "service_activation",
320            "service-activation",
321            "azure_resource_group",
322            "azure-resource-group",
323            "azure_storage_account",
324            "azure-storage-account",
325            "azure_container_apps_environment",
326            "azure-container-apps-environment",
327            "azure_service_bus_namespace",
328            "azure-service-bus-namespace",
329            "an-unregistered-extension-type",
330        ]);
331
332        for resource_type in types {
333            if resource_type == "sandbox" {
334                continue;
335            }
336            let policy = ownership_policy_for_resource_type(resource_type);
337            for lifecycle in [ResourceLifecycle::Frozen, ResourceLifecycle::Live] {
338                assert_eq!(
339                    policy.should_emit_in_setup(lifecycle),
340                    policy.emits_setup_scaffolding(lifecycle),
341                    "'{resource_type}' answers the two questions differently under {lifecycle:?}"
342                );
343            }
344        }
345    }
346
347    #[test]
348    fn artifact_registry_is_frozen_with_management() {
349        let policy = ownership_policy_for_resource_type("artifact-registry");
350        assert_eq!(policy.default_lifecycle(), ResourceLifecycle::Frozen);
351        assert!(policy.allows_lifecycle(ResourceLifecycle::Frozen));
352        assert!(!policy.allows_lifecycle(ResourceLifecycle::Live));
353        assert!(policy.should_emit_in_setup(ResourceLifecycle::Frozen));
354        assert!(policy.requires_management_permissions());
355        assert!(!policy.has_runtime_cleanup_before_teardown());
356    }
357
358    #[test]
359    fn removed_resource_type_tags_are_not_normal_policy_entries() {
360        for resource_type in ["function", "container-cluster"] {
361            let policy = ownership_policy_for_resource_type(resource_type);
362            assert!(!policy.allows_lifecycle(ResourceLifecycle::Frozen));
363            assert!(!policy.allows_lifecycle(ResourceLifecycle::Live));
364            assert!(!policy.requires_management_permissions());
365            assert!(!policy.has_runtime_cleanup_before_teardown());
366        }
367    }
368
369    #[test]
370    fn data_resources_can_be_frozen_or_live() {
371        for resource_type in ["storage", "queue", "kv", "vault", "redis", "ai"] {
372            let policy = ownership_policy_for_resource_type(resource_type);
373            assert_eq!(
374                policy.requires_management_permissions(),
375                resource_type == "redis"
376            );
377            assert_eq!(policy.default_lifecycle(), ResourceLifecycle::Frozen);
378            assert!(policy.allows_lifecycle(ResourceLifecycle::Frozen));
379            assert!(policy.allows_lifecycle(ResourceLifecycle::Live));
380            assert!(policy.should_emit_in_setup(ResourceLifecycle::Frozen));
381            assert!(!policy.should_emit_in_setup(ResourceLifecycle::Live));
382        }
383    }
384
385    #[test]
386    fn postgres_is_frozen_only() {
387        let policy = ownership_policy_for_resource_type("postgres");
388        assert_eq!(policy.default_lifecycle(), ResourceLifecycle::Frozen);
389        assert!(policy.allows_lifecycle(ResourceLifecycle::Frozen));
390        assert!(!policy.allows_lifecycle(ResourceLifecycle::Live));
391        assert!(policy.should_emit_in_setup(ResourceLifecycle::Frozen));
392    }
393
394    #[test]
395    fn experimental_aws_opensearch_is_frozen_only() {
396        let policy = ownership_policy_for_resource_type("experimental/aws-opensearch");
397        assert_eq!(policy.default_lifecycle(), ResourceLifecycle::Frozen);
398        assert!(policy.allows_lifecycle(ResourceLifecycle::Frozen));
399        assert!(!policy.allows_lifecycle(ResourceLifecycle::Live));
400        assert!(policy.should_emit_in_setup(ResourceLifecycle::Frozen));
401        assert!(!policy.requires_management_permissions());
402    }
403
404    #[test]
405    fn setup_resources_are_frozen_only() {
406        for resource_type in [
407            "build",
408            "network",
409            "remote-stack-management",
410            "resource-access",
411            "verifier",
412            "service-account",
413            "service_activation",
414            "azure_resource_group",
415            "azure_storage_account",
416            "azure_container_apps_environment",
417            "azure_service_bus_namespace",
418            "email",
419        ] {
420            let policy = ownership_policy_for_resource_type(resource_type);
421            assert!(policy.allows_lifecycle(ResourceLifecycle::Frozen));
422            assert!(!policy.allows_lifecycle(ResourceLifecycle::Live));
423            assert!(policy.should_emit_in_setup(ResourceLifecycle::Frozen));
424        }
425    }
426}