Hooks reference refactoring

content/sensu-core/2.0/reference/checks.md

@@ -144,12 +144,12 @@ subscriptions in [Sensu 1][12]. Prepending `roundrobin:` in front of
 subscriptions is no longer required in Sensu 2 since round-robin can now be
 enabled directly with the [round_robin][13] attribute in the check configuration.
 
-## Check Specification
+## Check specification
 
 ### Check naming
 
 Each check definition must have a unique name within its organization and
-+environment.
+environment.
 
 * A unique string used to name/identify the check
 * Cannot contain special characters or spaces

content/sensu-core/2.0/reference/filters.md

@@ -99,6 +99,26 @@ example      | {{< highlight shell >}}"statements": [
 ]
 {{< /highlight >}}
 
+organization | 
+-------------|------ 
+description  | The Sensu RBAC organization that this filter belongs to.
+required     | false 
+type         | String
+default      | current organization value configured for `sensuctl` (ie `default`) 
+example      | {{< highlight shell >}}
+  "organization": "default"
+{{</ highlight >}}
+
+environment  | 
+-------------|------ 
+description  | The Sensu RBAC environment that this filter belongs to.
+required     | false 
+type         | String 
+default      | current environment value configured for `sensuctl` (ie `default`) 
+example      | {{< highlight shell >}}
+  "environment": "default"
+{{</ highlight >}}
+
 ## Filter Examples
 
 ### Handling production events

content/sensu-core/2.0/reference/hooks.md

@@ -4,93 +4,133 @@ description: "The hooks reference guide."
 weight: 1
 version: "2.0"
 product: "Sensu Core"
-platformContent: true
+platformContent: false
 menu:
   sensu-core-2.0:
     parent: reference
 ---
 
