github.com/choria-io/go-choria@v0.28.1-0.20240416190746-b3bf9c7d5a45/internal/fs/schemas/choria/machine/v1/manifest.json (about)

     1  {
     2      "$schema": "http://json-schema.org/draft-07/schema",
     3      "id": "https://choria.io/schemas/choria/machine/v1/manifest.json",
     4      "description": "Choria Autonomous Agent manifest",
     5      "type":"object",
     6      "required":["name","version","initial_state","transitions","watchers"],
     7      "definitions": {
     8          "GoDuration": {
     9              "type":"string",
    10              "pattern": "^\\d+[hms]$"
    11          },
    12          "GenericName": {
    13              "type":"string",
    14              "pattern":"^[a-zA-Z][a-zA-Z0-9_-]+$"
    15          },
    16          "EnvironmentVariable": {
    17              "type":"string",
    18              "description": "Environment variable as accepted by Go exec package",
    19              "pattern": "^[a-zA-Z_]+[a-zA-Z0-9_]*=.+"
    20          },
    21          "Transition": {
    22              "type":"object",
    23              "required": ["name", "from", "destination"],
    24              "additionalItems": false,
    25              "description": "A valid transition of the Finite State Machine",
    26              "properties": {
    27                  "name": {
    28                      "description": "A unique name for the transition event",
    29                      "$ref":"#/definitions/GenericName"
    30                  },
    31                  "from": {
    32                      "description": "The names of states that this transition is valid from",
    33                      "type":"array",
    34                      "items": {
    35                          "$ref":"#/definitions/GenericName"
    36                      }
    37                  },
    38                  "destination": {
    39                      "description": "The name of the state to transition to when this event fires",
    40                      "$ref":"#/definitions/GenericName"
    41                  },
    42                  "description": {
    43                      "description": "A human friendly description of the purpose of this transition",
    44                      "type": "string"
    45                  }
    46              }
    47          },
    48          "WatcherBase": {
    49              "type":"object",
    50              "required": ["name", "type"],
    51              "additionalItems": false,
    52              "properties": {
    53                  "name": {
    54                      "description": "The name of the watcher",
    55                      "$ref":"#/definitions/GenericName"
    56                  },
    57                  "state_match": {
    58                      "description": "State names where this watcher will be active",
    59                      "type":"array",
    60                      "items": {
    61                          "$ref":"#/definitions/GenericName"
    62                      }
    63                  },
    64                  "fail_transition": {
    65                      "description": "When this watcher fails the machine will receive this transition event",
    66                      "$ref":"#/definitions/GenericName"
    67                  },
    68                  "success_transition": {
    69                      "description": "When this watcher succeeds the machine will receive this transition event",
    70                      "$ref":"#/definitions/GenericName"
    71                  },
    72                  "interval": {
    73                      "description": "How often this watcher will be run when in any of the valid states",
    74                      "$ref":"#/definitions/GoDuration"
    75                  },
    76                  "announce_interval": {
    77                      "description": "How often the internal state of the watcher will be announced as events",
    78                      "$ref":"#/definitions/GoDuration"
    79                  }
    80              }
    81          },
    82          "WatcherKVProperties": {
    83              "type": "object",
    84              "default": "KV watcher properties",
    85              "required": ["bucket"],
    86              "properties": {
    87                  "bucket": {
    88                      "description": "The Bucket name that holds the data",
    89                      "type": "string",
    90                      "pattern": "^[a-zA-Z0-9_-]+$"
    91                  },
    92                  "key": {
    93                      "description": "The key to watch for changes",
    94                      "type": "string",
    95                      "pattern": "\\A[-/_a-zA-Z0-9]+\\z"
    96                  },
    97                  "mode": {
    98                      "description": "The method used for watching the values, must be poll for bucket watch",
    99                      "type": "string",
   100                      "default": "poll",
   101                      "enum": ["poll","watch"]
   102                  },
   103                  "bucket_prefix": {
   104                      "description": "When storing data prefix the data keys with the Bucket name",
   105                      "type": "boolean",
   106                      "default": true
   107                  }
   108              }
   109          },
   110          "WatcherKV": {
   111              "description": "A watcher that observes the state of a Choria Key-Value store Bucket or Key",
   112              "type": "object",
   113              "additionalItems": false,
   114              "allOf": [
   115                  {
   116                      "type":"object",
   117                      "required": ["type"],
   118                      "properties": {
   119                          "type": {
   120                              "enum": ["kv"]
   121                          }
   122                      }
   123                  },
   124                  {"$ref":"#/definitions/WatcherBase"},
   125                  {
   126                      "type":"object",
   127                      "required": ["properties"],
   128                      "properties": {
   129                          "properties": { "$ref":"#/definitions/WatcherKVProperties" }
   130                      }
   131                  }
   132              ]
   133          },
   134          "WatcherFileProperties": {
   135              "type":"object",
   136              "description": "File watcher properties",
   137              "required": ["path"],
   138              "properties": {
   139                  "path": {
   140                      "type": "string",
   141                      "description": "The path to a file to watch relative to the machine root"
   142                  },
   143                  "gather_initial_state": {
   144                      "type":"boolean",
   145                      "description": "If the properties of the file should be gathered on initial load"
   146                  }
   147              }
   148          },
   149          "WatcherFile": {
   150              "description": "A watcher that observes the state of a file regularly",
   151              "type": "object",
   152              "additionalItems": false,
   153              "allOf": [
   154                  {
   155                      "type":"object",
   156                      "required": ["type"],
   157                      "properties": {
   158                          "type": {
   159                              "enum": ["file"]
   160                          }
   161                      }
   162                  },
   163                  {"$ref":"#/definitions/WatcherBase"},
   164                  {
   165                      "type":"object",
   166                      "required": ["properties"],
   167                      "properties": {
   168                          "properties": { "$ref":"#/definitions/WatcherFileProperties" }
   169                      }
   170                  }
   171              ]
   172          },
   173          "WatcherNagiosProperties": {
   174              "type": "object",
   175              "description": "Nagios watcher properties",
   176              "required": ["plugin"],
   177              "properties": {
   178                  "annotations": {
   179                      "type": "object",
   180                      "description": "Map of strings presented as additional annotations per check",
   181                      "propertyNames": {
   182                          "pattern": "^[a-zA-Z_-]+$",
   183                          "type": "string"
   184                      }
   185                  },
   186                  "builtin": {
   187                      "type": "string",
   188                      "description": "Execute an internal plugin",
   189                      "enum": ["goss", "heartbeat", "choria_status"]
   190                  },
   191                  "plugin": {
   192                      "type": "string",
   193                      "description": "The Nagios plugin to run including it's arguments"
   194                  },
   195                  "timeout": {
   196                      "description": "How long the commands are allowed to run",
   197                      "default": "10s",
   198                      "$ref":"#/definitions/GoDuration"
   199                  },
   200                  "gossfile": {
   201                      "description": "For the goss builtin, a check specific YAML file",
   202                      "type": "string"
   203                  },
   204                  "last_message": {
   205                      "description": "For the choria_status builtin how long ago the last RPC message should have been received, specified in go duration string format",
   206                      "type": "string"
   207                  }
   208              }
   209          },
   210          "WatcherNagios": {
   211              "description": "A watcher that executes Nagios plugins",
   212              "type": "object",
   213              "additionalItems": false,
   214              "allOf": [
   215                  {
   216                      "type":"object",
   217                      "required": ["properties"],
   218                      "properties": {
   219                          "properties": { "$ref":"#/definitions/WatcherNagiosProperties" }
   220                      }
   221                  },
   222                  {"$ref":"#/definitions/WatcherBase"},
   223                  {
   224                      "type":"object",
   225                      "required": ["type"],
   226                      "properties": {
   227                          "type": {
   228                              "enum": ["nagios"]
   229                          }
   230                      }
   231                  }
   232              ]
   233          },
   234          "WatcherExecProperties": {
   235              "type":"object",
   236              "description": "Exec watcher properties",
   237              "required": ["command"],
   238              "properties": {
   239                  "command": {
   240                      "type": "string",
   241                      "description": "The path to a command to run relative to the machine root"
   242                  },
   243                  "environment": {
   244                      "description": "List of environment variables to pass to the executable in the form VAR=VALUE",
   245                      "default": [],
   246                      "type":"array",
   247                      "items":  { "$ref":"#/definitions/EnvironmentVariable" }
   248                  },
   249                  "governor": {
   250                      "description": "Limit concurrent executions of the command using a named Choria Governor",
   251                      "type": "string"
   252                  },
   253                  "governor_timeout": {
   254                      "description": "How long to wait for a spot on the Governor prior to giving up and firing fail_transition",
   255                      "type": "string",
   256                      "default": "5m",
   257                      "$ref":"#/definitions/GoDuration"
   258                  },
   259                  "parse_as_data": {
   260                      "description": "Indicates that the command returns JSON data that should be parsed as Machine data and stored",
   261                      "type": "boolean",
   262                      "default": false
   263                  },
   264                  "suppress_success_announce": {
   265                      "description": "Disable publishing announcements on every successful execution, still does regular timed ones if configured and failed ones",
   266                      "default": false,
   267                      "type":"boolean"
   268                  },
   269                  "timeout": {
   270                      "description": "How long the commands are allowed to run",
   271                      "default": "10s",
   272                      "$ref":"#/definitions/GoDuration"
   273                  }
   274              }
   275          },
   276          "WatcherExec": {
   277              "description": "A watcher that executes a command regularly",
   278              "type": "object",
   279              "additionalItems": false,
   280              "allOf": [
   281                  {
   282                      "type":"object",
   283                      "required": ["properties"],
   284                      "properties": {
   285                          "properties": { "$ref":"#/definitions/WatcherExecProperties" }
   286                      }
   287                  },
   288                  {"$ref":"#/definitions/WatcherBase"},
   289                  {
   290                      "type":"object",
   291                      "required": ["type"],
   292                      "properties": {
   293                          "type": {
   294                              "enum": ["exec"]
   295                          }
   296                      }
   297                  }
   298              ]
   299          },
   300          "WatcherScheduleProperties": {
   301              "type":"object",
   302              "description": "Schedule watcher properties",
   303              "required": ["duration", "schedules"],
   304              "properties": {
   305                  "start_splay": {
   306                      "description": "Sleep a random period between 0 and this duration before firing the success_transition. Use this to spread a fleet of schedulers out naturally.",
   307                      "$ref":"#/definitions/GoDuration"
   308                  },
   309                  "duration": {
   310                      "description": "How long the scheduler should stay in the success state once triggered",
   311                      "$ref":"#/definitions/GoDuration"
   312                  },
   313                  "schedules": {
   314                      "description": "Cron like schedules for when the scheduler trigger success states",
   315                      "type":"array",
   316                      "items": {
   317                          "type":"string"
   318                      }
   319                  }
   320              }
   321          },
   322          "WatcherSchedule": {
   323              "description": "A watcher that triggers transitions based on a set of cron like schedules",
   324              "type":"object",
   325              "additionalItems": false,
   326              "allOf": [
   327                  {
   328                      "type":"object",
   329                      "required":["properties"],
   330                      "properties": {
   331                          "properties": { "$ref":"#/definitions/WatcherScheduleProperties" }
   332                      }
   333                  },
   334                  {"$ref":"#/definitions/WatcherBase"},
   335                  {
   336                      "type":"object",
   337                      "required": ["type"],
   338                      "properties": {
   339                          "type": {
   340                              "enum": ["schedule"]
   341                          }
   342                      }
   343                  }
   344              ]
   345          },
   346          "WatcherTimerProperties": {
   347              "type":"object",
   348              "description": "Timer watcher properties",
   349              "required": ["timer"],
   350              "properties": {
   351                  "timer": {
   352                      "description": "How long the timer should run for",
   353                      "$ref":"#/definitions/GoDuration"
   354                  }
   355              }
   356          },
   357          "WatcherTimer": {
   358              "description": "A watcher that starts a time when a machine transitions into a state and emits an event when the timer ends",
   359              "type":"object",
   360              "additionalItems": false,
   361              "allOf": [
   362                  {
   363                      "type":"object",
   364                      "required":["properties"],
   365                      "properties": {
   366                          "properties": { "$ref":"#/definitions/WatcherTimerProperties" }
   367                      }
   368                  },
   369                  {"$ref":"#/definitions/WatcherBase"},
   370                  {
   371                      "type":"object",
   372                      "required": ["type"],
   373                      "properties": {
   374                          "type": {
   375                              "enum": ["timer"]
   376                          }
   377                      }
   378                  }
   379              ]
   380          },
   381          "WatcherHomeKitProperties": {
   382              "type":"object",
   383              "description": "Home Kit watcher properties",
   384              "required": ["pin"],
   385              "properties": {
   386                  "pin": {
   387                      "description": "The pin to enter when setting up the Homekit device",
   388                      "type": "string",
   389                      "pattern": "^[0-9]+$"
   390                  },
   391                  "serial_number": {
   392                      "description": "The serial number to report to Home Kit",
   393                      "type": "string"
   394                  },
   395                  "model": {
   396                      "description": "The model to report to Home Kit",
   397                      "type": "string",
   398                      "default": "Autonomous Agent"
   399                  },
   400                  "setup_id": {
   401                      "description": "The Home Kit set up id to report",
   402                      "type": "string"
   403                  },
   404                  "initial": {
   405                      "description": "The initial state of the button",
   406                      "enum": ["on","off"],
   407                      "type": "string"
   408                  },
   409                  "on_when": {
   410                      "description": "When in any of these states the button will be on",
   411                      "type": "array",
   412                      "items": {
   413                          "$ref":"#/definitions/GenericName"
   414                      }
   415                  },
   416                  "off_when": {
   417                      "description": "When in any of these states the button will be off",
   418                      "type": "array",
   419                      "items": {
   420                          "$ref":"#/definitions/GenericName"
   421                      }
   422                  },
   423                  "disable_when": {
   424                      "description": "When in any of these states the button will be disabled",
   425                      "type": "array",
   426                      "items": {
   427                          "$ref":"#/definitions/GenericName"
   428                      }
   429                  }
   430              }
   431          },
   432          "WatcherHomekit": {
   433              "description": "A watcher creates an Apple Home Kit button that can be activated via iOS devices and Siri",
   434              "type":"object",
   435              "additionalItems": false,
   436              "allOf": [
   437                  {
   438                      "type":"object",
   439                      "required":["properties"],
   440                      "properties": {
   441                          "properties": { "$ref":"#/definitions/WatcherHomeKitProperties" }
   442                      }
   443                  },
   444                  {"$ref":"#/definitions/WatcherBase"},
   445                  {
   446                      "type":"object",
   447                      "required": ["type"],
   448                      "properties": {
   449                          "type": {
   450                              "enum": ["schedule"]
   451                          }
   452                      }
   453                  }
   454              ]
   455          },
   456          "WatcherMetricProperties": {
   457              "type":"object",
   458              "description": "Metric watcher properties",
   459              "required": ["command", "interval"],
   460              "properties": {
   461                  "command": {
   462                      "description": "The path to the command to run to retrieve the metric data",
   463                      "type": "string"
   464                  },
   465                  "interval": {
   466                      "description": "Interval to run the command",
   467                      "$ref": "#/definitions/GoDuration"
   468                  },
   469                  "labels": {
   470                      "description": "Labels that would override those from the command",
   471                      "type": "object",
   472                      "propertyNames": {
   473                          "propertyNames": {
   474                              "pattern": "^[a-zA-Z_-]+$",
   475                              "type": "string"
   476                          }
   477                      }
   478                  }
   479              }
   480          },
   481          "WatcherMetric": {
   482              "description": "A watcher that periodically runs a command and expose metrics found to Prometheus",
   483              "type":"object",
   484              "additionalItems": false,
   485              "allOf": [
   486                  {
   487                      "type":"object",
   488                      "required":["properties"],
   489                      "properties": {
   490                          "properties": { "$ref":"#/definitions/WatcherMetricProperties" }
   491                      }
   492                  },
   493                  {"$ref":"#/definitions/WatcherBase"},
   494                  {
   495                      "type":"object",
   496                      "required": ["type"],
   497                      "properties": {
   498                          "type": {
   499                              "enum": ["schedule"]
   500                          }
   501                      }
   502                  }
   503              ]
   504          }
   505      },
   506      "properties": {
   507          "name": {
   508              "description": "A unique name for this autonomous agent",
   509              "$ref":"#/definitions/GenericName"
   510          },
   511          "version": {
   512              "type":"string",
   513              "description": "SemVer compatible version of the autonomous agent",
   514              "minLength": 5,
   515              "pattern": "^\\d+\\.\\d+\\.\\d+$"
   516          },
   517          "initial_state": { "$ref":"#/definitions/GenericName" },
   518          "splay_start": {
   519              "type":"integer",
   520              "description": "Causes a random delay on start no longer than splay_start seconds",
   521              "default":0
   522          },
   523          "transitions": {
   524              "type":"array",
   525              "description": "A list of events that can be fired for this autonomous agent",
   526              "minItems": 1,
   527              "items": { "$ref":"#/definitions/Transition" }
   528          },
   529          "watchers": {
   530              "description": "Watchers to observe the environment in specific states",
   531              "type":"array",
   532              "minItems": 1,
   533              "items": {
   534                  "anyOf": [
   535                      {"$ref":"#/definitions/WatcherFile"},
   536                      {"$ref":"#/definitions/WatcherExec"},
   537                      {"$ref":"#/definitions/WatcherNagios"},
   538                      {"$ref":"#/definitions/WatcherSchedule"},
   539                      {"$ref":"#/definitions/WatcherHomekit"},
   540                      {"$ref":"#/definitions/WatcherTimer"},
   541                      {"$ref":"#/definitions/WatcherMetric"},
   542                      {"$ref":"#/definitions/WatcherKV"}
   543                  ]
   544              }
   545          }
   546      }
   547  }