Merge pull request #5 from jay7x/wip

Add cluster management support

Author: jay7x

README.md

@@ -4,7 +4,8 @@ Table of Contents
 
 1. [Description](#description)
 2. [Requirements](#requirements)
-3. [Usage](#usage)
+3. [Inventory plugin usage](#inventory-plugin-usage)
+4. [Cluster management plans usage](#cluster-management-plans-usage)
 
 ## Description
 
@@ -36,6 +37,53 @@ groups:
         except_matching_names: '^default'
 ```
 
+## Cluster management plans usage
+
+This module provides a way to define and manage clusters of Lima VMs. It's expected to define clusters in the [plan_hierarchy of your Bolt project's Hiera](https://www.puppet.com/docs/bolt/latest/hiera.html#outside-apply-blocks).
+
+Below is the example of a Hiera file under `plan_hierarchy`:
+
+```yaml
+---
+# Leverage YAML features to define templates required
+x-ubuntu2004: &ubuntu2004
+  images:
+  - location: "https://cloud-images.ubuntu.com/releases/20.04/release-20230117/ubuntu-20.04-server-cloudimg-amd64.img"
+    arch: "x86_64"
+    digest: "sha256:3e44e9f886eba6b91662086d24028894bbe320c1de89be5c091019fedf9c5ce6"
+  - location: "https://cloud-images.ubuntu.com/releases/20.04/release-20230117/ubuntu-20.04-server-cloudimg-arm64.img"
+    arch: "aarch64"
+    digest: "sha256:4ea4700f7b1de194a2f6bf760b911ea3071e0309fcea14d3a465a3323d57c60e"
+  - location: "https://cloud-images.ubuntu.com/releases/20.04/release/ubuntu-20.04-server-cloudimg-amd64.img"
+    arch: "x86_64"
+  - location: "https://cloud-images.ubuntu.com/releases/20.04/release/ubuntu-20.04-server-cloudimg-arm64.img"
+    arch: "aarch64"
+  mounts:
+  - location: "~"
+
+# Cluster definitions
+lima::clusters:
+  example: # `example` cluster
+    nodes:
+      - example1
+        template: ubuntu  # Use latest ubuntu version on this VM
+      - example2
+      - example3
+    config:
+      <<: *ubuntu2004
+```
+
+Now when you have some clusters defined you can use cluster management plans to start/stop/delete a cluster. E.g.:
+
+```bash
+# Start the cluster (create example[123] VMs)
+bolt plan run lima::cluster::start name=example
+# Stop the cluster (stop example[123] VMs)
+bolt plan run lima::cluster::stop name=example
+# Delete the cluster (delete example[123] VMs)
+bolt plan run lima::cluster::delete name=example
+```
+
 ## Reference
 
 Reference documentation for the module is generated using

REFERENCE.md

@@ -12,6 +12,13 @@
 * [`start`](#start): Create or start Lima VM
 * [`stop`](#stop): Stop Lima VM
 
+### Plans
+
+* [`lima::cluster::delete`](#lima--cluster--delete): Delete the cluster of Lima VMs
+* [`lima::cluster::start`](#lima--cluster--start): Create/start the cluster of Lima VMs
+* [`lima::cluster::stop`](#lima--cluster--stop): Stop the cluster of Lima VMs
+* [`lima::clusters`](#lima--clusters): Return the cluster definition
+
 ## Tasks
 
 ### <a name="delete"></a>`delete`
@@ -144,3 +151,132 @@ Data type: `String[1]`
 
 VM name
 
+## Plans
+
+### <a name="lima--cluster--delete"></a>`lima::cluster::delete`
+
+Delete the cluster of Lima VMs
+
+#### Parameters
+
+The following parameters are available in the `lima::cluster::delete` plan:
+
+* [`name`](#-lima--cluster--delete--name)
+* [`clusters`](#-lima--cluster--delete--clusters)
+* [`target`](#-lima--cluster--delete--target)
+
+##### <a name="-lima--cluster--delete--name"></a>`name`
+
+Data type: `String[1]`
+
+Cluster name
+
+##### <a name="-lima--cluster--delete--clusters"></a>`clusters`
+
+Data type: `Optional[Hash]`
+
+Hash of all defined clusters. Populated from Hiera usually.
+
+Default value: `undef`
+
+##### <a name="-lima--cluster--delete--target"></a>`target`
+
+Data type: `TargetSpec`
+
+The host to run the limactl on
+
+Default value: `'localhost'`
+
+### <a name="lima--cluster--start"></a>`lima::cluster::start`
+
+Create/start the cluster of Lima VMs
+
+#### Parameters
+
+The following parameters are available in the `lima::cluster::start` plan:
+
+* [`name`](#-lima--cluster--start--name)
+* [`clusters`](#-lima--cluster--start--clusters)
+* [`target`](#-lima--cluster--start--target)
+
+##### <a name="-lima--cluster--start--name"></a>`name`
+
+Data type: `String[1]`
+
+Cluster name
+
+##### <a name="-lima--cluster--start--clusters"></a>`clusters`
+
+Data type: `Optional[Hash]`
+
+Hash of all defined clusters. Populated from Hiera usually.
+
+Default value: `undef`
+
+##### <a name="-lima--cluster--start--target"></a>`target`
+
+Data type: `TargetSpec`
+
+The host to run the limactl on
+
+Default value: `'localhost'`
+
+### <a name="lima--cluster--stop"></a>`lima::cluster::stop`
+
+Stop the cluster of Lima VMs
+
+#### Parameters
+
+The following parameters are available in the `lima::cluster::stop` plan:
+
+* [`name`](#-lima--cluster--stop--name)
+* [`clusters`](#-lima--cluster--stop--clusters)
+* [`target`](#-lima--cluster--stop--target)
+
+##### <a name="-lima--cluster--stop--name"></a>`name`
+
+Data type: `String[1]`
+
+Cluster name
+
+##### <a name="-lima--cluster--stop--clusters"></a>`clusters`
+
+Data type: `Optional[Hash]`
+
+Hash of all defined clusters. Populated from Hiera usually.
+
+Default value: `undef`
+
+##### <a name="-lima--cluster--stop--target"></a>`target`
+
+Data type: `TargetSpec`
+
+The host to run the limactl on
+
+Default value: `'localhost'`
+
+### <a name="lima--clusters"></a>`lima::clusters`
+
+Return the cluster definition
+
+#### Parameters
+
+The following parameters are available in the `lima::clusters` plan:
+
+* [`name`](#-lima--clusters--name)
+* [`clusters`](#-lima--clusters--clusters)
+
+##### <a name="-lima--clusters--name"></a>`name`
+
+Data type: `String[1]`
+
+Cluster name
+
+##### <a name="-lima--clusters--clusters"></a>`clusters`
+
+Data type: `Hash`
+
+Hash of all defined clusters. Populated from Hiera usually.
+
+Default value: `lookup('lima::clusters', 'default_value' => {})`
+

hiera.yaml

@@ -19,3 +19,8 @@ hierarchy:
       - "os/%{facts.os.family}.yaml"
   - name: 'common'
     path: 'common.yaml'
+
+# Define plan lookup hierarchy
+# This prevents "Interpolations are not supported in lookups outside of an apply
+# block" error when plan with lookup is executed
+plan_hierarchy: []

plans/cluster/delete.pp

@@ -0,0 +1,33 @@
+# @summary Delete the cluster of Lima VMs
+# @param name
+#   Cluster name
+# @param clusters
+#   Hash of all defined clusters. Populated from Hiera usually.
+# @param target
+#   The host to run the limactl on
+plan lima::cluster::delete (
+  String[1] $name,
+  Optional[Hash] $clusters = undef,
+  TargetSpec $target = 'localhost',
+) {
+  $cluster = run_plan('lima::clusters', 'clusters' => $clusters, 'name' => $name)
+
+  $defined_nodes = $cluster['nodes'].map |$node| {
+    $node ? {
+      Hash => $node['name'],
+      String => $node,
+      default => undef,
+    }
+  }
+  out::verbose("Nodes to delete: ${defined_nodes}")
+
+  $stop_res = parallelize ($defined_nodes) |$node| {
+    run_task(
+      'lima::delete',
+      $target,
+      'name' => $node,
+    )
+  }
+
+  return $stop_res
+}

plans/cluster/start.pp

@@ -0,0 +1,102 @@
+# @summary Create/start the cluster of Lima VMs
+# @param name
+#   Cluster name
+# @param clusters
+#   Hash of all defined clusters. Populated from Hiera usually.
+# @param target
+#   The host to run the limactl on
+plan lima::cluster::start (
+  String[1] $name,
+  Optional[Hash] $clusters = undef,
+  TargetSpec $target = 'localhost',
+) {
+  $cluster = run_plan('lima::clusters', 'clusters' => $clusters, 'name' => $name)
+  $tgt = get_target($target)
+
+  $cluster_config = $cluster['nodes'].map |$node| {
+    $n = $node ? {
+      Hash => $node,
+      String => { 'name' => $node },
+      default => {},
+    }
+
+    # Use per-node configs first. Use cluster-wide configs otherwise.
+    # Look for explicit config hash first then template then url.
+    $cfg = [
+      [$n['config'], 'config'],
+      [$n['template'], 'template'],
+      [$n['url'], 'url'],
+      [$cluster['config'], 'config'],
+      [$cluster['template'], 'template'],
+      [$cluster['url'], 'url'],
+    ].filter |$x| { $x[0] } # Delete undefined options
+
+    unless $cfg.count >= 1 {
+      fail("Node ${n['name']} has no config/template/url defined in the cluster configuration")
+    }
+
+    # Use first defined option ($cfg[0])
+    ({ 'name' => $n['name'], $cfg[0][1] => $cfg[0][0] })
+  }
+
+  $defined_nodes = $cluster_config.map |$node| { $node['name'] }
+  out::verbose("Defined nodes: ${defined_nodes}")
+
+  # Collect and set the target's facts
+  if empty(facts($tgt)) {
+    without_default_logging() || {
+      run_plan('facts', $tgt, '_catch_errors' => true)
+    }
+  }
+  $cpus = facts($tgt).get('processors.count')
+  $start_threads = if $cpus < 4 { 1 } else { $cpus / 2 } # Assume every VM can consume up to 200% of a CPU core on start
+
+  # Get existing VMs
+  $list_res = without_default_logging() || {
+    run_task(
+      'lima::list',
+      $tgt,
+      { names => $defined_nodes },
+    )
+  }
+  $lima_config = $list_res.find($target).value['list']
+
+  # Create missing nodes
+  $missing_nodes = $defined_nodes - $lima_config.map |$x| { $x['name'] }
+  out::verbose("Nodes to create: ${missing_nodes}")
+
+  # `limactl start` cannot create multiple images in parallel
+  # See https://github.com/lima-vm/lima/issues/1354
+  # So creating VMs sequentially..
+  $create_res = $missing_nodes.map |$node| {
+    run_task(
+      'lima::start',
+      $tgt,
+      "Create VM ${node}",
+      'name' => $node,
+      'template' => $cluster['template'],
+      'config' => $cluster['config'],
+      'url' => $cluster['url'],
+    )
+  }
+
+  # Start existing but non-running nodes
+  $stopped_nodes = $lima_config
+  .filter |$x| { $x['status'] == 'Stopped' }
+  .map |$x| { $x['name'] }
+  out::verbose("Nodes to start (${start_threads} nodes per batch): ${stopped_nodes}")
+
+  # Run in batches of $start_threads VMs in parallel
+  $start_res = $stopped_nodes.slice($start_threads).map |$batch| {
+    $batch.parallelize |$node| {
+      run_task(
+        'lima::start',
+        $tgt,
+        "Start VM ${node}",
+        'name' => $node,
+      )
+    }
+  }
+
+  return flatten($create_res + $start_res)
+}