-# Hooks
-
-### What are hooks?
-
-Hooks are commands run by the Sensu client in response to the result of a check execution. The Sensu client will execute the appropriate configured hook command, depending on the execution status (e.g. 1). The hook command output, status, executed timestamp, and duration are captured and published in the event result. Hook commands can optionally receive JSON serialized Sensu client data via STDIN.
-
-### New and improved hooks!
-
-In 2.x, we've redesigned and expanded on the concept of 1.x check hooks. Hooks are now their own resource, and can be created and managed independent of the check configuration scope. With unique and descriptive identifiers, hooks are now reusable! And thats not all, you can now execute multiple hooks for any given response code.
-
-Check out Sean's [blog post](https://blog.sensuapp.org/using-check-hooks-a739a362961f) about Sensu Core check hooks to see how you can use Sensu for auto-remediation tasks!
-
-### Viewing
-
-To view all the hooks that are currently configured for the cluster, enter:
-
-{{< highlight shell >}}
-sensuctl hook list
-{{< /highlight >}}
-
-If you want more details on a hook, the `info` subcommand can help you out.
-
-> sensuctl hook info nginx-start
-{{< highlight shell >}}
-=== nginx-start
-Name:           nginx-start
-Command:        sudo /etc/init.d/nginx start
-Timeout:        60
-Stdin?:         false
-Organization:   default
-Environment:    default
-{{< /highlight >}}
-
-### Management
-
-Hooks can be configured both interactively or by using CLI flags.
-
-{{< highlight shell >}}
-sensuctl hook create nginx-start --command 'sudo /etc/init.d/nginx start' --timeout 10
-{{< /highlight >}}
-
-To delete an existing hook, simply pass the name of the hook to the `delete` command.
-
-{{< highlight shell >}}
-sensuctl hook delete nginx-start
-{{< /highlight >}}
-
-## Check hooks
-
-### What is a check hook?
-
-A check hook is a type of hook that lives in the check configuration scope. Check hooks associate existing hooks to a check and type. The check hook type is defined by the response code or severity of the check execution result. Valid check hook types include (in order of precedence): "0"-"255", "ok", "warning", "critical", "unknown", and "non-zero".
-
-ex:
-{{< highlight shell >}}
-"checks": {
-    "nginx_process": {
-        "command": "check-process.rb -p nginx",
-        "subscribers": ["proxy"],
-        "interval”: 30,
-        "check_hooks": [
-        {
-            "critical": ["nginx-start", "hook-with-custom-script"],
-        },
-        {
-            "non-zero": ["ps-aux"],
-        }],
-    }
+## How do hooks work?
+
+Hooks are executed in response to the result of a command execution (e.g.,
+check command) and based on the exit status code of that command (e.g., `1`).
+Hook commands can optionally receive JSON serialized Sensu client data via
+STDIN.
+
+Each **type** of response (e.g., `non-zero`) can contain one or more hooks, and
+correspond to one or more exit status code. Hooks are executed, in order of
+precedence, based on their type:
+
+* `1` to `255`
+* `ok`
+* `warning`
+* `critical`
+* `unknown`
+* `non-zero`
+
+### Check hooks
+
+The hook command output, status, executed timestamp and duration are captured
+and published in the resulting event. 
+
+## New and improved hooks
+
+In Sensu 2.0, we’ve redesigned and expanded on the concept of 1.0 check hooks.
+Hooks are now their own resource, and can be created and managed independent of
+the check configuration scope. With unique and descriptive identifiers, hooks
+are now reusable! And that's not all, you can now execute multiple hooks for any
+given response code.
+
+Check out Sean’s [blog post][1] about Sensu Core check hooks to see how you can use
+Sensu for auto-remediation tasks!
+
+## Hooks specification
+
+### Hook naming
+
+Each hook definition must have a unique name within its organization and
+environment.
+
+* A unique string used to name/identify the hook
+* Cannot contain special characters or spaces
+* Validated with Go regex [`\A[\w\.\-]+\z`](https://regex101.com/r/zo9mQU/2)
+
+### Hook attributes
+
+command      | 
+-------------|------
+description  | The hook command to be executed.
+required     | true
+type         | String
+example      | {{< highlight shell >}}"command": "sudo /etc/init.d/nginx start"{{< /highlight >}}
+
+timeout      | 
+-------------|------
+description  | The hook execution duration timeout in seconds (hard stop).
+required     | false
+type         | Integer
+default      | 60
+example      | {{< highlight shell >}}"timeout": 30{{< /highlight >}}
+
+stdin        | 
+-------------|------
+description  | If the Sensu agent writes JSON serialized Sensu entity and check data to the command process’ STDIN. The command must expect the JSON data via STDIN, read it, and close STDIN. This attribute cannot be used with existing Sensu check plugins, nor Nagios plugins etc, as Sensu agent will wait indefinitely for the hook process to read and close STDIN.
+required     | false
+type         | Boolean
+default      | false
+example      | {{< highlight shell >}}"stdin": true{{< /highlight >}}
+
+organization | 
+-------------|------ 
+description  | The Sensu RBAC organization that this hook belongs to.
+required     | false 
+type         | String
+default      | current organization value configured for `sensuctl` (ie `default`) 
+example      | {{< highlight shell >}}
+  "organization": "default"
+{{</ highlight >}}
+
+environment  | 
+-------------|------ 
+description  | The Sensu RBAC environment that this hook belongs to.
+required     | false 
+type         | String 
+default      | current environment value configured for `sensuctl` (ie `default`) 
+example      | {{< highlight shell >}}
+  "environment": "default"
+{{</ highlight >}}
+
+## Examples
+
+### Rudimentary auto-remediation
+
+Hooks can be used for rudimentary auto-remediation tasks, for example, starting
+a process that is no longer running.
+
+{{< highlight json >}}
+{
+  "name": "restart_nginx",
+  "command": "sudo systemctl start nginx",
+  "timeout": 60,
+  "environment": "default",
+  "organization": "default"
 }
 {{< /highlight >}}
 
-### Managing check hooks
+### Capture the process tree
 
-To add hooks to a check, use the `add-hook` subcommand.
+Hooks can also be used for automated data gathering for incident triage, for
+example, a check hook could be used to capture the process tree when a process
+has been determined to be not running etc.
 
-{{< highlight shell >}}
-sensuctl check add-hook nginx_process --type critical --hooks nginx-start,hook-with-custom-script
+{{< highlight json >}}
+{
+  "name": "process_tree",
+  "command": "ps aux",
+  "timeout": 60,
+  "environment": "default",
+  "organization": "default"
+}
 {{< /highlight >}}
 
-To remove a hook from a check, use the `remove-hook` subcommand.
-
-{{< highlight shell >}}
-sensuctl check remove-hook nginx_process critical hook-with-custom-script
-{{< /highlight >}}
+[1]: https://blog.sensuapp.org/using-check-hooks-a739a362961f