FM-602: Proxmox guest lifecycle and task operations

crates/fleet-api/src/lib.rs

@@ -129,6 +129,7 @@ pub const API_BASE_PATH: &str = "/api/v1";
         proxmox::AssociatedGuestDto,
         proxmox::AssociationCandidateDto,
         proxmox::ObserveProxmoxGuestRequest,
+        proxmox::StartProxmoxLifecycleRequest,
         proxmox::ProviderAgentDto,
         proxmox::ProviderInterfaceDto,
         node::CreateEnrollmentTokenRequest,
@@ -234,6 +235,7 @@ pub fn api(state: Arc<operations::ApiState>) -> (Router, utoipa::openapi::OpenAp
                 .routes(routes!(proxmox::discover_proxmox_cluster))
                 .routes(routes!(proxmox::list_proxmox_guests))
                 .routes(routes!(proxmox::observe_proxmox_guest))
+                .routes(routes!(proxmox::start_proxmox_lifecycle))
                 .with_state(state),
         )
         .split_for_parts();

crates/fleet-api/src/proxmox.rs

@@ -963,3 +963,139 @@ pub async fn observe_proxmox_guest(
         .map_err(|error| map_proxmox_error(&error, correlation_id))?;
     Ok(StatusCode::NO_CONTENT)
 }
+
+/// The lifecycle request: the guest's node and VMID.
+#[derive(Debug, Deserialize, ToSchema)]
+#[serde(rename_all = "camelCase")]
+pub struct StartProxmoxLifecycleRequest {
+    /// The guest's hosting node.
+    pub node: String,
+    /// The guest's VMID.
+    pub vmid: u32,
+    /// The deadline, in seconds. Bounded by the executor.
+    pub timeout_seconds: u64,
+}
+
+/// Runs a lifecycle action on one guest as a durable operation. The
+/// operation is authorized through the catalog's `proxmox.operate`
+/// (catalog-level, like the source kinds — a Proxmox guest is not a Fleet
+/// machine) and executed by the worker with Fleet-owned UPID polling.
+///
+/// # Errors
+///
+/// Returns the public error envelope on refusal or a malformed request.
+#[utoipa::path(
+    post,
+    path = "/proxmox/accounts/{accountId}/guests/{vmid}/{action}",
+    tag = "proxmox",
+    operation_id = "startProxmoxLifecycle",
+    params(
+        (
+            "accountId" = String,
+            Path,
+            description = "The account's identity."
+        ),
+        (
+            "vmid" = u32,
+            Path,
+            description = "The guest's VMID."
+        ),
+        (
+            "action" = String,
+            Path,
+            description = "The lifecycle action: start, stop, shutdown, or reboot."
+        ),
+    ),
+    request_body = StartProxmoxLifecycleRequest,
+    responses(
+        (
+            status = 202,
+            description = "The lifecycle operation was accepted and is durable.",
+            body = Resource<crate::operations::OperationDto>
+        ),
+        (
+            status = 400,
+            description = "The action is unrecognized or the request is malformed.",
+            body = crate::error::ApiError
+        ),
+        (
+            status = 403,
+            description = "The caller may not operate Proxmox guests.",
+            body = crate::error::ApiError
+        ),
+    )
+)]
+pub async fn start_proxmox_lifecycle(
+    State(state): State<Arc<crate::operations::ApiState>>,
+    principal: Option<Extension<crate::ActingPrincipal>>,
+    Extension(correlation_id): Extension<CorrelationId>,
+    headers: axum::http::HeaderMap,
+    Path((account_id, vmid, action)): Path<(String, u32, String)>,
+    Json(request): Json<StartProxmoxLifecycleRequest>,
+) -> Result<(StatusCode, Json<Resource<crate::operations::OperationDto>>), ApiErrorResponse> {
+    let principal = crate::operations::principal_or_error(principal, correlation_id)?;
+    // The body's VMID must agree with the path's: two names for one guest
+    // is a malformed request, not a fallback.
+    if request.vmid != vmid {
+        return Err(crate::machines::invalid_request(
+            "the body's vmid does not match the path's guest",
+            correlation_id,
+        ));
+    }
+    // The action is validated here so a malformed path is a 400, not an
+    // operation that fails later in the worker. The stable ids match the
+    // provider's `LifecycleAction` vocabulary; the executor re-validates.
+    if !matches!(action.as_str(), "start" | "stop" | "shutdown" | "reboot") {
+        return Err(crate::machines::invalid_request(
+            &format!("unrecognized lifecycle action {action:?}"),
+            correlation_id,
+        ));
+    }
+    // The executor re-applies the same gate at the account boundary; the
+    // catalog-level permission is checked here so a denial never creates
+    // an operation.
+    if let Err(decision) = fleet_application::authz::authorize(
+        state.authorizer.as_ref(),
+        fleet_application::authz::AccessRequest {
+            principal_id: &principal.id,
+            action: fleet_application::authz::Permission::ProxmoxOperate,
+            resource: None,
+        },
+    ) {
+        return Err(crate::machines::denied_error(decision, correlation_id));
+    }
+    let payload = serde_json::json!({
+        "accountId": account_id,
+        "node": request.node,
+        "vmid": vmid,
+        "timeoutSeconds": request.timeout_seconds,
+    });
+    let kind = format!("proxmox.guest.{action}");
+    // A caller-scoped idempotency key makes a retried POST return the
+    // original operation instead of a second one.
+    let idempotency_key = headers
+        .get(crate::IDEMPOTENCY_KEY_HEADER)
+        .and_then(|value| value.to_str().ok())
+        .map(|key| format!("{}:{key}", principal.id));
+    let operation = state
+        .operations
+        .create(
+            state.authorizer.as_ref(),
+            &principal.id,
+            &fleet_application::operation::NewOperation {
+                kind,
+                idempotency_key,
+                deadline_at: None,
+                correlation_id: Some(correlation_id.to_string()),
+                payload_json: Some(payload.to_string()),
+            },
+        )
+        .await
+        .map_err(|error| crate::operations::map_use_case_error(&error, correlation_id))?;
+    Ok((
+        StatusCode::ACCEPTED,
+        Json(Resource::new(crate::operations::OperationDto::from(
+            operation,
+        ))),
+    ))
+}

