Merge pull request #7 from sensu/ch/command-mode

Add support for labels and annotations
sensu · May 28, 2021 · 10f6905 · 10f6905
2 parents ef81a46 + 4dde660
commit 10f6905
Show file tree

Hide file tree

Showing 4 changed files with 314 additions and 76 deletions.
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
@@ -13,4 +13,4 @@ jobs:
     - name: Checkout code
       uses: actions/checkout@v2
     - name: Run golangci-lint
-      uses: actions-contrib/golangci-lint@v1
+      uses: golangci/golangci-lint-action@v2 
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,13 +1,32 @@
 # Changelog
+
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
-and this project adheres to [Semantic
-Versioning](http://semver.org/spec/v2.0.0.html).
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
 
+### Added
+
+- NEW `--add-labels` command, accepts newline separated list of key=value pairs
+- NEW `--add-annotations` command, accepts newline separated list of key=value pairs
+- NEW `--add-all` command, accepts newline separated list of commands + arguments; e.g.:
+
+  ```
+  add-subscription postgres
+  add-label region=us-west-1
+  add-annotation foo=bar
+  ```
+
+  This enables support for discovery plugins that may modify multiple entity attributes (e.g. subscriptions + labels).
+
+### Fixed
+
+- The `sensu.io/plugins/sensu-entity-manager/config/patch/annotations` and `sensu.io/plugins/sensu-entity-manager/config/patch/subscriptions` annotations are now supported.
+  These were documented in the README previously but there were never implemented.
+
 ### Changed
+
 - Q1 '21 handler maintenance:
   - Updated modules (go get -u && go mod tidy)
   - Add pull_request to lint and test GitHub Actions
@@ -18,4 +37,5 @@ Versioning](http://semver.org/spec/v2.0.0.html).
 ## [0.0.1] - 2000-01-01
 
 ### Added
+
 - Initial release
diff --git a/README.md b/README.md
@@ -20,8 +20,151 @@
 
 ## Overview
 
-Event-based Sensu entity management for service-discovery (add/remove 
-subscriptions) and other automation workflows.                     
+Event-based Sensu entity management for automated service-discovery (add/remove subscriptions) and other automation workflows.
+The Sensu Entity Manager works with any check plugin or event producer that generates one instruction per line of `event.check.output` in any of the following formats:
+
+- **Subscriptions (one string per line):**
+
+  Example check output:
+
+  ```
+  system/linux
+  postgres
+  ```
+
+  Example event payload:
+
+  ```json
+  {
+    "metadata": {},
+    "entity": {},
+    "check": {
+      "metadata": {
+        "name": "example",
+        "labels": {},
+        "metadata": {}
+      },
+      "handlers": [
+        "subscription-manager"
+      ],
+      "output": "system/linux\npostgres",
+      "status": 0,
+      "...": "..."
+    },
+    "metrics": {},
+    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "timestamp": 1234567890
+  }
+  ```
+
+  Example handler definition: 
+
+  ```yaml
+  ---
+  type: Handler
+  api_version: core/v2
+  metadata:
+    name: subscription-manager
+  spec:
+    command: sensu-entity-manager --add-subscriptions
+    ...: ...
+  ```
+
+- **Labels and Annotations (one `key=value` pair per line):**
+
+  Example check output:
+
+  ```
+  region=us-west-2
+  application_id=1001
+  ```
+
+  Example event payload:
+
+  ```json
+  {
+    "metadata": {},
+    "entity": {},
+    "check": {
+      "metadata": {
+        "name": "example",
+        "labels": {},
+        "metadata": {}
+      },
+      "handlers": [
+        "label-manager"
+      ],
+      "output": "region=us-west-2\napplication_id=1001",
+      "status": 0,
+      "...": "..."
+    },
+    "metrics": {},
+    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "timestamp": 1234567890
+  }
+  ```
+
+  Example handler definition: 
+
+  ```yaml
+  ---
+  type: Handler
+  api_version: core/v2
+  metadata:
+    name: label-manager
+  spec:
+    command: sensu-entity-manager --add-labels
+    ...: ...
+  ```
+
+- **Commands (one space-separated `command argument` pair per line):**
+
+  Example check output:
+
+  ```
+  add-subscription system/linux
+  add-subscription postgres
+  add-label region=us-west-2
+  add-annotation application_id=1001
+  ```
+
+  Example event payload:
+
+  ```json
+  {
+    "metadata": {},
+    "entity": {},
+    "check": {
+      "metadata": {
+        "name": "example",
+        "labels": {},
+        "metadata": {}
+      },
+      "handlers": [
+        "entity-manager"
+      ],
+      "output": "add-subscription system/linux\nadd-subscription postgres\nadd-label region=us-west-2\nadd-annotation application_id=1001",
+      "status": 0,
+      "...": "..."
+    },
+    "metrics": {},
+    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "timestamp": 1234567890
+  }
+  ```
+
+  Example handler definition: 
+
+  ```yaml
+  ---
+  type: Handler
+  api_version: core/v2
+  metadata:
+    name: entity-manager
+  spec:
+    command: sensu-entity-manager --add-all
+    ...: ...
+  ```
 
 ## Usage examples
 
@@ -41,6 +184,9 @@ Available Commands:
 
 Flags:
   -t, --access-token string      Sensu Access Token
+      --add-all                  Checks event.Check.Output for a newline-separated list of entity management commands to execute
+      --add-annotations          Checks event.Check.Output for a newline-separated list of annotation key=value pairs to add
+      --add-labels               Checks event.Check.Output for a newline-separated list of label key=value pairs to add
       --add-subscriptions        Checks event.Check.Output for a newline-separated list of subscriptions to add
   -k, --api-key string           Sensu API Key
   -a, --api-url string           Sensu API URL (default "http://127.0.0.1:8080")
@@ -52,26 +198,24 @@ Use "sensu-entity-manager [command] --help" for more information about a command
 
 ### Environment variables
 
-|Argument          |Environment Variable  |
-|------------------|----------------------|
-|--api-url         |SENSU_API_URL         |
-|--api-key         |SENSU_API_KEY         |
-|--access-token    |SENSU_ACCESS_TOKEN    |
-|--trusted-ca-file |SENSU_TRUSTED_CA_FILE |
+| Argument          | Environment Variable  |
+|-------------------|-----------------------|
+| --api-url         | SENSU_API_URL         |
+| --api-key         | SENSU_API_KEY         |
+| --access-token    | SENSU_ACCESS_TOKEN    |
+| --trusted-ca-file | SENSU_TRUSTED_CA_FILE |
 
-**Security Note:** Care should be taken to not expose the API key or access token for this handler
-by specifying either on the command line or by directly setting the environment variable(s) in the
-handler definition.  It is suggested to make use of [secrets management][3] to surface either as an
-environment variable.  The [handler definition shown below](#handler-definition) references the API Key as a secret
-using the built-in [env secrets provider][4].
+**Security Note:** Care should be taken to not expose the API key or access token for this handler by explicitly specifying either on the command line or by directly setting the environment variable(s) in the handler definition.
+It is suggested to make use of [secrets management][3] to provide the API key or access token as environment variables.
+The [handler definition shown below](#handler-definition) references the API Key as a secret using the built-in [env secrets provider][4].
 
 ## Configuration
 
 ### Asset registration
 
-[Sensu Assets][10] are the best way to make use of this plugin. If you're not using an asset, please
-consider doing so! If you're using sensuctl 5.13 with Sensu Backend 5.13 or later, you can use the
-following command to add the asset:
+[Sensu Assets][10] are the best way to make use of this plugin.
+If you're not using an asset, please consider doing so!
+If you're using sensuctl 5.13 with Sensu Backend 5.13 or later, you can use the following command to add the asset:
 
 ```
 sensuctl asset add sensu/sensu-entity-manager
@@ -89,9 +233,9 @@ metadata:
   name: sensu-entity-manager
 spec:
   type: pipe
-  command: >- 
-    sensu-entity-manager 
-    --add-subscriptions
+  command: >-
+    sensu-entity-manager
+    --add-all
   timeout: 5
   runtime_assets:
   - sensu/sensu-entity-manager:0.1.1
@@ -103,39 +247,35 @@ type: Secret
 api_version: secrets/v1
 metadata:
   name: entity-manager-api-key
-spec: 
+spec:
   provider: env
   id: SENSU_ENTITY_MANAGER_API_KEY
 ```
 
 #### Proxy Support
 
-This handler supports the use of the environment variables HTTP_PROXY,
-HTTPS_PROXY, and NO_PROXY (or the lowercase versions thereof). HTTPS_PROXY takes
-precedence over HTTP_PROXY for https requests.  The environment values may be
-either a complete URL or a "host[:port]", in which case the "http" scheme is assumed.
+This handler supports the use of the environment variables HTTP_PROXY, HTTPS_PROXY, and NO_PROXY (or the lowercase versions thereof).
+HTTPS_PROXY takes precedence over HTTP_PROXY for https requests.
+The environment values may be either a complete URL or a "host[:port]", in which case the "http" scheme is assumed.
 
-### Supported Annotations 
+### Supported Annotations
 
-The following _event-scoped annotations_ are supported. 
+The following _event-scoped annotations_ are supported.
 
 - `sensu.io/plugins/sensu-entity-manager/config/patch/subscriptions`
 
-  Comma-separated list of subscriptions to add (e.g. `nginx,http-service`). 
+  Comma-separated list of subscriptions to add (e.g. `nginx,http-service`).
 
 - `sensu.io/plugins/sensu-entity-manager/config/patch/labels`
 
   Comma-separated list of key=value pairs to add (e.g. `region=us-west-1,app=example`).
 
 - `sensu.io/plugins/sensu-entity-manager/config/patch/annotations`
 
-  Semicolon-separated list of key=value pairs to add (e.g. 
-  `scrape_config="{\"ports\": [9091,9093]}";service_account=sensu`). 
+  Semicolon-separated list of key=value pairs to add (e.g. `scrape_config="{\"ports\": [9091,9093]}";service_account=sensu`).
 
-> _NOTE: event-scoped annotations are set at the root-level of the event 
-> (i.e. `event.Annotations`). Entity-scoped (`event.Entity.Annotations`) and 
-> Check-scoped (`event.Check.Annotations`) annotations are currently not 
-> supported._
+> _NOTE: event-scoped annotations are set at the root-level of the event (i.e. `event.Annotations`).
+> Entity-scoped (`event.Entity.Annotations`) and Check-scoped (`event.Check.Annotations`) annotations are currently not supported._
 
 
 #### Examples
@@ -153,9 +293,8 @@ metadata:
 
 ## Installation from source
 
-The preferred way of installing and deploying this plugin is to use it as an Asset. If you would
-like to compile and install the plugin from source or contribute to it, download the latest version
-or create an executable from this source.
+The preferred way of installing and deploying this plugin is to use it as an Asset.
+If you would like to compile and install the plugin from source or contribute to it, download the latest version or create an executable from this source.
 
 From the local path of the sensu-entity-manager repository:
 
@@ -166,9 +305,9 @@ go build
 ## Roadmap
 
 - [x] Add support for adding/modifying entity subscriptions
-- [ ] Add support for adding/modifying entity labels  
-- [ ] Add support for adding/modifying entity annotations  
-- [ ] Add support for modifying other [entity-patchable fields][11] (e.g. 
+- [x] Add support for adding/modifying entity labels
+- [x] Add support for adding/modifying entity annotations
+- [ ] Add support for modifying other [entity-patchable fields][11] (e.g.
       `created_by`, `entity_class`, `deregister`, etc).
 
 ## Contributing
@@ -180,4 +319,4 @@ For more information about contributing to this plugin, see [Contributing][1].
 [3]: https://docs.sensu.io/sensu-go/latest/guides/secrets-management/
 [4]: https://docs.sensu.io/sensu-go/latest/guides/secrets-management/#use-env-for-secrets-management
 [10]: https://docs.sensu.io/sensu-go/latest/reference/assets/
-[11]: https://docs.sensu.io/sensu-go/latest/api/entities/#update-an-entity-with-patch 
+[11]: https://docs.sensu.io/sensu-go/latest/api/entities/#update-an-entity-with-patch