From 0499cec1534a35a0ada3ff57f6ec6d0ae1ce8419 Mon Sep 17 00:00:00 2001
From: James Rasell <jrasell@hashicorp.com>
Date: Tue, 16 Apr 2024 15:24:20 +0100
Subject: [PATCH] docs: add config option overview and example.

---
 README.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 97 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index f32b4f6..94f4079 100644
--- a/README.md
+++ b/README.md
@@ -40,8 +40,6 @@ Features that aren't support today but could be:
 
 - Replace `Config.RPCHandler` with a simulated network stack
 - Server mode
-- Task Driver Plugins (or a builtin fake one)
-- Configuration file instead of args
 - Add universal "?node_id=..." HTTP API support upstream to route the RPCs to
   individual Client instances.
 
@@ -50,3 +48,100 @@ Features that aren't support today but could be:
 Features that probably can't be supported:
 
 - Consul - Consul assumes a Consul agent per Nomad agent per Machine.
+
+## Configuration Options
+The `nomad-nodesim` application supports providing configuration parameters via CLI flags and a
+config file in [HCL](https://github.com/hashicorp/hcl) format.
+
+### CLI Flags
+- `alloc-runner-type` (`"sim"`) - Defines what alloc-runner `nomad-nodesim` will use. It supports
+  either the basic simulated runner included within this application, or the "real" one pulled
+  directly from Nomad. Supports `"sim"` or `"real"`.
+
+- `config` (`""`) - The path to a config file to load.
+
+- `log-include-location` (`false`) - Whether the `nomad-nodesim` logs should include file and line
+  information.
+
+- `log-json` (`false`) - Whether the `nomad-nodesim` logs should be output in JSON format.
+
+- `log-level` (`"debug"`) - The verbosity level of the `nomad-nodesim` logs. This currently supports
+  `"trace"`, `"debug"`, `"info"`, `"warn"`, and `"error"`.
+
+- `node-name-prefix` (`""`) - The prefix used to name each Nomad client. When not supplied, this
+  will be generated using a concatenation of `node-` and a generated short UUID such as
+  `node-8a48e733`.
+
+- `node-num` (`1`) - The number of Nomad clients that will be started within the `nomad-nodesim`
+  application.
+
+- `server-addr` (`["127.0.0.1:4647"]`) This flag can be supplied multiple times and specifies the
+  Nomad server RPC addresses that the Nomad clients should use for registration and connectivity.
+
+- `work-dir` (`""`) - The working directory for the application. Each nodesim client will store its
+  data directory within this. When not supplied, this will be placed within the directory it is run
+  from and will be prefixed with `nomad-nodesim-`.
+
+### Config File Parameters
+- `node_name_prefix` (`""`) - The prefix used to name each Nomad client. When not supplied, this
+  will be generated using a concatenation of `node-` and a generated short UUID such as
+  `node-8a48e733`.
+
+- `node_num` (`1`) - The number of Nomad clients that will be started within the nomad-nodesim
+  application.
+
+- `server_addr` (`["127.0.0.1:4647"]`) Specifies a list of Nomad server RPC addresses that the Nomad
+  clients should use for registration and connectivity.
+
+- `work_dir` (`""`) - The working directory for the application. Each nodesim client will store its
+  data directory within this. When not supplied, this will be placed within the directory it is run
+  from and will be prefixed with `nomad-nodesim-`.
+
+#### `log` Parameters
+- `include-location` (`false`) - Whether the `nomad-nodesim` logs should include file and line
+  information.
+
+- `json` (`false`) - Whether the `nomad-nodesim` logs should be output in JSON format.
+
+- `level` (`"debug"`) - The verbosity level of the `nomad-nodesim` logs. This currently supports
+  `"trace"`, `"debug"`, `"info"`, `"warn"`, and `"error"`.
+
+#### `node` Parameters
+- `datacenter` - (`"global"`) - Specifies the data center of the `nomad-nodesim` clients.
+
+- `node_class` - (`""`) - Specifies an arbitrary string used to logically group
+  `nomad-nodesim` clients.
+
+- `node_pool` - (`"default"`) -  Specifies the node pool in which `nomad-nodesim` clients are
+  registered.
+
+- `region` - (`"dc1"`) - Specifies the region of the `nomad-nodesim` clients.
+
+- `options` - (`"map[string]string"`) - Specifies a key-value mapping of internal configuration for
+  `nomad-nodesim` clients, such as for driver configuration.
+
+#### Config File Example
+The example below demonstrates setting config parameter within a configuration file.
+```hcl
+work_dir         = "/tmp/nomad-nodesim/"
+node_name_prefix = "node-8a48e733"
+server_addr      = ["127.0.0.1:4647"]
+node_num         = 100
+
+log {
+  level            = "info"
+  json             = true
+  include_location = true
+}
+
+node {
+  region     = "kent-1"
+  datacenter = "fav"
+  node_pool  = "default"
+  node_class = "high_mem"
+
+  options = {
+    "fingerprint.denylist" = "env_aws,env_gce,env_azure,env_digitalocean"
+  }
+}
+```