crates/fleet-application/src/authz.rs

@@ -136,6 +136,9 @@ pub enum Permission {
     /// Create, confirm trust for, or remove a Proxmox account. A
     /// mutation: it stores or removes a credential or a trust anchor.
     ProxmoxConfig,
+    /// Run a lifecycle action (start/stop/shutdown/reboot) on a Proxmox
+    /// guest. A mutation: it changes the guest's power state.
+    ProxmoxOperate,
 }
 
 impl Permission {
@@ -181,6 +184,7 @@ impl Permission {
         Permission::SourceActivate,
         Permission::ProxmoxRead,
         Permission::ProxmoxConfig,
+        Permission::ProxmoxOperate,
     ];
 
     /// The stable action id, as recorded in decisions and audit events.
@@ -225,6 +229,7 @@ impl Permission {
             Permission::SourceActivate => "source.activate",
             Permission::ProxmoxRead => "proxmox.read",
             Permission::ProxmoxConfig => "proxmox.config",
+            Permission::ProxmoxOperate => "proxmox.operate",
         }
     }
 
@@ -271,7 +276,8 @@ impl Permission {
             | Permission::SourceFetch
             | Permission::SourceActivate
             | Permission::ProxmoxRead
-            | Permission::ProxmoxConfig => true,
+            | Permission::ProxmoxConfig
+            | Permission::ProxmoxOperate => true,
         }
     }
 
