diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 0891e1f..d29e9db 100644 --- 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 index 346f3ea..0f2ded1 100644 --- 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 index 8b81d86..6907752 100644 --- 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,25 +247,24 @@ 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` @@ -129,13 +272,10 @@ The following _event-scoped annotations_ are supported. - `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 diff --git a/main.go b/main.go index 0e53110..d6e8679 100644 --- a/main.go +++ b/main.go @@ -30,6 +30,7 @@ type Config struct { AddSubscriptions bool AddLabels bool AddAnnotations bool + AddAll bool } // EntitySubscriptions is a partial Entity definition for use with the @@ -37,13 +38,16 @@ type Config struct { // type Deregistration struct { // Handler string `json:"handler"` // } +type ObjectMeta struct { + Labels map[string]string `json:"labels,omitempty"` + Annotations map[string]string `json:"annotations,omitempty"` +} // EntityPatch is a shell of an Entity object for use with the // PATCH /entities API type EntityPatch struct { - Subscriptions []string `json:"subscriptions,omitempty"` - Labels map[string]string `json:"labels,omitempty"` - Annotations map[string]string `json:"annotations,omitempty"` + Subscriptions []string `json:"subscriptions,omitempty"` + Metadata ObjectMeta `json:"metadata,omitempty"` // TBD if we want to support other Entity-patchable fields: // CreatedBy string `json:"created_by,omitempty"` // EntityClass string `json:"entity_class,omitempty"` @@ -130,31 +134,13 @@ var ( Value: &plugin.AddAnnotations, }, { - Path: "patch/subscriptions", - Env: "", - Argument: "", - Shorthand: "", - Default: []string{}, - Usage: "Sensu Entity Subscriptions", - Value: &plugin.Subscriptions, - }, - { - Path: "patch/labels", - Env: "", - Argument: "", - Shorthand: "", - Default: "", - Usage: "Sensu Entity Labels", - Value: &plugin.Labels, - }, - { - Path: "patch/annotations", + Path: "", Env: "", - Argument: "", + Argument: "add-all", Shorthand: "", - Default: "", - Usage: "Sensu Entity Annotations", - Value: &plugin.Annotations, + Default: false, + Usage: "Checks event.Check.Output for a newline-separated list of entity management commands to execute", + Value: &plugin.AddAll, }, } ) @@ -186,14 +172,32 @@ func checkArgs(event *types.Event) error { plugin.ApiUrl = os.Getenv("SENSU_API_URL") } if plugin.AddSubscriptions { - checkOutputSubs := strings.Split(event.Check.Output, "\n") - plugin.Subscriptions = mergeStringSlices(plugin.Subscriptions, checkOutputSubs) - fmt.Printf("Added %v subscriptions from event.Check.Output\n", len(checkOutputSubs)) + fmt.Printf("Adding subscriptions from \"event.check.output\"\n") + addSubscriptions(strings.Split(event.Check.Output, "\n")) } if len(event.Annotations["sensu.io/plugins/sensu-entity-manager/config/patch/subscriptions"]) > 0 { - annotationSubs := strings.Split(event.Annotations["sensu.io/plugins/sensu-entity-manager/config/patch/subscriptions"], ",") - plugin.Subscriptions = mergeStringSlices(plugin.Subscriptions, annotationSubs) - fmt.Printf("Added %v subscriptions from the \"sensu.io/plugins/sensu-entity-manager/config/patch/subscriptions\" event annotation\n", len(annotationSubs)) + fmt.Printf("Adding subscriptions from the \"sensu.io/plugins/sensu-entity-manager/config/patch/subscriptions\" event annotation\n") + addSubscriptions(strings.Split(event.Annotations["sensu.io/plugins/sensu-entity-manager/config/patch/subscriptions"], ",")) + } + if plugin.AddLabels { + fmt.Printf("Adding labels from \"event.check.output\"\n") + addLabels(strings.Split(event.Check.Output, "\n")) + } + if len(event.Annotations["sensu.io/plugins/sensu-entity-manager/config/patch/labels"]) > 0 { + fmt.Printf("Adding labels from the \"sensu.io/plugins/sensu-entity-manager/config/patch/labels\" event annotation\n") + addLabels(strings.Split(event.Annotations["sensu.io/plugins/sensu-entity-manager/config/patch/labels"], ",")) + } + if plugin.AddAnnotations { + fmt.Printf("Adding annotations from \"event.check.output\"\n") + addAnnotations(strings.Split(event.Check.Output, "\n")) + } + if len(event.Annotations["sensu.io/plugins/sensu-entity-manager/config/patch/annotations"]) > 0 { + fmt.Printf("Adding annotations from the \"sensu.io/plugins/sensu-entity-manager/config/patch/annotations\" event annotation\n") + addAnnotations(strings.Split(event.Annotations["sensu.io/plugins/sensu-entity-manager/config/patch/annotations"], ",")) + } + if plugin.AddAll { + fmt.Printf("Adding entity properties from \"event.check.output\"\n") + parseCommands(strings.Split(event.Check.Output, "\n")) } return nil } @@ -236,6 +240,7 @@ func initHTTPClient() *http.Client { return client } +// Return the index location of a string in a []string func indexOf(s []string, k string) int { for i, v := range s { if v == k { @@ -245,6 +250,18 @@ func indexOf(s []string, k string) int { return -1 } +// Merge two map[string]string objects +// NOTE: this is a potentially destructive method (values may be overwritten) +func mergeMapStringStrings(a map[string]string, b map[string]string) map[string]string { + if a == nil { + fmt.Printf("Error: no entity labels; %v", a) + } + for k, v := range b { + a[k] = v + } + return a +} + func mergeStringSlices(a []string, b []string) []string { for _, v := range b { if indexOf(a, v) < 0 { @@ -264,15 +281,77 @@ func trimSlice(s []string) []string { return s } +// Parse a slice of strings containing key=value pairs +func parseKvStringSlice(s []string) map[string]string { + var m = make(map[string]string) + for _, kvString := range s { + i := strings.Split(kvString, "=") + if len(i) > 1 { + k := strings.TrimSpace(i[0]) + v := strings.TrimSpace(i[1]) + if len(strings.Split(k, " ")) > 1 { + fmt.Printf("WARNING: invalid key name: \"%s\" (did you mean to use --add-all?)\n", k) + } else { + m[k] = v + } + } + } + return m +} + +func addSubscriptions(subs []string) { + plugin.Subscriptions = mergeStringSlices(plugin.Subscriptions, subs) +} + +func addLabels(labels []string) { + plugin.Labels = parseKvStringSlice(labels) +} + +func addAnnotations(annotations []string) { + plugin.Annotations = parseKvStringSlice(annotations) +} + func patchEntity(event *types.Event) *EntityPatch { entity := new(EntityPatch) // Merge subscriptions entity.Subscriptions = trimSlice(mergeStringSlices(event.Entity.Subscriptions, plugin.Subscriptions)) + // Init Metadata + entity.Metadata = ObjectMeta{} + + // Merge labels + entity.Metadata.Labels = mergeMapStringStrings(event.Entity.Labels, plugin.Labels) + + // Merge annotations + entity.Metadata.Annotations = mergeMapStringStrings(event.Entity.Annotations, plugin.Annotations) + return entity } +// Parse commands +func parseCommands(s []string) { + for _, str := range s { + instructions := strings.Split(str, " ") + if len(instructions) < 2 { + fmt.Printf("WARNING: invalid command: \"%s\"\n", str) + } else { + command := strings.TrimSpace(instructions[0]) + argument := strings.TrimSpace(instructions[1]) + switch command { + case "add-subscription": + addSubscriptions([]string{argument}) + case "add-label": + addLabels([]string{argument}) + case "add-annotation": + addAnnotations([]string{argument}) + default: + fmt.Printf("WARNING: nothing to do for command: \"%v\" (argument: \"%s\").\n", command, argument) + } + } + } +} + func executeHandler(event *types.Event) error { data := patchEntity(event) postBody, err := json.Marshal(data)