// SPDX-License-Identifier: Apache-2.0
// Virtual machine lifecycle. Every mutating call is a long-running operation
// that returns a task id; poll TaskService or watch the inventory.
syntax = "proto3";

package kyvernon.v1;

import "kyvernon/v1/common.proto";

// Life cycle of virtual machines. Every call starts a task and returns its reference.
service VmService {
  // Creates a virtual machine from a specification.
  rpc CreateVm(CreateVmRequest) returns (TaskRef);
  // Deletes a virtual machine.
  rpc DeleteVm(VmRequest) returns (TaskRef);
  // Powers a virtual machine on.
  rpc PowerOn(VmRequest) returns (TaskRef);
  // Hard power-off, at once; the guest is not asked. Succeeds on a VM that is off.
  rpc PowerOff(VmRequest) returns (TaskRef);
  // Graceful shutdown: the guest is asked to power off; after the timeout the VM is
  // powered off hard.
  rpc Shutdown(ShutdownVmRequest) returns (TaskRef);
  // Resets a running virtual machine, as a hardware reset.
  rpc Reset(VmRequest) returns (TaskRef);
  // Suspends a running virtual machine.
  rpc Suspend(VmRequest) returns (TaskRef);
  // Replaces the VM configuration (`config` object as JSON).
  rpc Reconfigure(ReconfigureVmRequest) returns (TaskRef);
}

// Graceful shutdown of a virtual machine.
message ShutdownVmRequest {
  // Id of the virtual machine.
  string id = 1;
  // Repeating a request with the same key returns the same task.
  string idempotency_key = 2;
  // Seconds the guest gets before the hard power-off (1 to 3600; 0: the default, 90).
  uint64 timeout_seconds = 3;
}

// Names one virtual machine.
message VmRequest {
  // Id of the virtual machine.
  string id = 1;
  // Repeating a request with the same key returns the same task.
  string idempotency_key = 2;
}

// Creates a virtual machine.
message CreateVmRequest {
  // VM folder (group-vN).
  string folder = 1;
  // JSON body in the VirtualMachine schema.
  string spec_json = 2;
  // Key that makes a retried request create the virtual machine once.
  string idempotency_key = 3;
}

// Changes the configuration of a virtual machine.
message ReconfigureVmRequest {
  // Id of the virtual machine.
  string id = 1;
  // JSON body in the VmConfig schema.
  string config_json = 2;
  // Key that makes a retried request apply the change once.
  string idempotency_key = 3;
}