@@ -296,7 +302,8 @@ impl Permission {
             | Permission::SourceFetch
             | Permission::SourceActivate
             | Permission::ProxmoxRead
-            | Permission::ProxmoxConfig => false,
+            | Permission::ProxmoxConfig
+            | Permission::ProxmoxOperate => false,
             Permission::MachineReadSensitive
             | Permission::OperationCancel
             | Permission::SecretRead

crates/fleet-application/src/operation.rs

@@ -43,7 +43,7 @@ use crate::authz::{AccessRequest, Authorizer, Decision, Permission, ReasonId, au
 /// machine-scoped shape plus the plan and its approval identities
 /// (FM-402); the source kinds carry the remote/commit payloads and are
 /// catalog-level (FM-403).
-pub const CREATABLE_KINDS: [&str; 31] = [
+pub const CREATABLE_KINDS: [&str; 35] = [
     "noop",
     "ssh.exec",
     "agentless.inventory",
@@ -75,6 +75,10 @@ pub const CREATABLE_KINDS: [&str; 31] = [
     "apply.workflow",
     "source.fetch",
     "source.activate",
+    "proxmox.guest.start",
+    "proxmox.guest.stop",
+    "proxmox.guest.shutdown",
+    "proxmox.guest.reboot",
 ];
 
 /// The machine-scoped permission a kind's creation requires, when any.
@@ -83,12 +87,23 @@ pub const CREATABLE_KINDS: [&str; 31] = [
 /// governs both the dedicated endpoint and the generic one.
 #[must_use]
 fn machine_scoped_kind_permission(kind: &str, payload: Option<&str>) -> Option<Permission> {
-    // The source kinds are catalog-level: their permission is enforced
-    // here with `resource: None`, never a machine id.
+    machine_scoped_kind_permission_inner(kind, payload)
+}
+
+/// The catalog-level permission a kind's creation requires, when any.
+/// The source and Proxmox lifecycle kinds act on infrastructure that is
+/// not a Fleet machine, so their permission is enforced with
+/// `resource: None` — never a machine id.
+#[must_use]
+fn catalog_scoped_kind_permission(kind: &str) -> Option<Permission> {
     match kind {
         "source.fetch" => Some(Permission::SourceFetch),
         "source.activate" => Some(Permission::SourceActivate),
-        _ => machine_scoped_kind_permission_inner(kind, payload),
+        "proxmox.guest.start"
+        | "proxmox.guest.stop"
+        | "proxmox.guest.shutdown"
+        | "proxmox.guest.reboot" => Some(Permission::ProxmoxOperate),
+        _ => None,
     }
 }
 
@@ -509,6 +524,16 @@ impl Operations {
                 },
             )
             .map_err(OperationUseCaseError::Denied)?;
+        } else if let Some(permission) = catalog_scoped_kind_permission(&new.kind) {
+            authorize(
+                authorizer,
+                AccessRequest {
+                    principal_id,
+                    action: permission,
+                    resource: None,
+                },
+            )
+            .map_err(OperationUseCaseError::Denied)?;
         }
         let operation = self
             .port
@@ -634,6 +659,19 @@ impl Operations {
         Ok(operation.state)
     }
 
+    /// Whether cancellation has been requested for the operation. The
+    /// worker reads this between poll cycles; it bypasses authorization
+    /// like the other worker-side reads, because the worker already owns
+    /// the claimed operation.
+    ///
+    /// # Errors
+    ///
+    /// Fails when the operation is unknown or the backend errors.
+    pub async fn cancel_requested(&self, id: &str) -> Result<bool, PortFailure> {
+        let operation = self.port.get(id).await?;
+        Ok(operation.cancel_requested)
+    }
+
     /// Reads one operation.
     ///
     /// # Errors

crates/fleet-auth/tests/authz_adapter.rs

@@ -103,7 +103,7 @@ fn every_catalog_action_has_a_unique_stable_id_and_a_risk_ruling() {
     assert!(Permission::MachineReadSensitive.is_risky());
     assert!(!Permission::SystemRead.is_risky());
     // The catalog is the complete vocabulary the adapter permits.
-    assert_eq!(Permission::ALL.len(), 38);
+    assert_eq!(Permission::ALL.len(), 39);
 }
 
 #[test]

crates/fleet-controller/src/lib.rs

@@ -20,6 +20,7 @@ pub mod install;
 pub mod mise;
 pub mod node_crypto;
 pub mod onboard;
+pub mod proxmox_exec;
 pub mod proxmox_store;
 pub mod ready;
 pub mod skills;

crates/fleet-controller/src/main.rs

@@ -285,6 +285,41 @@ fn run_serve(config: fleet_config::ControllerConfig) -> ExitCode {
                     )),
                 ))
             };
+            // The Proxmox lifecycle executor handles the FM-602 kinds over
+            // the same accounts and secret store the discovery surfaces
+            // use; it composes after the source dispatch so its kinds
+            // reach it and everything else falls through.
+            let with_proxmox: std::sync::Arc<dyn fleet_application::worker::OperationExecutor> = {
+                let proxmox_client = fleet_provider_proxmox::ProxmoxClient::new(
+                    std::sync::Arc::new(fleet_provider_proxmox::ReqwestPveTransport::new()),
+                );
+                let accounts: std::sync::Arc<dyn fleet_application::proxmox::ProxmoxAccountPort> =
+                    std::sync::Arc::new(fleet_storage_sqlite::ProxmoxAccountRepository::new(
+                        store.pool().clone(),
+                    ));
+                let credentials: std::sync::Arc<
+                    dyn fleet_application::proxmox::ProxmoxCredentialStore,
+                > = match &secrets {
+                    Some(secrets) => std::sync::Arc::new(
+                        fleet_controller::proxmox_store::SecretBackedProxmoxCredentials::new(
+                            secrets.clone(),
+                        ),
+                    ),
+                    None => std::sync::Arc::new(
+                        fleet_controller::proxmox_store::AbsentProxmoxCredentials,
+                    ),
+                };
+                std::sync::Arc::new(fleet_controller::proxmox_exec::ProxmoxDispatch::new(
+                    with_source.clone(),
+                    std::sync::Arc::new(
+                        fleet_controller::proxmox_exec::ProxmoxLifecycleExecutor::new(
+                            accounts,
+                            credentials,
+                            proxmox_client,
+                        ),
+                    ),
+                ))
+            };
             match &services {
                 Some(services) => {
                     let node_machines: std::sync::Arc<dyn fleet_application::machine::MachinePort> =
@@ -295,11 +330,11 @@ fn run_serve(config: fleet_config::ControllerConfig) -> ExitCode {
                         std::sync::Arc::new(fleet_controller::gateway::NodeCommandExecutor::new(
                             services.gateway.clone(),
                             node_machines,
-                            with_source.clone(),
+                            with_proxmox.clone(),
                         ));
                     executor
                 }
-                None => with_source.clone(),
+                None => with_proxmox.clone(),
             }
         };
         let worker_host = WorkerHost::new(worker_operations, executor, 4);