Run Scripts on Node Provision

In order to allow users to easily extend the functionality of Structsure nodes, Structsure's RKE2 IAC provides the ability to automatically copy scripts onto each node as part of its provisioning process, which can then be executed as part of the node's launch template.

This document assumes that an RKE2-based Structsure cluster already exists and is functional, and that you would like to extend its functionality by running an arbitrary script at node provision time.

The rke2-cluster Terraform module has support for uploading custom files, which will be downloaded by each node as part of its provisioning process, and can be optionally executed during the provisioning process for the nodes. In order to take advantage of this, provide the absolute path to the directory and the relative paths to any executable shell scripts within that directory in your Terragrunt env.hcl file using a block like this:

locals {
  cluster_inputs = {
    userdata_command_files = ["script_relative_path/your_script.sh"]
    userdata_files_dir = /absolute/path/
  }
}

This will cause a file such as /absolute/path/script_relative_path/your_script.sh on the machine running Terragrunt to be copied to the RKE2 nodes with a path like /opt/structsure/userdata/script_relative_path/your_script.sh.

As part of its provisioning process, the files will be verified for authenticity using their SHA256 output and be executed as part of the user-data. If the SHA256 sums do not match, the file will be skipped during the execution of the user-data.

A secondary option is providing your desired user-data commands without the need of a file. In order to take advantage of this, provide your commands in your Terragrunt env.hcl file using a block like this:

locals {
  cluster_inputs = {
    userdata_command = <<-EOT
      #!/bin/bash
      echo "My user-data commands"
    EOT
  }
}

This will cause your script to run as part of the RKE2 node's provisioning process, prior to RKE2's initial startup on that node.

To complete the process, you must run terragrunt apply to update the launch template for the nodes and then rotate the existing nodes to ensure that all the nodes run the updated launch template. For more information on these steps, see our Updating RKE2 guide.